Fourth batch

diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt
index 69510ae57afcedbe13334160c6a26c52c42e8d54..8bf3e37f5375584e5c9f4543523a40377e08686f 100644 (file)
--- a/Documentation/technical/api-run-command.txt
+++ b/Documentation/technical/api-run-command.txt
@@ -13,6 +13,10 @@ produces in the caller in order to process it.
 Functions
 ---------
 
+`child_process_init`::
+
+       Initialize a struct child_process variable.
+
 `start_command`::
 
        Start a sub-process. Takes a pointer to a `struct child_process`
@@ -42,6 +46,13 @@ Functions
        The argument dir corresponds the member .dir. The argument env
        corresponds to the member .env.
 
+`child_process_clear`::
+
+       Release the memory associated with the struct child_process.
+       Most users of the run-command API don't need to call this
+       function explicitly because `start_command` invokes it on
+       failure and `finish_command` calls it automatically already.
+
 The functions above do the following:
 
 . If a system call failed, errno is set and -1 is returned. A diagnostic
@@ -96,8 +107,8 @@ command to run in a sub-process.
 
 The caller:
 
-1. allocates and clears (memset(&chld, 0, sizeof(chld));) a
-   struct child_process variable;
+1. allocates and clears (using child_process_init() or
+   CHILD_PROCESS_INIT) a struct child_process variable;
 2. initializes the members;
 3. calls start_command();
 4. processes the data;
@@ -165,6 +176,11 @@ string pointers (NULL terminated) in .env:
 . If the string does not contain '=', it names an environment
   variable that will be removed from the child process's environment.
 
+If the .env member is NULL, `start_command` will point it at the
+.env_array `argv_array` (so you may use one or the other, but not both).
+The memory in .env_array will be cleaned up automatically during
+`finish_command` (or during `start_command` when it is unsuccessful).
+
 To specify a new initial working directory for the sub-process,
 specify it in the .dir member.