share/man/man9/fail.9

   1 .\"
   2 .\" Copyright (c) 2009 Isilon Inc http://www.isilon.com/
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  14 .\"
  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
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd May 10, 2009
  30 .Dt FAIL 9
  31 .Os
  32 .Sh NAME
  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 ,
  38 .Nm fail_point ,
  39 .Nm DEBUG_FP
  40 .Nd fail points
  41 .Sh SYNOPSIS
  42 .In sys/fail.h
  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"
  48 .Sh DESCRIPTION
  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
  53 .Xr sysctl 9
  54 MIB, and a parser for that MIB that describes how the error
  55 injection code should fire.
  56 .Pp
  57 The base fail point macro is
  58 .Fn KFAIL_POINT_CODE
  59 where
  60 .Fa parent
  61 is a sysctl tree (frequently
  62 .Sy DEBUG_FP
  63 for kernel fail points, but various subsystems may wish to provide
  64 their own fail point trees), and
  65 .Fa name
  66 is the name of the MIB in that tree, and
  67 .Fa code
  68 is the error injection code.
  69 The
  70 .Fa code
  71 argument does not require braces, but it is considered good style to
  72 use braces for any multi-line code arguments.
  73 Inside the
  74 .Fa code
  75 argument, the evaluation of
  76 .Sy RETURN_VALUE
  77 is derived from the
  78 .Fn return
  79 value set in the sysctl MIB.
  80 See
  81 .Sx SYSCTL VARIABLES
  82 below.
  83 .Pp
  84 The remaining
  85 .Fn KFAIL_POINT_*
  86 macros are wrappers around common error injection paths:
  87 .Bl -tag -width 8
  88 .It Fn KFAIL_POINT_RETURN parent name
  89 is the equivalent of
  90 .Sy KFAIL_POINT_CODE(..., return RETURN_VALUE)
  91 .It Fn KFAIL_POINT_RETURN_VOID parent name
  92 is the equivalent of
  93 .Sy KFAIL_POINT_CODE(..., return)
  94 .It Fn KFAIL_POINT_ERROR parent name error_var
  95 is the equivalent of
  96 .Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE)
  97 .It Fn KFAIL_POINT_GOTO parent name error_var label
  98 is the equivalent of
  99 .Sy KFAIL_POINT_CODE(...,
 100   { error_var = RETURN_VALUE; goto label;})
 101 .El
 102 .Sh SYSCTL VARIABLES
 103 The
 104 .Fn KFAIL_POINT_*
 105 macros add sysctl MIBs where specified.
 106 Many base kernel MIBs can be found in the
 107 .Sy debug.fail_point
 108 tree (referenced in code by
 109 .Sy DEBUG_FP ) .
 110 .Pp
 111 The sysctl variable may be set using the following grammar:
 112 .Pp
 113 .Bd -literal
 114   <fail_point> ::
 115       <term> ( "->" <term> )*
 116
 117   <term> ::
 118       ( (<float> "%") | (<integer> "*" ) )*
 119       <type>
 120       [ "(" <integer> ")" ]
 121
 122   <float> ::
 123       <integer> [ "." <integer> ] |
 124       "." <integer>
 125
 126   <type> ::
 127       "off" | "return" | "sleep" | "panic" | "break" | "print"
 128 .Ed
 129 .Pp
 130 The <type> argument specifies which action to take:
 131 .Bl -tag -width ".Dv return"
 132 .It Sy off
 133 Take no action (does not trigger fail point code)
 134 .It Sy return
 135 Trigger fail point code with specified argument
 136 .It Sy sleep
 137 Sleep the specified number of milliseconds
 138 .It Sy panic
 139 Panic
 140 .It Sy break
 141 Break into the debugger, or trap if there is no debugger support
 142 .It Sy print
 143 Print that the fail point executed
 144 .El
 145 .Pp
 146 The <float>% and <integer>* modifiers prior to <type> control when
 147 <type> is executed.
 148 The <float>% form (e.g. "1.2%") can be used to specify a
 149 probability that <type> will execute.
 150 The <integer>* form (e.g. "5*") can be used to specify the number of
 151 times <type> should be executed before this <term> is disabled.
 152 Only the last probability and the last count are used if multiple
 153 are specified, i.e. "1.2%2%" is the same as "2%".
 154 When both a probability and a count are specified, the probability
 155 is evaluated before the count, i.e. "2%5*" means "2% of the time,
 156 but only 5 times total".
 157 .Pp
 158 The operator -> can be used to express cascading terms.
 159 If you specify <term1>-><term2>, it means that if <term1> does not
 160 .Ql execute ,
 161 <term2> is evaluated.
 162 For the purpose of this operator, the return() and print() operators
 163 are the only types that cascade.
 164 A return() term only cascades if the code executes, and a print()
 165 term only cascades when passed a non-zero argument.
 166 .Sh EXAMPLES
 167 .Bl -tag
 168 .It Sy sysctl debug.fail_point.foobar="2.1%return(5)"
 169 21/1000ths of the time, execute
 170 .Fa code
 171 with RETURN_VALUE set to 5.
 172 .It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"
 173 2/100ths of the time, execute
 174 .Fa code
 175 with RETURN_VALUE set to 5.
 176 If that does not happen, 5% of the time execute
 177 .Fa code
 178 with RETURN_VALUE set to 22.
 179 .It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)"
 180 For 5 times, return 5.
 181 After that, 1/1000th of the time, return 22.
 182 .It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)"
 183 Return 5 for 1 in 1000 executions, but only 5 times total.
 184 .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)"
 185 1/100th of the time, sleep 50ms.
 186 .El
 187 .Sh CAVEATS
 188 It is easy to shoot yourself in the foot by setting fail points too
 189 aggressively or setting too many in combination.
 190 For example, forcing
 191 .Fn malloc
 192 to fail consistently is potentially harmful to uptime.
 193 .Pp
 194 The
 195 .Fn sleep
 196 sysctl setting may not be appropriate in all situations.
 197 Currently,
 198 .Fn fail_point_eval
 199 does not verify whether the context is appropriate for calling
 200 .Fn msleep .
 201 .Sh AUTHORS
 202 .An -nosplit
 203 This manual page was written by
 204 .An Zach Loafman Aq zml@FreeBSD.org .