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 #define RUN_HOOKS_OPT_INIT { \
  36         .env = STRVEC_INIT, \
  37         .args = STRVEC_INIT, \
  38 }
  39
  40 struct hook_cb_data {
  41         /* rc reflects the cumulative failure state */
  42         int rc;
  43         const char *hook_name;
  44         const char *hook_path;
  45         struct run_hooks_opt *options;
  46 };
  47
  48 /*
  49  * Returns the path to the hook file, or NULL if the hook is missing
  50  * or disabled. Note that this points to static storage that will be
  51  * overwritten by further calls to find_hook and run_hook_*.
  52  */
  53 const char *find_hook(const char *name);
  54
  55 /**
  56  * A boolean version of find_hook()
  57  */
  58 int hook_exists(const char *hookname);
  59
  60 /**
  61  * Takes a `hook_name`, resolves it to a path with find_hook(), and
  62  * runs the hook for you with the options specified in "struct
  63  * run_hooks opt". Will free memory associated with the "struct run_hooks_opt".
  64  *
  65  * Returns the status code of the run hook, or a negative value on
  66  * error().
  67  */
  68 int run_hooks_opt(const char *hook_name, struct run_hooks_opt *options);
  69
  70 /**
  71  * A wrapper for run_hooks_opt() which provides a dummy "struct
  72  * run_hooks_opt" initialized with "RUN_HOOKS_OPT_INIT".
  73  */
  74 int run_hooks(const char *hook_name);
  75
  76 /**
  77  * Like run_hooks(), a wrapper for run_hooks_opt().
  78  *
  79  * In addition to the wrapping behavior provided by run_hooks(), this
  80  * wrapper takes a list of strings terminated by a NULL
  81  * argument. These things will be used as positional arguments to the
  82  * hook. This function behaves like the old run_hook_le() API.
  83  */
  84 int run_hooks_l(const char *hook_name, ...);
  85 #endif