Library
Module
Module type
Parameter
Class
Class type
Buffered byte channels
A channel is a high-level object for performing input/output (IO). It allows to read/write from/to the outside world in an efficient way, by minimising the number of system calls.
An output channel is used to send data and an input channel is used to receive data.
If you are familiar with buffered channels you may be familiar too with the flush operation. Note that byte channels of this module are automatically flushed when there is nothing else to do (i.e. before the program becomes idle), so this means that you no longer have to write:
eprintf "log message\n";
flush stderr;
to have your messages displayed.
Note about errors: input functions of this module raise End_of_file
when the end-of-file is reached (i.e. when the read function returns 0
). Other exceptions are ones caused by the backend read/write functions, such as Unix.Unix_error
.
Exception raised when a channel is closed. The parameter is a description of the channel.
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
val pipe :
?in_buffer:Lwt_bytes.t ->
?out_buffer:Lwt_bytes.t ->
unit ->
input_channel * output_channel
pipe ?in_buffer ?out_buffer ()
creates a pipe using Lwt_unix.pipe
and makes two channels from the two returned file descriptors
val make :
?buffer:Lwt_bytes.t ->
?close:(unit -> unit Lwt.t) ->
?seek:(int64 -> Unix.seek_command -> int64 Lwt.t) ->
mode:'mode mode ->
(Lwt_bytes.t -> int -> int -> int Lwt.t) ->
'mode channel
make ?buffer ?close ~mode perform_io
is the main function for creating new channels.
val of_bytes : mode:'mode mode -> Lwt_bytes.t -> 'mode channel
Create a channel from a byte array. Reading/writing is done directly on the provided array.
val of_fd :
?buffer:Lwt_bytes.t ->
?close:(unit -> unit Lwt.t) ->
mode:'mode mode ->
Lwt_unix.file_descr ->
'mode channel
of_fd ?buffer ?close ~mode fd
creates a channel from a file descriptor.
val of_unix_fd :
?buffer:Lwt_bytes.t ->
?close:(unit -> unit Lwt.t) ->
mode:'mode mode ->
Unix.file_descr ->
'mode channel
of_unix_fd ?buffer ?close ~mode fd
is a short-hand for:
of_fd ?buffer ?close (Lwt_unix.of_unix_file_descr fd)
close ch
closes the given channel. If ch
is an output channel, it performs all pending actions, flushes it and closes it. If ch
is an input channel, it just closes it immediately.
close
returns the result of the close function of the channel. Multiple calls to close
will return exactly the same value.
Note: you cannot use close
on channels obtained with atomic
.
abort ch
abort current operations and close the channel immediately.
atomic f
transforms a sequence of io operations into one single atomic io operation.
Note:
f
is invalid after f
terminatesatomic
can be called inside another atomic
val file_length : string -> int64 Lwt.t
Retrieves the length of the file at the given path. If the path refers to a directory, the returned promise is rejected with Unix.(Unix_error (EISDIR, _, _))
.
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
val flush_all : unit -> unit Lwt.t
flush_all ()
flushes all open output channels
val buffer_size : 'a channel -> int
Returns the size of the internal buffer.
val is_busy : 'a channel -> bool
is_busy channel
returns whether the given channel is currently busy. A channel is busy when there is at least one job using it that has not yet terminated.
val position : 'a channel -> int64
position ch
Returns the current position in the channel.
set_position ch pos
Sets the position in the output channel. This does not work if the channel does not support random access.
Note: except for functions dealing with streams (read_chars
and read_lines
) all functions are atomic.
val read_char : input_channel -> char Lwt.t
read_char ic
reads the next character of ic
.
val read_char_opt : input_channel -> char option Lwt.t
Same as read_byte
but does not raise 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 raised. 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 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
If ~count
is specified, read ~count ic
reads at most ~count
characters from ic
. Note that fewer than ~count
characters can be read; check the size of the resulting string. read
returns ""
if the end of input is reached.
If ~count
is not specified, read ic
reads all bytes until the end of input.
val read_into : input_channel -> bytes -> 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 -> bytes -> int -> int -> unit Lwt.t
read_into_exactly ic buffer offset length
reads exactly length
bytes and stores them in buffer
at offset offset
.
val read_value : input_channel -> 'a Lwt.t
read_value channel
reads a marshaled value from channel
; it corresponds to the standard library's Marshal.from_channel
. The corresponding writing function is write_value
.
Note that reading marshaled values is not, in general, type-safe. See the warning in the description of module Marshal
for details. The short version is: if you read a value of one type, such as string
, when a value of another type, such as int
has actually been marshaled to channel
, you may get arbitrary behavior, including segmentation faults, access violations, security bugs, etc.
Note: as for reading functions, all functions except write_chars
and write_lines
are atomic.
For example if you use write_line
in two 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 of 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 -> bytes -> 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_string : output_channel -> string -> int -> int -> int Lwt.t
See write
.
val write_from_exactly : output_channel -> bytes -> 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_from_string_exactly :
output_channel ->
string ->
int ->
int ->
unit Lwt.t
See write_from_exactly
.
val write_value :
output_channel ->
?flags:Marshal.extern_flags list ->
'a ->
unit Lwt.t
write_value channel ?flags v
writes v
to channel
using the Marshal
module of the standard library. See Marshal.to_channel
for an explanation of ?flags
.
The corresponding reading function is read_value
. See warnings about type safety in the description of read_value
.
These functions are basically helpers. Also you may prefer using the name printl
rather than 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 channelstdout
'e'
, which means that the function prints on 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 stringval 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) format4 -> 'a
%!
does nothing here. To flush the channel, use Lwt_io.flush channel
.
val fprintlf : output_channel -> ('a, unit, string, unit Lwt.t) format4 -> 'a
%!
does nothing here. To flush the channel, use Lwt_io.flush channel
.
val print : string -> unit Lwt.t
val printl : string -> unit Lwt.t
%!
does nothing here. To flush the channel, use Lwt_io.(flush stdout)
.
%!
does nothing here. To flush the channel, use Lwt_io.(flush stdout)
.
val eprint : string -> unit Lwt.t
val eprintl : string -> unit Lwt.t
%!
does nothing here. To flush the channel, use Lwt_io.(flush stderr)
.
%!
does nothing here. To flush the channel, use Lwt_io.(flush stderr)
.
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)
val open_file :
?buffer:Lwt_bytes.t ->
?flags:Unix.open_flag list ->
?perm:Unix.file_perm ->
mode:'a mode ->
file_name ->
'a channel Lwt.t
open_file ?buffer ?flags ?perm ~mode filename
opens the file with name filename
and returns a channel for reading/writing it.
val with_file :
?buffer:Lwt_bytes.t ->
?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 ?flags ?perm ~mode filename f
opens 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_temp_file :
?buffer:Lwt_bytes.t ->
?flags:Unix.open_flag list ->
?perm:Unix.file_perm ->
?temp_dir:string ->
?prefix:string ->
unit ->
(string * output_channel) Lwt.t
open_temp_file ()
starts creating a new temporary file, and evaluates to a promise for the pair of the file's name, and an output channel for writing to the file.
The caller should take care to delete the file later. Alternatively, see Lwt_io.with_temp_file
.
The ?buffer
and ?perm
arguments are passed directly to an internal call to Lwt.io.open_file
.
If not specified, ?flags
defaults to [O_CREATE; O_EXCL; O_WRONLY; O_CLOEXEC]
. If specified, the specified flags are used exactly. Note that these should typically contain at least O_CREAT
and O_EXCL
, otherwise open_temp_file
may open an existing file.
?temp_dir
can be used to choose the directory in which the file is created. For the current directory, use Filename.current_dir_name
. If not specified, the directory is taken from Filename.get_temp_dir_name
, which is typically set to your system temporary file directory.
?prefix
helps determine the name of the file. It will be the prefix concatenated with a random sequence of characters. If not specified, open_temp_file
uses some default prefix.
val with_temp_file :
?buffer:Lwt_bytes.t ->
?flags:Unix.open_flag list ->
?perm:Unix.file_perm ->
?temp_dir:string ->
?prefix:string ->
((string * output_channel) -> 'b Lwt.t) ->
'b Lwt.t
with_temp_file f
calls open_temp_file
()
, passing all optional arguments directly to it. It then attaches f
to run after the file is created, passing the filename and output channel to f
. When the promise returned by f
is resolved, with_temp_file
closes the channel and deletes the temporary file by calling Lwt_unix.unlink
.
val open_connection :
?fd:Lwt_unix.file_descr ->
?in_buffer:Lwt_bytes.t ->
?out_buffer:Lwt_bytes.t ->
Unix.sockaddr ->
(input_channel * output_channel) Lwt.t
open_connection ?fd ?in_buffer ?out_buffer addr
opens a connection to the given address and returns two channels for using it. If fd
is not specified, a fresh one will be used.
The connection is completly closed when you close both channels.
val with_connection :
?fd:Lwt_unix.file_descr ->
?in_buffer:Lwt_bytes.t ->
?out_buffer:Lwt_bytes.t ->
Unix.sockaddr ->
((input_channel * output_channel) -> 'a Lwt.t) ->
'a Lwt.t
with_connection ?fd ?in_buffer ?out_buffer addr f
opens a connection to the given address and passes the channels to f
val establish_server_with_client_address :
?fd:Lwt_unix.file_descr ->
?buffer_size:int ->
?backlog:int ->
?no_close:bool ->
Unix.sockaddr ->
(Lwt_unix.sockaddr -> (input_channel * output_channel) -> unit Lwt.t) ->
server Lwt.t
establish_server_with_client_address listen_address f
creates a server which listens for incoming connections on listen_address
. When a client makes a new connection, it is passed to f
: more precisely, the server calls
f client_address (in_channel, out_channel)
where client_address
is the address (peer name) of the new client, and in_channel
and out_channel
are two channels wrapping the socket for communicating with that client.
The server does not block waiting for f
to complete: it concurrently tries to accept more client connections while f
is handling the client.
When the promise returned by f
completes (i.e., f
is done handling the client), establish_server_with_client_address
automatically closes in_channel
and out_channel
. This is a default behavior that is useful for simple cases, but for a robust application you should explicitly close these channels yourself, and handle any exceptions. If the channels are still open when f
completes, and their automatic closing raises an exception, establish_server_with_client_address
treats it as an unhandled exception reaching the top level of the application: it passes that exception to Lwt.async_exception_hook
, the default behavior of which is to print the exception and terminate your process.
Automatic closing can be completely disabled by passing ~no_close:true
.
Similarly, if f
raises an exception (or the promise it returns fails with an exception), establish_server_with_client_address
can do nothing with that exception, except pass it to Lwt.async_exception_hook
.
~fd
can be specified to use an existing file descriptor for listening. Otherwise, a fresh socket is created internally.
~backlog
is the argument passed to Lwt_unix.listen
.
The returned promise (a server Lwt.t
) resolves when the server has just started listening on listen_address
: right after the internal call to listen
, and right before the first internal call to accept
.
Closes the given server's listening socket. The returned promise resolves when the close(2)
system call completes. This function does not affect the sockets of connections that have already been accepted, i.e. passed to f
by establish_server
.
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 file with name name
.
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 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
module type NumberIO = sig ... end
Common interface for reading/writing integers in binary
Reading/writing of numbers in the system endianness.
include NumberIO
val read_int : input_channel -> int Lwt.t
Reads a 32-bits integer as an ocaml int
val read_int16 : input_channel -> int Lwt.t
val read_int32 : input_channel -> int32 Lwt.t
val read_int64 : input_channel -> int64 Lwt.t
val read_float32 : input_channel -> float Lwt.t
Reads an IEEE single precision floating point value
val read_float64 : input_channel -> float Lwt.t
Reads an IEEE double precision floating point value
val write_int : output_channel -> int -> unit Lwt.t
Writes an ocaml int as a 32-bits integer
val write_int16 : output_channel -> int -> unit Lwt.t
val write_int32 : output_channel -> int32 -> unit Lwt.t
val write_int64 : output_channel -> int64 -> unit Lwt.t
val write_float32 : output_channel -> float -> unit Lwt.t
Writes an IEEE single precision floating point value
val write_float64 : output_channel -> float -> unit Lwt.t
Writes an IEEE double precision floating point value
val system_byte_order : byte_order
Same as Lwt_sys.byte_order
.
val block : 'a channel -> int -> (Lwt_bytes.t -> 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 read or write these chars. size
must satisfy 0 <= size <= 16
type direct_access = {
da_buffer : Lwt_bytes.t;
The internal buffer
*)mutable da_ptr : int;
The pointer to:
mutable da_max : int;
The maximum offset
*)da_perform : unit -> int Lwt.t;
}
Information for directly accessing the internal buffer of a channel
val direct_access : 'a channel -> (direct_access -> 'b Lwt.t) -> 'b Lwt.t
direct_access ch f
passes to f
a direct_access
structure. f
must use it and update da_ptr
to reflect how many bytes have been read/written.
Return the default size for buffers. Channels that are created without a specific buffer use new buffer of this size.
val establish_server :
?fd:Lwt_unix.file_descr ->
?buffer_size:int ->
?backlog:int ->
?no_close:bool ->
Unix.sockaddr ->
((input_channel * output_channel) -> unit Lwt.t) ->
server Lwt.t
Like establish_server_with_client_address
, but does not pass the client address to the callback f
.
module Versioned : sig ... end
Versioned variants of APIs undergoing breaking changes.