git.ozlabs.org Git - ccan/blob - ccan/failtest/failtest.h

   1 #ifndef CCAN_FAILTEST_H
   2 #define CCAN_FAILTEST_H
   3 #include <sys/types.h>
   4 #include <stdbool.h>
   5 #include <ccan/compiler/compiler.h>
   6
   7 /**
   8  * failtest_init - initialize the failtest module
   9  * @argc: the number of commandline arguments
  10  * @argv: the commandline argument array
  11  *
  12  * This initializes the module, and in particular if argv[1] is "--failpath="
  13  * then it ensures that failures follow that pattern.  This allows easy
  14  * debugging of complex failure paths.
  15  */
  16 void failtest_init(int argc, char *argv[]);
  17
  18 /**
  19  * failtest_exit - clean up and exit the test
  20  * @status: the status (usually exit_status() from ccan/tap).
  21  *
  22  * This cleans up and changes to files made in this child, and exits the test.
  23  * It also calls your failtest_default_hook, if any.
  24  *
  25  * A child which does not exit via failtest_exit() will cause the overall test
  26  * to fail.
  27  */
  28 void NORETURN failtest_exit(int status);
  29
  30 /**
  31  * enum failtest_call_type - discriminator for failtest_call.u
  32  */
  33 enum failtest_call_type {
  34         FAILTEST_MALLOC,
  35         FAILTEST_CALLOC,
  36         FAILTEST_REALLOC,
  37         FAILTEST_OPEN,
  38         FAILTEST_PIPE,
  39         FAILTEST_READ,
  40         FAILTEST_WRITE,
  41 };
  42
  43 struct calloc_call {
  44         void *ret;
  45         size_t nmemb;
  46         size_t size;
  47 };
  48
  49 struct malloc_call {
  50         void *ret;
  51         size_t size;
  52 };
  53
  54 struct realloc_call {
  55         void *ret;
  56         void *ptr;
  57         size_t size;
  58 };
  59
  60 struct open_call {
  61         int ret;
  62         const char *pathname;
  63         int flags;
  64         mode_t mode;
  65 };
  66
  67 struct pipe_call {
  68         int ret;
  69         int fds[2];
  70 };
  71
  72 struct read_call {
  73         ssize_t ret;
  74         int fd;
  75         void *buf;
  76         size_t count;
  77 };
  78
  79 struct write_call {
  80         ssize_t ret;
  81         int fd;
  82         const void *buf;
  83         size_t count;
  84 };
  85
  86 /**
  87  * struct failtest_call - description of a call redirected to failtest module
  88  * @type: the call type
  89  * @file: the filename of the caller
  90  * @line: the line number of the caller
  91  * @fail: did this call fail
  92  * @error: the errno (if any)
  93  * @u: the union of call data
  94  *
  95  * This structure is used to represent the ordered history of calls.
  96  *
  97  * See Also:
  98  *      failtest_hook, failtest_exit_check
  99  */
 100 struct failtest_call {
 101         enum failtest_call_type type;
 102         /* Where we were called from. */
 103         const char *file;
 104         unsigned int line;
 105         /* Did we fail? */
 106         bool fail;
 107         /* What we set errno to. */
 108         int error;
 109         /* The actual call data. */
 110         union {
 111                 struct calloc_call calloc;
 112                 struct malloc_call malloc;
 113                 struct realloc_call realloc;
 114                 struct open_call open;
 115                 struct pipe_call pipe;
 116                 struct read_call read;
 117                 struct write_call write;
 118         } u;
 119 };
 120
 121 /**
 122  * failtest_hook - whether a certain call should fail or not.
 123  * @history: the ordered history of all failtest calls.
 124  * @num: the number of elements in @history (greater than 0)
 125  *
 126  * The default value of this hook is failtest_default_hook(), which returns
 127  * true (ie. yes, fail the call).
 128  *
 129  * You can override it, and avoid failing certain calls.  The parameters
 130  * of the call (but not the return value(s)) will be filled in for the last
 131  * call.
 132  *
 133  * Example:
 134  *      static bool dont_fail_allocations(struct failtest_call *history,
 135  *                                        unsigned num)
 136  *      {
 137  *              return history[num-1].type != FAILTEST_MALLOC
 138  *                      && history[num-1].type != FAILTEST_CALLOC
 139  *                      && history[num-1].type != FAILTEST_REALLOC;
 140  *      }
 141  *      ...
 142  *              failtest_hook = dont_fail_allocations;
 143  */
 144 extern bool (*failtest_hook)(struct failtest_call *history, unsigned num);
 145
 146 /**
 147  * failtest_exit_check - hook for additional checks on a failed child.
 148  * @history: the ordered history of all failtest calls.
 149  * @num: the number of elements in @history (greater than 0)
 150  *
 151  * Your program might have additional checks to do on failure, such as
 152  * check that a file is not corrupted, or than an error message has been
 153  * logged.
 154  *
 155  * If this returns false, the path to this failure will be printed and the
 156  * overall test will fail.
 157  */
 158 extern bool (*failtest_exit_check)(struct failtest_call *history,
 159                                    unsigned num);
 160
 161 /* This usually fails the call. */
 162 bool failtest_default_hook(struct failtest_call *history, unsigned num);
 163
 164 /**
 165  * failtest_timeout_ms - how long to wait before killing child.
 166  *
 167  * Default is 20,000 (20 seconds).
 168  */
 169 extern unsigned int failtest_timeout_ms;
 170 #endif /* CCAN_FAILTEST_H */