THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

Git Source Code Mirror - This is a publish-only repository and all pull requests are ignored. Please follow Documentation/SubmittingPatches procedure for any of your improvements.
git
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

236 lines
8.1KB

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