gloomycoder

SAL 이란?

• 특별한 표식으로 함수의 파라메터, 리턴값 이전에 추가할 수 있으며, 함수의 동작에 관한 리턴값, 파라메터를 설명한다.

• 주석 타입

  • Buffer Annotations (버퍼 표식)

    • 해당 함수가 포인터 파라메터를 어떻게 사용하는지에 대해 설명한다.

  • Advanced Annotations (고급 표식)

    • 복잡하거나 흔하지 않은 버퍼의 행동에 대해 설명하거나, 달리 표현할 수 없는 파라메터에 대해 자세한 정보를 제공한다

Buffer Annotations (버퍼 표식)

• 함수에서 사용되는 파라메터, 리턴값의 일관성있는 표식을 제공한다.
• 각각의 표식은 단일버퍼에 (스트링, 고정 & 가변 배열, 단순 포인터) 대해 함수에서 어디에 있는지, 얼마나 큰지, 얼마나 초기화 되는지, 함수에서 버퍼를 어떻게 사용하는지에 대해 설명한다.
• 주어진 버퍼에 적절한 매크로를 사용하여 다음과 같은 테이블을 만들 수 있다. 그리고 레이어 테이블에서 적절한 값을 받아 옵션 테이블에 해당 옵션을 추가할 수 있다. 그러나 몇몇 조합은 버퍼 표식을 의미없게 만들기도 한다. 반드시 의미가 있는 표식만을 코드에 사용해야 한다.

• 단일 버퍼 표식에 사용해야 하는 파라메터 정보는 다음과 같다.

  
  
  

  (Pre / Post Layer 는 Paramters Layer 나 Return Value Layer 에서 적당한 옵션을 찾지 못한 경우에만 사용해야 한다.)

  
  
  

• Layer , Options 파라메터에 대한 설명

  • Parameters Layer (함수가 파라메터를 어떻게 사용하는지에 대한 설명)

    • (none) : alloc 혹은 free 를 위해서 사용되는 버퍼로 버퍼에 액세스 할 수 없다. 호출자는 반드시 버퍼를 제공해야 한다.
    • _In_ : 함수에서 버퍼에 대한 real 작업을 하며, 호출자는 반드시 초기화된 버퍼를 제공해야 한다.
    • _Out_ : 함수에서 버퍼에 대한 write 작업을 하며, 해당 버퍼를 초기화 할 것이다. 호출자는 버퍼를 제공해야 한다.
    • _Inout_ : 함수에서 버퍼에 대해 read & write 작업을 할 것이며, 호출자는 초기화된 버퍼를 제공해야 한다.
    • _Deref_out_ : 이 옵션은 역참조 되는 output parameter 에 적용된다. (parameter p가 있으면 *p 는 버퍼 포인터이다. p는 NULL 일 수 없다.) 함수는 버퍼에 write 작업을 하며, 함수는 버퍼를 제공해야하며, 초기화를 해야한다.

  • Return Value Layer (함수가 리턴값 버퍼를 어떻게 사용하는지에 대한 설명)

    • (none) : alloc 혹은 free 를 위해서 사용되는 버퍼로 버퍼에 액세스할 수 없다. 함수에서 버퍼를 제공해야 하며, 리턴시점까지 초기화 되지 않아야 한다.
    • _Ret_ : 함수는 초기화된 버퍼를 제공해야 한다.
    • _Deref_ret_ :  이 옵션은 역참조 되는 Return Value 에 적용된다. (parameter p가 있으면 *p 는 버퍼 포인터이다. p는 NULL 일 수 없다.) 함수는 버퍼를 제공해야하며, 초기화를 해야한다.

  • Pre / Post Layer (함수에서 버퍼를 어떻게 사용하는지 설명한다. Paramter layer 혹은 Return Value Layer 에서 적용할 수 있는 옵션이 존재하지 않는 경우에만 사용해야 한다.)

    • _Pre_ : 함수 호출 전 충족되어야 할 조건에 대해 설명한다.
    • _Post_ : 함수 호출 후 적용되어야할 조건에 대해 설명한다.
    • _Deref_pre_ : 함수 호출 전 역참조 되는 배열원소의 조건에 대해 설명한다.
    • _Deref_post_ : 함수 호출 후 적용되어야할 조건에 대해 설명한다. (MSDN 에 _Post_ 와 _Deref_post_ 가 동일하게 설명되어 있다. 하지만 뜻을보면 _Deref_pre_ 와 비슷하게 함수 호출 후 역참조 되는 배열원소의 조건에 데해 설명하는게 맞는거 같다)

  • Optional Options (버퍼 자체 옵션이 존재하는 경우에 대해 설명한다. 이러한 표식들은 parameter layer, return value layer, pre / post layer 에 적용할 수 있다.

    • (none) : 버퍼 포인터가 NULL 일 수 없다.
    • opt_ : 버퍼 포인터가 NULL 일 수 있으며, 역참조 이전에 체크 될 것이다.

  • Null-Termination Option (버퍼의 마지막 유요한 원소가 '\0' 표시로 종료되는 경우에 대해 설명한다. 이러한 표식들은 parameter layer, return value layer, pre / post layer 에 적용할 수 있다.

    • (none) : 버퍼가 null-terminated 가 아닐 수 있고, '\0' 표식이 버퍼의 끝을 가리키지 않는다.

    • z_ : '\0' 표식이 버퍼의 끝을 가리킨다.

  •  

    Extent Option (이 옵션들은 읽기 및 쓰기 가능한 버퍼에 적용할 수 있다. 이러한 표식들은 parameter layer, return value layer, pre / post layer 에 적용할 수 있다.

    • (none) : parameter 혹은 return value 가 읽기 혹은 쓰기 가능한 버퍼가 아니다.

    • cap_[c_|x_](size),  bytecap_[c_|x_](size), ptrdiff_cap_(ptr)

      •  쓰기 가능한 버퍼의 크기를 나타낸다. 이 옵션은 일반적으로 _Out_ 표식과 함께 사용된다.

      •  크기가 원소의 개수로 주어지면 cap_ 을 사용하고, 크기가 바이트로 주어지면 bytecap_ 을 사용한다. 크기가 경계가 있는 포인터일 경우 ptrdiff_cap_ 을 사용한다.

      • 버퍼의 크기가 비상수 parameter 인 경우 c_ 혹은 x_ 를 사용할 필요가 없다. Ex) cap_(size), bytecap_(size) 는 유효한 표식이다.

      • 버퍼의 크기가 상수 표현식인 경우, c_ 옵션을 사용해야 한다. Ex) cap_c_(size), bytecap_c_(size) 는 유효한 표식이다.

      • 버퍼의 크기가 상수 표현식 혹은 비상수 parameter 둘 다 아닌경우 x_ 옵션을 사용해야 한다. Ex) cap_x_(size), bytecap_x_(size)는 유효한 표식이다.

    • count_[c_|x_](size), bytecount_[c_|x_](size), ptrdiff_count_(ptr)

      • 쓰기 가능한 버퍼의 크기를 나타낸다. 이 옵션은 일반적으로 _In_ 표식과 함께 사용된다.

      • 사용법은 cap, bytecap, ptrdiff_cap 과 동일하다 

     

Advanced Annotations

• 고급 표식 기능은 일반적인 버퍼 매크로로 표현할 수 없는 행동에 대해 설명한다. 이것은 복잡하거나 조건별 행동이 존재하는 buffer parameter  표현 하거나 정보를 추가하여 기존에 존재하는 표식에 대한 설명을 자세하게 한다.

• Annotation

  • _Check_return_ : 함수의 리턴값을 콜러가 무시할 수 없게 한다.

  • _Printf_format_string_ : % 마커가 존재하는 printf 스타일의 스트링을 의미한다.

  • _Scanf_format_string_ : % 마커가 존재하는 scanf 스타일의 스트링을 의미한다.

  • _Scanf_s_format_string_ : % 마커가 존재하는 scanf_s 스타일의 스트링을 의미한다.

  • _Success_(expr) : expr 은 함수가 성공 혹은 실패인지를 나타낸다. 함수 종료시 expr 이 true 인 경우 함수의주어진 다른 표식들이 모두 정상이라는 것을 보장한다. 그러나 false 인 경우 콜러는 해당 함수에게 주언식 표식들이 모두 정상이라고 기대하면 안된다. 만약 사용하지 않는 경우 함수는 항상 정상이라는것을 보장해야 한다.덧 붙여 스스로 성공을 가리키는 경우 HRESULT 반환값은 표준적인 방법으로 알린다.

이 글은 스프링노트에서 작성되었습니다.

크리에이티브 커먼즈 라이선스

이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-동일조건변경허락 2.0 대한민국 라이선스에 따라 이용하실 수 있습니다.