Reference manual

Version 1.2.0

Index

Lwt

Eliom

Main modules

Pages with Ocamlduce

XHTML pages typed with variants

Other pages

Eliom_predefmod

Creating new kinds of pages

Ocsigen

This is a preliminary version of the documentation. Help us to improve it by filling tickets. We are looking for native english speakers to proof read the documentation. Contact us!

Module Lwt_io

module Lwt_io: sig .. end

Buffered byte channels

A channel is a high-level object for performing IOs. It allow to read/write things from/to the outside worlds in an efficient way, by minimising the number of system calls.

An output channel is a channel that can be used to send data and an input channel is a channel that can used to receive data.

If you are familiar with buffered channels you may be familiar too with the flush operation. Note that byte channles of this modules are automatically flushed when there is nothing else to do (i.e. before the program goes into idle), so this means that you no longer have to write:

      eprintf "log message\n";      flush stderr;

to have you messages displayed.

exception Channel_closed of string

Exception raised whan a channel is closed. The parameter is a description of the channel.

Types

type 'a channel

Type of buffered byte channels

type input

Input mode

type output

Output mode

type 'a mode = private

`\|`	`Input`
`\|`	`Output`

Channel mode

val input : input mode

input input mode representation

val output : output mode

output output mode representation

type input_channel = input channel

Type of input channels

type output_channel = output channel

Type of output channels

val mode : 'a channel -> 'a mode

mode ch returns the mode of a channel

Well-known instances

val stdin : input_channel

The standard input, it reads data from Lwt_unix.stdin

val stdout : output_channel

The standard output, it writes data to Lwt_unix.stdout

val stderr : output_channel

The standard output for error messages, it writes data to Lwt_unix.stderr

val zero : input_channel

Inputs which returns always '\x00'

val null : output_channel

Output which drops everything

Channels creation/manipulation

val pipe : ?buffer_size:int -> unit -> input_channel * output_channel

pipe ?buffer_size () creates a pipe using Lwt_unix.pipe and makes two channels from the two returned file descriptors

val make : ?buffer_size:int ->
       ?close:(unit -> unit Lwt.t) ->
       ?seek:(int64 -> Unix.seek_command -> int64 Lwt.t) ->
       mode:'a mode ->
       (string -> int -> int -> int Lwt.t) -> 'a channel

make ?buffer_size ?close ~mode perform_io is the main function for creating new channels.

buffer_size : is the size of the internal buffer. It is not used if buffer is provided.

close : is the close function of the channel. It defaults to Lwt.return

seek : has the same meaning as Unix.lseek

mode : is either Lwt_io.input or Lwt_io.output

val of_fd : ?buffer_size:int ->
       mode:'a mode -> Lwt_unix.file_descr -> 'a channel

of_fd ~mode ~fd creates a channel from a file descriptor

val of_unix_fd : ?buffer_size:int ->
       mode:'a mode -> Unix.file_descr -> 'a channel

of_unix_fd ~mode ~fd is a short-hand for:

of_fd (Lwt_unix.of_unix_file_descr fd)

val close : 'a channel -> unit Lwt.t

close ch closes the given channel: wait for all pending operations to terminate, preventing new one to be queued, then flush the channel if it is an output channel and close it.

close returns the result of the close function of the channel. Multiple calls to close will return exactly the same value.

val abort : 'a channel -> unit Lwt.t

abort ch abort current operations and close the channel immediatly.

val atomic : ('a channel -> 'b Lwt.t) -> 'a channel -> 'b Lwt.t

atomic f transforms a sequence of io operations into one single atomic io operation.

Note:

the channel passed to f is invalid after f terminates
atomic can be called inside another atomic
the ``auto-flushing'' is performed only when all operations on the main channel are terminated

val file_length : string -> int64 Lwt.t

Returns the length of a file

val buffered : 'a channel -> int

buffered oc returns the number of bytes in the buffer

val flush : output_channel -> unit Lwt.t

flush oc performs all pending writes on oc

Random access

val position : 'a channel -> int64

position ch Returns the current position in the channel.

val set_position : 'a channel -> int64 -> unit Lwt.t

set_position ch pos Sets the position in the output channel. This does not work if the channel do not support random access.

val length : 'a channel -> int64 Lwt.t

Returns the length of the channel in bytes

Reading

Note: except for functions dealing with streams (Lwt_io.read_chars and Lwt_io.read_lines) all functions are atomic.

val read_char : input_channel -> char Lwt.t

read_char ic reads the next character of ic.
Raises End_of_file if the end of the file is reached

val read_char_opt : input_channel -> char option Lwt.t

Same as read_byte but do not raises End_of_file on end of input

val read_chars : input_channel -> char Lwt_stream.t

read_chars ic returns a stream holding all characters of ic

val read_line : input_channel -> string Lwt.t

read_line ic reads one complete line from ic and returns it without the end of line. End of line is either "\n" or "\r\n".

If the end of line is reached before reading any character, End_of_file is reached. If it is reached before reading an end of line but characters have already been read, they are returned.

val read_line_opt : input_channel -> string option Lwt.t

Same as Lwt_io.read_line but do not raise End_of_file on end of input.

val read_lines : input_channel -> string Lwt_stream.t

read_lines ic returns a stream holding all lines of ic

val read : ?count:int -> input_channel -> string Lwt.t

read ?count ic reads at most len characters from ic. It returns "" if the end of input is reached. If count is not specified, it reads all bytes until the end of input.

val read_into : input_channel -> string -> int -> int -> int Lwt.t

read_into ic buffer offset length reads up to length bytes, stores them in buffer at offset offset, and returns the number of bytes read.

Note: read_into does not raise End_of_file, it returns a length of 0 instead.

val read_into_exactly : input_channel -> string -> int -> int -> unit Lwt.t

read_into_exactly ic buffer offset length reads exactly length bytes and stores them in buffer at offset offset.
Raises End_of_file on end of input

val read_value : input_channel -> 'a Lwt.t

read_value ic reads a marshaled value from ic

Writing

Note: as for reading functions, all functions except Lwt_io.write_chars and Lwt_io.write_lines are atomic.

For example if you use Lwt_io.write_line in to different threads, the two operations will be serialized, and lines cannot be mixed.

val write_char : output_channel -> char -> unit Lwt.t

write_char oc char writes char on oc

val write_chars : output_channel -> char Lwt_stream.t -> unit Lwt.t

write_chars oc chars writes all characters contained hold by chars on oc

val write : output_channel -> string -> unit Lwt.t

write oc str writes all characters of str on oc

val write_line : output_channel -> string -> unit Lwt.t

write_line oc str writes str on oc followed by a new-line.

val write_lines : output_channel -> string Lwt_stream.t -> unit Lwt.t

write_lines oc lines writes all lines of lines to oc

val write_from : output_channel -> string -> int -> int -> int Lwt.t

write_from oc buffer offset length writes up to length bytes to oc, from buffer at offset offset and returns the number of bytes actually written

val write_from_exactly : output_channel -> string -> int -> int -> unit Lwt.t

write_from_exactly oc buffer offset length writes all length bytes from buffer at offset offset to oc

val write_value : output_channel -> ?flags:Marshal.extern_flags list -> 'a -> unit Lwt.t

write_value oc ?flags x marshals the value x to oc

Printing

The functions are basically helpers. Also you may prefer the using the name Lwt_io.printl rather than Lwt_io.write_line because it is shorter.

The general name of a printing function is <prefix>print<suffixes>.

Where <prefix> is one of:

'f', which means that the function takes as argument a channel
nothing, which means that the function prints on Lwt_io.stdout
'e', which means that the function prints on Lwt_io.stderr

and <suffixes> is a combination of:

'l' which means that a new-line character is printed after the message
'f' which means that the function takes as argument a format instead of a string

val fprint : output_channel -> string -> unit Lwt.t

val fprintl : output_channel -> string -> unit Lwt.t

val fprintf : output_channel ->
       ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val fprintlf : output_channel ->
       ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val print : string -> unit Lwt.t

val printl : string -> unit Lwt.t

val printf : ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val printlf : ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val eprint : string -> unit Lwt.t

val eprintl : string -> unit Lwt.t

val eprintf : ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val eprintlf : ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

Utilities

val hexdump_stream : output_channel -> char Lwt_stream.t -> unit Lwt.t

hexdump_stream oc byte_stream produces the same output as the command hexdump -C.

val hexdump : output_channel -> string -> unit Lwt.t

hexdump oc str = hexdump_stream oc (Lwt_stream.of_string str)

File utilities

type file_name = string

Type of file names

val open_file : ?buffer_size:int ->
       ?flags:Unix.open_flag list ->
       ?perm:Unix.file_perm ->
       mode:'a mode -> file_name -> 'a channel

open_file ?buffer_size ?flags ?perm ~mode filename open the file with name filename and returns a channel for reading/writing it.
Raises Sys_error on error

val with_file : ?buffer_size:int ->
       ?flags:Unix.open_flag list ->
       ?perm:Unix.file_perm ->
       mode:'a mode ->
       file_name -> ('a channel -> 'b Lwt.t) -> 'b Lwt.t

with_file ?buffer_size ?flags ?perm ~mode filename f open a file and passes the channel to f. It is ensured that the channel is closed when f ch terminates (even if it fails).

val open_connection : ?buffer_size:int ->
       Unix.sockaddr -> (input_channel * output_channel) Lwt.t

open_connection ?buffer_size ~mode addr open a connection to the given address and returns two channels for using it.

The connection is completly closed when you close both channels.
Raises Sys_error on error

val with_connection : ?buffer_size:int ->
       Unix.sockaddr ->
       (input_channel * output_channel -> 'a Lwt.t) -> 'a Lwt.t

with_connection ?buffer_size ~mode addr f open a connection to the given address and passes the channels to f

val lines_of_file : file_name -> string Lwt_stream.t

lines_of_file name returns a stream of all lines of the file with name name. The file is automatically closed when all lines have been read.

val lines_to_file : file_name -> string Lwt_stream.t -> unit Lwt.t

lines_to_file name lines writes all lines of lines to files

val chars_of_file : file_name -> char Lwt_stream.t

chars_of_file name returns a stream of all characters of the file with name name. As for Lwt_io.lines_of_file the file is closed when all characters have been read.

val chars_to_file : file_name -> char Lwt_stream.t -> unit Lwt.t

chars_to_file name chars writes all characters of chars to name

Input/output of integers

module type NumberIO = sig .. end

Common interface for reading/writing integers in binary

module LE: NumberIO

Reading/writing of integers in little-endian

module BE: NumberIO

Reading/writing of integers in big-endian

Low-level access to the internal buffer

val block : 'a channel -> int -> (string -> int -> 'b Lwt.t) -> 'b Lwt.t

block ch size f pass to f the internal buffer and an offset. The buffer contains size chars at offset. f may reads or writes these chars.

type direct_access = {

`da_buffer : string;`	`(*`	The internal buffer	`*)`
`mutable da_ptr : int;`	`(*`	The pointer to: the beginning of free space for output channels the beginning of data for input channels	`*)`
`mutable da_max : int;`	`(*`	The maximum offset	`*)`
`da_perform : unit -> int Lwt.t;`	`(*`	- for input channels: refill the buffer and returns how many bytes have been read for output channels: flush partially the buffer and returns how many bytes have been written	`*)`

}

Informations for accessing directly to the internal buffer of a channel:

val direct_access : 'a channel -> (direct_access -> 'b Lwt.t) -> 'b Lwt.t

direct_access ch f pass to f a Lwt_io.direct_access structure. f must use it and update da_ptr to reflect how many bytes have been read/written.

Misc

val default_buffer_size : unit -> int

Return the default size for buffers. Channels that are created without specific size use this one.

val set_default_buffer_size : int -> unit

Change the default buffer size.
Raises Invalid_argument if the given size is smaller than 16 or greater than Sys.max_string_length