2 .\" Copyright (c) 2009 Isilon Inc http://www.isilon.com/
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice(s), this list of conditions and the following disclaimer as
9 .\" the first lines of this file unmodified other than the possible
10 .\" addition of one or more copyright notices.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice(s), this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
33 .Nm KFAIL_POINT_CODE ,
34 .Nm KFAIL_POINT_RETURN ,
35 .Nm KFAIL_POINT_RETURN_VOID ,
36 .Nm KFAIL_POINT_ERROR ,
37 .Nm KFAIL_POINT_GOTO ,
43 .Fn KFAIL_POINT_CODE "parent" "name" "code"
44 .Fn KFAIL_POINT_RETURN "parent" "name"
45 .Fn KFAIL_POINT_RETURN_VOID "parent" "name"
46 .Fn KFAIL_POINT_ERROR "parent" "name" "error_var"
47 .Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label"
49 Fail points are used to add code points where errors may be injected
50 in a user controlled fashion.
51 Fail points provide a convenient wrapper around user-provided error
52 injection code, providing a
54 MIB, and a parser for that MIB that describes how the error
55 injection code should fire.
57 The base fail point macro is
61 is a sysctl tree (frequently
63 for kernel fail points, but various subsystems may wish to provide
64 their own fail point trees), and
66 is the name of the MIB in that tree, and
68 is the error injection code.
71 argument does not require braces, but it is considered good style to
72 use braces for any multi-line code arguments.
75 argument, the evaluation of
79 value set in the sysctl MIB.
86 macros are wrappers around common error injection paths:
88 .It Fn KFAIL_POINT_RETURN parent name
90 .Sy KFAIL_POINT_CODE(..., return RETURN_VALUE)
91 .It Fn KFAIL_POINT_RETURN_VOID parent name
93 .Sy KFAIL_POINT_CODE(..., return)
94 .It Fn KFAIL_POINT_ERROR parent name error_var
96 .Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE)
97 .It Fn KFAIL_POINT_GOTO parent name error_var label
99 .Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;})
104 macros add sysctl MIBs where specified.
105 Many base kernel MIBs can be found in the
107 tree (referenced in code by
110 The sysctl variable may be set using the following grammar:
113 <term> ( "->" <term> )*
116 ( (<float> "%") | (<integer> "*" ) )*
118 [ "(" <integer> ")" ]
119 [ "[pid " <integer> "]" ]
122 <integer> [ "." <integer> ] |
126 "off" | "return" | "sleep" | "panic" | "break" | "print"
129 The <type> argument specifies which action to take:
130 .Bl -tag -width ".Dv return"
132 Take no action (does not trigger fail point code)
134 Trigger fail point code with specified argument
136 Sleep the specified number of milliseconds
140 Break into the debugger, or trap if there is no debugger support
142 Print that the fail point executed
145 The <float>% and <integer>* modifiers prior to <type> control when
147 The <float>% form (e.g. "1.2%") can be used to specify a
148 probability that <type> will execute.
149 The <integer>* form (e.g. "5*") can be used to specify the number of
150 times <type> should be executed before this <term> is disabled.
151 Only the last probability and the last count are used if multiple
152 are specified, i.e. "1.2%2%" is the same as "2%".
153 When both a probability and a count are specified, the probability
154 is evaluated before the count, i.e. "2%5*" means "2% of the time,
155 but only 5 times total".
157 The operator -> can be used to express cascading terms.
158 If you specify <term1>-><term2>, it means that if <term1> does not
160 <term2> is evaluated.
161 For the purpose of this operator, the return() and print() operators
162 are the only types that cascade.
163 A return() term only cascades if the code executes, and a print()
164 term only cascades when passed a non-zero argument.
165 A pid can optionally be specified.
166 The fail point term is only executed when invoked by a process with a
171 .It Sy sysctl debug.fail_point.foobar="2.1%return(5)"
172 21/1000ths of the time, execute
174 with RETURN_VALUE set to 5.
175 .It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"
176 2/100ths of the time, execute
178 with RETURN_VALUE set to 5.
179 If that does not happen, 5% of the time execute
181 with RETURN_VALUE set to 22.
182 .It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)"
183 For 5 times, return 5.
184 After that, 1/1000th of the time, return 22.
185 .It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)"
186 Return 5 for 1 in 1000 executions, but only 5 times total.
187 .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)"
188 1/100th of the time, sleep 50ms.
189 .It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]"
190 Return 5 once, when pid 1234 executes the fail point.
194 This manual page was written by
195 .An Zach Loafman Aq zml@FreeBSD.org .
197 It is easy to shoot yourself in the foot by setting fail points too
198 aggressively or setting too many in combination.
201 to fail consistently is potentially harmful to uptime.
205 sysctl setting may not be appropriate in all situations.
208 does not verify whether the context is appropriate for calling