1 /* Licensed under LGPL - see LICENSE file for details */
2 #ifndef CCAN_FAILTEST_H
3 #define CCAN_FAILTEST_H
5 #if HAVE_FILE_OFFSET_BITS
6 #define _FILE_OFFSET_BITS 64
11 #include <ccan/compiler/compiler.h>
12 #include <ccan/tlist/tlist.h>
15 * failtest_init - initialize the failtest module
16 * @argc: the number of commandline arguments
17 * @argv: the commandline argument array
19 * This initializes the module, and in particular if argv[1] is "--failpath="
20 * then it ensures that failures follow that pattern. This allows easy
21 * debugging of complex failure paths.
23 void failtest_init(int argc, char *argv[]);
26 * failtest_exit - clean up and exit the test
27 * @status: the status (usually exit_status() from ccan/tap).
29 * This cleans up and changes to files made in this child, and exits the test.
30 * It also calls your failtest_default_hook, if any.
32 * A child which does not exit via failtest_exit() will cause the overall test
35 void NORETURN failtest_exit(int status);
38 * enum failtest_call_type - discriminator for failtest_call.u
40 enum failtest_call_type {
125 * struct failtest_call - description of a call redirected to failtest module
126 * @type: the call type
127 * @file: the filename of the caller
128 * @line: the line number of the caller
129 * @fail: did this call fail
130 * @error: the errno (if any)
131 * @u: the union of call data
133 * This structure is used to represent the ordered history of calls.
136 * failtest_hook, failtest_exit_check
138 struct failtest_call {
139 /* We're in the history list. */
140 struct list_node list;
141 enum failtest_call_type type;
142 /* Where we were called from. */
147 /* What we set errno to. */
149 /* How do we clean this up? */
150 void (*cleanup)(void *u);
151 /* Backtrace of call chain. */
153 unsigned int backtrace_num;
154 /* The actual call data. */
156 struct calloc_call calloc;
157 struct malloc_call malloc;
158 struct realloc_call realloc;
159 struct open_call open;
160 struct close_call close;
161 struct pipe_call pipe;
162 struct read_call read;
163 struct write_call write;
164 struct fcntl_call fcntl;
165 struct mmap_call mmap;
169 /* This defines struct tlist_calls. */
170 TLIST_TYPE(calls, struct failtest_call);
172 enum failtest_result {
173 /* Yes try failing this call. */
175 /* No, don't try failing this call. */
177 /* Try failing this call but don't go too far down that path. */
182 * failtest_hook - whether a certain call should fail or not.
183 * @history: the ordered history of all failtest calls.
185 * The default value of this hook is failtest_default_hook(), which returns
186 * FAIL_OK (ie. yes, fail the call).
188 * You can override it, and avoid failing certain calls. The parameters
189 * of the call (but not the return value(s)) will be filled in for the last
193 * static enum failtest_result dont_fail_alloc(struct tlist_calls *history)
195 * struct failtest_call *call;
196 * call = tlist_tail(history, struct failtest_call, list);
197 * if (call->type == FAILTEST_MALLOC
198 * || call->type == FAILTEST_CALLOC
199 * || call->type == FAILTEST_REALLOC)
200 * return FAIL_DONT_FAIL;
204 * failtest_hook = dont_fail_alloc;
206 extern enum failtest_result (*failtest_hook)(struct tlist_calls *history);
209 * failtest_exit_check - hook for additional checks on a failed child.
210 * @history: the ordered history of all failtest calls.
212 * Your program might have additional checks to do on failure, such as
213 * check that a file is not corrupted, or than an error message has been
216 * If this returns false, the path to this failure will be printed and the
217 * overall test will fail.
219 extern bool (*failtest_exit_check)(struct tlist_calls *history);
222 * failtest_has_failed - determine if a failure has occurred.
224 * Sometimes you want to exit immediately if you've experienced an
225 * injected failure. This is useful when you have four separate tests
226 * in your test suite, and you don't want to do the next one if you've
227 * had a failure in a previous one.
229 extern bool failtest_has_failed(void);
232 * failtest_timeout_ms - how long to wait before killing child.
234 * Default is 20,000 (20 seconds).
236 extern unsigned int failtest_timeout_ms;
237 #endif /* CCAN_FAILTEST_H */