Functions
---------
+`child_process_init`::
+
+ Initialize a struct child_process variable.
+
`start_command`::
Start a sub-process. Takes a pointer to a `struct child_process`
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
non-zero.
. If the program terminated due to a signal, then the return value is the
- signal number - 128, ie. it is negative and so indicates an unusual
- condition; a diagnostic is printed. This return value can be passed to
- exit(2), which will report the same code to the parent process that a
- POSIX shell's $? would report for a program that died from the signal.
+ signal number + 128, ie. the same value that a POSIX shell's $? would
+ report. A diagnostic is printed.
`start_async`::
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;
without a path). If the command to run is a git command, set argv[0] to
the command name without the 'git-' prefix and set .git_cmd = 1.
+Note that the ownership of the memory pointed to by .argv stays with the
+caller, but it should survive until `finish_command` completes. If the
+.argv member is NULL, `start_command` will point it at the .args
+`argv_array` (so you may use one or the other, but you must use exactly
+one). The memory in .args will be cleaned up automatically during
+`finish_command` (or during `start_command` when it is unsuccessful).
+
The members .in, .out, .err are used to redirect stdin, stdout,
stderr as follows:
. 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.
There are serious restrictions on what the asynchronous function can do
-because this facility is implemented by a pipe to a forked process on
-UNIX, but by a thread in the same address space on Windows:
+because this facility is implemented by a thread in the same address
+space on most platforms (when pthreads is available), but by a pipe to
+a forked process otherwise:
. It cannot change the program's state (global variables, environment,
etc.) in a way that the caller notices; in other words, .in and .out