/usr/include/fiu-control.h is in libfiu-dev 0.93-2+b1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 | /** @file
*
* This header contains the control API.
* It should be used for controlling the injection of failures, usually when
* writing tests.
*/
#ifndef _FIU_CONTROL_H
#define _FIU_CONTROL_H
#ifdef __cplusplus
extern "C" {
#endif
/* Flags for fiu_enable*() */
/** Only fail once; the point of failure will be automatically disabled
* afterwards. */
#define FIU_ONETIME 1
/** Enables the given point of failure unconditionally.
*
* @param name Name of the point of failure to enable.
* @param failnum What will fiu_fail() return, must be != 0.
* @param failinfo What will fiu_failinfo() return.
* @param flags Flags.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_enable(const char *name, int failnum, void *failinfo,
unsigned int flags);
/** Enables the given point of failure, with the given probability. That makes
* it fail with the given probability.
*
* @param name Name of the point of failure to enable.
* @param failnum What will fiu_fail() return, must be != 0.
* @param failinfo What will fiu_failinfo() return.
* @param flags Flags.
* @param probability Probability a fiu_fail() call will return failnum,
* between 0 (never fail) and 1 (always fail). As a special fast case, -1
* can also be used to always fail.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_enable_random(const char *name, int failnum, void *failinfo,
unsigned int flags, float probability);
/** Type of external callback functions.
* They must return 0 to indicate not to fail, != 0 to indicate otherwise. Can
* modify failnum, failinfo and flags, in order to alter the values of the
* point of failure. */
typedef int external_cb_t(const char *name, int *failnum, void **failinfo,
unsigned int *flags);
/** Enables the given point of failure, leaving the decision whether to fail
* or not to the given external function.
*
* @param name Name of the point of failure to enable.
* @param failnum What will fiu_fail() return, must be != 0.
* @param failinfo What will fiu_failinfo() return.
* @param flags Flags.
* @param external_cb Function to call to determine whether to fail or not.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_enable_external(const char *name, int failnum, void *failinfo,
unsigned int flags, external_cb_t *external_cb);
/* Enables the given point of failure, but only if the given function is in
* the stack at the given position.
*
* This function relies on GNU extensions such as backtrace() and dladdr(), so
* it may not be available on your platform.
*
* - name: point of failure name.
* - failnum: what will fiu_fail() return, must be != 0.
* - failinfo: what will fiu_failinfo() return.
* - flags: flags.
* - func: pointer to the function.
* - func_pos: position where we expect the function to be; use -1 for "any".
* Values other than -1 are not supported at the moment, but will be in
* the future.
*/
int fiu_enable_stack(const char *name, int failnum, void *failinfo,
unsigned int flags, void *func, int func_pos_in_stack);
/** Enables the given point of failure, but only if 'func_name' is in
* the stack at 'func_pos_in_stack'.
*
* This function relies on GNU extensions such as backtrace() and dladdr(), so
* if your platform does not support them, it will always return failure.
*
* It is exactly like fiu_enable_stack() but takes a function name, it will
* ask the dynamic linker to find the corresponding function pointer.
*
* @param name Name of the point of failure to enable.
* @param failnum What will fiu_fail() return, must be != 0.
* @param failinfo What will fiu_failinfo() return.
* @param flags Flags.
* @param func_name Name of the function.
* @param func_pos_in_stack Position where we expect the function to be; use
* -1 for "any". Values other than -1 are not supported at the
* moment, but will be in the future.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_enable_stack_by_name(const char *name, int failnum, void *failinfo,
unsigned int flags, const char *func_name,
int func_pos_in_stack);
/** Disables the given point of failure. That makes it NOT fail.
*
* @param name Name of the point of failure to disable.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_disable(const char *name);
/** Enables remote control over a named pipe.
*
* The name pipe path will begin with the given basename. "-$PID" will be
* appended to it to form the final path. After the process dies, the pipe
* will be removed. If the process forks, a new pipe will be created.
*
* Once this function has been called, the fiu-ctrl utility can be used to
* control the points of failure externally.
*
* @param basename Base path to use in the creation of the named pipes.
* @returns 0 on success, -1 on errors. */
int fiu_rc_fifo(const char *basename);
/** Applies a remote control command given via a string.
*
* The format of the string is not stable and is still subject to change.
* At the moment, this function is exported for consumption by the libfiu
* utilities.
*
* @param cmd: A zero-terminated string with the command to apply.
* @param error: In case of an error, it will point to a human-readable error
* message.
* @returns 0 if success, < 0 otherwise.
*/
int fiu_rc_string(const char *cmd, char ** const error);
#ifdef __cplusplus
}
#endif
#endif // _FIU_CONTROL_H
|