Provided by: libfiu-dev_1.2-2_amd64 bug

NAME

       libfiu - Fault injection in userspace

SYNOPSIS

       /* 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
       albertito@blitiri.com.ar.  For  more   information   about   libfiu,   you   can   go   to
       http://blitiri.com.ar/p/libfiu.

                                           17/Feb/2009                                  libfiu(3)