Tool search
val find_tool : ?search:Fpath.t list -> Cmd.tool -> (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
.
- If
tool
has a single path segment. Thetool
file is searched, in list order, for the first matching executable file in the directories ofsearch
. These directories default to those that result from parsingPATH
withFpath.list_of_search_path
. - If
tool
has multiple path segments the corresponding file is simply tested for existence and executability.Ok (Some tool)
is returned if that is case andOk None
otherwise.
val must_find_tool : ?search:Fpath.t list -> Cmd.tool -> (Fpath.t, string) Stdlib.result
must_find_tool
is like find_tool
except it errors if Ok None
is returned.
val find_first_tool : ?search:Fpath.t list -> Cmd.tool list -> (Fpath.t option, string) Stdlib.result
find_first_tool
is the first tool that can be found in the list with find_tool
.
val find : ?search:Fpath.t list -> Cmd.t -> (Cmd.t option, string) Stdlib.result
find ~search cmd
resolves cmd
's tool as find_tool
does.
val must_find : ?search:Fpath.t list -> Cmd.t -> (Cmd.t, string) Stdlib.result
must_find ~search cmd
resolves cmd
's tool as must_find_tool
does.
val find_first : ?search:Fpath.t list -> Cmd.t list -> (Cmd.t option, string) Stdlib.result
find_first ~search cmds
resolves cmds
's Cmd
.toos as find_first_tool
does.
Process completion statuses
pp_cmd_status
is a formatter for command process exit statuses.
Process standard inputs
val in_string : string -> stdi
in_string s
is a standard input that reads the string s
.
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
out_file ~force ~make_path file
is a standard output that writes to file file
.
- If
make_path
istrue
and the parent directory offile
does not exist the whole path to the parent is created as needed with permission0o755
(readable and traversable by everyone, writable by the user). - If
force
istrue
andfile
exists at call time as a regular file it tries to overwrite it, in all other cases the function errors iffile
exists. mode
are the permissions of the written file; they default to0o644
, readable by everyone, writable by the user.
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
val run_status : ?env:Env.assignments -> ?cwd:Fpath.t -> ?stdin:stdi -> ?stdout:stdo -> ?stderr:stdo -> 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
.
env
defaults toEnv.current_assignments
()
cwd
defaults toDir:cwd
()
stdin
defaults toin_stdin
stdout
defaults toout_stdout
stderr
defaults toout_stderr
val run_status_out : ?env:Env.assignments -> ?cwd:Fpath.t -> ?stdin:stdi -> ?stderr:[ `Stdo of stdo | `Out ] -> trim:bool -> Cmd.t -> (status * string, string) Stdlib.result
run_status_out
is like run_status
except stdout
is read from the process to a string. The string is String.trim
ed 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) Stdlib.result
run
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) Stdlib.result
run
is run_status_out
with non-`Exited 0
statuses turned into errors via pp_cmd_status
.
Non-blocking
val pid_to_int : pid -> int
pid_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) 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 Env.current_assignments
()
, cwd
to Dir
.current
()
, stdin
to in_stdin
, stdout
to out_stdout
and stderr
to 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 option -> Env.assignments option -> cwd:Fpath.t option -> Cmd.t -> unit
The 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_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 spawn_tracer_nop
.
val set_spawn_tracer : spawn_tracer -> unit
set_tracer t
sets the current spawn tracer to t
.
Executing files
val execv : ?env:Env.assignments -> ?cwd:Fpath.t -> Fpath.t -> 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 B00
.OS.Env.current_assignments ()
, cwd
to Dir
.current ()
.