path: root/Documentation/technical/api-run-command.txt
AgeCommit message (Collapse)Author
2015-11-02run-command: factor out child_process_clear()René Scharfe
Avoid duplication by moving the code to release allocated memory for arguments and environment to its own function, child_process_clear(). Export it to provide a counterpart to child_process_init(). Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2014-10-31Merge branch 'rs/child-process-init'Junio C Hamano
* rs/child-process-init: api-run-command: add missing list item marker
2014-10-28api-run-command: add missing list item markerRené Scharfe
Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2014-10-19run-command: add env_array, an optional argv_array for envRené Scharfe
Similar to args, add a struct argv_array member to struct child_process that simplifies specifying the environment for children. It is freed automatically by finish_command() or if start_command() encounters an error. Suggested-by: Jeff King <> Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2014-08-20run-command: introduce child_process_init()René Scharfe
Add a helper function for initializing those struct child_process variables for which the macro CHILD_PROCESS_INIT can't be used. Suggested-by: Jeff King <> Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2014-08-20run-command: introduce CHILD_PROCESS_INITRené Scharfe
Most struct child_process variables are cleared using memset first after declaration. Provide a macro, CHILD_PROCESS_INIT, that can be used to initialize them statically instead. That's shorter, doesn't require a function call and is slightly more readable (especially given that we already have STRBUF_INIT, ARGV_ARRAY_INIT etc.). Helped-by: Johannes Sixt <> Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2014-05-15run-command: store an optional argv_arrayJeff King
All child_process structs need to point to an argv. For flexibility, we do not mandate the use of a dynamic argv_array. However, because the child_process does not own the memory, this can make memory management with a separate argv_array difficult. For example, if a function calls start_command but not finish_command, the argv memory must persist. The code needs to arrange to clean up the argv_array separately after finish_command runs. As a result, some of our code in this situation just leaks the memory. To help such cases, this patch adds a built-in argv_array to the child_process, which gets cleaned up automatically (both in finish_command and when start_command fails). Callers may use it if they choose, but can continue to use the raw argv if they wish. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2013-01-06run-command: encode signal death as a positive integerJeff King
When a sub-command dies due to a signal, we encode the signal number into the numeric exit status as "signal - 128". This is easy to identify (versus a regular positive error code), and when cast to an unsigned integer (e.g., by feeding it to exit), matches what a POSIX shell would return when reporting a signal death in $? or through its own exit code. So we have a negative value inside the code, but once it passes across an exit() barrier, it looks positive (and any code we receive from a sub-shell will have the positive form). E.g., death by SIGPIPE (signal 13) will look like -115 to us in inside git, but will end up as 141 when we call exit() with it. And a program killed by SIGPIPE but run via the shell will come to us with an exit code of 141. Unfortunately, this means that when the "use_shell" option is set, we need to be on the lookout for _both_ forms. We might or might not have actually invoked the shell (because we optimize out some useless shell calls). If we didn't invoke the shell, we will will see the sub-process's signal death directly, and run-command converts it into a negative value. But if we did invoke the shell, we will see the shell's 128+signal exit status. To be thorough, we would need to check both, or cast the value to an unsigned char (after checking that it is not -1, which is a magic error value). Fortunately, most callsites do not care at all whether the exit was from a code or from a signal; they merely check for a non-zero status, and sometimes propagate the error via exit(). But for the callers that do care, we can make life slightly easier by just using the consistent positive form. This actually fixes two minor bugs: 1. In launch_editor, we check whether the editor died from SIGINT or SIGQUIT. But we checked only the negative form, meaning that we would fail to notice a signal death exit code which was propagated through the shell. 2. In handle_alias, we assume that a negative return value from run_command means that errno tells us something interesting (like a fork failure, or ENOENT). Otherwise, we simply propagate the exit code. Negative signal death codes confuse us, and we print a useless "unable to run alias 'foo': Success" message. By encoding signal deaths using the positive form, the existing code just propagates it as it would a normal non-zero exit code. The downside is that callers of run_command can no longer differentiate between a signal received directly by the sub-process, and one propagated. However, no caller currently cares, and since we already optimize out some calls to the shell under the hood, that distinction is not something that should be relied upon by callers. Fix the same logic in t/test-terminal.perl for consistency [jc: raised by Jonathan in the discussion]. Signed-off-by: Jeff King <> Acked-by: Johannes Sixt <> Reviewed-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-03-10Enable threaded async procedures whenever pthreads is availableJohannes Sixt
Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2010-02-21Merge branch 'sp/push-sideband'Junio C Hamano
* sp/push-sideband: receive-pack: Send internal errors over side-band #2 t5401: Use a bare repository for the remote peer receive-pack: Send hook output over side band #2 receive-pack: Wrap status reports inside side-band-64k receive-pack: Refactor how capabilities are shown to the client send-pack: demultiplex a sideband stream with status data run-command: support custom fd-set in async run-command: Allow stderr to be a caller supplied pipe
2010-02-06run-command: support custom fd-set in asyncErik Faye-Lund
This patch adds the possibility to supply a set of non-0 file descriptors for async process communication instead of the default-created pipe. Additionally, we now support bi-directional communiction with the async procedure, by giving the async function both read and write file descriptors. To retain compatiblity and similar "API feel" with start_command, we require start_async callers to set .out = -1 to get a readable file descriptor. If either of .in or .out is 0, we supply no file descriptor to the async process. [sp: Note: Erik started this patch, and a huge bulk of it is his work. All bugs were introduced later by Shawn.] Signed-off-by: Erik Faye-Lund <> Signed-off-by: Shawn O. Pearce <> Signed-off-by: Junio C Hamano <>
2010-02-06run-command: Allow stderr to be a caller supplied pipeShawn O. Pearce
Like .out, .err may now be set to a file descriptor > 0, which is a writable pipe/socket/file that the child's stderr will be redirected into. Signed-off-by: Shawn O. Pearce <> Signed-off-by: Junio C Hamano <>
2010-01-31Fix typos in technical documentation.Ralf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2009-08-08api-run-command.txt: describe error behavior of run_command functionsJohannes Sixt
Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2009-01-18run_hook(): allow more than 9 hook argumentsStephan Beyer
This is done using the ALLOC_GROW macro. Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2009-01-18api-run-command.txt: talk about run_hook()Stephan Beyer
Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2008-10-03run-command.c: remove run_command_v_opt_cd()Nanako Shiraishi
This function is not used anywhere. Johannes Sixt <>: > Future callers can use run_command_v_opt_cd_env() instead. Signed-off-by: Nanako Shiraishi <> Signed-off-by: Shawn O. Pearce <>
2008-07-18api-run-command.txt: typofixStephan Beyer
Replace "run_command_v_opt_dir" by "run_command_v_opt_cd". Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2008-06-17run-command documentation: fix "memset()" parameterMiklos Vajna
When initializing the struct async and struct child_process structures, the documentation suggested "clearing" the structure with '0' instead of '\0'. It is enough to use integer zero here. Signed-off-by: Miklos Vajna <> Signed-off-by: Junio C Hamano <>
2008-03-05run-command: Redirect stderr to a pipe before redirecting stdout to stderrChristian Couder
With this patch, in the 'start_command' function after forking we now take care of stderr in the child process before stdout. This way if 'start_command' is called with a 'child_process' argument like this: .err = -1; .stdout_to_stderr = 1; then stderr will be redirected to a pipe before stdout is redirected to stderr. So we can now get the process' stdout from the pipe (as well as its stderr). Earlier such a call would have redirected stdout to stderr before stderr was itself redirected, and therefore stdout would not have followed stderr, which would not have been very useful anyway. Update documentation in 'api-run-command.txt' accordingly. Signed-off-by: Christian Couder <> Acked-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2008-03-03Fix doc typos.Ralf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2008-02-20Technical documentation of the run-command API.Johannes Sixt
Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2007-12-15Start preparing the API documents.Junio C Hamano
Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <>