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, effectively
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
mandatory 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 [email protected]. For more information about libfiu, you can go to http://blitiri.com.ar/p/libfiu. 17/Feb/2009 libfiu(3)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
