/*** *sal.h - markers for documenting the semantics of APIs * * Copyright (c) Microsoft Corporation. All rights reserved. * *Purpose: * sal.h provides a set of annotations to describe how a function uses its * parameters - the assumptions it makes about them, and the guarantees it makes * upon finishing. * * [Public] * ****/

/*========================================================================== The comments in this file are intended to give basic understanding of the usage of SAL, the Microsoft Source Code Annotation Language. For more details, please see https://go.microsoft.com/fwlink/?LinkID=242134 The macros are defined in 3 layers, plus the structural set: _In_/_Out_/_Ret_ Layer: ---------------------- This layer provides the highest abstraction and its macros should be used in most cases. These macros typically start with: _In_ : input parameter to a function, unmodified by called function _Out_ : output parameter, written to by called function, pointed-to location not expected to be initialized prior to call _Outptr_ : like _Out_ when returned variable is a pointer type (so param is pointer-to-pointer type). Called function provides/allocated space. _Outref_ : like _Outptr_, except param is reference-to-pointer type. _Inout_ : inout parameter, read from and potentially modified by called function. _Ret_ : for return values _Field_ : class/struct field invariants For common usage, this class of SAL provides the most concise annotations. Note that _In_/_Out_/_Inout_/_Outptr_ annotations are designed to be used with a parameter target. Using them with _At_ to specify non-parameter targets may yield unexpected results. This layer also includes a number of other properties that can be specified to extend the ability of code analysis, most notably: -- Designating parameters as format strings for printf/scanf/scanf_s -- Requesting stricter type checking for C enum parameters _Pre_/_Post_ Layer: ------------------ The macros of this layer only should be used when there is no suitable macro in the _In_/_Out_ layer. Its macros start with _Pre_ or _Post_. This layer provides the most flexibility for annotations. Implementation Abstraction Layer: -------------------------------- Macros from this layer should never be used directly. The layer only exists to hide the implementation of the annotation macros. Structural Layer: ---------------- These annotations, like _At_ and _When_, are used with annotations from any of the other layers as modifiers, indicating exactly when and where the annotations apply. Common syntactic conventions: ---------------------------- Usage: ----- _In_, _Out_, _Inout_, _Pre_, _Post_, are for formal parameters. _Ret_, _Deref_ret_ must be used for return values. Nullness: -------- If the parameter can be NULL as a precondition to the function, the annotation contains _opt. If the macro does not contain '_opt' the parameter cannot be NULL. If an out/inout parameter returns a null pointer as a postcondition, this is indicated by _Ret_maybenull_ or _result_maybenull_. If the macro is not of this form, then the result will not be NULL as a postcondition. _Outptr_ - output value is not NULL _Outptr_result_maybenull_ - output value might be NULL String Type: ----------- _z: NullTerminated string for _In_ parameters the buffer must have the specified stringtype before the call for _Out_ parameters the buffer must have the specified stringtype after the call for _Inout_ parameters both conditions apply Extent Syntax: ------------- Buffer sizes are expressed as element counts, unless the macro explicitly contains _byte_ or _bytes_. Some annotations specify two buffer sizes, in which case the second is used to indicate how much of the buffer is valid as a postcondition. This table outlines the precondition buffer allocation size, precondition number of valid elements, postcondition allocation size, and postcondition number of valid elements for representative buffer size annotations: Pre | Pre | Post | Post alloc | valid | alloc | valid Annotation elems | elems | elems | elems ---------- ------------------------------------ _In_reads_(s) s | s | s | s _Inout_updates_(s) s | s | s | s _Inout_updates_to_(s,c) s | s | s | c _Out_writes_(s) s | 0 | s | s _Out_writes_to_(s,c) s | 0 | s | c _Outptr_result_buffer_(s) ? | ? | s | s _Outptr_result_buffer_to_(s,c) ? | ? | s | c For the _Outptr_ annotations, the buffer in question is at one level of dereference. The called function is responsible for supplying the buffer. Success and failure: ------------------- The SAL concept of success allows functions to define expressions that can be tested by the caller, which if it evaluates to non-zero, indicates the function succeeded, which means that its postconditions are guaranteed to hold. Otherwise, if the expression evaluates to zero, the function is considered to have failed, and the postconditions are not guaranteed. The success criteria can be specified with the _Success_(expr) annotation: _Success_(return != FALSE) BOOL PathCanonicalizeA(_Out_writes_(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : pszBuf is only guaranteed to be NULL-terminated when TRUE is returned, and FALSE indiates failure. In common practice, callers check for zero vs. non-zero returns, so it is preferable to express the success criteria in terms of zero/non-zero, not checked for exactly TRUE. Functions can specify that some postconditions will still hold, even when the function fails, using _On_failure_(anno-list), or postconditions that hold regardless of success or failure using _Always_(anno-list). The annotation _Return_type_success_(expr) may be used with a typedef to give a default _Success_ criteria to all functions returning that type. This is the case for common Windows API status types, including HRESULT and NTSTATUS. This may be overridden on a per-function basis by specifying a _Success_ annotation locally. ============================================================================*/

// Disable expansion of SAL macros in non-Prefast mode to

// improve compiler throughput.

// safeguard for MIDL and RC builds

// Some annotations aren't officially SAL2 yet.

//============================================================================

// Structural SAL:

// These annotations modify the use of other annotations. They may

// express the annotation target (i.e. what parameter/field the annotation

// applies to) or the condition under which the annotation is applicable.

//============================================================================

// _At_(target, annos) specifies that the annotations listed in 'annos' is to

// be applied to 'target' rather than to the identifier which is the current

// lexical target.

// _At_buffer_(target, iter, bound, annos) is similar to _At_, except that

// target names a buffer, and each annotation in annos is applied to each

// element of target up to bound, with the variable named in iter usable

// by the annotations to refer to relevant offsets within target.

// _When_(expr, annos) specifies that the annotations listed in 'annos' only

// apply when 'expr' evaluates to non-zero.

// <expr> indicates whether normal post conditions apply to a function

// <expr> indicates whether post conditions apply to a function returning

// the type that this annotation is applied to

// Establish postconditions that apply only if the function does not succeed

// Establish postconditions that apply in both success and failure cases.

// Only applicable with functions that have _Success_ or _Return_type_succss_.

// Usable on a function defintion. Asserts that a function declaration is

// in scope, and its annotations are to be used. There are no other annotations

// allowed on the function definition.

// _Notref_ may precede a _Deref_ or "real" annotation, and removes one

// level of dereference if the parameter is a C++ reference (&). If the

// net deref on a "real" annotation is negative, it is simply discarded.

// Annotations for defensive programming styles.

//============================================================================

// _In_/_Out_ Layer:

//============================================================================

// Reserved pointer parameters, must always be NULL.

// _Const_ allows specification that any namable memory location is considered

// readonly for a given call.

// Input parameters --------------------------

// _In_ - Annotations for parameters where data is passed into the function, but not modified.

// _In_ by itself can be used with non-pointer types (although it is redundant).

// e.g. void SetPoint( _In_ const POINT* pPT );

// nullterminated 'in' parameters.

// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );

// 'input' buffers with given size

// 'input' buffers valid to the given end pointer

// Output parameters --------------------------

// _Out_ - Annotations for pointer or reference parameters where data passed back to the caller.

// These are mostly used where the pointer/reference is to a non-pointer type.

// _Outptr_/_Outref) (see below) are typically used to return pointers via parameters.

// e.g. void GetPoint( _Out_ POINT* pPT );

// Inout parameters ----------------------------

// _Inout_ - Annotations for pointer or reference parameters where data is passed in and

// potentially modified.

// void ModifyPoint( _Inout_ POINT* pPT );

// void ModifyPointByRef( _Inout_ POINT& pPT );

// For modifying string buffers

// void toupper( _Inout_z_ char* sz );

// For modifying buffers with explicit element size

// For modifying buffers with explicit byte size

// Pointer to pointer parameters -------------------------

// _Outptr_ - Annotations for output params returning pointers

// These describe parameters where the called function provides the buffer:

// HRESULT SHStrDupW(_In_ LPCWSTR psz, _Outptr_ LPWSTR *ppwsz);

// The caller passes the address of an LPWSTR variable as ppwsz, and SHStrDupW allocates

// and initializes memory and returns the pointer to the new LPWSTR in *ppwsz.

//

// _Outptr_opt_ - describes parameters that are allowed to be NULL.

// _Outptr_*_result_maybenull_ - describes parameters where the called function might return NULL to the caller.

//

// Example:

// void MyFunc(_Outptr_opt_ int **ppData1, _Outptr_result_maybenull_ int **ppData2);

// Callers:

// MyFunc(NULL, NULL); // error: parameter 2, ppData2, should not be NULL

// MyFunc(&pData1, &pData2); // ok: both non-NULL

// if (*pData1 == *pData2) ... // error: pData2 might be NULL after call

// Annotations for _Outptr_ parameters returning pointers to null terminated strings.

// Annotations for _Outptr_ parameters where the output pointer is set to NULL if the function fails.

// Annotations for _Outptr_ parameters which return a pointer to a ref-counted COM object,

// following the COM convention of setting the output to NULL on failure.

// The current implementation is identical to _Outptr_result_nullonfailure_.

// For pointers to types that are not COM objects, _Outptr_result_nullonfailure_ is preferred.

// Annotations for _Outptr_ parameters returning a pointer to buffer with a specified number of elements/bytes

// Annotations for output reference to pointer parameters.

// Annotations for output reference to pointer parameters that guarantee

// that the pointer is set to NULL on failure.

// Generic annotations to set output value of a by-pointer or by-reference parameter to null/zero on failure.

// return values -------------------------------

//

// _Ret_ annotations

//

// describing conditions that hold for return values after the call

// e.g. _Ret_z_ CString::operator const wchar_t*() const noexcept;

// used with allocated but not yet initialized objects

// used with allocated and initialized objects

// returns single valid object

// returns pointer to initialized buffer of specified size

// returns pointer to partially initialized buffer, with total size 'size' and initialized size 'count'

// Annotations for strict type checking

// Check the return value of a function e.g. _Check_return_ ErrorCode Foo();

// e.g. MyPrintF( _Printf_format_string_ const wchar_t* wzFormat, ... );

// annotations to express value of integral or pointer parameter

// annotation to express that a value (usually a field of a mutable class)

// is not changed by a function call

// Annotations to allow expressing generalized pre and post conditions.

// 'cond' may be any valid SAL expression that is considered to be true as a precondition

// or postcondition (respsectively).

// Annotations to express struct, class and field invariants

//============================================================================

// _Pre_/_Post_ Layer:

//============================================================================

//

// Raw Pre/Post for declaring custom pre/post conditions

//

//

// Validity property

//

//

// Buffer size properties

//

// Expressing buffer sizes without specifying pre or post condition

// Expressing buffer size as pre or post condition

//

// Pointer null-ness properties

//

//

// _Pre_ annotations ---

//

// describing conditions that must be met before the call of the function

// e.g. int strlen( _Pre_z_ const char* sz );

// buffer is a zero terminated string

// valid size unknown or indicated by type (e.g.:LPSTR)

// Overrides recursive valid when some field is not yet initialized when using _Inout_

// used with allocated but not yet initialized objects

//

// _Post_ annotations ---

//

// describing conditions that hold after the function call

// void CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_ char* szFrom, size_t cchFrom );

// buffer will be a zero-terminated string after the call

// e.g. HRESULT InitStruct( _Post_valid_ Struct* pobj );

// e.g. void free( _Post_ptr_invalid_ void* pv );

// e.g. void ThrowExceptionIfNull( _Post_notnull_ const void* pv );

// e.g. HRESULT GetObject(_Outptr_ _On_failure_(_At_(*p, _Post_null_)) T **p);

/*========================================================================== This section contains definitions for macros defined for VS2010 and earlier. Usage of these macros is still supported, but the SAL 2 macros defined above are recommended instead. This comment block is retained to assist in understanding SAL that still uses the older syntax. The macros are defined in 3 layers: _In_/_Out_ Layer: ---------------- This layer provides the highest abstraction and its macros should be used in most cases. Its macros start with _In_, _Out_ or _Inout_. For the typical case they provide the most concise annotations. _Pre_/_Post_ Layer: ------------------ The macros of this layer only should be used when there is no suitable macro in the _In_/_Out_ layer. Its macros start with _Pre_, _Post_, _Ret_, _Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most flexibility for annotations. Implementation Abstraction Layer: -------------------------------- Macros from this layer should never be used directly. The layer only exists to hide the implementation of the annotation macros. Annotation Syntax: |--------------|----------|----------------|-----------------------------| | Usage | Nullness | ZeroTerminated | Extent | |--------------|----------|----------------|-----------------------------| | _In_ | <> | <> | <> | | _Out_ | opt_ | z_ | [byte]cap_[c_|x_]( size ) | | _Inout_ | | | [byte]count_[c_|x_]( size ) | | _Deref_out_ | | | ptrdiff_cap_( ptr ) | |--------------| | | ptrdiff_count_( ptr ) | | _Ret_ | | | | | _Deref_ret_ | | | | |--------------| | | | | _Pre_ | | | | | _Post_ | | | | | _Deref_pre_ | | | | | _Deref_post_ | | | | |--------------|----------|----------------|-----------------------------| Usage: ----- _In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for formal parameters. _Ret_, _Deref_ret_ must be used for return values. Nullness: -------- If the pointer can be NULL the annotation contains _opt. If the macro does not contain '_opt' the pointer may not be NULL. String Type: ----------- _z: NullTerminated string for _In_ parameters the buffer must have the specified stringtype before the call for _Out_ parameters the buffer must have the specified stringtype after the call for _Inout_ parameters both conditions apply Extent Syntax: |------|---------------|---------------| | Unit | Writ/Readable | Argument Type | |------|---------------|---------------| | <> | cap_ | <> | | byte | count_ | c_ | | | | x_ | |------|---------------|---------------| 'cap' (capacity) describes the writable size of the buffer and is typically used with _Out_. The default unit is elements. Use 'bytecap' if the size is given in bytes 'count' describes the readable size of the buffer and is typically used with _In_. The default unit is elements. Use 'bytecount' if the size is given in bytes. Argument syntax for cap_, bytecap_, count_, bytecount_: (<parameter>|return)[+n] e.g. cch, return, cb+2 If the buffer size is a constant expression use the c_ postfix. E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16) If the buffer size is given by a limiting pointer use the ptrdiff_ versions of the macros. If the buffer size is neither a parameter nor a constant expression use the x_ postfix. e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string. No analysis can be done for x_ annotations but they at least tell the tool that the buffer has some sort of extent description. x_ annotations might be supported by future compiler versions. ============================================================================*/

// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )

// valid buffer extent described by another parameter

// valid buffer extent described by a constant extression

// nullterminated 'input' buffers with given size

// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )

// nullterminated valid buffer extent described by another parameter

// nullterminated valid buffer extent described by a constant extression

// buffer capacity is described by another pointer

// e.g. void Foo( _In_ptrdiff_count_(pchMax) const char* pch, const char* pchMax ) { while pch < pchMax ) pch++; }

// 'x' version for complex expressions that are not supported by the current compiler version

// e.g. void Set3ColMatrix( _In_count_x_(3*cRows) const Elem* matrix, int cRows );

// 'out' with buffer size

// e.g. void GetIndeces( _Out_cap_(cIndeces) int* rgIndeces, size_t cIndices );

// buffer capacity is described by another parameter

// buffer capacity is described by a constant expression

// buffer capacity is described by another parameter multiplied by a constant expression

// buffer capacity is described by another pointer

// e.g. void Foo( _Out_ptrdiff_cap_(pchMax) char* pch, const char* pchMax ) { while pch < pchMax ) pch++; }

// buffer capacity is described by a complex expression

// a zero terminated string is filled into a buffer of given capacity

// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );

// buffer capacity is described by another parameter

// buffer capacity is described by a constant expression

// buffer capacity is described by a complex expression

// a zero terminated string is filled into a buffer of given capacity

// e.g. size_t CopyCharRange( _In_count_(cchFrom) const char* rgchFrom, size_t cchFrom, _Out_cap_post_count_(cchTo,return)) char* rgchTo, size_t cchTo );

// a zero terminated string is filled into a buffer of given capacity

// e.g. size_t CopyStr( _In_z_ const char* szFrom, _Out_z_cap_post_count_(cchTo,return+1) char* szTo, size_t cchTo );

// only use with dereferenced arguments e.g. '*pcch'

// e.g. GetString( _Out_z_capcount_(*pLen+1) char* sz, size_t* pLen );

// 'inout' buffers with initialized elements before and after the call

// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices );

// nullterminated 'inout' buffers with initialized elements before and after the call

// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices );

// e.g. void AppendToLPSTR( _In_ LPCSTR szFrom, _Inout_cap_(cchTo) LPSTR* szTo, size_t cchTo );

// inout string buffers with writable size

// e.g. void AppendStr( _In_z_ const char* szFrom, _Inout_z_cap_(cchTo) char* szTo, size_t cchTo );

// returning pointers to valid objects

// annotations to express 'boundedness' of integral value parameter

// e.g. HRESULT HrCreatePoint( _Deref_out_opt_ POINT** ppPT );

// e.g. void CloneString( _In_z_ const wchar_t* wzFrom, _Deref_out_z_ wchar_t** pWzTo );

//

// _Deref_pre_ ---

//

// describing conditions for array elements of dereferenced pointer parameters that must be met before the call

// e.g. void SaveStringArray( _In_count_(cStrings) _Deref_pre_z_ const wchar_t* const rgpwch[] );

// e.g. void FillInArrayOfStr32( _In_count_(cStrings) _Deref_pre_cap_c_(32) _Deref_post_z_ wchar_t* const rgpwch[] );

// buffer capacity is described by another parameter

// buffer capacity is described by a constant expression

// buffer capacity is described by a complex condition

// convenience macros for nullterminated buffers with given capacity

// known capacity and valid but unknown readable extent

// e.g. void SaveMatrix( _In_count_(n) _Deref_pre_count_(n) const Elem** matrix, size_t n );

// valid buffer extent is described by another parameter

// valid buffer extent is described by a constant expression

// valid buffer extent is described by a complex expression

// e.g. void PrintStringArray( _In_count_(cElems) _Deref_pre_valid_ LPCSTR rgStr[], size_t cElems );

// restrict access rights

//

// _Deref_post_ ---

//

// describing conditions for array elements or dereferenced pointer parameters that hold after the call

// e.g. void CloneString( _In_z_ const Wchar_t* wzIn _Out_ _Deref_post_z_ wchar_t** pWzOut );

// e.g. HRESULT HrAllocateMemory( size_t cb, _Out_ _Deref_post_bytecap_(cb) void** ppv );

// buffer capacity is described by another parameter

// buffer capacity is described by a constant expression

// buffer capacity is described by a complex expression

// convenience macros for nullterminated buffers with given capacity

// known capacity and valid but unknown readable extent

// e.g. HRESULT HrAllocateZeroInitializedMemory( size_t cb, _Out_ _Deref_post_bytecount_(cb) void** ppv );

// valid buffer extent is described by another parameter

// buffer capacity is described by a constant expression

// buffer capacity is described by a complex expression

// e.g. void GetStrings( _Out_count_(cElems) _Deref_post_valid_ LPSTR const rgStr[], size_t cElems );

//

// _Deref_ret_ ---

//

//

// special _Deref_ ---

//

//

// _Ret_ ---

//

// e.g. _Ret_opt_valid_ LPSTR void* CloneSTR( _Pre_valid_ LPSTR src );

// e.g. _Ret_opt_bytecap_(cb) void* AllocateMemory( size_t cb );

// Buffer capacity is described by another parameter

// Buffer capacity is described by a constant expression

// Buffer capacity is described by a complex condition

// return value is nullterminated and capacity is given by another parameter

// e.g. _Ret_opt_bytecount_(cb) void* AllocateZeroInitializedMemory( size_t cb );

// Valid Buffer extent is described by another parameter

// Valid Buffer extent is described by a constant expression

// Valid Buffer extent is described by a complex expression

// return value is nullterminated and length is given by another parameter

// _Pre_ annotations ---

// restrict access rights

// e.g. void FreeMemory( _Pre_bytecap_(cb) _Post_ptr_invalid_ void* pv, size_t cb );

// buffer capacity described by another parameter

// buffer capacity described by a constant expression

// buffer capacity is described by another parameter multiplied by a constant expression

// buffer capacity described by size of other buffer, only used by dangerous legacy APIs

// e.g. int strcpy(_Pre_cap_for_(src) char* dst, const char* src);

// buffer capacity described by a complex condition

// buffer capacity described by the difference to another pointer parameter

// e.g. void AppendStr( _Pre_z_ const char* szFrom, _Pre_z_cap_(cchTo) _Post_z_ char* szTo, size_t cchTo );

// known capacity and valid but unknown readable extent

// e.g. void AppendCharRange( _Pre_count_(cchFrom) const char* rgFrom, size_t cchFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );

// Valid buffer extent described by another parameter

// Valid buffer extent described by a constant expression

// Valid buffer extent described by a complex expression

// Valid buffer extent described by the difference to another pointer parameter

// char * strncpy(_Out_cap_(_Count) _Post_maybez_ char * _Dest, _In_z_ const char * _Source, _In_ size_t _Count)

// buffer maybe zero-terminated after the call

// e.g. SIZE_T HeapSize( _In_ HANDLE hHeap, DWORD dwFlags, _Pre_notnull_ _Post_bytecap_(return) LPCVOID lpMem );

// e.g. int strlen( _In_z_ _Post_count_(return+1) const char* sz );

// e.g. size_t CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_count_(return+1) char* szFrom, size_t cchFrom );

//

// _Prepost_ ---

//

// describing conditions that hold before and after the function call

//

// _Deref_<both> ---

//

// short version for _Deref_pre_<ann> _Deref_post_<ann>

// describing conditions for array elements or dereferenced pointer parameters that hold before and after the call

//

// _Deref_<miscellaneous>

//

// used with references to arrays

//============================================================================

// Implementation Layer:

//============================================================================

// Naming conventions:

// A symbol the begins with _SA_ is for the machinery of creating any

// annotations; many of those come from sourceannotations.h in the case

// of attributes.

// A symbol that ends with _impl is the very lowest level macro. It is

// not required to be a legal standalone annotation, and in the case

// of attribute annotations, usually is not. (In the case of some declspec

// annotations, it might be, but it should not be assumed so.) Those

// symols will be used in the _PreN..., _PostN... and _RetN... annotations

// to build up more complete annotations.

// A symbol ending in _impl_ is reserved to the implementation as well,

// but it does form a complete annotation; usually they are used to build

// up even higher level annotations.

// Using "nothing" for sal

// Obsolete -- may be needed for transition to attributes.

// This section contains the deprecated annotations

/* ------------------------------------------------------------------------------- Introduction sal.h provides a set of annotations to describe how a function uses its parameters - the assumptions it makes about them, and the guarantees it makes upon finishing. Annotations may be placed before either a function parameter's type or its return type, and describe the function's behavior regarding the parameter or return value. There are two classes of annotations: buffer annotations and advanced annotations. Buffer annotations describe how functions use their pointer parameters, and advanced annotations either describe complex/unusual buffer behavior, or provide additional information about a parameter that is not otherwise expressible. ------------------------------------------------------------------------------- Buffer Annotations The most important annotations in sal.h provide a consistent way to annotate buffer parameters or return values for a function. Each of these annotations describes a single buffer (which could be a string, a fixed-length or variable-length array, or just a pointer) that the function interacts with: where it is, how large it is, how much is initialized, and what the function does with it. The appropriate macro for a given buffer can be constructed using the table below. Just pick the appropriate values from each category, and combine them together with a leading underscore. Some combinations of values do not make sense as buffer annotations. Only meaningful annotations can be added to your code; for a list of these, see the buffer annotation definitions section. Only a single buffer annotation should be used for each parameter. |------------|------------|---------|--------|----------|----------|---------------| | Level | Usage | Size | Output | NullTerm | Optional | Parameters | |------------|------------|---------|--------|----------|----------|---------------| | <> | <> | <> | <> | _z | <> | <> | | _deref | _in | _ecount | _full | _nz | _opt | (size) | | _deref_opt | _out | _bcount | _part | | | (size,length) | | | _inout | | | | | | | | | | | | | | |------------|------------|---------|--------|----------|----------|---------------| Level: Describes the buffer pointer's level of indirection from the parameter or return value 'p'. <> : p is the buffer pointer. _deref : *p is the buffer pointer. p must not be NULL. _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of the annotation is ignored. Usage: Describes how the function uses the buffer. <> : The buffer is not accessed. If used on the return value or with _deref, the function will provide the buffer, and it will be uninitialized at exit. Otherwise, the caller must provide the buffer. This should only be used for alloc and free functions. _in : The function will only read from the buffer. The caller must provide the buffer and initialize it. Cannot be used with _deref. _out : The function will only write to the buffer. If used on the return value or with _deref, the function will provide the buffer and initialize it. Otherwise, the caller must provide the buffer, and the function will initialize it. _inout : The function may freely read from and write to the buffer. The caller must provide the buffer and initialize it. If used with _deref, the buffer may be reallocated by the function. Size: Describes the total size of the buffer. This may be less than the space actually allocated for the buffer, in which case it describes the accessible amount. <> : No buffer size is given. If the type specifies the buffer size (such as with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one element long. Must be used with _in, _out, or _inout. _ecount : The buffer size is an explicit element count. _bcount : The buffer size is an explicit byte count. Output: Describes how much of the buffer will be initialized by the function. For _inout buffers, this also describes how much is initialized at entry. Omit this category for _in buffers; they must be fully initialized by the caller. <> : The type specifies how much is initialized. For instance, a function initializing an LPWSTR must NULL-terminate the string. _full : The function initializes the entire buffer. _part : The function initializes part of the buffer, and explicitly indicates how much. NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer. _z : A '\0' indicated the end of the buffer _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the buffer. Optional: Describes if the buffer itself is optional. <> : The pointer to the buffer must not be NULL. _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced. Parameters: Gives explicit counts for the size and length of the buffer. <> : There is no explicit count. Use when neither _ecount nor _bcount is used. (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part. (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part and _bcount_part. ------------------------------------------------------------------------------- Buffer Annotation Examples LWSTDAPI_(BOOL) StrToIntExA( __in LPCSTR pszString, DWORD dwFlags, __out int *piRet -- A pointer whose dereference will be filled in. ); void MyPaintingFunction( __in HWND hwndControl, -- An initialized read-only parameter. __in_opt HDC hdcOptional, -- An initialized read-only parameter that might be NULL. __inout IPropertyStore *ppsStore -- An initialized parameter that may be freely used -- and modified. ); LWSTDAPI_(BOOL) PathCompactPathExA( __out_ecount(cchMax) LPSTR pszOut, -- A string buffer with cch elements that will -- be NULL terminated on exit. __in LPCSTR pszSrc, UINT cchMax, DWORD dwFlags ); HRESULT SHLocalAllocBytes( size_t cb, __deref_bcount(cb) T **ppv -- A pointer whose dereference will be set to an -- uninitialized buffer with cb bytes. ); __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at entry and exit, and may be written to by this function. __out_ecount_part(count, *countOut) : A buffer with count elements that will be partially initialized by this function. The function indicates how much it initialized by setting *countOut. ------------------------------------------------------------------------------- Advanced Annotations Advanced annotations describe behavior that is not expressible with the regular buffer macros. These may be used either to annotate buffer parameters that involve complex or conditional behavior, or to enrich existing annotations with additional information. __success(expr) f : <expr> indicates whether function f succeeded or not. If <expr> is true at exit, all the function's guarantees (as given by other annotations) must hold. If <expr> is false at exit, the caller should not expect any of the function's guarantees to hold. If not used, the function must always satisfy its guarantees. Added automatically to functions that indicate success in standard ways, such as by returning an HRESULT. __nullterminated p : Pointer p is a buffer that may be read or written up to and including the first NULL character or pointer. May be used on typedefs, which marks valid (properly initialized) instances of that type as being NULL-terminated. __nullnullterminated p : Pointer p is a buffer that may be read or written up to and including the first sequence of two NULL characters or pointers. May be used on typedefs, which marks valid instances of that type as being double-NULL terminated. __reserved v : Value v must be 0/NULL, reserved for future use. __checkReturn v : Return value v must not be ignored by callers of this function. __typefix(ctype) v : Value v should be treated as an instance of ctype, rather than its declared type. __override f : Specify C#-style 'override' behaviour for overriding virtual methods. __callback f : Function f can be used as a function pointer. __format_string p : Pointer p is a string that contains % markers in the style of printf. __blocksOn(resource) f : Function f blocks on the resource 'resource'. __fallthrough : Annotates switch statement labels where fall-through is desired, to distinguish from forgotten break statements. ------------------------------------------------------------------------------- Advanced Annotation Examples __success(return != FALSE) LWSTDAPI_(BOOL) PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. ------------------------------------------------------------------------------- */

/* ------------------------------------------------------------------------------- Helper Macro Definitions These express behavior common to many of the high-level annotations. DO NOT USE THESE IN YOUR CODE. ------------------------------------------------------------------------------- */

/* The helper annotations are only understood by the compiler version used by various defect detection tools. When the regular compiler is running, they are defined into nothing, and do not affect the compiled code. */

/* ------------------------------------------------------------------------------- Buffer Annotation Definitions Any of these may be used to directly annotate functions, but only one should be used for each parameter. To determine which annotation to use for a given buffer, use the table in the buffer annotations section. ------------------------------------------------------------------------------- */

/* ------------------------------------------------------------------------------- Advanced Annotation Definitions Any of these may be used to directly annotate functions, and may be used in combination with each other or with regular buffer macros. For an explanation of each annotation, see the advanced annotations section. ------------------------------------------------------------------------------- */

//

// Set the analysis mode (global flags to analysis).

// They take effect at the point of declaration; use at global scope

// as a declaration.

//

// Synthesize a unique symbol.

//

// Floating point warnings are only meaningful in kernel-mode on x86

// so avoid reporting them on other platforms.

//

// The following are predefined:

// _Analysis_operator_new_throw_ (operator new throws)

// _Analysis_operator_new_null_ (operator new returns null)

// _Analysis_operator_new_never_fails_ (operator new never fails)

//

// Function class annotations.