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.
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 Channel_closed of string
Exception raised when 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 ->
(Lwt_bytes.t -> int -> int -> int Lwt.t) -> 'a channel
make ?buffer_size ?close ~mode perform_io is the
main function for creating new channels.
buffer_size : size of the internal buffer. It must be between 16 and Sys.max_string_length
close : close function of the channel. It defaults to Lwt.return
seek : same meaning as Unix.lseek
mode : either Lwt_io.input or Lwt_io.output
val of_bytes : mode:'a mode -> Lwt_bytes.t -> 'a channel
Create a channel from a byte array. Reading/writing is done
directly on the provided array.
val of_fd :
?buffer_size:int ->
?close:(unit -> unit Lwt.t) ->
mode:'a mode -> Lwt_unix.file_descr -> 'a channel
of_fd ?buffer_size ?close ~mode fd creates a channel from a
file descriptor.
close : defaults to closing the file descriptor.
val of_unix_fd :
?buffer_size:int ->
?close:(unit -> unit Lwt.t) ->
mode:'a mode -> Unix.file_descr -> 'a channel
of_unix_fd ?buffer_size ?close ~mode fd is a short-hand for:
of_fd ?buffer_size ?close (Lwt_unix.of_unix_file_descr fd)
val close : 'a channel -> unit Lwt.t
close ch closes the given channel. If ch is an output
channel, it performs all pending actions, flush it and close
it. If ch is an input channel, it just close it immediatly.
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 channel obtained with an
Lwt_io.atomic.
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
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
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 resize_buffer : 'a channel -> int -> unit Lwt.t
Resize the internal buffer to the given size
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.
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 does 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 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 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 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 -> 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 ¶
These 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 Lwt.t
open_file ?buffer_size ?flags ?perm ~mode filename open the
file with name filename and returns a channel for
reading/writing it.
Raises Unix.Unix_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 Unix.Unix_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
type server
Type of a server
val establish_server :
?buffer_size:int ->
?backlog:int ->
Unix.sockaddr ->
(input_channel * output_channel -> unit) ->
server
establich_server ?buffer_size ?backlog sockaddr f creates a
server which will listen for incomming connections. New
connections are passed to f. Note that f must not raise any
exception.
backlog is the argument passed to Lwt_unix.listen
val shutdown_server : server -> unit
Shutdown the given 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
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 numbers in little-endian
module BE : NumberIO
Reading/writing of numbers in big-endian
include Lwt_io.NumberIO
Reading/writing of numbers in the system endianness.
type byte_order = Lwt_sys.byte_order = | Little_endian | Big_endian(* Type of byte order *)
val system_byte_order : byte_order
Same as Lwt_sys.byte_order.
Low-level access to the internal buffer ¶
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
reads or writes these chars. size must verify 0 <= size <=
16
type direct_access = { da_buffer: Lwt_bytes.t;(* The internal buffer *) mutable da_ptr: int;(* The pointer to:* the beginning of free space for output channels Lists not enabled in this syntax *) 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