api-run-command.txt: describe error behavior of run_command functions
Signed-off-by: Johannes Sixt <j6t@kdbg.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johannes Sixt committed
Aug 8, 2009 at 22:44 UTC
0b91322311b649a4b5f9581fec2dca9e1c2da716
1 file changed
+28
-3
Documentation/technical/api-run-command.txt
+28
-3
@@ -35,12 +35,32 @@ Functions
35
Convenience functions that encapsulate a sequence of
36
start_command() followed by finish_command(). The argument argv
37
specifies the program and its arguments. The argument opt is zero
38
- or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or
39
- `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members
40
- .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`.
38
+ or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`,
39
+ `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE`
40
+ that correspond to the members .no_stdin, .git_cmd,
41
+ .stdout_to_stderr, .silent_exec_failure of `struct child_process`.
42
The argument dir corresponds the member .dir. The argument env
43
corresponds to the member .env.
44
45
+The functions above do the following:
46
+
47
+. If a system call failed, errno is set and -1 is returned. A diagnostic
48
+ is printed.
49
+
50
+. If the program was not found, then -1 is returned and errno is set to
51
+ ENOENT; a diagnostic is printed only if .silent_exec_failure is 0.
52
+
53
+. Otherwise, the program is run. If it terminates regularly, its exit
54
+ code is returned. No diagnistic is printed, even if the exit code is
55
+ non-zero.
56
+
57
+. If the program terminated due to a signal, then the return value is the
58
+ signal number - 128, ie. it is negative and so indicates an unusual
59
+ condition; a diagnostic is printed. This return value can be passed to
60
+ exit(2), which will report the same code to the parent process that a
61
+ POSIX shell's $? would report for a program that died from the signal.
62
+
63
+
64
`start_async`::
65
66
Run a function asynchronously. Takes a pointer to a `struct
@@ -143,6 +163,11 @@ string pointers (NULL terminated) in .env:
163
To specify a new initial working directory for the sub-process,
164
specify it in the .dir member.
165
166
+If the program cannot be found, the functions return -1 and set
167
+errno to ENOENT. Normally, an error message is printed, but if
168
+.silent_exec_failure is set to 1, no message is printed for this
169
+special error condition.
170
+
171
172
* `struct async`
173