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