Module Channel

module Channel: sig .. end

Generalized channels and file descriptor manipulation.

Types

Channel Types

type descr = Unix.file_descr

The abstract type for UNIX file descriptors.

type any_channel = [ `InChannel of Pervasives.in_channel | `OutChannel of Pervasives.out_channel ]

Union of in_channel and out_channel. Returned by Channel.open_thunk, Channel.open_command, and Channel.open_program.

type gen_in_channel = [ `InChannel of Pervasives.in_channel
       | `InDescr of descr
       | `InFd of int ]

Generalized input channels. Union of buffered in_channel and UNIX file descriptors, both abstract and as ints.

type gen_out_channel = [ `OutChannel of Pervasives.out_channel
       | `OutDescr of descr
       | `OutFd of int ]

Generalized output channels. Union of buffered out_channel and UNIX file descriptors, both abstract and as ints.

type gen_channel = [ `InChannel of Pervasives.in_channel
       | `InDescr of descr
       | `InFd of int
       | `OutChannel of Pervasives.out_channel
       | `OutDescr of descr
       | `OutFd of int ]

Generalized channels. Union of Channel.gen_in_channel and Channel.gen_out_channel.

Dup Source Types

type dup_in_source = [ `Close
       | `Filename of string
       | `InChannel of Pervasives.in_channel
       | `InDescr of descr
       | `InFd of int
       | `Null ]

Sources for input dup operations.

Channel.dup2 (`Filename s, gen) opens the file s on generalized channel gen.
Channel.dup2 (`Close, gen) closes gen.
Channel.dup2 (`Null, gen) opens /dev/null for input on gen.

type dup_out_source = [ `Close
       | `Filename of string
       | `Filespec of string * clobber_spec
       | `Null
       | `OutChannel of Pervasives.out_channel
       | `OutDescr of descr
       | `OutFd of int ]

Sources for output dup operations.

`Filespec allows specifying how an output file is to be opened according to Channel.clobber_spec.
The other constructors are as for Channel.dup_in_source, except that `Filename uses Channel.clobber as its open mode.

type clobber_spec = [ `Append | `AppendOnly | `Clobber | `NoClobber ]

File open modes for Channel.dup_out_source.

`Clobber opens the file and truncates it if it exists.
`NoClobber fails if the file exists.
`Append opens the file for appending and creates it if it doesn't exist.
`AppendOnly opens the file for appending if it exists and fails otherwise.

type dup_source = [ `Close
       | `Filename of string
       | `Filespec of string * clobber_spec
       | `InChannel of Pervasives.in_channel
       | `InDescr of descr
       | `InFd of int
       | `Null
       | `OutChannel of Pervasives.out_channel
       | `OutDescr of descr
       | `OutFd of int ]

Union of input and output dup sources.

Common Argument Types

type dup_spec = (dup_source * gen_channel) list

A list of dups (either direction).

type pipe_spec = gen_channel list

A list of channels to connect to pipes.

type procref = Proc.t option Pervasives.ref

A cell in which to stash a Proc.t. Used as an out-parameter by functions that fork.

Values

Opening and Closing

val clobber : clobber_spec Pervasives.ref

The default Channel.clobber_spec for when Channel.dup2 opens a file for output.

val descr_of_gen : gen_channel -> descr

Get the Channel.descr underlying a generalized channel. Note that if the channel is a managed in_channel or out_channel, the descriptor may be closed when the channel is collected.

val descr_of_fd : int -> descr

The abstract file descriptor of a concrete integer.

val fd_of_descr : descr -> int

The concrete integer of an abstract file descriptor.

val open_file_in : string -> Pervasives.in_channel

Open a file for input. Attaches a finalizer to close the channel.

val open_file_out : string -> Pervasives.out_channel

Open a file for output. Attaches a finalizer to close the channel.

val null_in : unit -> Pervasives.in_channel

Open a /dev/null for input. Attaches a finalizer.

val null_out : unit -> Pervasives.out_channel

Open a /dev/null for output. Attaches a finalizer.

val close_in : Pervasives.in_channel -> unit

Close an input channel.

val close_out : Pervasives.out_channel -> unit

Close an output channel.

val close_gen : gen_channel -> unit

Close a generalized channel.

Dup and Friends

val dup2 : dup_source * gen_channel -> unit

Copy an underlying file descriptor. Channel.dup2 (src, dest) copies src to dest so that future operations on dest use src. If dest is an out_channel, it is flushed first; if dest in an in_channel, its buffer is discarded.

Some sources have special behaviors; see Channel.dup_in_source and Channel.dup_out_source.

val mov2 : dup_source * gen_channel -> unit

Move an underlying file descriptor. This is like Channel.dup2, but the source channel is closed after the operation (unless the source and the destination are the same).

val with_dups : dup_spec -> (unit -> 'a) -> 'a

Perform redirections before a thunk and reverse them afterward.

val dup_in : dup_in_source -> Pervasives.in_channel

Duplicate an in_channel from an input dup source.

val dup_out : dup_out_source -> Pervasives.out_channel

Duplicate an out_channel from an input dup source.

module Dup: sig .. end

Convenience operators for specifying shell-style dups.

Connecting to Other Processes

val open_thunk : ?pipes:pipe_spec ->
       ?dups:dup_spec -> (unit -> unit) -> Proc.t * any_channel list

Spawn a thunk, opening pipes.

Channel.open_thunk ~pipes ~dups

 thunk

forks and calls thunk in the child process. Any given dups are performed in the child before calling the thunk. Channels specified in pipes are connected to pipes, and the other ends are returned in a list, along with the Proc.t of the child process.

The functions Channel.open_thunk_in, Channel.open_thunk_out, Channel.open_thunk2, and Channel.open_thunk3 are special cases. Rather than return the Proc.t, they stash it in the optional argument ?procref.

val open_thunk_in : ?procref:procref ->
       ?dups:dup_spec -> (unit -> unit) -> Pervasives.in_channel

Spawn a thunk and pipe from its stdout.

val open_thunk_out : ?procref:procref ->
       ?dups:dup_spec -> (unit -> unit) -> Pervasives.out_channel

Spawn a thunk and pipe to its stdin.

val open_thunk2 : ?procref:procref ->
       ?dups:dup_spec ->
       (unit -> unit) -> Pervasives.in_channel * Pervasives.in_channel

Spawn a thunk and pipe from its stdout and stderr.

val open_thunk3 : ?procref:procref ->
       ?dups:dup_spec ->
       (unit -> unit) ->
       Pervasives.out_channel * Pervasives.in_channel * Pervasives.in_channel

Spawn a thunk and pipe its stdin, stdout, and stderr.

val open_command : ?pipes:pipe_spec ->
       ?dups:dup_spec -> string -> Proc.t * any_channel list

Spawn a command, opening pipes. Like Channel.open_thunk, but takes a command to run in the shell.

val open_command_in : ?procref:procref ->
       ?dups:dup_spec -> string -> Pervasives.in_channel

Spawn a command and pipe from its stdout.

val open_command_out : ?procref:procref ->
       ?dups:dup_spec -> string -> Pervasives.out_channel

Spawn a command and pipe to its stdin.

val open_command2 : ?procref:procref ->
       ?dups:dup_spec ->
       string -> Pervasives.in_channel * Pervasives.in_channel

Spawn a command and pipe from its stdout and stderr.

val open_command3 : ?procref:procref ->
       ?dups:dup_spec ->
       string ->
       Pervasives.out_channel * Pervasives.in_channel * Pervasives.in_channel

Spawn a command and pipe its stdin, stdout, and stderr.

val open_program : ?pipes:pipe_spec ->
       ?dups:dup_spec ->
       ?path:bool ->
       string -> ?argv0:string -> string list -> Proc.t * any_channel list

Spawn a program with arguments, opening pipes. Like Channel.open_thunk, but takes a program and arguments.

val open_program_in : ?procref:procref ->
       ?dups:dup_spec ->
       ?path:bool -> string -> ?argv0:string -> string list -> Pervasives.in_channel

Spawn a program and pipe from its stdout.

val open_program_out : ?procref:procref ->
       ?dups:dup_spec ->
       ?path:bool ->
       string -> ?argv0:string -> string list -> Pervasives.out_channel

Spawn a program and pipe to its stdin.

val open_program2 : ?procref:procref ->
       ?dups:dup_spec ->
       ?path:bool ->
       string ->
       ?argv0:string -> string list -> Pervasives.in_channel * Pervasives.in_channel

Spawn a program and pipe from its stdout and stderr.

val open_program3 : ?procref:procref ->
       ?dups:dup_spec ->
       ?path:bool ->
       string ->
       ?argv0:string ->
       string list ->
       Pervasives.out_channel * Pervasives.in_channel * Pervasives.in_channel

Spawn a program and pipe its stdin, stdout, and stderr.

Doing Things with Strings

val string_of_channel : Pervasives.in_channel -> string

Read the entire contents a channel into a string.

val string_of_command : ?procref:procref -> string -> string

Collect the output of a command as a string.

val string_of_program : ?procref:procref ->
       ?path:bool -> string -> ?argv0:string -> string list -> string

Collect the output of a program as a string.

val open_string_in : string -> Pervasives.in_channel

Open an in_channel whose contents is a given string.

val with_out_string : (Pervasives.out_channel -> 'a) -> 'a * string

Collect the output of a thunk in a string. Given a thunk, collects everything it prints to stdout and returns the return value of the thunk and the collected output.

Directories

These functions correspond directly to those of the same name in the Unix structure. However, these directory handles are managed by the garbage collected and thus closed if they become unreachable.

type directory

A managed dir handle.

val opendir : string -> directory

Open a managed dir handle. See Unix.opendir.

val closedir : directory -> unit

Manually close a managed dir handle. See Unix.closedir.

val readdir : directory -> string

Read an entry from a managed dir handle. See Unix.readdir.

val rewinddir : directory -> unit

Rewind a managed dir handle. See Unix.rewinddir.

Pretty-printing

val pp_descr : Format.formatter -> descr -> unit

Pretty-printer for Channel.descr.

val pp_in_channel : Format.formatter -> Pervasives.in_channel -> unit

Pretty-printer for in_channel.

val pp_out_channel : Format.formatter -> Pervasives.out_channel -> unit

Pretty-printer for out_channel.