Copyright (c) 2009 Isilon Inc 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.
$FreeBSD: releng/10.2/share/man/man9/fail.9 235373 2012-05-12 20:46:19Z gjb $
.Dd May 10, 2009 .Dt FAIL 9 .Os .Sh NAME .Nm KFAIL_POINT_CODE , .Nm KFAIL_POINT_RETURN , .Nm KFAIL_POINT_RETURN_VOID , .Nm KFAIL_POINT_ERROR , .Nm KFAIL_POINT_GOTO , .Nm fail_point , .Nm DEBUG_FP .Nd fail points .Sh SYNOPSIS n sys/fail.h .Fn KFAIL_POINT_CODE "parent" "name" "code" .Fn KFAIL_POINT_RETURN "parent" "name" .Fn KFAIL_POINT_RETURN_VOID "parent" "name" .Fn KFAIL_POINT_ERROR "parent" "name" "error_var" .Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" .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.
p 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. See .Sx SYSCTL VARIABLES below.
p The remaining .Fn KFAIL_POINT_* macros are wrappers around common error injection paths: l -inset t Fn KFAIL_POINT_RETURN parent name is the equivalent of .Sy KFAIL_POINT_CODE(..., return RETURN_VALUE) t Fn KFAIL_POINT_RETURN_VOID parent name is the equivalent of .Sy KFAIL_POINT_CODE(..., return) t Fn KFAIL_POINT_ERROR parent name error_var is the equivalent of .Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) t Fn KFAIL_POINT_GOTO parent name error_var label is the equivalent of .Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) .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 ) .
p The sysctl variable may be set using the following grammar: d -literal <fail_point> :: <term> ( "->" <term> )* <term> :: ( (<float> "%") | (<integer> "*" ) )* <type> [ "(" <integer> ")" ] [ "[pid " <integer> "]" ] <float> :: <integer> [ "." <integer> ] | "." <integer> <type> :: "off" | "return" | "sleep" | "panic" | "break" | "print" .Ed
p The <type> argument specifies which action to take: l -tag -width ".Dv return" t Sy off Take no action (does not trigger fail point code) t Sy return Trigger fail point code with specified argument t Sy sleep Sleep the specified number of milliseconds t Sy panic Panic t Sy break Break into the debugger, or trap if there is no debugger support t Sy print Print that the fail point executed .El
p 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".
p 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 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. 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 l -tag -width Sy t Sy sysctl debug.fail_point.foobar="2.1%return(5)" 21/1000ths of the time, execute .Fa code with RETURN_VALUE set to 5. t 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. t 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. t Sy sysctl debug.fail_point.foobar="0.1%5*return(5)" Return 5 for 1 in 1000 executions, but only 5 times total. t Sy sysctl debug.fail_point.foobar="1%*sleep(50)" 1/100th of the time, sleep 50ms. t 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 .An Zach Loafman Aq 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.
p 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 .