CA-33440: add ocamldoc to forkhelpers.mli

Signed-off-by: David Scott <dave.scott@eu.citrix.com>

diff --git a/stdext/forkhelpers.mli b/stdext/forkhelpers.mli
index 7bbb86c713649cd881c037e596ccea22051b1afa..2d9d2f12de518f334e6ab15460a30ecccb4cf45d 100644 (file)
--- a/stdext/forkhelpers.mli
+++ b/stdext/forkhelpers.mli
@@ -14,26 +14,48 @@
 (* Functions to safely fork potentially long-running sub-processes without
    leaking file descriptors or accidentally deadlocking the parent process. *)
 
-(* Functions should:
-   1. Arrange to close all fds except the ones they actually want to keep open
-   2. Not access any ocaml library or runtime function which might touch a lock
-   (since that would cause deadlock) *)
-
-(** Standalone wrapper process which safely closes fds before exec()ing another program.
-       Needs the binary /opt/xensource/libexec/closeandexec installed by close-and-exec. *)
+(** [execute_command_get_output cmd args] runs [cmd args] and returns (stdout, stderr)
+       on success (exit 0). On failure this raises [Spawn_internal_error(stderr, stdout, Unix.process_status)]
+*)
+val execute_command_get_output : ?cb_set:(int -> unit) -> ?cb_clear:(unit -> unit) -> string -> string list -> string * string
 
-exception Subprocess_failed of int
-exception Subprocess_killed of int
+(** Thrown by [execute_command_get_output] if the subprocess exits with a non-zero exit code *)
 exception Spawn_internal_error of string * string * Unix.process_status
 
+(** Represents a forked process *)
 type pidty
 
+(** [string_of_pidty p] returns a printable string description of [p] *)
 val string_of_pidty : pidty -> string
 
-(** Safe function which forks a command, closing all fds except a whitelist and
-    having performed some fd operations in the child *)
+(** [getpid p] returns the integer process id *)
+val getpid : pidty -> int
+
+(** Thrown by [safe_close_and_exec] if the process exits with a non-zero exit code. *)
+exception Subprocess_failed of int
+(** Thrown by [safe_close_and_exec] if the process exits due to a signal *)
+exception Subprocess_killed of int
+
+(** [safe_close_and_exec stdin stdout stderr id_to_fd_list cmd args] runs [cmd args]
+       with the optional [stdin], [stdout] and [stderr] file descriptors (or /dev/null if not
+       specified) and with any key from [id_to_fd_list] in [args] replaced by the integer
+       value of the file descriptor in the final process. *)
 val safe_close_and_exec : ?env:string array -> Unix.file_descr option -> Unix.file_descr option -> Unix.file_descr option -> (string * Unix.file_descr) list -> string -> string list -> pidty
 
+(** [waitpid p] returns the (pid, Unix.process_status) *)
+val waitpid : pidty -> (int * Unix.process_status)
+(** [waitpid_nohang p] returns the (pid, Unix.process_status) if the process has already
+       quit or (0, Unix.WEXITTED 0) if the process is still running. *)
+val waitpid_nohang : pidty -> (int * Unix.process_status)
+(** [dontwaitpid p]: signals the caller's desire to never call waitpid. Note that the final
+       process will not persist as a zombie. *)
+val dontwaitpid : pidty -> unit
+(** [waitpid_fail_if_bad_exit p] calls waitpid on [p] and throws [Subprocess_failed x] if the 
+       process exits with non-zero code x and [Subprocess_killed x] if the process is killed by a 
+       signal and exits with non-zero code x. *)
+val waitpid_fail_if_bad_exit : pidty -> unit
+
+
 type 'a result = Success of string * 'a | Failure of string * exn
 
 (** Creates a temporary file and opens it for logging. The fd is passed to the function
@@ -41,14 +63,5 @@ type 'a result = Success of string * 'a | Failure of string * exn
     function 'f' throws an error then the log file contents are read in *)
 val with_logfile_fd : ?delete:bool -> string -> (Unix.file_descr -> 'a) -> 'a result
 
-(*val with_dev_null : (Unix.file_descr -> 'a) -> 'a
-val with_dev_null_read : (Unix.file_descr -> 'a) -> 'a*)
 
-(** Execute a command, return the stdout logging or throw a Spawn_internal_error exception *)
-val execute_command_get_output : ?cb_set:(int -> unit) -> ?cb_clear:(unit -> unit) -> string -> string list -> string * string
 
-val waitpid : pidty -> (int * Unix.process_status)
-val waitpid_nohang : pidty -> (int * Unix.process_status)
-val dontwaitpid : pidty -> unit
-val waitpid_fail_if_bad_exit : pidty -> unit
-val getpid : pidty -> int