関数パラメーターおよび戻り値の注釈設定

この記事では、単純な関数パラメーター (スカラー、構造体とクラスへのポインター)、およびほとんどの種類のバッファーに対する注釈の一般的な使用方法について説明します。 この記事では、注釈の一般的な使用パターンについても説明します。 関数に関連するその他の注釈については、「関数の動作に注釈を付ける」を参照してください。

ポインター パラメーター

次の表の注釈については、ポインター パラメーターに注釈を付けると、ポインターが null の場合、アナライザーはエラーを報告します。 この注釈は、ポインターと、ポイントされている任意のデータ項目に適用されます。

注釈と説明

• _In_

  スカラー、構造体、構造体へのポインター、およびなどの入力パラメーターに注釈を入力します。 単純なスカラーでは、明示的に使用できます。 パラメーターは、事前状態で有効である必要があり、変更されません。

• _Out_

  スカラー、構造体、構造体へのポインター、およびなどの出力パラメーターに注釈を記述します。 値によって渡されるスカラーなど、値を返さないオブジェクトにこの注釈を適用しないでください。 パラメーターは、事前状態では有効である必要はありませんが、事後状態で有効である必要があります。

• _Inout_

  関数によって変更されるパラメーターに注釈を設定します。 これは、事前状態と事後状態の両方で有効である必要がありますが、呼び出しの前後に異なる値があると見なされます。 変更可能な値に適用する必要があります。

• _In_z_

  入力として使用される null で終わる文字列へのポインター。 文字列は、事前状態で有効である必要があります。 には、既に正しい注釈がある PSTR のバリアントが推奨されています。

• _Inout_z_

  変更される null で終わる文字配列へのポインター。 呼び出しの前後で有効である必要がありますが、値が変更されたと見なされます。 Null 終端文字は移動できますが、元の null 終端文字までの要素のみがアクセスされる可能性があります。

• _In_reads_(s)

  _In_reads_bytes_(s)

  関数によって読み取られる配列へのポインター。 配列はサイズ s の要素であり、すべて有効である必要があります。

  _bytes_ バリアントは、要素の代わりにサイズをバイト単位で示します。 このバリアントは、サイズを要素として表現できない場合にのみ使用してください。 たとえば、char 文字列では、同様の関数が wchar_t を使用する場合のみ、_bytes_ バリアントが使用されます。

• _In_reads_z_(s)

  Null で終了し、既知のサイズを持つ配列へのポインター。 Null 終端文字までの要素 (または null 終端文字がない場合は s) は、事前状態で有効である必要があります。 サイズがバイト単位でわかっている場合は、要素のサイズで s をスケーリングします。

• _In_reads_or_z_(s)

  Null で終わるか、既知のサイズ (またはその両方) を持つ配列へのポインター。 Null 終端文字までの要素 (または null 終端文字がない場合は s) は、事前状態で有効である必要があります。 サイズがバイト単位でわかっている場合は、要素のサイズで s をスケーリングします。 (strn ファミリで使用されます)。

• _Out_writes_(s)

  _Out_writes_bytes_(s)

  関数によって書き込まれる s 要素の配列 (resp) へのポインター。 配列要素は、事前状態で有効である必要はなく、事後状態で有効な要素の数が指定されていません。 パラメーターの型に注釈がある場合は、事後状態で適用されます。 次に例を示します。

  typedef _Null_terminated_ wchar_t *PWSTR;
  void MyStringCopy(_Out_writes_(size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);
  

  この例では、呼び出し元は p1 の size 要素のバッファーを提供します。 MyStringCopy はこれらの要素の一部を有効にします。 さらに重要なのは、PWSTR の _Null_terminated_ 注釈は、p1 が post 状態で null で終了することを意味します。 この方法では、有効な要素の数は引き続き明確に定義されますが、特定の要素数は必要ありません。

  _bytes_ バリアントは、要素の代わりにサイズをバイト単位で示します。 このバリアントは、サイズを要素として表現できない場合にのみ使用してください。 たとえば、char 文字列では、同様の関数が wchar_t を使用する場合のみ、_bytes_ バリアントが使用されます。

• _Out_writes_z_(s)

  s 要素の配列へのポインター。 要素は、事前状態で有効である必要はありません。 事後の状態では、null 終端文字 (存在する必要がある) を介して要素が有効である必要があります。 サイズがバイト単位でわかっている場合は、要素のサイズで s をスケーリングします。

• _Inout_updates_(s)

  _Inout_updates_bytes_(s)

  配列へのポインター。関数内で読み取りと書き込みの両方を行います。 これはサイズ s の要素であり、事前状態と事後状態で有効です。

  _bytes_ バリアントは、要素の代わりにサイズをバイト単位で示します。 このバリアントは、サイズを要素として表現できない場合にのみ使用してください。 たとえば、char 文字列では、同様の関数が wchar_t を使用する場合のみ、_bytes_ バリアントが使用されます。

• _Inout_updates_z_(s)

  Null で終了し、既知のサイズを持つ配列へのポインター。 Null 終端文字 (存在する必要がある) までの要素は、事前状態と事後状態の両方で有効である必要があります。 事後状態の値は、前の状態の値とは異なるものと見なされます。null 終端記号の位置を含みます。 サイズがバイト単位でわかっている場合は、要素のサイズで s をスケーリングします。

• _Out_writes_to_(s,c)

  _Out_writes_bytes_to_(s,c)

  _Out_writes_all_(s)

  _Out_writes_bytes_all_(s)

  s 要素の配列へのポインター。 要素は、事前状態で有効である必要はありません。 事後の状態では、c-th 要素までの要素が有効である必要があります。 この _bytes_ バリアントは、サイズが要素数ではなくバイト単位ということがわかっている場合に使用できます。

  次に例を示します。

  void *memcpy(_Out_writes_bytes_all_(s) char *p1, _In_reads_bytes_(s) char *p2, _In_ int s);
  void *wordcpy(_Out_writes_all_(s) DWORD *p1, _In_reads_(s) DWORD *p2, _In_ int s);
  

• _Inout_updates_to_(s,c)

  _Inout_updates_bytes_to_(s,c)

  配列へのポインター。この配列は、関数によって読み取られ、書き込まれます。 これはサイズ s の要素であり、すべてが事前状態で有効である必要があり、c 要素は事後状態で有効である必要があります。

  _bytes_ バリアントは、要素の代わりにサイズをバイト単位で示します。 このバリアントは、サイズを要素として表現できない場合にのみ使用してください。 たとえば、char 文字列では、同様の関数が wchar_t を使用する場合のみ、_bytes_ バリアントが使用されます。

• _Inout_updates_all_(s)

  _Inout_updates_bytes_all_(s)

  サイズ s 要素の関数によって読み取られ、書き込まれる配列へのポインター。 次の同等のものとして定義されます。

  _Inout_updates_to_(_Old_(s), _Old_(s)) _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

  つまり、前の状態にある最大 s のバッファーに存在するすべての要素は、事前状態と事後状態で有効です。

  _bytes_ バリアントは、要素の代わりにサイズをバイト単位で示します。 このバリアントは、サイズを要素として表現できない場合にのみ使用してください。 たとえば、char 文字列では、同様の関数が wchar_t を使用する場合のみ、_bytes_ バリアントが使用されます。

• _In_reads_to_ptr_(p)

  p - _Curr_ (つまり、p から _Curr_ を減算) が有効な式である、配列へのポインター。 p より前の要素は、事前状態で有効ある必要があります。

  次に例を示します。

  int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);
  

• _In_reads_to_ptr_z_(p)

  式 p - _Curr_ (つまり、p から _Curr_ を減算) が有効な式である、Null で終わる配列へのポインター。 p より前の要素は、事前状態で有効ある必要があります。

• _Out_writes_to_ptr_(p)

  p - _Curr_ (つまり、p から _Curr_ を減算) が有効な式である、配列へのポインター。 p の前の要素は、事前状態で有効である必要はなく、事後状態で有効である必要があります。

• _Out_writes_to_ptr_z_(p)

  p - _Curr_ (つまり、p から _Curr_ を減算) が有効な式である、Null で終わる配列へのポインター。 p の前の要素は、事前状態で有効である必要はなく、事後状態で有効である必要があります。

省略可能なポインター パラメーター

ポインター パラメーター注釈に _opt_ が含まれている場合は、パラメーターが null である可能性があることを示します。 それ以外の場合、注釈は、_opt_ を含まないバージョンと同じように動作します。 ポインター パラメーター注釈の _opt_ バリアントの一覧を次に示します。

出力のポインター パラメーター

出力ポインター パラメーターには、パラメーターとポイント先の位置を明確に区別するための特別な表記が必要です。

注釈と説明

• _Outptr_

  パラメーターを null にすることはできません。また、post 状態では、ポイント先の場所を null にすることはできず、有効である必要があります。

• _Outptr_opt_

  パラメーターは null にすることができますが、post 状態では、ポイント先の場所を null にすることはできず、有効である必要があります。

• _Outptr_result_maybenull_

  パラメーターを null にすることはできません。また、状態を示す位置を null にすることもできます。

• _Outptr_opt_result_maybenull_

  パラメーターは null にすることができます。また、状態を示す位置を null にすることもできます。

  次の表では、注釈の意味をさらに修飾するために、注釈名に追加の部分文字列が挿入されています。 さまざまな部分文字列は _z、_COM_、_buffer_、_bytebuffer_、および _to_ です。

• _Outptr_result_z_

  _Outptr_opt_result_z_

  _Outptr_result_maybenull_z_

  _Outptr_opt_result_maybenull_z_

  返されるポインターには _Null_terminated_ 注釈があります。

• _COM_Outptr_

  _COM_Outptr_opt_

  _COM_Outptr_result_maybenull_

  _COM_Outptr_opt_result_maybenull_

  返されるポインターには COM セマンティクスがあります。これは、返されたポインターが null である _On_failure_ 事後条件を持つ理由です。

• _Outptr_result_buffer_(s)

  _Outptr_result_bytebuffer_(s)

  _Outptr_opt_result_buffer_(s)

  _Outptr_opt_result_bytebuffer_(s)

  返されるポインターは、サイズ s 要素またはバイトの有効なバッファーを指します。

• _Outptr_result_buffer_to_(s, c)

  _Outptr_result_bytebuffer_to_(s, c)

  _Outptr_opt_result_buffer_to_(s,c)

  _Outptr_opt_result_bytebuffer_to_(s,c)

  返されるポインターは、サイズ s 要素またはバイトのバッファーを指します。このバッファーの最初の c は有効です。

特定のインターフェイス規則では、エラー時に出力パラメーターが null に設定されている必要があります。 明示的に COM コードを除き、次の表の形式が推奨されます。 COM コードの場合は、前のセクションで示した対応する COM フォームを使用します。

• _Result_nullonfailure_

  他の注釈を変更します。 関数が失敗した場合、結果は null に設定されます。

• _Result_zeroonfailure_

  他の注釈を変更します。 関数が失敗した場合、結果は 0 に設定されます。

• _Outptr_result_nullonfailure_

  返されたポインターは、関数が成功した場合は有効なバッファーを指し、関数が失敗した場合は null を指します。 この注釈は、省略可能でないパラメーター用です。

• _Outptr_opt_result_nullonfailure_

  返されたポインターは、関数が成功した場合は有効なバッファーを指し、関数が失敗した場合は null を指します。 この注釈は、省略可能なパラメーター用です。

• _Outref_result_nullonfailure_

  返されたポインターは、関数が成功した場合は有効なバッファーを指し、関数が失敗した場合は null を指します。 この注釈は、参照パラメーター用です。

出力の参照パラメーター

参照パラメーターの一般的な使用は、出力パラメーターです。 int&、_Out_ などの単純な出力参照パラメーターの場合、正しいセマンティクスが提供されます。 ただし、出力値が int *& などのポインターである場合、_Outptr_ int ** のような同等のポインター注釈では、正しいセマンティクスが提供されません。 ポインター型の出力参照パラメーターのセマンティクスを簡潔に表現するには、次の複合注釈を使用します。

注釈と説明

• _Outref_

  結果は事後状態で有効である必要があります。null にすることはできません。

• _Outref_result_maybenull_

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。

• _Outref_result_buffer_(s)

  結果は事後状態で有効である必要があります。null にすることはできません。 サイズ s 要素の有効なバッファーをポイントします。

• _Outref_result_bytebuffer_(s)

  結果は事後状態で有効である必要があります。null にすることはできません。 サイズ s バイトの有効なバッファーをポイントします。

• _Outref_result_buffer_to_(s, c)

  結果は事後状態で有効である必要があります。null にすることはできません。 s 要素のバッファーをポイントします。最初の c は有効です。

• _Outref_result_bytebuffer_to_(s, c)

  結果は事後状態で有効である必要があります。null にすることはできません。 s バイトのバッファーをポイントします。最初の c は有効です。

• _Outref_result_buffer_all_(s)

  結果は事後状態で有効である必要があります。null にすることはできません。 サイズ s の有効な要素の有効なバッファーをポイントします。

• _Outref_result_bytebuffer_all_(s)

  結果は事後状態で有効である必要があります。null にすることはできません。 有効な要素の s バイトの有効なバッファーをポイントします。

• _Outref_result_buffer_maybenull_(s)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 サイズ s 要素の有効なバッファーをポイントします。

• _Outref_result_bytebuffer_maybenull_(s)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 サイズ s バイトの有効なバッファーをポイントします。

• _Outref_result_buffer_to_maybenull_(s, c)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 s 要素のバッファーをポイントします。最初の c は有効です。

• _Outref_result_bytebuffer_to_maybenull_(s,c)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 s バイトのバッファーをポイントします。最初の c は有効です。

• _Outref_result_buffer_all_maybenull_(s)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 サイズ s の有効な要素の有効なバッファーをポイントします。

• _Outref_result_bytebuffer_all_maybenull_(s)

  結果は事後状態で有効である必要がありますが、事後状態では null になる場合があります。 有効な要素の s バイトの有効なバッファーをポイントします。

戻り値

関数の戻り値は _Out_ パラメーターに似ているが、参照を削除するレベルが異なっているので、結果へのポインターの概念を考慮する必要はありません。 次の注釈の場合、戻り値は注釈付きオブジェクト (スカラー、構造体へのポインター、またはバッファーへのポインター) です。 これらの注釈は、対応する _Out_ 注釈と同じセマンティクスを持っています。

形式文字列パラメーター

• _Printf_format_string_パラメーターが printf 式で使用する書式指定文字列を示します。

  例

  int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwprintf(format, args);
         va_end(args);
         return ret;
  }
  

• _Scanf_format_string_パラメーターが scanf 式で使用する書式指定文字列を示します。

  例

  int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwscanf(format, args);
         va_end(args);
         return ret;
  }
  

• _Scanf_s_format_string_パラメーターが scanf_s 式で使用する書式指定文字列を示します。

  例

  int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwscanf_s(format, args);
         va_end(args);
         return ret;
  }
  

その他の一般的な注釈

注釈と説明

• _In_range_(low, hi)

  _Out_range_(low, hi)

  _Ret_range_(low, hi)

  _Deref_in_range_(low, hi)

  _Deref_out_range_(low, hi)

  _Deref_inout_range_(low, hi)

  _Field_range_(low, hi)

  パラメーター、フィールド、または結果は、low から hi の範囲 (含む) になります。 注釈付きオブジェクトに、適切な事前状態または事後状態の条件と共に適用される _Satisfies_(_Curr_ >= low && _Curr_ <= hi) のと同じです。

  重要

  名前には "in" と "out" が含まれていますが、_In_ と _Out_ のセマンティクスは、注釈には適用されません。

• _Pre_equal_to_(expr)

  _Post_equal_to_(expr)

  注釈付きの値は正確に expr です。 注釈付きオブジェクトに、適切な事前状態または事後状態の条件と共に適用される _Satisfies_(_Curr_ == expr) のと同じです。

• _Struct_size_bytes_(size)

  構造体またはクラスの宣言に適用されます。 この型の有効なオブジェクトが、size で指定されているバイト数を使用して、宣言された型よりも大きくなる可能性があることを示します。 次に例を示します。

  typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... };

  次に、MyStruct * 型のパラメーター pM のバッファー サイズをバイト単位で指定します。

  min(pM->nSize, sizeof(MyStruct))

関連項目

• C/C++ コードの欠陥を減らすための SAL 注釈の使用
• SAL について
• 関数の動作に注釈を付ける
• 構造体とクラスに注釈を付ける
• ロック動作に注釈を付ける
• 注釈を適用するタイミングと場所の指定
• 組み込み関数
• ベスト プラクティスと例