Up

module Lwt_process

: sig

Process management

This module allows you to spawn processes and communicate with them.

#
type command = string * string array

A command. The first field is the name of the executable and the second is the list of arguments. For example:

          ("ls", [|"ls"; "-l"|])

.

Notes:

  • if the name is the empty string, then the first argument will be used. You should specify a name only if you do not want the executable to be searched in the PATH. On Windows the only way to enable automatic seach in PATH is to pass an empty name.
  • it is possible to ``inline'' an argument, i.e. split it into multiple arguments. To do that prefix it with "\000". For example:
          ("", [|"echo"; "\000foo bar"|])

is the same as:

          ("", [|"echo"; "foo"; "bar"|])

.

#
val shell : string -> command

A command executed with the shell. (with "/bin/sh -c <cmd>" on Unix and "cmd.exe /c <cmd>" on Windows).

All the following functions take an optional argument timeout. If specified, after expiration, the process will be sent a Unix.sigkill signal and channels will be closed.

High-level functions

Redirections

#
type redirection = [
| `Keep
| `Dev_null
| `Close
| `FD_copy of Unix.file_descr
| `FD_move of Unix.file_descr
]

A file descriptor redirection. It describes how standard file descriptors are redirected in the child process.

Note: all optional redirection arguments default to `Keep

Executing

#
val exec : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stdout:redirection -> ?stderr:redirection -> command -> Unix.process_status Lwt.t

Executes the given command and returns its exit status.

Receiving

#
val pread : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> string Lwt.t
#
val pread_chars : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> char Lwt_stream.t
#
val pread_line : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> string Lwt.t
#
val pread_lines : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> string Lwt_stream.t

Sending

#
val pwrite : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> string -> unit Lwt.t
#
val pwrite_chars : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> char Lwt_stream.t -> unit Lwt.t
#
val pwrite_line : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> string -> unit Lwt.t
#
val pwrite_lines : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> string Lwt_stream.t -> unit Lwt.t

Mapping

#
val pmap : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> string -> string Lwt.t
#
val pmap_chars : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> char Lwt_stream.t -> char Lwt_stream.t
#
val pmap_line : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> string -> string Lwt.t
#
val pmap_lines : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> string Lwt_stream.t -> string Lwt_stream.t

Spawning processes

#
type state =
# | Running
(*The process is still running*)
# | Exited of Unix.process_status
(*The process has exited*)

State of a sub-process

#
class process_none : ?timeout:float option -> ?env:string array option -> ?stdin:redirection option -> ?stdout:redirection option -> ?stderr:redirection option -> command ->
#
method pid : int

Pid of the sub-process

#
method state : state

Return the state of the process

#
method kill : int -> unit

kill signum sends signum to the process if it is still running.

#
method terminate : unit

Terminates the process. It is equivalent to kill Sys.sigkill on Unix but also works on Windows (unlike kill).

#
method status : Unix.process_status Lwt.t

Threads which wait for the sub-process to exit then returns its exit status

#
method rusage : Lwt_unix.resource_usage Lwt.t

Threads which wait for the sub-process to exit then returns its resource usages

#
method close : Unix.process_status Lwt.t

Closes the process and returns its exit status. This closes all channels used to communicate with the process

#
val open_process_none : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stdout:redirection -> ?stderr:redirection -> command -> process_none
#
val with_process_none : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stdout:redirection -> ?stderr:redirection -> command -> (process_none -> 'a Lwt.t) -> 'a Lwt.t
#
class process_in : ?timeout:float option -> ?env:string array option -> ?stdin:redirection option -> ?stderr:redirection option -> command ->
inherit process_none
#
method stdout : Lwt_io.input_channel

The standard output of the process

#
val open_process_in : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> process_in
#
val with_process_in : ?timeout:float -> ?env:string array -> ?stdin:redirection -> ?stderr:redirection -> command -> (process_in -> 'a Lwt.t) -> 'a Lwt.t
#
class process_out : ?timeout:float option -> ?env:string array option -> ?stdout:redirection option -> ?stderr:redirection option -> command ->
inherit process_none
#
method stdin : Lwt_io.output_channel

The standard input of the process

#
val open_process_out : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> process_out
#
val with_process_out : ?timeout:float -> ?env:string array -> ?stdout:redirection -> ?stderr:redirection -> command -> (process_out -> 'a Lwt.t) -> 'a Lwt.t
#
class process : ?timeout:float option -> ?env:string array option -> ?stderr:redirection option -> command ->
inherit process_none
#
method stdin : Lwt_io.output_channel
#
method stdout : Lwt_io.input_channel
#
val open_process : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> process
#
val with_process : ?timeout:float -> ?env:string array -> ?stderr:redirection -> command -> (process -> 'a Lwt.t) -> 'a Lwt.t
#
class process_full : ?timeout:float option -> ?env:string array option -> command ->
inherit process_none
#
method stdin : Lwt_io.output_channel
#
method stdout : Lwt_io.input_channel
#
method stderr : Lwt_io.input_channel
#
val open_process_full : ?timeout:float -> ?env:string array -> command -> process_full
#
val with_process_full : ?timeout:float -> ?env:string array -> command -> (process_full -> 'a Lwt.t) -> 'a Lwt.t
end