diff options
Diffstat (limited to 'static/freebsd/man9/fail.9 3.html')
| -rw-r--r-- | static/freebsd/man9/fail.9 3.html | 263 |
1 files changed, 0 insertions, 263 deletions
diff --git a/static/freebsd/man9/fail.9 3.html b/static/freebsd/man9/fail.9 3.html deleted file mode 100644 index 273245d4..00000000 --- a/static/freebsd/man9/fail.9 3.html +++ /dev/null @@ -1,263 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">FAIL(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">FAIL(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">DEBUG_FP</code>, - <code class="Nm">KFAIL_POINT_CODE</code>, - <code class="Nm">KFAIL_POINT_CODE_FLAGS</code>, - <code class="Nm">KFAIL_POINT_CODE_COND</code>, - <code class="Nm">KFAIL_POINT_ERROR</code>, - <code class="Nm">KFAIL_POINT_EVAL</code>, - <code class="Nm">KFAIL_POINT_DECLARE</code>, - <code class="Nm">KFAIL_POINT_DEFINE</code>, - <code class="Nm">KFAIL_POINT_GOTO</code>, - <code class="Nm">KFAIL_POINT_RETURN</code>, - <code class="Nm">KFAIL_POINT_RETURN_VOID</code>, - <code class="Nm">KFAIL_POINT_SLEEP_CALLBACKS</code>, - <code class="Nm">fail_point</code> — <span class="Nd">fail - points</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/fail.h</a>></code></p> -<p class="Pp"><code class="Fn">KFAIL_POINT_CODE</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">code</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_CODE_FLAGS</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">flags</var>, - <var class="Fa" style="white-space: nowrap;">code</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_CODE_COND</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">cond</var>, - <var class="Fa" style="white-space: nowrap;">flags</var>, - <var class="Fa" style="white-space: nowrap;">code</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_ERROR</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">error_var</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_EVAL</code>(<var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">code</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_DECLARE</code>(<var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_DEFINE</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">flags</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_GOTO</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">error_var</var>, - <var class="Fa" style="white-space: nowrap;">label</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_RETURN</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_RETURN_VOID</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">KFAIL_POINT_SLEEP_CALLBACKS</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">pre_func</var>, - <var class="Fa" style="white-space: nowrap;">pre_arg</var>, - <var class="Fa" style="white-space: nowrap;">post_func</var>, - <var class="Fa" style="white-space: nowrap;">post_arg</var>, - <var class="Fa" style="white-space: nowrap;">code</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">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 - <a class="Xr">sysctl(9)</a> MIB, and a parser for that MIB that describes - how the error injection code should fire.</p> -<p class="Pp" id="KFAIL_POINT_CODE">The base fail point macro is - <a class="permalink" href="#KFAIL_POINT_CODE"><code class="Fn">KFAIL_POINT_CODE</code></a>() - where <var class="Fa">parent</var> is a sysctl tree (frequently - <b class="Sy">DEBUG_FP</b> for kernel fail points, but various subsystems - may wish to provide their own fail point trees), and - <var class="Fa">name</var> is the name of the MIB in that tree, and - <var class="Fa">code</var> is the error injection code. The - <var class="Fa">code</var> argument does not require braces, but it is - considered good style to use braces for any multi-line code arguments. - Inside the <var class="Fa">code</var> argument, the evaluation of - <a class="permalink" href="#RETURN_VALUE"><b class="Sy" id="RETURN_VALUE">RETURN_VALUE</b></a> - is derived from the <code class="Fn">return</code>() value set in the sysctl - MIB.</p> -<p class="Pp" id="KFAIL_POINT_CODE_FLAGS">Additionally, - <a class="permalink" href="#KFAIL_POINT_CODE_FLAGS"><code class="Fn">KFAIL_POINT_CODE_FLAGS</code></a>() - provides a <var class="Fa">flags</var> 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 <b class="Sy">sleep</b> action to be - coerced to a busy wait. The supported flags are:</p> -<dl class="Bl-ohang Bd-indent"> - <dt>FAIL_POINT_USE_TIMEOUT_PATH</dt> - <dd>Rather than sleeping on a <code class="Fn">sleep</code>() call, just fire - the post-sleep function after a timeout fires.</dd> - <dt>FAIL_POINT_NONSLEEPABLE</dt> - <dd>Mark the fail point as being in a non-sleepable context, which coerces - <code class="Fn">sleep</code>() calls to <code class="Fn">delay</code>() - calls.</dd> -</dl> -<p class="Pp" id="KFAIL_POINT_CODE_COND">Likewise, - <a class="permalink" href="#KFAIL_POINT_CODE_COND"><code class="Fn">KFAIL_POINT_CODE_COND</code></a>() - supplies a <var class="Fa">cond</var> argument, which allows you to set the - condition under which the fail point's code may fire. This is equivalent - to:</p> -<div class="Bd Pp Li"> -<pre> if (cond) - KFAIL_POINT_CODE_FLAGS(...); - -</pre> -</div> -See <a class="Sx" href="#SYSCTL_VARIABLES">SYSCTL VARIABLES</a> below. -<p class="Pp" id="KFAIL_POINT_*">The remaining - <a class="permalink" href="#KFAIL_POINT_*"><code class="Fn">KFAIL_POINT_*</code></a>() - macros are wrappers around common error injection paths:</p> -<dl class="Bl-inset"> - <dt id="KFAIL_POINT_RETURN"><a class="permalink" href="#KFAIL_POINT_RETURN"><code class="Fn">KFAIL_POINT_RETURN</code></a>(<var class="Fa">parent</var>, - <var class="Fa">name</var>)</dt> - <dd>is the equivalent of <b class="Sy">KFAIL_POINT_CODE(..., return - RETURN_VALUE)</b></dd> - <dt id="KFAIL_POINT_RETURN_VOID"><a class="permalink" href="#KFAIL_POINT_RETURN_VOID"><code class="Fn">KFAIL_POINT_RETURN_VOID</code></a>(<var class="Fa">parent</var>, - <var class="Fa">name</var>)</dt> - <dd>is the equivalent of <b class="Sy">KFAIL_POINT_CODE(..., return)</b></dd> - <dt id="KFAIL_POINT_ERROR"><a class="permalink" href="#KFAIL_POINT_ERROR"><code class="Fn">KFAIL_POINT_ERROR</code></a>(<var class="Fa">parent</var>, - <var class="Fa">name</var>, <var class="Fa">error_var</var>)</dt> - <dd>is the equivalent of <b class="Sy">KFAIL_POINT_CODE(..., error_var = - RETURN_VALUE)</b></dd> - <dt id="KFAIL_POINT_GOTO"><a class="permalink" href="#KFAIL_POINT_GOTO"><code class="Fn">KFAIL_POINT_GOTO</code></a>(<var class="Fa">parent</var>, - <var class="Fa">name</var>, <var class="Fa">error_var</var>, - <var class="Fa">label</var>)</dt> - <dd>is the equivalent of <b class="Sy">KFAIL_POINT_CODE(..., { error_var = - RETURN_VALUE; goto label;})</b></dd> -</dl> -<p class="Pp">You can also introduce fail points by separating the declaration, - definition, and evaluation portions.</p> -<dl class="Bl-inset"> - <dt id="KFAIL_POINT_DECLARE"><a class="permalink" href="#KFAIL_POINT_DECLARE"><code class="Fn">KFAIL_POINT_DECLARE</code></a>(<var class="Fa">name</var>)</dt> - <dd>is used to declare the <b class="Sy">fail_point</b> struct.</dd> - <dt id="KFAIL_POINT_DEFINE"><a class="permalink" href="#KFAIL_POINT_DEFINE"><code class="Fn">KFAIL_POINT_DEFINE</code></a>(<var class="Fa">parent</var>, - <var class="Fa">name</var>, <var class="Fa">flags</var>)</dt> - <dd>defines and initializes the <b class="Sy">fail_point</b> and sets up its - <a class="Xr">sysctl(9)</a>.</dd> - <dt id="KFAIL_POINT_EVAL"><a class="permalink" href="#KFAIL_POINT_EVAL"><code class="Fn">KFAIL_POINT_EVAL</code></a>(<var class="Fa">name</var>, - <var class="Fa">code</var>)</dt> - <dd>is used at the point that the fail point is executed.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL - VARIABLES</a></h1> -<p class="Pp">The <code class="Fn">KFAIL_POINT_*</code>() macros add sysctl MIBs - where specified. Many base kernel MIBs can be found in the - <a class="permalink" href="#debug.fail_point"><b class="Sy" id="debug.fail_point">debug.fail_point</b></a> - tree (referenced in code by <b class="Sy">DEBUG_FP</b>).</p> -<p class="Pp">The sysctl variable may be set in a number of ways:</p> -<div class="Bd Pp Li"> -<pre> [<pct>%][<cnt>*]<type>[(args...)][-><more terms>]</pre> -</div> -<p class="Pp">The <type> argument specifies which action to take; it can - be one of:</p> -<dl class="Bl-tag"> - <dt id="off"><a class="permalink" href="#off"><b class="Sy">off</b></a></dt> - <dd>Take no action (does not trigger fail point code)</dd> - <dt id="return"><a class="permalink" href="#return"><b class="Sy">return</b></a></dt> - <dd>Trigger fail point code with specified argument</dd> - <dt id="sleep"><a class="permalink" href="#sleep"><b class="Sy">sleep</b></a></dt> - <dd>Sleep the specified number of milliseconds</dd> - <dt id="panic"><a class="permalink" href="#panic"><b class="Sy">panic</b></a></dt> - <dd>Panic</dd> - <dt id="break"><a class="permalink" href="#break"><b class="Sy">break</b></a></dt> - <dd>Break into the debugger, or trap if there is no debugger support</dd> - <dt id="print"><a class="permalink" href="#print"><b class="Sy">print</b></a></dt> - <dd>Print that the fail point executed</dd> - <dt id="pause"><a class="permalink" href="#pause"><b class="Sy">pause</b></a></dt> - <dd>Threads sleep at the fail point until the fail point is set to - <b class="Sy">off</b></dd> - <dt id="yield"><a class="permalink" href="#yield"><b class="Sy">yield</b></a></dt> - <dd>Thread yields the cpu when the fail point is evaluated</dd> - <dt id="delay"><a class="permalink" href="#delay"><b class="Sy">delay</b></a></dt> - <dd>Similar to sleep, but busy waits the cpu. (Useful in non-sleepable - contexts.)</dd> -</dl> -<p class="Pp">The <pct>% and <cnt>* modifiers prior to <type> - control when <type> is executed. The <pct>% form (e.g. - "1.2%") can be used to specify a probability that <type> - will execute. 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. 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".</p> -<p class="Pp" id="return~2">The operator -> can be used to express cascading - terms. If you specify <term1>-><term2>, it means that if - <term1> does not ‘<code class="Li">execute</code>’, - <term2> is evaluated. For the purpose of this operator, the - <a class="permalink" href="#return~2"><code class="Fn">return</code></a>() - and <code class="Fn">print</code>() operators are the only types that - cascade. A <code class="Fn">return</code>() term only cascades if the code - executes, and a <code class="Fn">print</code>() term only cascades when - passed a non-zero argument. A pid can optionally be specified. The fail - point term is only executed when invoked by a process with a matching - p_pid.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<dl class="Bl-tag"> - <dt id="sysctl"><a class="permalink" href="#sysctl"><b class="Sy">sysctl - debug.fail_point.foobar="2.1%return(5)"</b></a></dt> - <dd>21/1000ths of the time, execute <var class="Fa">code</var> with - RETURN_VALUE set to 5.</dd> - <dt id="sysctl~2"><a class="permalink" href="#sysctl~2"><b class="Sy">sysctl - debug.fail_point.foobar="2%return(5)->5%return(22)"</b></a></dt> - <dd>2/100ths of the time, execute <var class="Fa">code</var> with RETURN_VALUE - set to 5. If that does not happen, 5% of the time execute - <var class="Fa">code</var> with RETURN_VALUE set to 22.</dd> - <dt id="sysctl~3"><a class="permalink" href="#sysctl~3"><b class="Sy">sysctl - debug.fail_point.foobar="5*return(5)->0.1%return(22)"</b></a></dt> - <dd>For 5 times, return 5. After that, 1/1000th of the time, return 22.</dd> - <dt id="sysctl~4"><a class="permalink" href="#sysctl~4"><b class="Sy">sysctl - debug.fail_point.foobar="0.1%5*return(5)"</b></a></dt> - <dd>Return 5 for 1 in 1000 executions, but only 5 times total.</dd> - <dt id="sysctl~5"><a class="permalink" href="#sysctl~5"><b class="Sy">sysctl - debug.fail_point.foobar="1%*sleep(50)"</b></a></dt> - <dd>1/100th of the time, sleep 50ms.</dd> - <dt id="sysctl~6"><a class="permalink" href="#sysctl~6"><b class="Sy">sysctl - debug.fail_point.foobar="1*return(5)[pid 1234]"</b></a></dt> - <dd>Return 5 once, when pid 1234 executes the fail point.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">This manual page was written by</p> -<p class="Pp"><span class="An">Matthew Bryan</span> - <<a class="Mt" href="mailto:matthew.bryan@isilon.com">matthew.bryan@isilon.com</a>> - and</p> -<p class="Pp"><span class="An">Zach Loafman</span> - <<a class="Mt" href="mailto:zml@FreeBSD.org">zml@FreeBSD.org</a>>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> -<p class="Pp">It is easy to shoot yourself in the foot by setting fail points - too aggressively or setting too many in combination. For example, forcing - <code class="Fn">malloc</code>() to fail consistently is potentially harmful - to uptime.</p> -<p class="Pp" id="FAIL_POINT_NONSLEEPABLE">The <code class="Fn">sleep</code>() - sysctl setting may not be appropriate in all situations. Currently, - <code class="Fn">fail_point_eval</code>() does not verify whether the - context is appropriate for calling <code class="Fn">msleep</code>(). You can - force it to evaluate a <b class="Sy">sleep</b> action as a - <b class="Sy">delay</b> action by specifying the - <a class="permalink" href="#FAIL_POINT_NONSLEEPABLE"><b class="Sy">FAIL_POINT_NONSLEEPABLE</b></a> - flag at the point the fail point is declared.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">June 6, 2019</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |