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