Module Proc

module Proc: sig .. end

An Ocaml abstraction for UNIX processes. The Proc module takes responsiblity for reaping children and provides access to exit codes through abstract Proc.t objects. (If you need to reap yourself, Proc.don't_autoreap will turn off the Sys.sigchld handler, and Proc.autoreap will turn it back on.)

Because the Proc module is responsible for reaping, it makes exit status available as many times as necessary, though Proc.wait and Proc.status_of_proc.

It's also possible to construct a Proc.t object from a pid (int) even if the process wasn't created using this library. In this case, the library detects whether the process is a child or not. We don't allow waiting on or getting the status of non-child processes, because UNIX doesn't.

Much of this design is due to Cash/Scsh.

Types

exception Not_child

Raised on attempts to get the exit status of a process that isn't a child of the current process

type t

The abstract type of a process representation

type status = Unix.process_status =

`\|`	`WEXITED of int`	`(*`	The process terminated normally by exit; the argument is the return code.	`*)`
`\|`	`WSIGNALED of int`	`(*`	The process was killed by a signal; the argument is the signal number.	`*)`
`\|`	`WSTOPPED of int`	`(*`	The process was stopped by a signal; the argument is the signal number.	`*)`

Alias for Unix.process_status

Process Management

val fork : unit -> t option

Return Some t in the parent and None in the child

val spawn : ?quiet:bool -> (unit -> unit) -> t

Run a thunk in a subprocess, returning its Proc.t. Proc.spawn will not allow control in the subprocess to return to its caller; to this end, it catches all exceptions, printing a message and then exiting with status 2. The optional argument ?quiet (default false) suppresses the message.

val kill : ?raise:bool -> int -> t -> unit

Send a signal to a process. Proc.kill n p sends signal n to process p. The optional argument ?raise (default true) specifies whether to raise an exception if the process doesn't exist or we aren't allowed to kill it.

Raises Unix.Unix_error (see Unix.kill)

val wait : t -> status

Proc.wait proc performs a blocking wait on proc; if the child has already exited, it returns immediately. Unlike Unix.waitpid, Proc.wait may be called multiple times for the same process. If proc is not a child of the calling process, raises Proc.Not_child.

val wait_any : t list -> t

Given a list of Proc.ts, return any one of them that has exited. If one has exited already, it return immediately, but if all are still running, it blocks. Calling Proc.wait_any may reap children other than those in the list.

Raises Not_child if given the empty list or any non-children.

val status_of_proc : t -> status option

Retrieve the status of a process if it has exited; non-blocking. Raises Proc.Not_child if proc is not a child of the calling process.

val is_child : t -> bool

Is a process a child of the calling process?

val pid_of_proc : t -> int

The UNIX process ID associated with proc

val proc_of_pid : int -> t

Find or create a Proc.t associated with a UNIX process. If there is no Proc.t but the process exists, it constructs one. Raises Not_found if there is no process with the given process id, or Invalid_argument "procs_of_pid" if the pid is non-positive.

val procs_of_pid : int -> t list

Returns a list of all Proc.ts with the given process id. There may be more than one if the same process id has been used multiple times (rarely).

val exit_with_status : status -> 'a

Exit with the given exit status. If the status indicates a signal, this function sets the default signal handler and signals the current process.

Autoreaping

val autoreap : unit -> unit

Turn on autoreaping of processes. When set, Shcaml will automatically wait on processes and store their exit status for retrieval by Proc.wait or Proc.status_of_proc.

val don't_autoreap : unit -> unit

Turn off autoreaping of processes. If autoreaping is disabled, Proc.wait and Proc.status_of_proc will still work, but the user is responsible to reap all processes.

Running Programs

val system : string -> status

Run a command and wait for it to exit. Passes the command to the shell for parsing. If the shell cannot be found or run, raises the same exceptions as Unix.execv.

This function delegates to the shell for argument parsing; if you already have a list, use Proc.system_program.

val system_program : ?path:bool -> string -> ?argv0:string -> string list -> status

Run a program with arguments and wait for it to exit. Optional argument ?path (default true) specifies whether to search the path, and ?argv0 (default prog) specifies an alternate value for the new process's argv.(0).

If Unix.execv raises an exception in the child process, Proc.system_program re-raises the exception on the parent process.

This function takes an already-parsed argument list. To have the shell do it, use Proc.system.

val vfork : string -> t

Run a command asynchonously. Like Proc.system, but doesn't wait.

val vfork_program : ?path:bool -> string -> ?argv0:string -> string list -> t

Run a program asynchonously. Like Proc.system_program, but doesn't wait.

val exec : string -> 'a

Replace the current process image with a command. Like Proc.vfork, but doesn't fork.

val exec_program : ?path:bool -> string -> ?argv0:string -> string list -> 'a

Replace the current process image with another. Like Proc.vfork_program, but doesn't fork.

The `execspec` Record.

type execspec = {

`path : bool option;`	`(*`	An Ocaml abstraction for UNIX processes. The `Proc` module takes responsiblity for reaping children and provides access to exit codes through abstract `Proc.t` objects. (If you need to reap yourself, `Proc.don't_autoreap` will turn off the `Sys.sigchld` handler, and `Proc.autoreap` will turn it back on.) Because the `Proc` module is responsible for reaping, it makes exit status available as many times as necessary, though `Proc.wait` and `Proc.status_of_proc`. It's also possible to construct a `Proc.t` object from a pid (`int`) even if the process wasn't created using this library. In this case, the library detects whether the process is a child or not. We don't allow waiting on or getting the status of non-child processes, because UNIX doesn't. Much of this design is due to Cash/Scsh.	`*)`
`program : string;`	`(*`	An Ocaml abstraction for UNIX processes. The `Proc` module takes responsiblity for reaping children and provides access to exit codes through abstract `Proc.t` objects. (If you need to reap yourself, `Proc.don't_autoreap` will turn off the `Sys.sigchld` handler, and `Proc.autoreap` will turn it back on.) Because the `Proc` module is responsible for reaping, it makes exit status available as many times as necessary, though `Proc.wait` and `Proc.status_of_proc`. It's also possible to construct a `Proc.t` object from a pid (`int`) even if the process wasn't created using this library. In this case, the library detects whether the process is a child or not. We don't allow waiting on or getting the status of non-child processes, because UNIX doesn't. Much of this design is due to Cash/Scsh.	`*)`
`argv0 : string option;`	`(*`	An Ocaml abstraction for UNIX processes. The `Proc` module takes responsiblity for reaping children and provides access to exit codes through abstract `Proc.t` objects. (If you need to reap yourself, `Proc.don't_autoreap` will turn off the `Sys.sigchld` handler, and `Proc.autoreap` will turn it back on.) Because the `Proc` module is responsible for reaping, it makes exit status available as many times as necessary, though `Proc.wait` and `Proc.status_of_proc`. It's also possible to construct a `Proc.t` object from a pid (`int`) even if the process wasn't created using this library. In this case, the library detects whether the process is a child or not. We don't allow waiting on or getting the status of non-child processes, because UNIX doesn't. Much of this design is due to Cash/Scsh.	`*)`
`args : string list;`	`(*`	An Ocaml abstraction for UNIX processes. The `Proc` module takes responsiblity for reaping children and provides access to exit codes through abstract `Proc.t` objects. (If you need to reap yourself, `Proc.don't_autoreap` will turn off the `Sys.sigchld` handler, and `Proc.autoreap` will turn it back on.) Because the `Proc` module is responsible for reaping, it makes exit status available as many times as necessary, though `Proc.wait` and `Proc.status_of_proc`. It's also possible to construct a `Proc.t` object from a pid (`int`) even if the process wasn't created using this library. In this case, the library detects whether the process is a child or not. We don't allow waiting on or getting the status of non-child processes, because UNIX doesn't. Much of this design is due to Cash/Scsh.	`*)`

}

Several Shcaml functions (such as Proc.exec_program and Proc.system_program) take the same arguments to specify a program to execute. It's sometimes helpful to package these arguments in a record and pass them to such a function later.

val execspec : ?path:bool -> string -> ?argv0:string -> string list -> execspec

Constructs an Proc.execspec, given the same arguments as Proc.exec_program.

val with_execspec : execspec ->
       (?path:bool -> string -> ?argv0:string -> string list -> 'a) -> 'a

Call a function with a given Proc.execspec. For example, Proc.with_execspec (Proc.execspec ~path program ~argv0 args) f calls f ~path program ~argv0 args.