SAL 注釈

  • [アーティクル]

更新 : 2007 年 11 月

ライブラリ ヘッダー ファイルを調べると、_In_z、_Out_z_cap_(_Size) など、いくつかの特殊な注釈に気付きます。これらは、Microsoft の標準ソース コード注釈言語 (SAL) の例です。SAL は、関数が自身のパラメータをどのように使用するかを記述する注釈のセットを提供します。つまり、これらの注釈は、関数がそのパラメータについて何を前提としているか、および、関数が終了時に何を保証するかを示します。これらの注釈はヘッダー ファイル <sal.h> で定義されています。

注釈は、関数のパラメータの型またはその戻り値の型の前に置かれ、そのパラメータまたは戻り値について関数がどのように動作するかを示します。注釈には、バッファ注釈と詳細な注釈の 2 つのクラスがあります。バッファ注釈は、関数がポインタ パラメータをどのように使用するかを示し、詳細な注釈は、バッファの複雑な動作または特殊な動作を記述したり、他の方法では表現できないパラメータについての補足情報を提供したりします。

バッファ注釈

最も重要な注釈として、関数のバッファ パラメータまたは戻り値を注釈する一貫した方法を提供します。これらの注釈はそれぞれ、関数が対話する単一のバッファ (文字列、固定長または可変長の配列、またはポインタ) について、その位置、サイズ、初期化レベル、および関数による使用法について記述します。

特定のバッファに対する適切なマクロは、以下の表を使用して構築できます。"レイヤ" 表から適切な値を選択し、"オプション" 表の適切なオプションを追加します。組み合わせによっては、バッファ注釈として意味を成さないものもあります。意味のある注釈のみコードに追加できます。意味のある注釈の一覧については、<sal.h> 内のバッファ注釈定義セクションを参照してください。

各パラメータには、単一のバッファ注釈のみ使用できます。

レイヤ

可能なオプション

パラメータ レイヤ

(なし)

_In_

_Out_

_Inout_

_Deref_out_

戻り値レイヤ

_Ret_

_Deref_ret_

前後条件レイヤ

(パラメータ レイヤまたは戻り値レイヤに適切なオプションがない場合のみ使用します)

_Pre_

_Post_

_Deref_pre_

_Deref_post_

オプション

可能なオプション

省略可能

(なし)

opt_

null 終端

(なし)

z_

範囲

(なし)

cap_[c_|x_](size)

bytecap_[c_|x_](size)

count_[c_|x_](size)

bytecount_[c_|x_](size)

ptrdiff_cap_(ptr)

ptrdiff_count_(ptr)

次に、さまざまなカテゴリとそれぞれのオプションについて説明します。

パラメータ レイヤ

関数が仮パラメータのバッファをどのように使用するかを示します。

(なし)

バッファはアクセスされません。呼び出し元がバッファを提供する必要があります。これは、alloc 関数と free 関数に対してのみ使用できます。

_In_

関数はバッファからの読み込みのみ行います。呼び出し元がバッファを提供し、初期化する必要があります。

_Out_

関数はバッファへの書き込みのみ行います。呼び出し元がバッファを提供する必要があります。そして、関数がこれを初期化します。

_Inout_

関数はバッファからの読み込みとバッファへの書き込みの両方を行うことができます。呼び出し元がバッファを提供し、初期化する必要があります。

_Deref_out_

このオプションは、逆参照されている出力パラメータに適用されます。パラメータが p の場合、 *p がバッファ ポインタになります。p は NULL にはできません。

関数はバッファへの書き込みのみ行います。関数がバッファを提供し、初期化します。

戻り値レイヤ

関数が戻り値のバッファをどのように使用するかを示します。

(なし)

バッファはアクセスされません。関数がバッファを提供し、終了時、初期化前の状態に戻します。これは、alloc 関数と free 関数に対してのみ使用できます。

_Ret_

関数がバッファを提供し、初期化します。

_Deref_ret_

このオプションは、逆参照されている戻り値に適用されます。戻り値が p の場合、 *p がバッファ ポインタになります。p は NULL にはできません。

関数がバッファを提供し、初期化します。

前後条件レイヤ

関数がバッファをどのように使用するかを示します。パラメータ レイヤまたは戻り値レイヤの値が適用されていない場合のみ、このレイヤの値を使用します。

_Pre_

関数を呼び出す前に必要な条件を説明します。

_Post_

関数を呼び出した後に必要な条件を説明します。

_Deref_pre_

呼び出す前に必要な逆参照ポインタ パラメータの配列要素の条件を説明します。

_Deref_post_

関数を呼び出した後に必要な条件を説明します。

省略可能オプション

バッファそのものが省略可能であるかどうかを示します。この注釈は、パラメータ レイヤ、戻り値レイヤ、または前後条件レイヤの値に適用できます。

(なし)

バッファへのポインタは NULL 以外である必要があります。

opt_

バッファへのポインタが NULL であってもかまいません。逆参照される前にチェックされます。

null 終端オプション

\0 がバッファ内の有効な要素の終端を示すかどうかを記述します。この注釈は、パラメータ レイヤ、戻り値レイヤ、または前後条件レイヤの値に適用できます。

(なし)

バッファは null で終わらない場合があり、\0 はバッファの終端を表しません。

z_

\0 がバッファの終端を示します。

範囲オプション

このオプションは、読み取り可能バッファと書き込み可能バッファに適用されます。この注釈は、パラメータ レイヤ、戻り値レイヤ、または前後条件レイヤの値に適用できます。

(なし)

パラメータまたは戻り値が読み取り可能または書き込み可能のバッファではありません。

cap_[c_|x_](size)

bytecap_[c_|x_](size)

ptrdiff_cap_(ptr)

バッファの書き込み可能サイズを示します。このオプションは、通常、_Out_ 注釈と一緒に使用します。

このサイズが配列で示される場合は、cap_ を使用します。サイズがバイト単位で示される場合は、bytecap_ を使用します。サイズが制限ポインタによって示される場合は、ptrdiff_cap_ を使用します。

バッファ サイズが非定数パラメータである場合は、c_ または x_ を指定する必要はありません。たとえば、有効な注釈は、cap_(size)、bytecap_(size) などになります。

バッファ サイズが定数式である場合は、c_ オプションを指定してください。たとえば、有効な注釈は、cap_c_(size)、bytecap_c_(size) などになります。

バッファ サイズが定数式でもパラメータでもない場合は、x_ オプションを指定してください。たとえば、有効な注釈は、cap_x_(size)、bytecap_x_(size) などになります。

count_[c_|x_](size)

bytecount_[c_|x_](size)

ptrdiff_count_(ptr)

バッファの書き込み可能サイズを示します。このオプションは、通常、_In_ 注釈と一緒に使用します。

このサイズが配列で示される場合は、count_ を使用します。サイズがバイト単位で示される場合は、bytecount_ を使用します。サイズが制限ポインタによって示される場合は、ptrdiff_count_ を使用します。

バッファ サイズが非定数パラメータである場合は、c_ または x_ を指定する必要はありません。たとえば、有効な注釈は、count_(size)、bytecount_(size) などになります。

バッファ サイズが定数式である場合は、c_ オプションを指定してください。たとえば、有効な注釈は、count_c_(size)、bytecount_c_(size) などになります。

バッファ サイズが定数式でもパラメータでもない場合は、x_ オプションを指定してください。たとえば、有効な注釈は、count_x_(size)、bytecount_x_(size) などになります。

詳細な注釈

詳細な注釈では、通常のバッファ マクロでは表現できない動作を記述します。これらは、複雑または条件付きの動作が含まれるバッファのパラメータを注釈したり、既存の注釈に補足情報を追加したりするのに使用できます。

注釈

説明

_Check_return_

この関数の呼び出し元は戻り値を無視できません。

_Printf_format_string_

printf のスタイルに % マーカーを含む文字列。

_Scanf_format_string_

scanf のスタイルに % マーカーを含む文字列。

_Scanf_s_format_string_

scanf_s のスタイルに % マーカーを含む文字列。

_Success_(expr)

expr は、関数が成功したかどうかを示します。出口で expr が true の場合、関数のすべての保証 (他の注釈で指定されている内容) が守られます。出口で expr が false である場合、呼び出し元は、関数の保証を期待できません。使用されない場合、関数は常に保証事項を満たす必要があります。HRESULT を返すなど、標準的な方法で成功を示す関数には自動的にこの注釈が追加されます。

参照

参照

C ランタイム ライブラリ