| fail.9 (246e7a2b6494cd991b08ac669ed761ecea0cc98c) | fail.9 (70e20d4e1a6b23cb7bd8b869d1ff782c590f0fa8) |
|---|---|
| 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 --- 12 unchanged lines hidden (view full) --- 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.\" | 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 --- 12 unchanged lines hidden (view full) --- 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 | 29.Dd February 02, 2016 |
| 30.Dt FAIL 9 31.Os 32.Sh NAME 33.Nm KFAIL_POINT_CODE , | 30.Dt FAIL 9 31.Os 32.Sh NAME 33.Nm KFAIL_POINT_CODE , |
| 34.Nm KFAIL_POINT_CODE_FLAGS , 35.Nm KFAIL_POINT_CODE_COND , |
|
| 34.Nm KFAIL_POINT_RETURN , 35.Nm KFAIL_POINT_RETURN_VOID , 36.Nm KFAIL_POINT_ERROR , 37.Nm KFAIL_POINT_GOTO , | 36.Nm KFAIL_POINT_RETURN , 37.Nm KFAIL_POINT_RETURN_VOID , 38.Nm KFAIL_POINT_ERROR , 39.Nm KFAIL_POINT_GOTO , |
| 40.Nm KFAIL_POINT_SLEEP_CALLBACKS , |
|
| 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" | 41.Nm fail_point , 42.Nm DEBUG_FP 43.Nd fail points 44.Sh SYNOPSIS 45.In sys/fail.h 46.Fn KFAIL_POINT_CODE "parent" "name" "code" |
| 47.Fn KFAIL_POINT_CODE_FLAGS "parent" "name" "flags" "code" 48.Fn KFAIL_POINT_CODE_COND "parent" "name" "cond" "flags" "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.Fn KFAIL_POINT_RETURN "parent" "name" 50.Fn KFAIL_POINT_RETURN_VOID "parent" "name" 51.Fn KFAIL_POINT_ERROR "parent" "name" "error_var" 52.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" |
| 53.Fn KFAIL_POINT_SLEEP_CALLBACKS "parent" "name" "pre_func" "pre_arg" "post_func" "post_arg" "code" |
|
| 48.Sh DESCRIPTION 49Fail points are used to add code points where errors may be injected 50in a user controlled fashion. 51Fail points provide a convenient wrapper around user-provided error 52injection code, providing a 53.Xr sysctl 9 54MIB, and a parser for that MIB that describes how the error 55injection code should fire. --- 16 unchanged lines hidden (view full) --- 72use braces for any multi-line code arguments. 73Inside the 74.Fa code 75argument, the evaluation of 76.Sy RETURN_VALUE 77is derived from the 78.Fn return 79value set in the sysctl MIB. | 54.Sh DESCRIPTION 55Fail points are used to add code points where errors may be injected 56in a user controlled fashion. 57Fail points provide a convenient wrapper around user-provided error 58injection code, providing a 59.Xr sysctl 9 60MIB, and a parser for that MIB that describes how the error 61injection code should fire. --- 16 unchanged lines hidden (view full) --- 78use braces for any multi-line code arguments. 79Inside the 80.Fa code 81argument, the evaluation of 82.Sy RETURN_VALUE 83is derived from the 84.Fn return 85value set in the sysctl MIB. |
| 86.Pp 87Additionally, 88.Fn KFAIL_POINT_CODE_FLAGS 89provides a 90.Fa flags 91argument which controls the fail point's behaviour. 92This can be used to e.g., mark the fail point's context as non-sleepable, 93which causes the 94.Sy sleep 95action to be coerced to a busy wait. 96The supported flags are: 97.Bl -ohang -offset indent 98.It FAIL_POINT_USE_TIMEOUT_PATH 99Rather than sleeping on a 100.Fn sleep 101call, just fire the post-sleep function after a timeout fires. 102.It FAIL_POINT_NONSLEEPABLE 103Mark the fail point as being in a non-sleepable context, which coerces 104.Fn sleep 105calls to 106.Fn delay 107calls. 108.El 109.Pp 110Likewise, 111.Fn KFAIL_POINT_CODE_COND 112supplies a 113.Fa cond 114argument, which allows you to set the condition under which the fail point's 115code may fire. 116This is equivalent to: 117.Bd -literal 118 if (cond) 119 KFAIL_POINT_CODE_FLAGS(...); 120 121.Ed |
|
| 80See 81.Sx SYSCTL VARIABLES 82below. 83.Pp 84The remaining 85.Fn KFAIL_POINT_* 86macros are wrappers around common error injection paths: 87.Bl -inset --- 14 unchanged lines hidden (view full) --- 102The 103.Fn KFAIL_POINT_* 104macros add sysctl MIBs where specified. 105Many base kernel MIBs can be found in the 106.Sy debug.fail_point 107tree (referenced in code by 108.Sy DEBUG_FP ) . 109.Pp | 122See 123.Sx SYSCTL VARIABLES 124below. 125.Pp 126The remaining 127.Fn KFAIL_POINT_* 128macros are wrappers around common error injection paths: 129.Bl -inset --- 14 unchanged lines hidden (view full) --- 144The 145.Fn KFAIL_POINT_* 146macros add sysctl MIBs where specified. 147Many base kernel MIBs can be found in the 148.Sy debug.fail_point 149tree (referenced in code by 150.Sy DEBUG_FP ) . 151.Pp |
| 110The sysctl variable may be set using the following grammar: | 152The sysctl variable may be set in a number of ways: |
| 111.Bd -literal | 153.Bd -literal |
| 112 <fail_point> :: 113 <term> ( "->" <term> )* 114 115 <term> :: 116 ( (<float> "%") | (<integer> "*" ) )* 117 <type> 118 [ "(" <integer> ")" ] 119 [ "[pid " <integer> "]" ] 120 121 <float> :: 122 <integer> [ "." <integer> ] | 123 "." <integer> 124 125 <type> :: 126 "off" | "return" | "sleep" | "panic" | "break" | "print" | 154 [<pct>%][<cnt>*]<type>[(args...)][-><more terms>] |
| 127.Ed 128.Pp | 155.Ed 156.Pp |
| 129The <type> argument specifies which action to take: | 157The <type> argument specifies which action to take; it can be one of: |
| 130.Bl -tag -width ".Dv return" 131.It Sy off 132Take no action (does not trigger fail point code) 133.It Sy return 134Trigger fail point code with specified argument 135.It Sy sleep 136Sleep the specified number of milliseconds 137.It Sy panic 138Panic 139.It Sy break 140Break into the debugger, or trap if there is no debugger support 141.It Sy print 142Print that the fail point executed | 158.Bl -tag -width ".Dv return" 159.It Sy off 160Take no action (does not trigger fail point code) 161.It Sy return 162Trigger fail point code with specified argument 163.It Sy sleep 164Sleep the specified number of milliseconds 165.It Sy panic 166Panic 167.It Sy break 168Break into the debugger, or trap if there is no debugger support 169.It Sy print 170Print that the fail point executed |
| 171.It Sy pause 172Threads sleep at the fail point until the fail point is set to 173.Sy off 174.It Sy yield 175Thread yields the cpu when the fail point is evaluated 176.It Sy delay 177Similar to sleep, but busy waits the cpu. 178(Useful in non-sleepable contexts.) |
|
| 143.El 144.Pp | 179.El 180.Pp |
| 145The <float>% and <integer>* modifiers prior to <type> control when | 181The <pct>% and <cnt>* modifiers prior to <type> control when |
| 146<type> is executed. | 182<type> is executed. |
| 147The <float>% form (e.g. "1.2%") can be used to specify a | 183The <pct>% form (e.g. "1.2%") can be used to specify a |
| 148probability that <type> will execute. | 184probability that <type> will execute. |
| 149The <integer>* form (e.g. "5*") can be used to specify the number of | 185This is a decimal in the range (0, 100] which can specify up to 1861/10,000% precision. 187The <cnt>* form (e.g. "5*") can be used to specify the number of |
| 150times <type> should be executed before this <term> is disabled. 151Only the last probability and the last count are used if multiple 152are specified, i.e. "1.2%2%" is the same as "2%". 153When both a probability and a count are specified, the probability 154is evaluated before the count, i.e. "2%5*" means "2% of the time, 155but only 5 times total". 156.Pp 157The operator -> can be used to express cascading terms. --- 28 unchanged lines hidden (view full) --- 186.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" 1871/100th of the time, sleep 50ms. 188.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" 189Return 5 once, when pid 1234 executes the fail point. 190.El 191.Sh AUTHORS 192.An -nosplit 193This manual page was written by | 188times <type> should be executed before this <term> is disabled. 189Only the last probability and the last count are used if multiple 190are specified, i.e. "1.2%2%" is the same as "2%". 191When both a probability and a count are specified, the probability 192is evaluated before the count, i.e. "2%5*" means "2% of the time, 193but only 5 times total". 194.Pp 195The operator -> can be used to express cascading terms. --- 28 unchanged lines hidden (view full) --- 224.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" 2251/100th of the time, sleep 50ms. 226.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" 227Return 5 once, when pid 1234 executes the fail point. 228.El 229.Sh AUTHORS 230.An -nosplit 231This manual page was written by |
| 232.Pp 233.An Matthew Bryan Aq Mt matthew.bryan@isilon.com 234and 235.Pp |
|
| 194.An Zach Loafman Aq Mt zml@FreeBSD.org . 195.Sh CAVEATS 196It is easy to shoot yourself in the foot by setting fail points too 197aggressively or setting too many in combination. 198For example, forcing 199.Fn malloc 200to fail consistently is potentially harmful to uptime. 201.Pp 202The 203.Fn sleep 204sysctl setting may not be appropriate in all situations. 205Currently, 206.Fn fail_point_eval 207does not verify whether the context is appropriate for calling 208.Fn msleep . | 236.An Zach Loafman Aq Mt zml@FreeBSD.org . 237.Sh CAVEATS 238It is easy to shoot yourself in the foot by setting fail points too 239aggressively or setting too many in combination. 240For example, forcing 241.Fn malloc 242to fail consistently is potentially harmful to uptime. 243.Pp 244The 245.Fn sleep 246sysctl setting may not be appropriate in all situations. 247Currently, 248.Fn fail_point_eval 249does not verify whether the context is appropriate for calling 250.Fn msleep . |
| 251You can force it to evaluate a 252.Sy sleep 253action as a 254.Sy delay 255action by specifying the 256.Sy FAIL_POINT_NONSLEEPABLE 257flag at the point the fail point is declared. |
|