Date: Wed, 27 May 2009 20:30:29 -0700 From: Zachary Loafman <zml@FreeBSD.org> To: Ben Kaduk <minimarmot@gmail.com> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, dfr@freebsd.org Subject: Re: Review: fail(9) style/grammar (was Re: svn commit: r192908 ...) Message-ID: <20090528033028.GE9388@isilon.com> In-Reply-To: <20090528014726.GG3704@isilon.com> References: <200905271636.n4RGasNe003922@svn.freebsd.org> <47d0403c0905271005t7f57f9b9h3d0721bbb1fbedc2@mail.gmail.com> <20090528014726.GG3704@isilon.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--a8Wt8u1KmwUX3Y2C
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
On Wed, May 27, 2009 at 06:47:26PM -0700, Zachary Loafman wrote:
> Thanks for the pedantry! I've attached a patch that should address your
> issues. (Doug, please review as mentor when you get a chance.)
Let's pretend I actually attached a patch. :)
--
Zach Loafman | Staff Engineer | Isilon Systems
--a8Wt8u1KmwUX3Y2C
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
filename="0008-Fix-style-grammar-issues-in-fail-9-man-page.patch"
>From f469a056fb1834167fe6d869026e98658908bc1c Mon Sep 17 00:00:00 2001
From: Zach Loafman <zachary.loafman@isilon.com>
Date: Wed, 27 May 2009 18:33:14 -0700
Subject: [PATCH] Fix style/grammar issues in fail(9) man page.
Suggested by: Ben Kaduk
Approved by: dfr (mentor)
---
share/man/man9/fail.9 | 75 ++++++++++++++++++++++++++++---------------------
1 files changed, 43 insertions(+), 32 deletions(-)
diff --git a/share/man/man9/fail.9 b/share/man/man9/fail.9
index 648f9d9..bd24b8c 100644
--- a/share/man/man9/fail.9
+++ b/share/man/man9/fail.9
@@ -48,9 +48,11 @@
.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label"
.Sh DESCRIPTION
Fail points are used to add code points where errors may be injected
-in a user controlled fashion. Fail points provide a convenient wrapper
-around user provided error injection code, providing a
-.Xr sysctl 9 MIB , and a parser for that MIB that describes how the error
+in a user controlled fashion.
+Fail points provide a convenient wrapper around user-provided error
+injection code, providing a
+.Xr sysctl 9
+MIB, and a parser for that MIB that describes how the error
injection code should fire.
.Pp
The base fail point macro is
@@ -64,16 +66,19 @@ their own fail point trees), and
.Fa name
is the name of the MIB in that tree, and
.Fa code
-is the error injection code. The
+is the error injection code.
+The
.Fa code
argument does not require braces, but it is considered good style to
-use braces for any multi-line code arguments. Inside the
+use braces for any multi-line code arguments.
+Inside the
.Fa code
argument, the evaluation of
.Sy RETURN_VALUE
is derived from the
.Fn return
-value set in the sysctl MIB. See
+value set in the sysctl MIB.
+See
.Sx SYSCTL SETTINGS
below.
.Pp
@@ -99,14 +104,14 @@ is the equivalent of
.Sh SYSCTL VARIABLES
The
.Fn KFAIL_POINT_*
-macros add sysctl MIBs where specified. Many base kernel MIBs can be
-found in the
+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
).
.Pp
-The sysctl setting recognizes the following grammar:
+The sysctl variable may be set using the following grammar:
.Pp
<fail_point> ::
<term> ( "->" <term> )*
@@ -135,27 +140,30 @@ Sleep the specified number of milliseconds
.It Sy panic
Panic
.It Sy break
-Break into the debugger.
+Break into the debugger, or trap if there is no debugger support
.It Sy print
Print that the fail point executed
.El
.Pp
The <float>% and <integer>* modifiers prior to <type> control when
-<type> is executed. The <float>% form (e.g. "1.2%") can be used to
-specify a probability that <type> will execute. The <integer>* form
-(e.g. "5*") can be used to specify the number of times <type> should
-be executed before this <term> is disabled. Only the last probability
-and the last count are used if multiple are specified, i.e. "1.2%2%"
-is the same as "2%". 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, but only execute it 5 times total".
+<type> is executed.
+The <float>% form (e.g. "1.2%") can be used to specify a
+probability that <type> will execute.
+The <integer>* form (e.g. "5*") can be used to specify the number of
+times <type> should be executed before this <term> is disabled.
+Only the last probability and the last count are used if multiple
+are specified, i.e. "1.2%2%" is the same as "2%".
+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,
+but only 5 times total".
.Pp
-The operator -> can be used to express cascading terms. If you specify
-<term1>-><term2>, it means that if <term1> doesn't 'execute', <term2>
-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.
+The operator -> can be used to express cascading terms.
+If you specify <term1>-><term2>, it means that if <term1> doesn't
+'execute', <term2> 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
@@ -164,29 +172,32 @@ when passed a non-zero argument.
.Fa code
with RETURN_VALUE set to 5.
.It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"
-2/100th of the time, execute
+2/100ths of the time, execute
.Fa code
-with RETURN_VALUE set to 5. If that doesn't happen, 5% of the time
-execute
+with RETURN_VALUE set to 5.
+If that doesn't 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)"
-For 5 times, return 5. After that, 1/1000ths of the time, return 22.
+For 5 times, return 5.
+After that, 1/1000th of the time, return 22.
.It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)"
-Return 5 for 1 in 1000 executions, but only execute 5 times total.
+Return 5 for 1 in 1000 executions, but only 5 times total.
.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)"
-1/100ths of the time, sleep 50ms.
+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
-aggressively or setting too many in combination. For example, forcing
+aggressively or setting too many in combination.
+For example, forcing
.Fn malloc
to fail consistently is potentially harmful to uptime.
.Pp
The
.Fn sleep
-sysctl setting may not be appropriate in all situations. Currently,
+sysctl setting may not be appropriate in all situations.
+Currently,
.Fn fail_point_eval
does not verify whether the context is appropriate for calling
.Fn msleep .
--
1.6.0.4
--a8Wt8u1KmwUX3Y2C--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20090528033028.GE9388>