0cc8f60c51ba15aa48e207c6088bfe4d39b70050
[ccan] / ccan / failtest / failtest.h
1 /* Licensed under LGPL - see LICENSE file for details */
2 #ifndef CCAN_FAILTEST_H
3 #define CCAN_FAILTEST_H
4 #include "config.h"
5 #if HAVE_FILE_OFFSET_BITS
6 #define _FILE_OFFSET_BITS 64
7 #endif
8 #include <sys/types.h>
9 #include <stdbool.h>
10 #include <fcntl.h>
11 #include <ccan/compiler/compiler.h>
12
13 /**
14  * failtest_init - initialize the failtest module
15  * @argc: the number of commandline arguments
16  * @argv: the commandline argument array
17  *
18  * This initializes the module, and in particular if argv[1] is "--failpath="
19  * then it ensures that failures follow that pattern.  This allows easy
20  * debugging of complex failure paths.
21  */
22 void failtest_init(int argc, char *argv[]);
23
24 /**
25  * failtest_exit - clean up and exit the test
26  * @status: the status (usually exit_status() from ccan/tap).
27  *
28  * This cleans up and changes to files made in this child, and exits the test.
29  * It also calls your failtest_default_hook, if any.
30  *
31  * A child which does not exit via failtest_exit() will cause the overall test
32  * to fail.
33  */
34 void NORETURN failtest_exit(int status);
35
36 /**
37  * enum failtest_call_type - discriminator for failtest_call.u
38  */
39 enum failtest_call_type {
40         FAILTEST_MALLOC,
41         FAILTEST_CALLOC,
42         FAILTEST_REALLOC,
43         FAILTEST_OPEN,
44         FAILTEST_CLOSE,
45         FAILTEST_PIPE,
46         FAILTEST_READ,
47         FAILTEST_WRITE,
48         FAILTEST_FCNTL,
49 };
50
51 struct calloc_call {
52         void *ret;
53         size_t nmemb;
54         size_t size;
55 };
56
57 struct malloc_call {
58         void *ret;
59         size_t size;
60 };
61
62 struct realloc_call {
63         void *ret;
64         void *ptr;
65         size_t size;
66 };
67
68 struct open_call {
69         int ret;
70         const char *pathname;
71         int flags;
72         mode_t mode;
73 };
74
75 struct close_call {
76         int fd;
77 };
78
79 struct pipe_call {
80         int ret;
81         int fds[2];
82         bool closed[2];
83 };
84
85 struct read_call {
86         ssize_t ret;
87         off_t off;
88         int fd;
89         void *buf;
90         size_t count;
91 };
92
93 struct write_call {
94         ssize_t ret;
95         int fd;
96         const void *buf;
97         size_t count;
98         off_t off;
99 };
100
101 struct fcntl_call {
102         int ret;
103         int fd;
104         int cmd;
105         union {
106                 struct flock fl;
107                 long l;
108                 int i;
109         } arg;
110 };
111
112 /**
113  * struct failtest_call - description of a call redirected to failtest module
114  * @type: the call type
115  * @file: the filename of the caller
116  * @line: the line number of the caller
117  * @fail: did this call fail
118  * @error: the errno (if any)
119  * @u: the union of call data
120  *
121  * This structure is used to represent the ordered history of calls.
122  *
123  * See Also:
124  *      failtest_hook, failtest_exit_check
125  */
126 struct failtest_call {
127         enum failtest_call_type type;
128         /* Where we were called from. */
129         const char *file;
130         unsigned int line;
131         /* Did we fail? */
132         bool fail;
133         /* What we set errno to. */
134         int error;
135         /* How do we clean this up? */
136         void (*cleanup)(void *u);
137         /* The actual call data. */
138         union {
139                 struct calloc_call calloc;
140                 struct malloc_call malloc;
141                 struct realloc_call realloc;
142                 struct open_call open;
143                 struct close_call close;
144                 struct pipe_call pipe;
145                 struct read_call read;
146                 struct write_call write;
147                 struct fcntl_call fcntl;
148         } u;
149 };
150
151 enum failtest_result {
152         /* Yes try failing this call. */
153         FAIL_OK,
154         /* No, don't try failing this call. */
155         FAIL_DONT_FAIL,
156         /* Try failing this call but don't go too far down that path. */
157         FAIL_PROBE,
158 };
159
160 /**
161  * failtest_hook - whether a certain call should fail or not.
162  * @history: the ordered history of all failtest calls.
163  * @num: the number of elements in @history (greater than 0)
164  *
165  * The default value of this hook is failtest_default_hook(), which returns
166  * FAIL_OK (ie. yes, fail the call).
167  *
168  * You can override it, and avoid failing certain calls.  The parameters
169  * of the call (but not the return value(s)) will be filled in for the last
170  * call.
171  *
172  * Example:
173  *      static enum failtest_result dont_fail_alloc(struct failtest_call *hist,
174  *                                                  unsigned num)
175  *      {
176  *              if (hist[num-1].type == FAILTEST_MALLOC
177  *                      || hist[num-1].type == FAILTEST_CALLOC
178  *                      || hist[num-1].type == FAILTEST_REALLOC)
179  *                      return FAIL_DONT_FAIL;
180  *              return FAIL_OK;
181  *      }
182  *      ...
183  *              failtest_hook = dont_fail_alloc;
184  */
185 extern enum failtest_result
186 (*failtest_hook)(struct failtest_call *history, unsigned num);
187
188 /**
189  * failtest_exit_check - hook for additional checks on a failed child.
190  * @history: the ordered history of all failtest calls.
191  * @num: the number of elements in @history (greater than 0)
192  *
193  * Your program might have additional checks to do on failure, such as
194  * check that a file is not corrupted, or than an error message has been
195  * logged.
196  *
197  * If this returns false, the path to this failure will be printed and the
198  * overall test will fail.
199  */
200 extern bool (*failtest_exit_check)(struct failtest_call *history,
201                                    unsigned num);
202
203 /**
204  * failtest_has_failed - determine if a failure has occurred.
205  *
206  * Sometimes you want to exit immediately if you've experienced a failure.
207  * This is useful when you have four separate tests in your test suite,
208  * and you don't want to do the next one if you've had a failure in a
209  * previous one.
210  */
211 extern bool failtest_has_failed(void);
212
213 /**
214  * failtest_timeout_ms - how long to wait before killing child.
215  *
216  * Default is 20,000 (20 seconds).
217  */
218 extern unsigned int failtest_timeout_ms;
219 #endif /* CCAN_FAILTEST_H */