fiu-run(1) [debian man page]
fiu-run(1) General Commands Manual fiu-run(1) NAME
fiu-run - a script to launch programs using libfiu SYNOPSIS
fiu-run [options] program [program arguments] DESCRIPTION
fiu-run is a script to make it easier to launch programs using libfiu(3). It can enable failure points and start libfiu's remote control capabilities before starting to execute the program, avoiding the need to write a special launcher to inject failures. It is specially useful when used to inject failures in the POSIX/libc functions, because it does not require any program modifications. After launching programs with fiu-run, fiu-ctrl(1) can be used to enable and disable their failure points at runtme. For additional documentation, go to the project's website at http://blitiri.com.ar/p/libfiu. OPTIONS
-c command Run the given libfiu remote control command before executing the program (see below for reference). -x Use the POSIX libfiu preload library, allows simulate failures in the POSIX and C standard library functions. -f ctrlpath Enable remote control over named pipes with the given path as base name, the process id will be appended (defaults to "$TMPDIR/fiu- ctrl", or "/tmp/fiu-ctrl" if "$TMPDIR" is not set). Set to "" to disable remote control over named pipes. -l path Path where to find the libfiu preload libraries. Defaults to the path where they were installed, so it is usually correct. Remote control commands are of the form "command param1=value1,param2=value2". Valid commands are: 'enable name=NAME' Enables the NAME failure point unconditionally. 'enable_random name=NAME,probability=P' Enables the NAME failure point with a probability of P. All of the enable* commands can also optionally take failnum and failinfo parameters, analogous to the ones taken by the C functions. EXAMPLES
The following will run the fortune(1) program simulating faults in read() with 5% probability (note that the -x parameter is required in this case to enable failure points in the POSIX and libc functions): fiu-run -x -c "enable_random name=posix/io/rw/read,probability=0.05" fortune By running it multiple times you will see that sometimes it works, but most of the time you get different errors, resulting from the simu- lated failures. SEE ALSO
libfiu(3), fiu-ctrl(1). BUGS
If you want to report bugs, or have any questions or comments, just let me know at albertito@blitiri.com.ar. For more information about libfiu, you can go to http://blitiri.com.ar/p/libfiu. 16/Jun/2009 fiu-run(1)
Check Out this Related Man Page
libfiu(3) Library Functions Manual libfiu(3) NAME
libfiu - Fault injection in userspace SYNOPSYS
/* Core API */ #include <fiu.h> int fiu_init(unsigned int flags); int fiu_fail(const char *name); void *fiu_failinfo(void); [void] fiu_do_on(char *name, action); [macro] [void] fiu_exit_on(char *name); [macro] [void] fiu_return_on(char *name, retval); [macro] /* Control API */ #include <fiu-control.h> int fiu_enable(const char *name, int failnum, void *failinfo, unsigned int flags); int fiu_enable_random(const char *name, int failnum, void *failinfo, unsigned int flags, float probability); typedef int external_cb_t(const char *name, int *failnum, void **failinfo, unsigned int *flags); int fiu_enable_external(const char *name, int failnum, void *failinfo, unsigned int flags, external_cb_t *external_cb); int fiu_enable_stack(const char *name, int failnum, void *failinfo, unsigned int flags, void *func, int func_pos_in_stack); 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); int fiu_disable(const char *name); int fiu_rc_fifo(const char *basename); DESCRIPTION
libfiu is a library for fault injection. It provides functions to mark "points of failure" inside your code (the "core API"), and functions to enable/disable the failure of those points (the "control API"). The core API is used inside the code wanting to perform fault injection on. The control API is used inside the testing code, in order to control the injection of failures. This page is an API reference and not a complete manual, and as such does not go into detail about how to use the library. The library's manual can be found in the distribution. CORE API To use the core API, you should #include <fiu.h> (or <fiu-local.h>, see below). Because fault injection is usually a debugging/testing facility, unwanted at runtime, some special considerations were taken to minimize the impact of the core API. First of all, if FIU_ENABLE is not defined, then fiu.h will define empty stubs for all the core API, effec- tively disabling fault injection completely. Also, the special header fiu-local.h is shipped with libfiu. It is meant to be included in your project to avoid having libfiu as a manda- tory build-time dependency. You can add it to your project, and #include it instead of fiu.h. It will take care of including the real fiu.h only when FIU_ENABLE is defined. It is entirely optional, but recommended. See the library's manual for more details. fiu_init(flags) Initializes the library. Ideally, you should only call this once, although it can cope with multiple calls. The flags parameter is currently unused and must be set to 0. Returns 0 on success, < 0 on error. fiu_fail(name) Returns the failure status of the given point of failure. 0 means it should not fail. By default, all points of failure do not fail; they're enabled in runtime using the control API. fiu_failinfo() Returns the information associated with the last failure, or NULL if there isn't one. This function is thread-aware and will only return information about failures in the calling thread. fiu_do_on(name, action) [macro] This is a macro that uses fiu_fail() to perform the given action when the given point of failure fails. The action can be any valid C statement. fiu_exit_on(name) [macro] This is a macro that uses fiu_fail() to exit the process when the given point of failure fails. The process is exit using exit(3), which is given the status EXIT_FAILURE. fiu_return_on(name, retval) [macro] This is a macro that uses fiu_fail() to make the current function return the given value (whose type obviously depends on the return type of the function). CONTROL API To use the control API, you should #include <fiu-control.h>. fiu_enable(name, failnum, failinfo, flags) Enables the given point of failure. failnum is what fiu_fail() will return, and must be != 0. failinfo is what fiu_failinfo() will return when called after the given point of failure has failed. flags can be either 0 or FIU_ONETIME, which indicates that this point of failure should only fail once. Returns 0 if success, < 0 otherwise. If the point of failure was already enabled, this overwrites the previous values. Successive calls to fiu_fail() will return failnum until this point of failure is disabled. If FIU_ONETIME was passed in the flags, this point of failure is disabled immediately after failing once. If the name ends with an asterisk, then it this will match all points of failure that begin with the given name (excluding the asterisk, of course). fiu_enable_random(name, failnum, failinfo, flags, probability) Enables the given point of failure, with the given probability (between 0 and 1). The rest of the parameters, as well as the return value, are the same as the ones in fiu_enable(). fiu_enable_external(name, failnum, failinfo, flags, external_cb) Enables the given point of failure, leaving the decision whether to fail or not to the given external function, which should return 0 if it is not to fail, or 1 otherwise. The rest of the parameters, as well as the return value, are the same as the ones in fiu_enable(). int fiu_enable_stack(name, failnum, failinfo, flags, func, func_pos_in_stack) Enables the given point of failure, but only if func is in the stack at func_pos_in_stack. func must be a function pointer, and func_pos_in_stack is the position where we expect the function to be, or -1 for "any" (values other than -1 are not yet supported). The rest of the parameters, as well as the return value, are the same as the ones in fiu_enable(). This function relies on some GNU extensions, so it may be not available in all platforms. int fiu_enable_stack_by_name(name, failnum, failinfo, flags, func_name, func_pos_in_stack) Enables the given point of failure, but only if func_name is in the stack at func_pos_in_stack. func must be the name of a function (resolved at runtime using dlsym()); the rest of the parameters, as well as the return value, are the same as the ones in fiu_enable_stack. This function relies on some GNU extensions, so it may be not available in all platforms. fiu_disable(name) Disables the given point of failure, undoing the actions of the fiu_enable*() functions. fiu_rc_fifo(basename) Enables remote control over named pipes with the given basename. See the remote control documentation that comes with the library for more detail. THREAD SAFETY The library is thread-safe. The list of enabled failure points is shared among all threads. Care should be taken in the user-provided functions given to fiu_enable_external(), as they can be run in parallel. SEE ALSO
fiu-run(1), fiu-ctrl(1). BUGS
If you want to report bugs, or have any questions or comments, just let me know at albertito@blitiri.com.ar. For more information about libfiu, you can go to http://blitiri.com.ar/p/libfiu. 17/Feb/2009 libfiu(3)