Previous  Up  Next

Module BatUnix


module BatUnix: sig .. end
Low-level interface to the operating system (both Unix and Windows).

This module only provides low-level functions and types. Unless you know that you need low-level access to the operating system, you probably don't. For higher-level functions, see modules BatShell, BatIO, BatFile.

Note This module is thread-safe.
Author(s): Xavier Leroy (Base module), David Teller


Low-level interface to the operating system (both Unix and Windows).

This module only provides low-level functions and types. Unless you know that you need low-level access to the operating system, you probably don't. For higher-level functions, see modules BatShell, BatIO, BatFile.

Note This module is thread-safe.

Interfacing with the standard input/output library

val input_of_descr : ?autoclose:bool -> ?cleanup:bool -> Unix.file_descr -> BatInnerIO.input
Create an input reading from the given descriptor. The input is initially in binary mode; use set_binary_mode_in ic false if text mode is desired.
autoclose : If true (default value), close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
cleanup : If true, close the underlying file descriptor when the input is closed. If false or unspecified, do nothing, in which case you will need to close the underlying file descriptor yourself to ensure proper cleanup.
val output_of_descr : ?cleanup:bool -> Unix.file_descr -> unit BatInnerIO.output
Create an output writing on the given descriptor. The output is initially in binary mode; use set_binary_mode_out oc false if text mode is desired.
cleanup : If true, close the underlying file descriptor when the output is closed. If false or unspecified, do nothing, in which case you will need to close the underlying file descriptor yourself to ensure proper cleanup.
val descr_of_input : BatInnerIO.input -> Unix.file_descr
Return the descriptor corresponding to an input.

Not all inputs have file descriptors. This function works only for inputs which have been created using module Unix.
Raises Invalid_argument "Unix.descr_of_in_channel" if this input channel doesn't have a file descriptor

val descr_of_output : unit BatInnerIO.output -> Unix.file_descr
Return the descriptor corresponding to an output.

Not all inputs have file descriptors. This function works only for inputs which have been created from module Unix.
Raises Invalid_arg "Unix.descr_of_out_channel" if this input channel doesn't have a file descriptor

val open_process_in : ?autoclose:bool -> ?cleanup:bool -> string -> BatInnerIO.input
High-level pipe and process management. This function runs the given command in parallel with the program. The standard output of the command is redirected to a pipe, which can be read via the returned input. The command is interpreted by the shell /bin/sh (cf. system).
autoclose : If true (default value), close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
cleanup : If true or unspecified, close the process when the input is closed. If false, do nothing, in which case you will need to close the process yourself to ensure proper cleanup.
val open_process_out : ?cleanup:bool -> string -> unit BatInnerIO.output
Same as Unix.open_process_in, but redirect the standard input of the command to a pipe. Data written to the returned output is sent to the standard input of the command.

Warning writes on outputs are buffered, hence be careful to call Pervasives.flush at the right times to ensure correct synchronization.

cleanup : If true or unspecified, close the process when the output is closed. If false, do nothing, in which case you will need to close the process yourself to ensure proper cleanup.
val open_process : ?autoclose:bool ->
       ?cleanup:bool -> string -> BatInnerIO.input * unit BatInnerIO.output
Same as Unix.open_process_out, but redirects both the standard input and standard output of the command to pipes connected to the two returned input/output. The returned input is connected to the output of the command, and the returned output to the input of the command.
autoclose : If true (default value), close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
cleanup : If true or unspecified, close the process when either the output or the output is closed. If false, do nothing, in which case you will need to close the process yourself to ensure proper cleanup.
val open_process_full : ?autoclose:bool ->
       ?cleanup:bool ->
       string ->
       string array -> BatInnerIO.input * unit BatInnerIO.output * BatInnerIO.input
Similar to Unix.open_process, but the second argument specifies the environment passed to the command. The result is a triple of input/output connected respectively to the standard output, standard input, and standard error of the command.
autoclose : If true (default value), close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
cleanup : If true or unspecified, close the process when either the output or the output is closed. If false, do nothing, in which case you will need to close the process yourself to ensure proper cleanup.
val close_process_in : BatInnerIO.input -> Unix.process_status
Close input opened by Unix.open_process_in, wait for the associated command to terminate, and return its termination status.
Raises Unix_error(EBADF, "close_process_in", "") if the argument is not an input opened by Unix.open_process_in.
val close_process_out : unit BatInnerIO.output -> Unix.process_status
Close output opened by Unix.open_process_out, wait for the associated command to terminate, and return its termination status.
Raises Unix_error(EBADF, "close_process_out", "") if the argument is not an output opened by Unix.open_process_out.
val close_process : BatInnerIO.input * unit BatInnerIO.output -> Unix.process_status
Close input/output opened by Unix.open_process, wait for the associated command to terminate, and return its termination status.
Raises Unix_error(EBADF, "close_process", "") if the argument is not pair of input/output opened by Unix.open_process.
val close_process_full : BatInnerIO.input * unit BatInnerIO.output * BatInnerIO.input ->
       Unix.process_status
Close i/o opened by Unix.open_process_full, wait for the associated command to terminate, and return its termination status.
Raises Unix_error(EBADF, "close_process_full", "") if the argument is not a triple of input/output opened by Unix.open_process_full.

High-level network connection functions

val open_connection : ?autoclose:bool -> Unix.sockaddr -> BatInnerIO.input * unit BatInnerIO.output
Connect to a server at the given address. Return a pair of input/output connected to the server. The connection is closed whenever either the input or the output is closed.

Remember to call Pervasives.flush on the output at the right times to ensure correct synchronization.

autoclose : If true (default value), close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
val shutdown_connection : BatInnerIO.input -> unit
Deprecated.Connections do not require a special function anymore. Use regular function BatIO.close_in for closing connections.
``Shut down'' a connection established with Unix.open_connection; that is, transmit an end-of-file condition to the server reading on the other side of the connection.
val establish_server : ?autoclose:bool ->
       ?cleanup:bool ->
       (BatInnerIO.input -> unit BatInnerIO.output -> unit) -> Unix.sockaddr -> unit
Establish a server on the given address.

establish_server f addr establishes a server on address addr. For each connection on this address, function f is called with two buffered channels connected to the client. A new process is created for each connection. The function Unix.establish_server never returns normally.

autoclose : If true (default value), inputs passed to f close the input automatically once there is no more content to read. Otherwise, the input will be closed according to the usual rules of module BatIO. Barring very specific needs (e.g. using file descriptors as locks), you probably want autoclose to be true.
cleanup : If true or unspecified, close the connection when the input or the output is closed or garbage-collected. If false, do nothing, in which case you will need to shutdown the connection using BatUnix.shutdown_connection to ensure proper cleanup.
val is_directory : string -> bool
is_directory filename returns true if filename refers to a directory (or symlink of a directory

Thread-safety internals

Unless you are attempting to adapt Batteries Included to a new model of concurrency, you probably won't need this.

val lock : BatConcurrent.lock Pervasives.ref
A lock used to synchronize internal operations.

By default, this is BatConcurrent.nolock. However, if you're using a version of Batteries compiled in threaded mode, this uses BatMutex. If you're attempting to use Batteries with another concurrency model, set the lock appropriately.


Obsolete stuff

val in_channel_of_descr : Unix.file_descr -> BatInnerIO.input
Deprecated.use BatUnix.input_of_descr
val out_channel_of_descr : Unix.file_descr -> unit BatInnerIO.output
Deprecated.use BatUnix.output_of_descr.
val descr_of_in_channel : BatInnerIO.input -> Unix.file_descr
Deprecated.use BatUnix.descr_of_input.
val descr_of_out_channel : unit BatInnerIO.output -> Unix.file_descr
Deprecated.use BatUnix.descr_of_output.