名称

KFAIL_POINT_CODE, KFAIL_POINT_RETURN, KFAIL_POINT_RETURN_VOID, KFAIL_POINT_ERROR, KFAIL_POINT_GOTO, fail_point, DEBUG_FP — フェイルポイント (fail point)

書式

#include < sys/fail.h>

KFAIL_POINT_CODE( parent, name, code);

KFAIL_POINT_RETURN( parent, name);

KFAIL_POINT_RETURN_VOID( parent, name);

KFAIL_POINT_ERROR( parent, name, error_var);

KFAIL_POINT_GOTO( parent, name, error_var, label);

解説

フェイルポイントは、エラーがユーザ管理された方法で注入されるコードポイントを追加するために使用されます。フェイルポイントは、 sysctl(9) MIB、とエラー注入コードがどのように適用されるべきであるかを記述するその MIB のためのパーサを提供する、ユーザによって提供されたエラー注入コードの周りの便利なラッパを提供します。

基本的なフェイルポイントマクロは、 parent が (しばしば、カーネルフェイルポイントのための DEBUG_FP ですが、様々なサブシステムは、それら自体のフェイルポイントツリーを提供したい) sysctl ツリーであり、 name が、そのツリーの MIB の名前であり、 code が、エラー注入コードである、 KFAIL_POINT_CODE() です。 code 引数は、ブレイス (brace) を必要としませんが、任意のマルチラインコード引数のためにブレイスを使用するために良いスタイルであると考えられています。 code 引数の中では、 RETURN_VALUE の評価は、sysctl MIB で設定される return() に由来します。下記の 「SYSCTL 変数」 を参照してください。

残っている KFAIL_POINT_*() マクロは、一般的なエラー注入パスの周りのラッパです:

KFAIL_POINT_RETURN( parent, name)

は、 KFAIL_POINT_CODE(..., return RETURN_VALUE) と同等です。

KFAIL_POINT_RETURN_VOID( parent, name)

は、 KFAIL_POINT_CODE(..., return) と同等です。

KFAIL_POINT_ERROR( parent, name, error_var)

は、 KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) と同等です。

KFAIL_POINT_GOTO( parent, name, error_var, label)

は、 KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) と同等です。

SYSCTL 変数

KFAIL_POINT_*() マクロは、指定されているところで sysctl MIB を追加します。 debug.fail_point ツリー ( DEBUG_FP によってコードで参照されている) で多くのベースカーネル MIB を見つけることができます。

sysctl 変数は、次の文法を使用するように設定されます:

  <fail_point> :: 
      <term> ( "->" <term> )* 
 
  <term> :: 
      ( (<float> "%") | (<integer> "*" ) )* 
      <type> 
      [ "(" <integer> ")" ] 
      [ "[pid " <integer> "]" ] 
 
  <float> :: 
      <integer> [ "." <integer> ] | 
      "." <integer> 
 
  <type> :: 
      "off" | "return" | "sleep" | "panic" | "break" | "print"

<type>引数は、次のどのようなアクションを取るかを指定します:

off

アクションを取りません (フェイルポイントコードのトリガとなりません)

return

指定された引数でフェイルポイントコードをトリガします。

sleep

指定されたミリ秒の数スリープします。

panic

パニック

break

デバッガに入るか、またはデバッガサポートがなければ、トラップします。

print

実行されたフェイルポイントを印刷します。

<type>の前の <float>% と <integer>* 修飾子は、 <type>がいつ実行されるかを制御します。 <type>が実行する確率を指定するために、 <float>% 形式 (例えば、"1.2%") を使用することができます。この <term>が無効にされる前に、 <type>が実行されるべきであると回数を指定するために <integer>* 形式 (例えば、"5*") を使用することができます。複数指定されているなら、最後の確率と最後のカウントだけが使用されます、すなわち、"1.2%2%"は、"2%"と同じです。確率とカウントの両方が指定されるとき、確率は、カウントの前に評価されます、すなわち、"2%5*"は、"時間の 2% ですが、合計 5 回だけです"。

カスケードの用語を表すために演算子 ->を使用することができます。利用者が <term1>-><term2>を指定するなら、それは、<term1>が‘ 実行’されないなら、 <term2>が評価されることを意味します。この演算子の目的のために、return() と print() 演算子は、そのカスケードのみタイプされます。コードが実行される場合にだけ、return() 用語のみカスケードし、 0 以外の引数が渡されるときのみ、print() 用語のみカスケードします。オプションで、pid を指定することができます。フェールポイントの用語は、マッチする p_pid と共にプロセスによって呼び出される場合のみ、実行されます。

使用例

sysctl debug.fail_point.foobar="2.1%return(5)"

21/1000 の確立で、RETURN_VALUE が 5 に設定されて code を実行します。

sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"

2/100 の確立で、RETURN_VALUE が 5 に設定されて code を実行します。それが起こらないなら、5% の確立で、RETURN_VALUE が 22 に設定されて code を実行します。

sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)"

5 回、5 を返します。その後に、1/1000 の確立で、22 を返します。

sysctl debug.fail_point.foobar="0.1%5*return(5)"

1000 回の実行で 1 回 5 を返しますが、合計 5 回だけです。

sysctl debug.fail_point.foobar="1%*sleep(50)"

1/100 の確立で、50ms スリープします。

sysctl debug.fail_point.foobar="1*return(5)[pid 1234]"

いったん pid 1234 がフェールポイントを実行するとき、5 を返します。

作者

このマニュアルページは、 Zach Loafman <zml@FreeBSD.org>によって書かれました。

警告

あまりに積極的にフェイルポイントを設定するか、または多く過ぎる組み合わせの設定によって、自ら災いを招くのは、簡単です。例えば、一貫して失敗する malloc() を強制することは、潜在的に稼働率に有害です。

sleep() sysctl 設定は、すべての状況で適切でないかもしれません。現在、 fail_point_eval() は、コンテキストが msleep() を呼び出すために適切であるかどうか確かめられません。