BatUnix

# 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.

###### Small tools

    val is_directory : string -> bool

`is_directory filename` returns true if `filename` refers to a directory (or symlink of a directory)

    val restart_on_EINTR : ('a -> 'b) -> 'a -> 'b

`restart_on_EINTR f x` invokes `f` on `x` repetedly until the function returns a value or raise another exception than EINTR.

###### 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`.