Provided by: freebsd-manpages_8.2-1_all bug

NAME

     KFAIL_POINT_CODE, KFAIL_POINT_RETURN, KFAIL_POINT_RETURN_VOID,
     KFAIL_POINT_ERROR, KFAIL_POINT_GOTO, fail_point, DEBUG_FP -- fail points

SYNOPSIS

     #include <sys/fail.h>

     KFAIL_POINT_CODE(parent, name, code);

     KFAIL_POINT_RETURN(parent, name);

     KFAIL_POINT_RETURN_VOID(parent, name);

     KFAIL_POINT_ERROR(parent, name, error_var);

     KFAIL_POINT_GOTO(parent, name, error_var, label);

DESCRIPTION

     Fail points are used to add code points where errors may be injected in a
     user controlled fashion.  Fail points provide a convenient wrapper around
     user-provided error injection code, providing a sysctl(9) MIB, and a
     parser for that MIB that describes how the error injection code should
     fire.

     The base fail point macro is KFAIL_POINT_CODE() where parent is a sysctl
     tree (frequently DEBUG_FP for kernel fail points, but various subsystems
     may wish to provide their own fail point trees), and name is the name of
     the MIB in that tree, and code is the error injection code.  The code
     argument does not require braces, but it is considered good style to use
     braces for any multi-line code arguments.  Inside the code argument, the
     evaluation of RETURN_VALUE is derived from the return() value set in the
     sysctl MIB.  See SYSCTL VARIABLES below.

     The remaining KFAIL_POINT_*() macros are wrappers around common error
     injection paths:

     KFAIL_POINT_RETURN(parent, name)
       is the equivalent of KFAIL_POINT_CODE(..., return RETURN_VALUE)

     KFAIL_POINT_RETURN_VOID(parent, name)
       is the equivalent of KFAIL_POINT_CODE(..., return)

     KFAIL_POINT_ERROR(parent, name, error_var)
       is the equivalent of KFAIL_POINT_CODE(..., error_var = RETURN_VALUE)

     KFAIL_POINT_GOTO(parent, name, error_var, label)
       is the equivalent of KFAIL_POINT_CODE(...,
         { error_var = RETURN_VALUE; goto label;})

SYSCTL VARIABLES

     The KFAIL_POINT_*() macros add sysctl MIBs where specified.  Many base
     kernel MIBs can be found in the debug.fail_point tree (referenced in code
     by DEBUG_FP).

     The sysctl variable may be set using the following grammar:

       <fail_point> ::
           <term> ( "->" <term> )*

       <term> ::
           ( (<float> "%") | (<integer> "*" ) )*
           <type>
           [ "(" <integer> ")" ]

       <float> ::
           <integer> [ "." <integer> ] |
           "." <integer>

       <type> ::
           "off" | "return" | "sleep" | "panic" | "break" | "print"

     The <type> argument specifies which action to take:

     off     Take no action (does not trigger fail point code)

     return  Trigger fail point code with specified argument

     sleep   Sleep the specified number of milliseconds

     panic   Panic

     break   Break into the debugger, or trap if there is no debugger support

     print   Print that the fail point executed

     The <float>% and <integer>* modifiers prior to <type> control when <type>
     is executed.  The <float>% form (e.g. "1.2%") can be used to specify a
     probability that <type> will execute.  The <integer>* form (e.g. "5*")
     can be used to specify the number of times <type> should be executed
     before this <term> is disabled.  Only the last probability and the last
     count are used if multiple are specified, i.e. "1.2%2%" is the same as
     "2%".  When both a probability and a count are specified, the probability
     is evaluated before the count, i.e. "2%5*" means "2% of the time, but
     only 5 times total".

     The operator -> can be used to express cascading terms.  If you specify
     <term1>-><term2>, it means that if <term1> does not 'execute', <term2> is
     evaluated.  For the purpose of this operator, the return() and print()
     operators are the only types that cascade.  A return() term only cascades
     if the code executes, and a print() term only cascades when passed a non-
     zero argument.

EXAMPLES

     sysctl debug.fail_point.foobar="2.1%return(5)"
             21/1000ths of the time, execute code with RETURN_VALUE set to 5.

     sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"
             2/100ths of the time, execute code with RETURN_VALUE set to 5.
             If that does not happen, 5% of the time execute code with
             RETURN_VALUE set to 22.

     sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)"
             For 5 times, return 5.  After that, 1/1000th of the time, return
             22.

     sysctl debug.fail_point.foobar="0.1%5*return(5)"
             Return 5 for 1 in 1000 executions, but only 5 times total.

     sysctl debug.fail_point.foobar="1%*sleep(50)"
             1/100th of the time, sleep 50ms.

CAVEATS

     It is easy to shoot yourself in the foot by setting fail points too
     aggressively or setting too many in combination.  For example, forcing
     malloc() to fail consistently is potentially harmful to uptime.

     The sleep() sysctl setting may not be appropriate in all situations.
     Currently, fail_point_eval() does not verify whether the context is
     appropriate for calling msleep().

AUTHORS

     This manual page was written by Zach Loafman <zml@FreeBSD.org>.