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