Previous  Up  Next

Module Kwexec

module Kwexec: sig .. end

Functions to execute processes


Author(s): Keith Waclena
exception Signaled of int
exception Stopped of int
val quote : string -> string
quote str: quote str to make it "safe" for use in shell commands.

Forking versions of the standard Unix.execv* functions.

These functions fork before exec'ing, wait on the child process, and return the exit status.

Unlike the Unix.execv* functions, these functions take argv as a list, rather than as an array. Also, these functions use the first element of the argv list as the program to run; you can override this by providing the ?prog parameter.

I provide these functions as alternatives to Sys.command and Unix.system, because I am averse to using the shell (with all it's quoting issues and corresponding security holes) simply to execute a trivial external command.

If, rather than exiting, the child process is terminated by a signal, the Kwexec.Signaled exception is raised; if the child is stopped, the Kwexec.Stopped exception is raised. If the child can't be forked or exec'ed, a Unix.Unix_error exception is raised. If the empty argv list is provided, a Failure exception is raised.

val fexecv : ?prog:string -> string list -> int
fexecv ?prog argv: execute the program in file prog, with the arguments args, and the current process environment. On success, the exit status is returned.
Returns the exit status
prog : name or path of program to exec, if given
argv : process argument list; if prog is not given, the first element of the list is used as the program to exec
val fexecve : ?prog:string -> string list -> string array -> int
fexecve ?prog argv env: execute the program in file prog, with the arguments args, and the given process environment. On success, the exit status is returned.
Returns the exit status
prog : name or path of program to exec, if given
argv : process argument list; if prog is not given, the first element of the list is used as the program to exec
env : the environment for the program
val fexecvp : ?prog:string -> string list -> int
fexecvp ?prog argv: execute the program named prog, with the arguments args, and the current process environment. On success, the exit status is returned. The program is searched for in the PATH.
Returns the exit status
prog : name or path of program to exec, if given
argv : process argument list; if prog is not given, the first element of the list is used as the program to exec
val fexecvpe : ?prog:string -> string list -> string array -> int
fexecvp ?prog argv: execute the program named prog, with the arguments args, and the given process environment. On success, the exit status is returned. The program is searched for in the PATH.
Returns the exit status
prog : name or path of program to exec, if given
argv : process argument list; if prog is not given, the first element of the list is used as the program to exec
env : the environment for the program

Non-shell versions of the Unix.open_process* functions.

Again, I provide these to avoid shell-quoting and security issues.

val open_process_in : ?prog:string ->
       ?env:string array ->
       ?exec:exec ->
       (string -> Pervasives.in_channel -> 'a) -> string list -> 'a
open_process_in ?prog ?env ?exec func argv: run command expressed by argv and feed its stdout to func.

This function runs the given command in parallel with the program. The standard output of the command is redirected to a pipe, which can be read by func via the returned input channel.

Unlike Unix.open_process_in, this function does not use the shell to interpret the command.

prog : name or path of program to exec, if given; else use argv.(0)
env : initial environment for exec = Unix.execve || exec = Unix.execvpe (default: [||])
exec : how to exec argv.(0): one of Execv, Execve, Execvp or Execvpe (default: Execvp)
func : func cmd chan: function invoked to read stdout of process (cmd is a string representing argv)
argv : process argument list; if prog is not given, the first element of the list is used as the program to exec
val open_process : ?read:(?size:int -> Pervasives.in_channel -> string) ->
       (Pervasives.out_channel -> 'a) -> string -> Unix.process_status * string
open_process ?read write cmd: This function runs the given shell command cmd in parallel with the program, redirecting both the standard input and standard output of the command to pipes. It calls write to write data to the command's standard input, and then calls read, which can read the data from the command's standard output; the result of read is returned.

Neither function should close their channels; this is done for you.

Don't forget to quote within your command appropriately!

read : function to read the stdout of cmd (default: Kwio.read)
write : function to write the stdin of cmd