1run-command API 2=============== 3 4The run-command API offers a versatile tool to run sub-processes with 5redirected input and output as well as with a modified environment 6and an alternate current directory. 7 8A similar API offers the capability to run a function asynchronously, 9which is primarily used to capture the output that the function 10produces in the caller in order to process it. 11 12 13Functions 14--------- 15 16`child_process_init`:: 17 18 Initialize a struct child_process variable. 19 20`start_command`:: 21 22 Start a sub-process. Takes a pointer to a `struct child_process` 23 that specifies the details and returns pipe FDs (if requested). 24 See below for details. 25 26`finish_command`:: 27 28 Wait for the completion of a sub-process that was started with 29 start_command(). 30 31`run_command`:: 32 33 A convenience function that encapsulates a sequence of 34 start_command() followed by finish_command(). Takes a pointer 35 to a `struct child_process` that specifies the details. 36 37`run_command_v_opt`, `run_command_v_opt_cd_env`:: 38 39 Convenience functions that encapsulate a sequence of 40 start_command() followed by finish_command(). The argument argv 41 specifies the program and its arguments. The argument opt is zero 42 or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, 43 `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE` 44 that correspond to the members .no_stdin, .git_cmd, 45 .stdout_to_stderr, .silent_exec_failure of `struct child_process`. 46 The argument dir corresponds the member .dir. The argument env 47 corresponds to the member .env. 48 49`child_process_clear`:: 50 51 Release the memory associated with the struct child_process. 52 Most users of the run-command API don't need to call this 53 function explicitly because `start_command` invokes it on 54 failure and `finish_command` calls it automatically already. 55 56The functions above do the following: 57 58. If a system call failed, errno is set and -1 is returned. A diagnostic 59 is printed. 60 61. If the program was not found, then -1 is returned and errno is set to 62 ENOENT; a diagnostic is printed only if .silent_exec_failure is 0. 63 64. Otherwise, the program is run. If it terminates regularly, its exit 65 code is returned. No diagnostic is printed, even if the exit code is 66 non-zero. 67 68. If the program terminated due to a signal, then the return value is the 69 signal number + 128, ie. the same value that a POSIX shell's $? would 70 report. A diagnostic is printed. 71 72 73`start_async`:: 74 75 Run a function asynchronously. Takes a pointer to a `struct 76 async` that specifies the details and returns a set of pipe FDs 77 for communication with the function. See below for details. 78 79`finish_async`:: 80 81 Wait for the completion of an asynchronous function that was 82 started with start_async(). 83 84`run_hook`:: 85 86 Run a hook. 87 The first argument is a pathname to an index file, or NULL 88 if the hook uses the default index file or no index is needed. 89 The second argument is the name of the hook. 90 The further arguments correspond to the hook arguments. 91 The last argument has to be NULL to terminate the arguments list. 92 If the hook does not exist or is not executable, the return 93 value will be zero. 94 If it is executable, the hook will be executed and the exit 95 status of the hook is returned. 96 On execution, .stdout_to_stderr and .no_stdin will be set. 97 (See below.) 98 99 100Data structures 101--------------- 102 103* `struct child_process` 104 105This describes the arguments, redirections, and environment of a 106command to run in a sub-process. 107 108The caller: 109 1101. allocates and clears (using child_process_init() or 111 CHILD_PROCESS_INIT) a struct child_process variable; 1122. initializes the members; 1133. calls start_command(); 1144. processes the data; 1155. closes file descriptors (if necessary; see below); 1166. calls finish_command(). 117 118The .argv member is set up as an array of string pointers (NULL 119terminated), of which .argv[0] is the program name to run (usually 120without a path). If the command to run is a git command, set argv[0] to 121the command name without the 'git-' prefix and set .git_cmd = 1. 122 123Note that the ownership of the memory pointed to by .argv stays with the 124caller, but it should survive until `finish_command` completes. If the 125.argv member is NULL, `start_command` will point it at the .args 126`argv_array` (so you may use one or the other, but you must use exactly 127one). The memory in .args will be cleaned up automatically during 128`finish_command` (or during `start_command` when it is unsuccessful). 129 130The members .in, .out, .err are used to redirect stdin, stdout, 131stderr as follows: 132 133. Specify 0 to request no special redirection. No new file descriptor 134 is allocated. The child process simply inherits the channel from the 135 parent. 136 137. Specify -1 to have a pipe allocated; start_command() replaces -1 138 by the pipe FD in the following way: 139 140 .in: Returns the writable pipe end into which the caller writes; 141 the readable end of the pipe becomes the child's stdin. 142 143 .out, .err: Returns the readable pipe end from which the caller 144 reads; the writable end of the pipe end becomes child's 145 stdout/stderr. 146 147 The caller of start_command() must close the so returned FDs 148 after it has completed reading from/writing to it! 149 150. Specify a file descriptor > 0 to be used by the child: 151 152 .in: The FD must be readable; it becomes child's stdin. 153 .out: The FD must be writable; it becomes child's stdout. 154 .err: The FD must be writable; it becomes child's stderr. 155 156 The specified FD is closed by start_command(), even if it fails to 157 run the sub-process! 158 159. Special forms of redirection are available by setting these members 160 to 1: 161 162 .no_stdin, .no_stdout, .no_stderr: The respective channel is 163 redirected to /dev/null. 164 165 .stdout_to_stderr: stdout of the child is redirected to its 166 stderr. This happens after stderr is itself redirected. 167 So stdout will follow stderr to wherever it is 168 redirected. 169 170To modify the environment of the sub-process, specify an array of 171string pointers (NULL terminated) in .env: 172 173. If the string is of the form "VAR=value", i.e. it contains '=' 174 the variable is added to the child process's environment. 175 176. If the string does not contain '=', it names an environment 177 variable that will be removed from the child process's environment. 178 179If the .env member is NULL, `start_command` will point it at the 180.env_array `argv_array` (so you may use one or the other, but not both). 181The memory in .env_array will be cleaned up automatically during 182`finish_command` (or during `start_command` when it is unsuccessful). 183 184To specify a new initial working directory for the sub-process, 185specify it in the .dir member. 186 187If the program cannot be found, the functions return -1 and set 188errno to ENOENT. Normally, an error message is printed, but if 189.silent_exec_failure is set to 1, no message is printed for this 190special error condition. 191 192 193* `struct async` 194 195This describes a function to run asynchronously, whose purpose is 196to produce output that the caller reads. 197 198The caller: 199 2001. allocates and clears (memset(&asy, 0, sizeof(asy));) a 201 struct async variable; 2022. initializes .proc and .data; 2033. calls start_async(); 2044. processes communicates with proc through .in and .out; 2055. closes .in and .out; 2066. calls finish_async(). 207 208The members .in, .out are used to provide a set of fd's for 209communication between the caller and the callee as follows: 210 211. Specify 0 to have no file descriptor passed. The callee will 212 receive -1 in the corresponding argument. 213 214. Specify < 0 to have a pipe allocated; start_async() replaces 215 with the pipe FD in the following way: 216 217 .in: Returns the writable pipe end into which the caller 218 writes; the readable end of the pipe becomes the function's 219 in argument. 220 221 .out: Returns the readable pipe end from which the caller 222 reads; the writable end of the pipe becomes the function's 223 out argument. 224 225 The caller of start_async() must close the returned FDs after it 226 has completed reading from/writing from them. 227 228. Specify a file descriptor > 0 to be used by the function: 229 230 .in: The FD must be readable; it becomes the function's in. 231 .out: The FD must be writable; it becomes the function's out. 232 233 The specified FD is closed by start_async(), even if it fails to 234 run the function. 235 236The function pointer in .proc has the following signature: 237 238 int proc(int in, int out, void *data); 239 240. in, out specifies a set of file descriptors to which the function 241 must read/write the data that it needs/produces. The function 242 *must* close these descriptors before it returns. A descriptor 243 may be -1 if the caller did not configure a descriptor for that 244 direction. 245 246. data is the value that the caller has specified in the .data member 247 of struct async. 248 249. The return value of the function is 0 on success and non-zero 250 on failure. If the function indicates failure, finish_async() will 251 report failure as well. 252 253 254There are serious restrictions on what the asynchronous function can do 255because this facility is implemented by a thread in the same address 256space on most platforms (when pthreads is available), but by a pipe to 257a forked process otherwise: 258 259. It cannot change the program's state (global variables, environment, 260 etc.) in a way that the caller notices; in other words, .in and .out 261 are the only communication channels to the caller. 262 263. It must not change the program's state that the caller of the 264 facility also uses.