From owner-svn-src-head@FreeBSD.ORG Thu May 28 03:30:56 2009 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 1DFCC106566C; Thu, 28 May 2009 03:30:56 +0000 (UTC) (envelope-from zml@FreeBSD.org) Received: from seaxch10.isilon.com (seaxch10.isilon.com [74.85.160.26]) by mx1.freebsd.org (Postfix) with ESMTP id E83C18FC16; Thu, 28 May 2009 03:30:55 +0000 (UTC) (envelope-from zml@FreeBSD.org) Received: from famine.isilon.com ([10.54.190.95]) by seaxch10.isilon.com with Microsoft SMTPSVC(6.0.3790.1830); Wed, 27 May 2009 20:30:30 -0700 Received: from zloafman by famine.isilon.com with local (Exim 4.69) (envelope-from ) id 1M9WK5-0003ej-Lr; Wed, 27 May 2009 20:30:29 -0700 Date: Wed, 27 May 2009 20:30:29 -0700 From: Zachary Loafman To: Ben Kaduk Message-ID: <20090528033028.GE9388@isilon.com> References: <200905271636.n4RGasNe003922@svn.freebsd.org> <47d0403c0905271005t7f57f9b9h3d0721bbb1fbedc2@mail.gmail.com> <20090528014726.GG3704@isilon.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="a8Wt8u1KmwUX3Y2C" Content-Disposition: inline In-Reply-To: <20090528014726.GG3704@isilon.com> User-Agent: Mutt/1.5.18 (2008-05-17) X-OriginalArrivalTime: 28 May 2009 03:30:30.0157 (UTC) FILETIME=[A68983D0:01C9DF44] 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 ...) X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 28 May 2009 03:30:56 -0000 --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 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 :: ( "->" )* @@ -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 % and * modifiers prior to control when - is executed. The % form (e.g. "1.2%") can be used to -specify a probability that will execute. The * form -(e.g. "5*") can be used to specify the number of times should -be executed before this 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". + is executed. +The % form (e.g. "1.2%") can be used to specify a +probability that will execute. +The * form (e.g. "5*") can be used to specify the number of +times should be executed before this 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 -->, it means that if doesn't '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. +The operator -> can be used to express cascading terms. +If you specify ->, it means that if doesn't +'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 @@ -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--