Module Subprocess.CoreSource

Here follows the interface defined in the Core module. This module is included in most of the user-facing modules for convenience, so you may stumble across its documentation in several places.

The interface defined here is needed to do almost anything with the library.

We begin with a set of placeholder types which are used to represent handles to the i/o streams of running processes (namely, stdin, stdout and stderr). Since only streams that have pipes in the parent process are really interactive in any way, these non-interactive place holders are used in other cases. Their main function is to provide type-level information about the streams.

Sourcetype stdin
Sourcetype stdout
Sourcetype stderr
Sourcetype channel
Sourcetype devnull
Sourcetype file
Sourcetype append
Sourcetype pipe
Sourceexception Subprocess_error of string

When the library raises, it always raises a Subprocess_error of string.

Sourcemodule Cmd : sig ... end

home of Cmd.t, which is kind of the whole basis of the thing.

Sourcemodule Exit : sig ... end

types for exit status with lots of extra info for fun and profit.

In and Out are I/O wrappers for process streams. It's thanks to these bad boys we can have such verbose types.

Sourcemodule In : sig ... end
Sourcemodule Out : sig ... end
Sourcetype ('stdin, 'stdout, 'stderr) t = {
  1. pid : int;
  2. cmd : ('stdin, 'stdout, 'stderr) Cmd.t;
  3. stdin : 'stdin In.t;
  4. stdout : 'stdout Out.t;
  5. stderr : 'stderr Out.t;
  6. close : ?mode:Unix.wait_flag list -> unit -> Exit.t;
}

The type t represents a process which may still be running. Some of the higher-level functions don't expose it directly, but almost everything else is implemented in terms of this type.

Apply () to the close property to close any managed file descriptors and wait for the process to exit.

Sourceval pp : Format.formatter -> ('stdin, 'stdout, 'stderr) t -> unit

Obligatory pretty printer, for your debugging pleasure.

Sourceval show : ('stdin, 'stdout, 'stderr) t -> string

What follows are some helper functions which fetch pipes to a running process for interactive reading and writting. They shadow channels with the same names in the standard library. Probably a good reason to only open Subprocess within a limited scope.

If you try to use one of these functions to access a stream which isn't a pipe, it's a type error.

Sourceval stdin : (pipe, 'stdout, 'stderr) t -> out_channel
Sourceval stdout : ('stdin, pipe, 'stderr) t -> in_channel
Sourceval stderr : ('stdin, 'stdout, pipe) t -> in_channel
Sourceval wait : ?mode:Unix.wait_flag list -> ('stdin, 'stdout, 'stderr) t -> int * Exit.status

Teeny, tiny, leaky wrapper for Unix.waitpid refer to its documentation

Sourceval poll : ('stdin, 'stdout, 'stderr) t -> Exit.status option

Find out if your process has finished executing.

Sourceval cmd : ?prog:string -> ?env:string list -> ?block:bool -> string list -> (stdin, stdout, stderr) Cmd.t

Helper funtions for constructing Cmd.t. The optional prog argument is mainly for if you don't want your path to be searched for the executable.

env is a list of strings with the format "NAME=value". block may be set to false for non-blocking I/O on pipes. This one setting is used with any pipes which are used for I/O. Remember to catch Sys_blocked_io when doing I/O with any non-blocking pipes.

Both env and block can also be set with combinators.

Sourceval pipe_in : (stdin, 'stdout, 'stderr) Cmd.t -> (pipe, 'stdout, 'stderr) Cmd.t

redirect stdin to a pipe for writing.

Sourceval pipe_out : ('stdin, stdout, 'stderr) Cmd.t -> ('stdin, pipe, 'stderr) Cmd.t

redirect stdout to a pipe for reading.

Sourceval pipe_err : ('stdin, 'stdout, stderr) Cmd.t -> ('stdin, 'stdout, pipe) Cmd.t

redirect stdout to a pipe for writing.

Sourceval channel_in : in_channel -> (stdin, 'stdout, 'stderr) Cmd.t -> (channel, 'stdout, 'stderr) Cmd.t

redirect stdin to an in_channel.

Sourceval channel_out : out_channel -> ('stdin, stdout, 'stderr) Cmd.t -> ('stdin, channel, 'stderr) Cmd.t

redirect stdout to an out_channel.

Sourceval channel_err : out_channel -> ('stdin, 'stdout, stderr) Cmd.t -> ('stdin, 'stdout, channel) Cmd.t

redirect stderr to an out_channel.

Sourceval file_in : string -> (stdin, 'stdout, 'stderr) Cmd.t -> (file, 'stdout, 'stderr) Cmd.t

redirect stdin to an named file. Similar to < in the shell.

Sourceval file_out : string -> ('stdin, stdout, 'stderr) Cmd.t -> ('stdin, file, 'stderr) Cmd.t

redirect stdout to an named file. Similar to > in the shell.

Sourceval file_err : string -> ('stdin, 'stdout, stderr) Cmd.t -> ('stdin, 'stdout, file) Cmd.t

redirect stderr to an named file. Similar to 2> in the shell.

Sourceval append_out : string -> ('stdin, stdout, 'stderr) Cmd.t -> ('stdin, append, 'stderr) Cmd.t

redirect stdout to an named file for appending. Similar to >> in the shell.

Sourceval append_err : string -> ('stdin, 'stdout, stderr) Cmd.t -> ('stdin, 'stdout, append) Cmd.t

redirect stderr to an named file for appending. Similar to 2>> in the shell.

Sourceval devnull_out : ('stdin, stdout, 'stderr) Cmd.t -> ('stdin, devnull, 'stderr) Cmd.t

redirect stdout to /dev/null. similar to > /dev/null in the shell

Sourceval devnull_err : ('stdin, 'stdout, stderr) Cmd.t -> ('stdin, 'stdout, devnull) Cmd.t

redirect stderr to /dev/null. similar to 2> /dev/null in the shell

Sourceval env : string list -> ('stdin, 'stdout, 'stderr) Cmd.t -> ('stdin, 'stdout, 'stderr) Cmd.t

Set additional environment variables. Variables are passed in as a list of strings with the format "NAME=value".

Sourceval no_block : ('stdin, 'stdout, 'stderr) Cmd.t -> ('stdin, 'stdout, 'stderr) Cmd.t

Use non-blocking I/O on any pipes. When doing I/O with any such channel, you must catch Sys_blocked_io in the event no data is ready for reading.