Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/fail.9
Show All 20 Lines | |||||
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | ||||
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH | ||||
.\" DAMAGE. | .\" DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd May 10, 2009 | .Dd February 02, 2016 | ||||
.Dt FAIL 9 | .Dt FAIL 9 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm KFAIL_POINT_CODE , | .Nm KFAIL_POINT_CODE , | ||||
.Nm KFAIL_POINT_CODE_FLAGS , | |||||
.Nm KFAIL_POINT_CODE_COND , | |||||
.Nm KFAIL_POINT_RETURN , | .Nm KFAIL_POINT_RETURN , | ||||
.Nm KFAIL_POINT_RETURN_VOID , | .Nm KFAIL_POINT_RETURN_VOID , | ||||
.Nm KFAIL_POINT_ERROR , | .Nm KFAIL_POINT_ERROR , | ||||
.Nm KFAIL_POINT_GOTO , | .Nm KFAIL_POINT_GOTO , | ||||
.Nm KFAIL_POINT_SLEEP_CALLBACKS , | |||||
.Nm fail_point , | .Nm fail_point , | ||||
.Nm DEBUG_FP | .Nm DEBUG_FP | ||||
.Nd fail points | .Nd fail points | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In sys/fail.h | .In sys/fail.h | ||||
.Fn KFAIL_POINT_CODE "parent" "name" "code" | .Fn KFAIL_POINT_CODE "parent" "name" "code" | ||||
.Fn KFAIL_POINT_CODE_FLAGS "parent" "name" "flags" "code" | |||||
.Fn KFAIL_POINT_CODE_COND "parent" "name" "cond" "flags" "code" | |||||
.Fn KFAIL_POINT_RETURN "parent" "name" | .Fn KFAIL_POINT_RETURN "parent" "name" | ||||
.Fn KFAIL_POINT_RETURN_VOID "parent" "name" | .Fn KFAIL_POINT_RETURN_VOID "parent" "name" | ||||
.Fn KFAIL_POINT_ERROR "parent" "name" "error_var" | .Fn KFAIL_POINT_ERROR "parent" "name" "error_var" | ||||
.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" | .Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" | ||||
.Fn KFAIL_POINT_SLEEP_CALLBACKS "parent" "name" "pre_func" "pre_arg" "post_func" "post_arg" "code" | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
Fail points are used to add code points where errors may be injected | Fail points are used to add code points where errors may be injected | ||||
in a user controlled fashion. | in a user controlled fashion. | ||||
Fail points provide a convenient wrapper around user-provided error | Fail points provide a convenient wrapper around user-provided error | ||||
injection code, providing a | injection code, providing a | ||||
.Xr sysctl 9 | .Xr sysctl 9 | ||||
MIB, and a parser for that MIB that describes how the error | MIB, and a parser for that MIB that describes how the error | ||||
injection code should fire. | injection code should fire. | ||||
Show All 16 Lines | |||||
use braces for any multi-line code arguments. | use braces for any multi-line code arguments. | ||||
Inside the | Inside the | ||||
.Fa code | .Fa code | ||||
argument, the evaluation of | argument, the evaluation of | ||||
.Sy RETURN_VALUE | .Sy RETURN_VALUE | ||||
is derived from the | is derived from the | ||||
.Fn return | .Fn return | ||||
value set in the sysctl MIB. | value set in the sysctl MIB. | ||||
.Pp | |||||
Additionally, | |||||
.Fn KFAIL_POINT_CODE_FLAGS | |||||
provides a | |||||
.Fa flags | |||||
argument which controls the fail point's behaviour. | |||||
This can be used to e.g., mark the fail point's context as non-sleepable, | |||||
which causes the | |||||
.Sy sleep | |||||
action to be coerced to a busy wait. | |||||
The supported flags are: | |||||
.Bl -ohang -offset indent | |||||
.It FAIL_POINT_USE_TIMEOUT_PATH | |||||
Rather than sleeping on a | |||||
.Fn sleep | |||||
call, just fire the post-sleep function after a timeout fires. | |||||
.It FAIL_POINT_NONSLEEPABLE | |||||
Mark the fail point as being in a non-sleepable context, which coerces | |||||
.Fn sleep | |||||
calls to | |||||
.Fn delay | |||||
calls. | |||||
.El | |||||
.Pp | |||||
Likewise, | |||||
.Fn KFAIL_POINT_CODE_COND | |||||
supplies a | |||||
.Fa cond | |||||
argument, which allows you to set the condition under which the fail point's | |||||
code may fire. | |||||
This is equivalent to: | |||||
.Bd -literal | |||||
if (cond) | |||||
KFAIL_POINT_CODE_FLAGS(...); | |||||
.Ed | |||||
See | See | ||||
.Sx SYSCTL VARIABLES | .Sx SYSCTL VARIABLES | ||||
below. | below. | ||||
.Pp | .Pp | ||||
The remaining | The remaining | ||||
.Fn KFAIL_POINT_* | .Fn KFAIL_POINT_* | ||||
macros are wrappers around common error injection paths: | macros are wrappers around common error injection paths: | ||||
.Bl -inset | .Bl -inset | ||||
Show All 14 Lines | |||||
The | The | ||||
.Fn KFAIL_POINT_* | .Fn KFAIL_POINT_* | ||||
macros add sysctl MIBs where specified. | macros add sysctl MIBs where specified. | ||||
Many base kernel MIBs can be found in the | Many base kernel MIBs can be found in the | ||||
.Sy debug.fail_point | .Sy debug.fail_point | ||||
tree (referenced in code by | tree (referenced in code by | ||||
.Sy DEBUG_FP ) . | .Sy DEBUG_FP ) . | ||||
.Pp | .Pp | ||||
The sysctl variable may be set using the following grammar: | The sysctl variable may be set in a number of ways: | ||||
.Bd -literal | .Bd -literal | ||||
<fail_point> :: | [<pct>%][<cnt>*]<type>[(args...)][-><more terms>] | ||||
<term> ( "->" <term> )* | |||||
<term> :: | |||||
( (<float> "%") | (<integer> "*" ) )* | |||||
<type> | |||||
[ "(" <integer> ")" ] | |||||
[ "[pid " <integer> "]" ] | |||||
<float> :: | |||||
<integer> [ "." <integer> ] | | |||||
"." <integer> | |||||
<type> :: | |||||
"off" | "return" | "sleep" | "panic" | "break" | "print" | |||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
The <type> argument specifies which action to take: | The <type> argument specifies which action to take; it can be one of: | ||||
.Bl -tag -width ".Dv return" | .Bl -tag -width ".Dv return" | ||||
.It Sy off | .It Sy off | ||||
Take no action (does not trigger fail point code) | Take no action (does not trigger fail point code) | ||||
.It Sy return | .It Sy return | ||||
Trigger fail point code with specified argument | Trigger fail point code with specified argument | ||||
.It Sy sleep | .It Sy sleep | ||||
Sleep the specified number of milliseconds | Sleep the specified number of milliseconds | ||||
.It Sy panic | .It Sy panic | ||||
Panic | Panic | ||||
.It Sy break | .It Sy break | ||||
Break into the debugger, or trap if there is no debugger support | Break into the debugger, or trap if there is no debugger support | ||||
.It Sy print | .It Sy print | ||||
Print that the fail point executed | Print that the fail point executed | ||||
.It Sy pause | |||||
Threads sleep at the fail point until the fail point is set to | |||||
.Sy off | |||||
.It Sy yield | |||||
Thread yields the cpu when the fail point is evaluated | |||||
.It Sy delay | |||||
Similar to sleep, but busy waits the cpu. | |||||
(Useful in non-sleepable contexts.) | |||||
.El | .El | ||||
.Pp | .Pp | ||||
The <float>% and <integer>* modifiers prior to <type> control when | The <pct>% and <cnt>* modifiers prior to <type> control when | ||||
<type> is executed. | <type> is executed. | ||||
The <float>% form (e.g. "1.2%") can be used to specify a | The <pct>% form (e.g. "1.2%") can be used to specify a | ||||
probability that <type> will execute. | probability that <type> will execute. | ||||
The <integer>* form (e.g. "5*") can be used to specify the number of | This is a decimal in the range (0, 100] which can specify up to | ||||
1/10,000% precision. | |||||
The <cnt>* form (e.g. "5*") can be used to specify the number of | |||||
times <type> should be executed before this <term> is disabled. | times <type> should be executed before this <term> is disabled. | ||||
Only the last probability and the last count are used if multiple | Only the last probability and the last count are used if multiple | ||||
are specified, i.e. "1.2%2%" is the same as "2%". | are specified, i.e. "1.2%2%" is the same as "2%". | ||||
When both a probability and a count are specified, the probability | When both a probability and a count are specified, the probability | ||||
is evaluated before the count, i.e. "2%5*" means "2% of the time, | is evaluated before the count, i.e. "2%5*" means "2% of the time, | ||||
but only 5 times total". | but only 5 times total". | ||||
.Pp | .Pp | ||||
The operator -> can be used to express cascading terms. | The operator -> can be used to express cascading terms. | ||||
Show All 28 Lines | |||||
.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" | .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" | ||||
1/100th of the time, sleep 50ms. | 1/100th of the time, sleep 50ms. | ||||
.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" | .It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" | ||||
Return 5 once, when pid 1234 executes the fail point. | Return 5 once, when pid 1234 executes the fail point. | ||||
.El | .El | ||||
.Sh AUTHORS | .Sh AUTHORS | ||||
.An -nosplit | .An -nosplit | ||||
This manual page was written by | This manual page was written by | ||||
.Pp | |||||
.An Matthew Bryan Aq Mt matthew.bryan@isilon.com | |||||
and | |||||
.Pp | |||||
.An Zach Loafman Aq Mt zml@FreeBSD.org . | .An Zach Loafman Aq Mt zml@FreeBSD.org . | ||||
.Sh CAVEATS | .Sh CAVEATS | ||||
It is easy to shoot yourself in the foot by setting fail points too | It is easy to shoot yourself in the foot by setting fail points too | ||||
aggressively or setting too many in combination. | aggressively or setting too many in combination. | ||||
For example, forcing | For example, forcing | ||||
.Fn malloc | .Fn malloc | ||||
to fail consistently is potentially harmful to uptime. | to fail consistently is potentially harmful to uptime. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn sleep | .Fn sleep | ||||
sysctl setting may not be appropriate in all situations. | sysctl setting may not be appropriate in all situations. | ||||
Currently, | Currently, | ||||
.Fn fail_point_eval | .Fn fail_point_eval | ||||
does not verify whether the context is appropriate for calling | does not verify whether the context is appropriate for calling | ||||
.Fn msleep . | .Fn msleep . | ||||
You can force it to evaluate a | |||||
.Sy sleep | |||||
action as a | |||||
.Sy delay | |||||
action by specifying the | |||||
.Sy FAIL_POINT_NONSLEEPABLE | |||||
flag at the point the fail point is declared. |