1 /* Licensed under LGPL - see LICENSE file for details */
2 #ifndef CCAN_FAILTEST_H
3 #define CCAN_FAILTEST_H
8 #include <ccan/compiler/compiler.h>
11 * failtest_init - initialize the failtest module
12 * @argc: the number of commandline arguments
13 * @argv: the commandline argument array
15 * This initializes the module, and in particular if argv[1] is "--failpath="
16 * then it ensures that failures follow that pattern. This allows easy
17 * debugging of complex failure paths.
19 void failtest_init(int argc, char *argv[]);
22 * failtest_exit - clean up and exit the test
23 * @status: the status (usually exit_status() from ccan/tap).
25 * This cleans up and changes to files made in this child, and exits the test.
26 * It also calls your failtest_default_hook, if any.
28 * A child which does not exit via failtest_exit() will cause the overall test
31 void NORETURN failtest_exit(int status);
34 * enum failtest_call_type - discriminator for failtest_call.u
36 enum failtest_call_type {
110 * struct failtest_call - description of a call redirected to failtest module
111 * @type: the call type
112 * @file: the filename of the caller
113 * @line: the line number of the caller
114 * @fail: did this call fail
115 * @error: the errno (if any)
116 * @u: the union of call data
118 * This structure is used to represent the ordered history of calls.
121 * failtest_hook, failtest_exit_check
123 struct failtest_call {
124 enum failtest_call_type type;
125 /* Where we were called from. */
130 /* What we set errno to. */
132 /* How do we clean this up? */
133 void (*cleanup)(void *u);
134 /* The actual call data. */
136 struct calloc_call calloc;
137 struct malloc_call malloc;
138 struct realloc_call realloc;
139 struct open_call open;
140 struct close_call close;
141 struct pipe_call pipe;
142 struct read_call read;
143 struct write_call write;
144 struct fcntl_call fcntl;
148 enum failtest_result {
149 /* Yes try failing this call. */
151 /* No, don't try failing this call. */
153 /* Try failing this call but don't go too far down that path. */
158 * failtest_hook - whether a certain call should fail or not.
159 * @history: the ordered history of all failtest calls.
160 * @num: the number of elements in @history (greater than 0)
162 * The default value of this hook is failtest_default_hook(), which returns
163 * FAIL_OK (ie. yes, fail the call).
165 * You can override it, and avoid failing certain calls. The parameters
166 * of the call (but not the return value(s)) will be filled in for the last
170 * static enum failtest_result dont_fail_alloc(struct failtest_call *hist,
173 * if (hist[num-1].type == FAILTEST_MALLOC
174 * || hist[num-1].type == FAILTEST_CALLOC
175 * || hist[num-1].type == FAILTEST_REALLOC)
176 * return FAIL_DONT_FAIL;
180 * failtest_hook = dont_fail_alloc;
182 extern enum failtest_result
183 (*failtest_hook)(struct failtest_call *history, unsigned num);
186 * failtest_exit_check - hook for additional checks on a failed child.
187 * @history: the ordered history of all failtest calls.
188 * @num: the number of elements in @history (greater than 0)
190 * Your program might have additional checks to do on failure, such as
191 * check that a file is not corrupted, or than an error message has been
194 * If this returns false, the path to this failure will be printed and the
195 * overall test will fail.
197 extern bool (*failtest_exit_check)(struct failtest_call *history,
201 * failtest_has_failed - determine if a failure has occurred.
203 * Sometimes you want to exit immediately if you've experienced a failure.
204 * This is useful when you have four separate tests in your test suite,
205 * and you don't want to do the next one if you've had a failure in a
208 extern bool failtest_has_failed(void);
211 * failtest_timeout_ms - how long to wait before killing child.
213 * Default is 20,000 (20 seconds).
215 extern unsigned int failtest_timeout_ms;
216 #endif /* CCAN_FAILTEST_H */