hook.h

   1 #ifndef HOOK_H
   2 #define HOOK_H
   3 #include "strvec.h"
   4
   5 struct run_hooks_opt
   6 {
   7         /* Environment vars to be set for each hook */
   8         struct strvec env;
   9
  10         /* Args to be passed to each hook */
  11         struct strvec args;
  12
  13         /* Emit an error if the hook is missing */
  14         unsigned int error_if_missing:1;
  15
  16         /**
  17          * An optional initial working directory for the hook,
  18          * translates to "struct child_process"'s "dir" member.
  19          */
  20         const char *dir;
  21
  22         /**
  23          * A pointer which if provided will be set to 1 or 0 depending
  24          * on if a hook was started, regardless of whether or not that
  25          * was successful. I.e. if the underlying start_command() was
  26          * successful this will be set to 1.
  27          *
  28          * Used for avoiding TOCTOU races in code that would otherwise
  29          * call hook_exist() after a "maybe hook run" to see if a hook
  30          * was invoked.
  31          */
  32         int *invoked_hook;
  33
  34         /**
  35          * Path to file which should be piped to stdin for each hook.
  36          */
  37         const char *path_to_stdin;
  38 };
  39
  40 #define RUN_HOOKS_OPT_INIT { \
  41         .env = STRVEC_INIT, \
  42         .args = STRVEC_INIT, \
  43 }
  44
  45 struct hook_cb_data {
  46         /* rc reflects the cumulative failure state */
  47         int rc;
  48         const char *hook_name;
  49         const char *hook_path;
  50         struct run_hooks_opt *options;
  51 };
  52
  53 /*
  54  * Returns the path to the hook file, or NULL if the hook is missing
  55  * or disabled. Note that this points to static storage that will be
  56  * overwritten by further calls to find_hook and run_hook_*.
  57  */
  58 const char *find_hook(const char *name);
  59
  60 /**
  61  * A boolean version of find_hook()
  62  */
  63 int hook_exists(const char *hookname);
  64
  65 /**
  66  * Takes a `hook_name`, resolves it to a path with find_hook(), and
  67  * runs the hook for you with the options specified in "struct
  68  * run_hooks opt". Will free memory associated with the "struct run_hooks_opt".
  69  *
  70  * Returns the status code of the run hook, or a negative value on
  71  * error().
  72  */
  73 int run_hooks_opt(const char *hook_name, struct run_hooks_opt *options);
  74
  75 /**
  76  * A wrapper for run_hooks_opt() which provides a dummy "struct
  77  * run_hooks_opt" initialized with "RUN_HOOKS_OPT_INIT".
  78  */
  79 int run_hooks(const char *hook_name);
  80
  81 /**
  82  * Like run_hooks(), a wrapper for run_hooks_opt().
  83  *
  84  * In addition to the wrapping behavior provided by run_hooks(), this
  85  * wrapper takes a list of strings terminated by a NULL
  86  * argument. These things will be used as positional arguments to the
  87  * hook. This function behaves like the old run_hook_le() API.
  88  */
  89 LAST_ARG_MUST_BE_NULL
  90 int run_hooks_l(const char *hook_name, ...);
  91 #endif