함수 매개 변수에 주석을 추가하고 값을 반환합니다.

  • 아티클

이 문서에서는 단순 함수 매개 변수(스칼라, 구조체 및 클래스에 대한 포인터) 및 대부분의 버퍼 종류에 대한 주석의 일반적인 용도에 대해 설명합니다. 이 문서에서는 주석에 대한 일반적인 사용 패턴도 보여 줍니다. 함수와 관련된 추가 주석은 함수 동작 주석 지정을 참조하세요.

포인터 매개 변수

다음 표의 주석에 대해 포인터 매개 변수에 주석이 추가되면 포인터가 null이면 분석기에서 오류를 보고합니다. 이 주석은 포인터 및 가리키는 모든 데이터 항목에 적용됩니다.

주석 및 설명

  • _In_

    스칼라, 구조체, 구조체에 대한 포인터 등 입력 매개 변수에 주석을 추가합니다. 단순 스칼라에서 명시적으로 사용할 수 있습니다. 매개 변수는 사전 상태에서 유효해야 하며 수정되지 않습니다.

  • _Out_

    스칼라, 구조체, 구조체에 대한 포인터 등 출력 매개 변수에 주석을 추가합니다. 값을 반환할 수 없는 개체(예: 값으로 전달되는 스칼라)에 이 주석을 적용하지 마세요. 매개 변수는 사전 상태에서 유효할 필요는 없지만 사후 상태에서 유효해야 합니다.

  • _Inout_

    함수에 의해 변경될 매개 변수에 주석을 추가합니다. 사전 상태와 사후 상태 모두에서 유효해야 하지만 호출 전후에 다른 값이 있는 것으로 간주됩니다. 수정 가능한 값에 적용해야 합니다.

  • _In_z_

    입력으로 사용되는 null로 끝나는 문자열에 대한 포인터입니다. 문자열은 사전 상태에서 유효해야 합니다. PSTR이미 올바른 주석이 있는 변형을 사용하는 것이 좋습니다.

  • _Inout_z_

    수정할 null로 끝나는 문자 배열에 대한 포인터입니다. 호출 전후에 유효해야 하지만 값이 변경된 것으로 가정합니다. null 종결자는 이동할 수 있지만 원래 null 종결자까지의 요소만 액세스할 수 있습니다.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    함수에서 읽는 배열에 대한 포인터입니다. 배열은 크기 s 요소이며 모두 유효해야 합니다.

    변형은 _bytes_ 요소 대신 크기(바이트)를 제공합니다. 크기를 요소로 표현할 수 없는 경우에만 이 변형을 사용합니다. 예를 들어 char 문자열은 사용하는 유사한 함수가 _bytes_ 있는 경우에만 변형을 사용합니다 wchar_t .

  • _In_reads_z_(s)

    null로 종료되고 알려진 크기를 갖는 배열에 대한 포인터입니다. null 종결자(또는 s null 종결자가 없는 경우)까지의 요소는 사전 상태에서 유효해야 합니다. 크기가 바이트 단위로 알려진 경우 요소 크기로 크기를 조정 s 합니다.

  • _In_reads_or_z_(s)

    null로 종료되거나 알려진 크기 또는 둘 다인 배열에 대한 포인터입니다. null 종결자(또는 s null 종결자가 없는 경우)까지의 요소는 사전 상태에서 유효해야 합니다. 크기가 바이트 단위로 알려진 경우 요소 크기로 크기를 조정 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);

    이 예제에서 호출자는 에 대한 요소의 size 버퍼를 p1제공합니다. MyStringCopy 는 이러한 요소 중 일부를 유효하게 만듭니다. 더 중요한 것은 주석이 _Null_terminated_PWSTR 사후 상태에서 null로 종료됨 p1 을 의미합니다. 이러한 방식으로 유효한 요소의 수는 여전히 잘 정의되어 있지만 특정 요소 수는 필요하지 않습니다.

    변형은 _bytes_ 요소 대신 크기(바이트)를 제공합니다. 크기를 요소로 표현할 수 없는 경우에만 이 변형을 사용합니다. 예를 들어 char 문자열은 사용하는 유사한 함수가 _bytes_ 있는 경우에만 변형을 사용합니다 wchar_t .

  • _Out_writes_z_(s)

    요소 배열에 대한 포인터입니다 s . 요소가 사전 상태에서 유효할 필요는 없습니다. 사후 상태에서는 존재해야 하는 null 종결자를 통한 요소가 유효해야 합니다. 크기가 바이트 단위로 알려진 경우 요소 크기로 크기를 조정 s 합니다.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    함수에서 읽고 쓰는 배열에 대한 포인터입니다. 크기 s 요소이며 사전 상태 및 사후 상태에서 유효합니다.

    변형은 _bytes_ 요소 대신 크기(바이트)를 제공합니다. 크기를 요소로 표현할 수 없는 경우에만 이 변형을 사용합니다. 예를 들어 char 문자열은 사용하는 유사한 함수가 _bytes_ 있는 경우에만 변형을 사용합니다 wchar_t .

  • _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 . 요소가 사전 상태에서 유효할 필요는 없습니다. 사후 상태에서는 -th 요소까지의 c요소가 유효해야 합니다. 크기가 _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 문자열은 사용하는 유사한 함수가 _bytes_ 있는 경우에만 변형을 사용합니다 wchar_t .

  • _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 문자열은 사용하는 유사한 함수가 _bytes_ 있는 경우에만 변형을 사용합니다 wchar_t .

  • _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)

    유효한 식인 null로 끝나는 배열(즉, p 빼기_Curr_)에 대한 p - _Curr_ 포인터입니다. 이전 p 요소는 사전 상태에서 유효할 필요가 없으며 사후 상태에서 유효해야 합니다.

선택적 포인터 매개 변수

포인터 매개 변수 주석에 포함된 _opt_경우 매개 변수가 null일 수 있음을 나타냅니다. 그렇지 않으면 주석이 포함되지 _opt_않은 버전과 동일하게 동작합니다. 다음은 포인터 매개 변수 주석의 변형 목록 _opt_ 입니다.

_In_opt_
_Out_opt_
_Inout_opt_
_In_opt_z_
_Inout_opt_z_
_In_reads_opt_
_In_reads_bytes_opt_
_In_reads_opt_z_

_Out_writes_opt_
_Out_writes_opt_z_
_Inout_updates_opt_
_Inout_updates_bytes_opt_
_Inout_updates_opt_z_
_Out_writes_to_opt_
_Out_writes_bytes_to_opt_
_Out_writes_all_opt_
_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_
_Inout_updates_bytes_to_opt_
_Inout_updates_all_opt_
_Inout_updates_bytes_all_opt_
_In_reads_to_ptr_opt_
_In_reads_to_ptr_opt_z_
_Out_writes_to_ptr_opt_
_Out_writes_to_ptr_opt_z_

출력 포인터 매개 변수

출력 포인터 매개 변수에는 매개 변수 및 뾰족한 위치에 대한 nullness를 명확히 하기 위해 특별한 표기법이 필요합니다.

주석 및 설명

  • _Outptr_

    매개 변수는 null일 수 없으며, 사후 상태에서는 가리키는 위치가 null일 수 없으며 유효해야 합니다.

  • _Outptr_opt_

    매개 변수는 null일 수 있지만 사후 상태에서는 가리키는 위치가 null일 수 없으며 유효해야 합니다.

  • _Outptr_result_maybenull_

    매개 변수는 null일 수 없으며 사후 상태에서는 가리키는 위치가 null일 수 있습니다.

  • _Outptr_opt_result_maybenull_

    매개 변수는 null일 수 있으며 사후 상태에서는 가리키는 위치가 null일 수 있습니다.

    다음 표에서는 주석의 의미를 한층 더 한정하기 위해 주석 이름에 추가 부분 문자열을 삽입합니다. 다양한 부분 문자열은 _z, _COM_, _buffer__bytebuffer_및 _to_.

Important

주석을 추가할 인터페이스가 COM인 경우 이러한 주석의 COM 형식을 사용합니다. COM 주석을 다른 형식 인터페이스와 함께 사용하지 마세요.

  • _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 의미 체계가 있으므로 반환된 _On_failure_ 포인터가 null이라는 사후 조건을 전달합니다.

  • _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)

    반환된 포인터는 첫 번째 c 가 유효한 크기 s 요소 또는 바이트의 버퍼를 가리킵니다.

특정 인터페이스 규칙은 실패할 때 출력 매개 변수가 무효화되는 것으로 가정합니다. 명시적으로 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일 수 없습니다. 첫 번째 c 요소가 유효한 요소의 s 버퍼를 가리킵니다.

  • _Outref_result_bytebuffer_to_(s, c)

    결과는 사후 상태에서 유효해야 하며 null일 수 없습니다. 첫 번째 c 바이트가 유효한 바이트의 버퍼 s 를 가리킵니다.

  • _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일 수 있습니다. 첫 번째 c 요소가 유효한 요소의 s 버퍼를 가리킵니다.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    결과는 사후 상태에서 유효해야 하지만 사후 상태에서는 null일 수 있습니다. 첫 번째 c 바이트가 유효한 바이트의 버퍼 s 를 가리킵니다.

  • _Outref_result_buffer_all_maybenull_(s)

    결과는 사후 상태에서 유효해야 하지만 사후 상태에서는 null일 수 있습니다. 유효한 요소 크기의 s 유효한 버퍼를 가리킵니다.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    결과는 사후 상태에서 유효해야 하지만 사후 상태에서는 null일 수 있습니다. 유효한 요소 바이 s 트의 유효한 버퍼를 가리킵니다.

반환 값

함수의 반환 값은 매개 변수와 _Out_ 유사하지만 참조 해제 수준이 다르며 결과에 대한 포인터의 개념을 고려할 필요가 없습니다. 다음 주석의 경우 반환 값은 주석이 추가된 개체(스칼라, 구조체에 대한 포인터 또는 버퍼에 대한 포인터)입니다. 이러한 주석에는 해당 _Out_ 주석과 동일한 의미 체계가 있습니다.

_Ret_z_
_Ret_writes_(s)
_Ret_writes_bytes_(s)
_Ret_writes_z_(s)
_Ret_writes_to_(s,c)
_Ret_writes_maybenull_(s)
_Ret_writes_to_maybenull_(s)
_Ret_writes_maybenull_z_(s)

_Ret_maybenull_
_Ret_maybenull_z_
_Ret_null_
_Ret_notnull_
_Ret_writes_bytes_to_
_Ret_writes_bytes_maybenull_
_Ret_writes_bytes_to_maybenull_

문자열 매개 변수 서식 지정

  • _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)

    매개 변수, 필드 또는 결과는 범위(포함)에서 lowhi. _Satisfies_(_Curr_ >= low && _Curr_ <= hi) 이에 해당하며 주석이 추가된 개체에 적절한 사전 상태 또는 사후 상태 조건과 함께 적용됩니다.

    Important

    이름에 "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; ... };

    그런 다음 형식 매개 변수 pM 의 버퍼 크기(바이트) MyStruct * 를 다음과 같이 만듭니다.

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

참고 항목