diff --git a/share/man/man9/fail.9 b/share/man/man9/fail.9 index bd24b8cc5551..ce43346b7a14 100644 --- a/share/man/man9/fail.9 +++ b/share/man/man9/fail.9 @@ -37,7 +37,6 @@ .Nm KFAIL_POINT_GOTO , .Nm fail_point , .Nm DEBUG_FP -. .Nd fail points .Sh SYNOPSIS .In sys/fail.h @@ -79,7 +78,7 @@ is derived from the .Fn return value set in the sysctl MIB. See -.Sx SYSCTL SETTINGS +.Sx SYSCTL VARIABLES below. .Pp The remaining @@ -100,7 +99,6 @@ is the equivalent of .Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) .El -.Pp .Sh SYSCTL VARIABLES The .Fn KFAIL_POINT_* @@ -108,28 +106,28 @@ macros add sysctl MIBs where specified. Many base kernel MIBs can be found in the .Sy debug.fail_point tree (referenced in code by -.Sy DEBUG_FP -). +.Sy DEBUG_FP ) . .Pp The sysctl variable may be set using the following grammar: .Pp +.Bd -literal :: ( "->" )* -.Pp + :: ( ( "%") | ( "*" ) )* [ "(" ")" ] -.Pp + :: [ "." ] | "." -.Pp + :: "off" | "return" | "sleep" | "panic" | "break" | "print" +.Ed .Pp -The -argument specifies which action to take: +The argument specifies which action to take: .Bl -tag -width ".Dv return" .It Sy off Take no action (does not trigger fail point code) @@ -158,13 +156,13 @@ is evaluated before the count, i.e. "2%5*" means "2% of the time, but only 5 times total". .Pp The operator -> can be used to express cascading terms. -If you specify ->, it means that if doesn't -'execute', is evaluated. +If you specify ->, it means that if does not +.Ql execute , + is evaluated. For the purpose of this operator, the return() and print() operators are the only types that cascade. A return() term only cascades if the code executes, and a print() term only cascades when passed a non-zero argument. -.Pp .Sh EXAMPLES .Bl -tag .It Sy sysctl debug.fail_point.foobar="2.1%return(5)" @@ -175,7 +173,7 @@ with RETURN_VALUE set to 5. 2/100ths of the time, execute .Fa code with RETURN_VALUE set to 5. -If that doesn't happen, 5% of the time execute +If that does not happen, 5% of the time execute .Fa code with RETURN_VALUE set to 22. .It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)" @@ -186,9 +184,8 @@ Return 5 for 1 in 1000 executions, but only 5 times total. .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" 1/100th of the time, sleep 50ms. .El -.Pp .Sh CAVEATS -It's 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. For example, forcing .Fn malloc @@ -201,7 +198,6 @@ Currently, .Fn fail_point_eval does not verify whether the context is appropriate for calling .Fn msleep . -.Pp .Sh AUTHORS .An -nosplit This manual page was written by