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.
find_tool ~search tool is the file path, if any, to the program executable for the tool specification tool.
tool has a single path segment. The tool file is searched, in list order, for the first matching executable file in the directories of search. These directories default to those that result from parsing PATH with Fpath.list_of_search_path.tool has multiple path segments the corresponding file is simply tested for existence and executability. Ok (Some tool) is returned if that is case and Ok None otherwise.must_find_tool is like find_tool except it errors if Ok None is returned.
find_first_tool is the first tool that can be found in the list with find_tool.
find ~search cmd resolves cmd's tool as find_tool does.
must_find ~search cmd resolves cmd's tool as must_find_tool does.
find_first ~search cmds resolves cmds's Cmd.toos as find_first_tool does.
pp_cmd_status is a formatter for command process exit statuses.
val in_string : string -> stdiin_string s is a standard input that reads the string s.
val in_fd : close:bool -> Unix.file_descr -> stdiin_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 : stdiin_stdin is in_fd ~close:false Unix.stdin, a standard input that reads from the current process standard input.
val in_null : stdiin_null is in_file File.null.
out_file ~force ~make_path file is a standard output that writes to file file.
make_path is true and the parent directory of file does not exist the whole path to the parent is created as needed with permission 0o755 (readable and traversable by everyone, writable by the user).force is true and file exists at call time as a regular file it tries to overwrite it, in all other cases the function errors if file exists.mode are the permissions of the written file; they default to 0o644, readable by everyone, writable by the user.val out_fd : close:bool -> Unix.file_descr -> stdoout_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 : stdoout_stdout is out_fd ~close:false Unix.stdout
val out_stderr : stdoout_stderr is out_fd ~close:false Unix.stderr
val out_null : stdoout_null is out_file File.null
These functions wait for the command to complete before proceeding.
val run_status :
?env:Env.assignments ->
?cwd:Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo ->
Cmd.t ->
(status, string) resultrun_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.
env defaults to Env.current_assignments ()cwd defaults to cwd ()stdin defaults to in_stdinstdout defaults to out_stdoutstderr defaults to out_stderrval run_status_out :
?env:Env.assignments ->
?cwd:Fpath.t ->
?stdin:stdi ->
?stderr:[ `Stdo of stdo | `Out ] ->
trim:bool ->
Cmd.t ->
(status * string, string) resultrun_status_out is like 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:Env.assignments ->
?cwd:Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo ->
Cmd.t ->
(unit, string) resultrun is run_status with non-`Exited 0 statuses turned into errors via pp_cmd_status.
val run_out :
?env:Env.assignments ->
?cwd:Fpath.t ->
?stdin:stdi ->
?stderr:[ `Stdo of stdo | `Out ] ->
trim:bool ->
Cmd.t ->
(string, string) resultrun is run_status_out with non-`Exited 0 statuses turned into errors via pp_cmd_status.
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.
val pid_to_int : pid -> intpid_to_int pid is the system identifier for process identifier pid.
val spawn :
?env:Env.assignments ->
?cwd:Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo ->
Cmd.t ->
(pid, string) resultspawn ~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 Env.current_assignments (), cwd to Dir.current
(), stdin to in_stdin, stdout to out_stdout and stderr to out_stderr.
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.
spawn_wait_status blocks and waits for pid's termination status to become available.
type spawn_tracer =
pid option ->
Env.assignments option ->
cwd:Fpath.t option ->
Cmd.t ->
unitThe type for spawn tracers. Called with each blocking and non-blocking spawned command aswell as execv. The function is given the process identifier of the spawn (or None in case of execv), the environment if different from the program's one, the current working directory if different from the program's one and the actual command.
val spawn_tracer_nop : spawn_tracerspawn_tracer_nop is a spawn tracer that does nothing. This is the initial spawn tracer.
val spawn_tracer : unit -> spawn_tracertracer () is the current spawn tracer. Initially this is spawn_tracer_nop.
val set_spawn_tracer : spawn_tracer -> unitset_tracer t sets the current spawn tracer to t.
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:Env.assignments ->
?cwd:Fpath.t ->
Fpath.t ->
Cmd.t ->
(unit, string) resultexecv ~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 B00.OS.Env.current_assignments (), cwd to Dir.current ().