Module B0_std.Os.Cmd

module Cmd: sig .. end

Executing commands.


Portability. In order to maximize portability no .exe suffix should be added to executable names on Windows, tool search adds the suffix during the tool search procedure.

val find_tool : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.tool -> (B0_std.Fpath.t option, string) Stdlib.result

find_tool ~search tool is the file path, if any, to the program executable for the tool specification tool.

val must_find_tool : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.tool -> (B0_std.Fpath.t, string) Stdlib.result

must_find_tool is like B0_std.Os.Cmd.find_tool except it errors if Ok None is returned.

val find_first_tool : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.tool list -> (B0_std.Fpath.t option, string) Stdlib.result

find_first_tool is the first tool that can be found in the list with B0_std.Os.Cmd.find_tool.

val find : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.t -> (B0_std.Cmd.t option, string) Stdlib.result

find ~search cmd resolves cmd's tool as B0_std.Os.Cmd.find_tool does.

val must_find : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.t -> (B0_std.Cmd.t, string) Stdlib.result

must_find ~search cmd resolves cmd's tool as B0_std.Os.Cmd.must_find_tool does.

val find_first : ?search:B0_std.Fpath.t list ->
B0_std.Cmd.t list -> (B0_std.Cmd.t option, string) Stdlib.result

find_first ~search cmds resolves cmds's Cmd.toos as B0_std.Os.Cmd.find_first_tool does.

Process completion statuses

type status = [ `Exited of int | `Signaled of int ] 

The type for process exit statuses.

val pp_status : status B0_std.Fmt.t

pp_status is a formatter for process exit statuses.

val pp_cmd_status : (B0_std.Cmd.t * status) B0_std.Fmt.t

pp_cmd_status is a formatter for command process exit statuses.

Process standard inputs

type stdi 

The type for representing the standard input of a process.

val in_string : string -> stdi

in_string s is a standard input that reads the string s.

val in_file : B0_std.Fpath.t -> stdi

in_file f is a standard input that reads from file f.

val in_fd : close:bool -> Unix.file_descr -> stdi

in_fd ~close fd is a standard input that reads from file descriptor fd. If close is true, fd is closed after the process is spawn.

val in_stdin : stdi

in_stdin is in_fd ~close:false Unix.stdin, a standard input that reads from the current process standard input.

val in_null : stdi

in_null is in_file File.null.

Process standard outputs

type stdo 

The type for representing the standard output of a process.

val out_file : B0_std.Fpath.t -> stdo

out_file f is a standard output that writes to file f.

val out_fd : close:bool -> Unix.file_descr -> stdo

out_fd ~close fd is a standard output that writes to file descriptor fd. If close is true, fd is closed after the process spawn.

val out_stdout : stdo

out_stdout is out_fd ~close:false Unix.stdout

val out_stderr : stdo

out_stderr is out_fd ~close:false Unix.stderr

val out_null : stdo

out_null is out_file File.null

Command execution

Blocking

These functions wait for the command to complete before proceeding.

val run_status : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo ->
B0_std.Cmd.t -> (status, string) Stdlib.result

run_status ~env ~cwd ~stdin ~stdout ~stderr cmd runs and waits for the completion of cmd in environment env with current directory cwd and standard IO connections stdin, stdout and stderr.

.

val run_status_out : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
?stdin:stdi ->
?stderr:[ `Out | `Stdo of stdo ] ->
?trim:bool ->
B0_std.Cmd.t -> (status * string, string) Stdlib.result

run_status_out is like B0_std.Os.Cmd.run_status except stdout is read from the process to a string. The string is String.trimed if trim is true (default). If stderr is `Out the process' stderr is redirected to stdout and thus read back in the string aswell.

val run : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo -> B0_std.Cmd.t -> (unit, string) Stdlib.result

run is B0_std.Os.Cmd.run_status with non-`Exited 0 statuses turned into errors via B0_std.Os.Cmd.pp_cmd_status.

val run_out : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
?stdin:stdi ->
?stderr:[ `Out | `Stdo of stdo ] ->
?trim:bool -> B0_std.Cmd.t -> (string, string) Stdlib.result

run is B0_std.Os.Cmd.run_status_out with non-`Exited 0 statuses turned into errors via B0_std.Os.Cmd.pp_cmd_status.

Non-blocking

Note. In contrast to waitpid(2) the following API does not allow to collect any child process completion. There are two reasons: first this is not supported on Windows, second this is anti-modular.

type pid 

The type for process identifiers.

val pid_to_int : pid -> int

pid_to_int pid is the system identifier for process identifier pid.

val spawn : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo ->
B0_std.Cmd.t -> (pid, string) Stdlib.result

spawn ~env ~cwd ~stdin ~stdout ~stderr cmd spawns command cmd in environment env with current directory cwd and standard IO connections stdin, stdout and stderr. env defaults to B0_std.Os.Env.current_assignments (), cwd to Dir.current
        ()
, stdin to B0_std.Os.Cmd.in_stdin, stdout to B0_std.Os.Cmd.out_stdout and stderr to B0_std.Os.Cmd.out_stderr.

val spawn_poll_status : pid -> (status option, string) Stdlib.result

spawn_poll_status pid tries to collect the exit status of command spawn pid. If block is false, Ok None is immediately returned if pid has not terinated yet.

val spawn_wait_status : pid -> (status, string) Stdlib.result

spawn_wait_status blocks and waits for pid's termination status to become available.

Tracing

type spawn_tracer = pid ->
B0_std.Os.Env.assignments option ->
cwd:B0_std.Fpath.t option -> B0_std.Cmd.t -> unit

The type for spawn tracers. Called with each blocking and non-blocking spawned command. The function is given the process identifier of the spawn, the environment if different from the program's one, the current working directory if different from the program's one and the acctual command.

val spawn_tracer_nop : spawn_tracer

spawn_tracer_nop is a spawn tracer that does nothing. This is the initial spawn tracer.

val spawn_tracer : unit -> spawn_tracer

tracer () is the current spawn tracer. Initially this is B0_std.Os.Cmd.spawn_tracer_nop.

val set_spawn_tracer : spawn_tracer -> unit

set_tracer t sets the current spawn tracer to t.

Executing files

Windows. On Windows a program executing an execv* function yields back control to the terminal as soon as the child starts (vs. ends on POSIX). This entails all sorts of unwanted behaviours. To workaround this, the following function executes, on Windows, the file as a spawned child process which is waited on for completion via waitpid(2). Once the child process has terminated the calling process is immediately exited with the status of the child.

val execv : ?env:B0_std.Os.Env.assignments ->
?cwd:B0_std.Fpath.t ->
B0_std.Fpath.t -> B0_std.Cmd.t -> (unit, string) Stdlib.result

execv ~env ~cwd f argv executes file f as a new process in environment env with args as the Sys.argv of this process (in particular Sys.argv.(0) is the name of the program not the first argument to the program). The function only recturns in case of error. env defaults to B0.OS.Env.current_assignments (), cwd to Dir.current ().