Module Subprocess.Core

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.

type stdin
type stdout
type stderr
type channel
type devnull
type file
type append
type pipe
exception Subprocess_error of string

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

module Cmd : sig ... end

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

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

module In : sig ... end
module Out : sig ... end
type ('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.

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

Obligatory pretty printer, for your debugging pleasure.

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

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

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

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

Find out if your process has finished executing.

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

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

redirect stdin to a pipe for writing.

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

redirect stdout to a pipe for reading.

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

redirect stdout to a pipe for writing.

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

redirect stdin to an in_channel.

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

redirect stdout to an out_channel.

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

redirect stderr to an out_channel.

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

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

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

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

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

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

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

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

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

val 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

val 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".

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