1#ifndef RUN_COMMAND_H 2#define RUN_COMMAND_H 3 4#ifndef NO_PTHREADS 5#include <pthread.h> 6#endif 7 8#include "argv-array.h" 9 10struct child_process { 11 const char **argv; 12 struct argv_array args; 13 struct argv_array env_array; 14 pid_t pid; 15 /* 16 * Using .in, .out, .err: 17 * - Specify 0 for no redirections (child inherits stdin, stdout, 18 * stderr from parent). 19 * - Specify -1 to have a pipe allocated as follows: 20 * .in: returns the writable pipe end; parent writes to it, 21 * the readable pipe end becomes child's stdin 22 * .out, .err: returns the readable pipe end; parent reads from 23 * it, the writable pipe end becomes child's stdout/stderr 24 * The caller of start_command() must close the returned FDs 25 * after it has completed reading from/writing to it! 26 * - Specify > 0 to set a channel to a particular FD as follows: 27 * .in: a readable FD, becomes child's stdin 28 * .out: a writable FD, becomes child's stdout/stderr 29 * .err: a writable FD, becomes child's stderr 30 * The specified FD is closed by start_command(), even in case 31 * of errors! 32 */ 33 int in; 34 int out; 35 int err; 36 const char *dir; 37 const char *const *env; 38 unsigned no_stdin:1; 39 unsigned no_stdout:1; 40 unsigned no_stderr:1; 41 unsigned git_cmd:1; /* if this is to be git sub-command */ 42 unsigned silent_exec_failure:1; 43 unsigned stdout_to_stderr:1; 44 unsigned use_shell:1; 45 unsigned clean_on_exit:1; 46 unsigned wait_after_clean:1; 47 void (*clean_on_exit_handler)(struct child_process *process); 48 void *clean_on_exit_handler_cbdata; 49}; 50 51#define CHILD_PROCESS_INIT { NULL, ARGV_ARRAY_INIT, ARGV_ARRAY_INIT } 52void child_process_init(struct child_process *); 53void child_process_clear(struct child_process *); 54 55int start_command(struct child_process *); 56int finish_command(struct child_process *); 57int finish_command_in_signal(struct child_process *); 58int run_command(struct child_process *); 59 60/* 61 * Returns the path to the hook file, or NULL if the hook is missing 62 * or disabled. Note that this points to static storage that will be 63 * overwritten by further calls to find_hook and run_hook_*. 64 */ 65extern const char *find_hook(const char *name); 66LAST_ARG_MUST_BE_NULL 67extern int run_hook_le(const char *const *env, const char *name, ...); 68extern int run_hook_ve(const char *const *env, const char *name, va_list args); 69 70#define RUN_COMMAND_NO_STDIN 1 71#define RUN_GIT_CMD 2 /*If this is to be git sub-command */ 72#define RUN_COMMAND_STDOUT_TO_STDERR 4 73#define RUN_SILENT_EXEC_FAILURE 8 74#define RUN_USING_SHELL 16 75#define RUN_CLEAN_ON_EXIT 32 76int run_command_v_opt(const char **argv, int opt); 77 78/* 79 * env (the environment) is to be formatted like environ: "VAR=VALUE". 80 * To unset an environment variable use just "VAR". 81 */ 82int run_command_v_opt_cd_env(const char **argv, int opt, const char *dir, const char *const *env); 83 84/** 85 * Execute the given command, sending "in" to its stdin, and capturing its 86 * stdout and stderr in the "out" and "err" strbufs. Any of the three may 87 * be NULL to skip processing. 88 * 89 * Returns -1 if starting the command fails or reading fails, and otherwise 90 * returns the exit code of the command. Any output collected in the 91 * buffers is kept even if the command returns a non-zero exit. The hint fields 92 * gives starting sizes for the strbuf allocations. 93 * 94 * The fields of "cmd" should be set up as they would for a normal run_command 95 * invocation. But note that there is no need to set the in, out, or err 96 * fields; pipe_command handles that automatically. 97 */ 98int pipe_command(struct child_process *cmd, 99 const char *in, size_t in_len, 100 struct strbuf *out, size_t out_hint, 101 struct strbuf *err, size_t err_hint); 102 103/** 104 * Convenience wrapper around pipe_command for the common case 105 * of capturing only stdout. 106 */ 107static inline int capture_command(struct child_process *cmd, 108 struct strbuf *out, 109 size_t hint) 110{ 111 return pipe_command(cmd, NULL, 0, out, hint, NULL, 0); 112} 113 114/* 115 * The purpose of the following functions is to feed a pipe by running 116 * a function asynchronously and providing output that the caller reads. 117 * 118 * It is expected that no synchronization and mutual exclusion between 119 * the caller and the feed function is necessary so that the function 120 * can run in a thread without interfering with the caller. 121 */ 122struct async { 123 /* 124 * proc reads from in; closes it before return 125 * proc writes to out; closes it before return 126 * returns 0 on success, non-zero on failure 127 */ 128 int (*proc)(int in, int out, void *data); 129 void *data; 130 int in; /* caller writes here and closes it */ 131 int out; /* caller reads from here and closes it */ 132#ifdef NO_PTHREADS 133 pid_t pid; 134#else 135 pthread_t tid; 136 int proc_in; 137 int proc_out; 138#endif 139 int isolate_sigpipe; 140}; 141 142int start_async(struct async *async); 143int finish_async(struct async *async); 144int in_async(void); 145void check_pipe(int err); 146 147/** 148 * This callback should initialize the child process and preload the 149 * error channel if desired. The preloading of is useful if you want to 150 * have a message printed directly before the output of the child process. 151 * pp_cb is the callback cookie as passed to run_processes_parallel. 152 * You can store a child process specific callback cookie in pp_task_cb. 153 * 154 * Even after returning 0 to indicate that there are no more processes, 155 * this function will be called again until there are no more running 156 * child processes. 157 * 158 * Return 1 if the next child is ready to run. 159 * Return 0 if there are currently no more tasks to be processed. 160 * To send a signal to other child processes for abortion, 161 * return the negative signal number. 162 */ 163typedef int (*get_next_task_fn)(struct child_process *cp, 164 struct strbuf *out, 165 void *pp_cb, 166 void **pp_task_cb); 167 168/** 169 * This callback is called whenever there are problems starting 170 * a new process. 171 * 172 * You must not write to stdout or stderr in this function. Add your 173 * message to the strbuf out instead, which will be printed without 174 * messing up the output of the other parallel processes. 175 * 176 * pp_cb is the callback cookie as passed into run_processes_parallel, 177 * pp_task_cb is the callback cookie as passed into get_next_task_fn. 178 * 179 * Return 0 to continue the parallel processing. To abort return non zero. 180 * To send a signal to other child processes for abortion, return 181 * the negative signal number. 182 */ 183typedef int (*start_failure_fn)(struct strbuf *out, 184 void *pp_cb, 185 void *pp_task_cb); 186 187/** 188 * This callback is called on every child process that finished processing. 189 * 190 * You must not write to stdout or stderr in this function. Add your 191 * message to the strbuf out instead, which will be printed without 192 * messing up the output of the other parallel processes. 193 * 194 * pp_cb is the callback cookie as passed into run_processes_parallel, 195 * pp_task_cb is the callback cookie as passed into get_next_task_fn. 196 * 197 * Return 0 to continue the parallel processing. To abort return non zero. 198 * To send a signal to other child processes for abortion, return 199 * the negative signal number. 200 */ 201typedef int (*task_finished_fn)(int result, 202 struct strbuf *out, 203 void *pp_cb, 204 void *pp_task_cb); 205 206/** 207 * Runs up to n processes at the same time. Whenever a process can be 208 * started, the callback get_next_task_fn is called to obtain the data 209 * required to start another child process. 210 * 211 * The children started via this function run in parallel. Their output 212 * (both stdout and stderr) is routed to stderr in a manner that output 213 * from different tasks does not interleave. 214 * 215 * start_failure_fn and task_finished_fn can be NULL to omit any 216 * special handling. 217 */ 218int run_processes_parallel(int n, 219 get_next_task_fn, 220 start_failure_fn, 221 task_finished_fn, 222 void *pp_cb); 223 224#endif