diff options
Diffstat (limited to 'static/freebsd/man9/fail.9')
| -rw-r--r-- | static/freebsd/man9/fail.9 | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/static/freebsd/man9/fail.9 b/static/freebsd/man9/fail.9 new file mode 100644 index 00000000..346f4dc3 --- /dev/null +++ b/static/freebsd/man9/fail.9 @@ -0,0 +1,283 @@ +.\" +.\" Copyright (c) 2009-2019 Dell EMC Isilon http://www.isilon.com/ +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.Dd June 6, 2019 +.Dt FAIL 9 +.Os +.Sh NAME +.Nm DEBUG_FP , +.Nm KFAIL_POINT_CODE , +.Nm KFAIL_POINT_CODE_FLAGS , +.Nm KFAIL_POINT_CODE_COND , +.Nm KFAIL_POINT_ERROR , +.Nm KFAIL_POINT_EVAL , +.Nm KFAIL_POINT_DECLARE , +.Nm KFAIL_POINT_DEFINE , +.Nm KFAIL_POINT_GOTO , +.Nm KFAIL_POINT_RETURN , +.Nm KFAIL_POINT_RETURN_VOID , +.Nm KFAIL_POINT_SLEEP_CALLBACKS , +.Nm fail_point +.Nd fail points +.Sh SYNOPSIS +.In sys/fail.h +.Fn KFAIL_POINT_CODE "parent" "name" "code" +.Fn KFAIL_POINT_CODE_FLAGS "parent" "name" "flags" "code" +.Fn KFAIL_POINT_CODE_COND "parent" "name" "cond" "flags" "code" +.Fn KFAIL_POINT_ERROR "parent" "name" "error_var" +.Fn KFAIL_POINT_EVAL "name" "code" +.Fn KFAIL_POINT_DECLARE "name" +.Fn KFAIL_POINT_DEFINE "parent" "name" "flags" +.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" +.Fn KFAIL_POINT_RETURN "parent" "name" +.Fn KFAIL_POINT_RETURN_VOID "parent" "name" +.Fn KFAIL_POINT_SLEEP_CALLBACKS "parent" "name" "pre_func" "pre_arg" "post_func" "post_arg" "code" +.Sh 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 +.Xr sysctl 9 +MIB, and a parser for that MIB that describes how the error +injection code should fire. +.Pp +The base fail point macro is +.Fn KFAIL_POINT_CODE +where +.Fa parent +is a sysctl tree (frequently +.Sy DEBUG_FP +for kernel fail points, but various subsystems may wish to provide +their own fail point trees), and +.Fa name +is the name of the MIB in that tree, and +.Fa code +is the error injection code. +The +.Fa code +argument does not require braces, but it is considered good style to +use braces for any multi-line code arguments. +Inside the +.Fa code +argument, the evaluation of +.Sy RETURN_VALUE +is derived from the +.Fn return +value set in the sysctl MIB. +.Pp +Additionally, +.Fn KFAIL_POINT_CODE_FLAGS +provides a +.Fa flags +argument which controls the fail point's behaviour. +This can be used to e.g., mark the fail point's context as non-sleepable, +which causes the +.Sy sleep +action to be coerced to a busy wait. +The supported flags are: +.Bl -ohang -offset indent +.It FAIL_POINT_USE_TIMEOUT_PATH +Rather than sleeping on a +.Fn sleep +call, just fire the post-sleep function after a timeout fires. +.It FAIL_POINT_NONSLEEPABLE +Mark the fail point as being in a non-sleepable context, which coerces +.Fn sleep +calls to +.Fn delay +calls. +.El +.Pp +Likewise, +.Fn KFAIL_POINT_CODE_COND +supplies a +.Fa cond +argument, which allows you to set the condition under which the fail point's +code may fire. +This is equivalent to: +.Bd -literal + if (cond) + KFAIL_POINT_CODE_FLAGS(...); + +.Ed +See +.Sx SYSCTL VARIABLES +below. +.Pp +The remaining +.Fn KFAIL_POINT_* +macros are wrappers around common error injection paths: +.Bl -inset +.It Fn KFAIL_POINT_RETURN parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return RETURN_VALUE) +.It Fn KFAIL_POINT_RETURN_VOID parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return) +.It Fn KFAIL_POINT_ERROR parent name error_var +is the equivalent of +.Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) +.It Fn KFAIL_POINT_GOTO parent name error_var label +is the equivalent of +.Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) +.El +.Pp +You can also introduce fail points by separating the declaration, +definition, and evaluation portions. +.Bl -inset +.It Fn KFAIL_POINT_DECLARE name +is used to declare the +.Sy fail_point +struct. +.It Fn KFAIL_POINT_DEFINE parent name flags +defines and initializes the +.Sy fail_point +and sets up its +.Xr sysctl 9 . +.It Fn KFAIL_POINT_EVAL name code +is used at the point that the fail point is executed. +.El +.Sh SYSCTL VARIABLES +The +.Fn KFAIL_POINT_* +macros add sysctl MIBs where specified. +Many base kernel MIBs can be found in the +.Sy debug.fail_point +tree (referenced in code by +.Sy DEBUG_FP ) . +.Pp +The sysctl variable may be set in a number of ways: +.Bd -literal + [<pct>%][<cnt>*]<type>[(args...)][-><more terms>] +.Ed +.Pp +The <type> argument specifies which action to take; it can be one of: +.Bl -tag -width ".Dv return" +.It Sy off +Take no action (does not trigger fail point code) +.It Sy return +Trigger fail point code with specified argument +.It Sy sleep +Sleep the specified number of milliseconds +.It Sy panic +Panic +.It Sy break +Break into the debugger, or trap if there is no debugger support +.It Sy print +Print that the fail point executed +.It Sy pause +Threads sleep at the fail point until the fail point is set to +.Sy off +.It Sy yield +Thread yields the cpu when the fail point is evaluated +.It Sy delay +Similar to sleep, but busy waits the cpu. +(Useful in non-sleepable contexts.) +.El +.Pp +The <pct>% and <cnt>* modifiers prior to <type> control when +<type> is executed. +The <pct>% form (e.g. "1.2%") can be used to specify a +probability that <type> will execute. +This is a decimal in the range (0, 100] which can specify up to +1/10,000% precision. +The <cnt>* 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". +.Pp +The operator -> can be used to express cascading terms. +If you specify <term1>-><term2>, it means that if <term1> does not +.Ql execute , +<term2> is evaluated. +For the purpose of this operator, the +.Fn return +and +.Fn print +operators are the only types that cascade. +A +.Fn return +term only cascades if the code executes, and a +.Fn print +term only cascades when passed a non-zero argument. +A pid can optionally be specified. +The fail point term is only executed when invoked by a process with a +matching p_pid. +.Sh EXAMPLES +.Bl -tag -width Sy +.It Sy sysctl debug.fail_point.foobar="2.1%return(5)" +21/1000ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +.It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)" +2/100ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +If that does not happen, 5% of the time execute +.Fa code +with RETURN_VALUE set to 22. +.It Sy 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. +.It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)" +Return 5 for 1 in 1000 executions, but only 5 times total. +.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" +1/100th of the time, sleep 50ms. +.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" +Return 5 once, when pid 1234 executes the fail point. +.El +.Sh AUTHORS +.An -nosplit +This manual page was written by +.Pp +.An Matthew Bryan Aq Mt matthew.bryan@isilon.com +and +.Pp +.An Zach Loafman Aq Mt zml@FreeBSD.org . +.Sh 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 +.Fn malloc +to fail consistently is potentially harmful to uptime. +.Pp +The +.Fn sleep +sysctl setting may not be appropriate in all situations. +Currently, +.Fn fail_point_eval +does not verify whether the context is appropriate for calling +.Fn msleep . +You can force it to evaluate a +.Sy sleep +action as a +.Sy delay +action by specifying the +.Sy FAIL_POINT_NONSLEEPABLE +flag at the point the fail point is declared. |