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