diff options
Diffstat (limited to 'src/pal/inc/rt/specstrings_strict.h')
-rw-r--r-- | src/pal/inc/rt/specstrings_strict.h | 1190 |
1 files changed, 1190 insertions, 0 deletions
diff --git a/src/pal/inc/rt/specstrings_strict.h b/src/pal/inc/rt/specstrings_strict.h new file mode 100644 index 0000000000..514106eedf --- /dev/null +++ b/src/pal/inc/rt/specstrings_strict.h @@ -0,0 +1,1190 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + +/************************************************************************* +* This file documents all the macros approved for use in windows source +* code. It includes some experimental macros which should only be used by +* experts. +* +* DO NOT include this file directly. This file is include after +* specstrings.h. So we can undefine every possible old definition including +* private internal macros people should not be using, as well as macros from +* sal.h. Macros are redefined here in a way to cause syntax errors when used +* incorrectly during a normal build when specstrings.h is included and +* __SPECSTRINGS_STRICT_LEVEL is defined. +* +* There are several levels of strictness, each level includes the behavior of +* all previous levels. +* +* 0 - Disable strict checking +* 1 - Break on unapproved macros and misuse of statement +* macros such as __fallthrough (default) +* 2 - Deprecated some old macros that should not be used +* 3 - Use VS 2005 Source Annotation to make sure every macro +* is used in the right context. For example placing __in on a return +* parameter will result in an error. +* + +* +************************************************************************/ +#ifndef __SPECSTRINGS_STRICT_LEVEL +#define __SPECSTRINGS_STRICT_LEVEL 1 +#endif +/************************************************************************ +* Introduction +* +* specstrings.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 must be placed before a function parameter's type or its return +* type. There are two basic classes of common 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 SpecStrings.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 | Optional | Parameters | +* |------------|------------|---------|--------|----------|---------------| +* | <> | <> | <> | <> | <> | <> | +* | _deref | _in | _ecount | _full | _opt | (size) | +* | _deref_opt | _out | _bcount | _part | | (size,length) | +* | | _inout | | | | | +* | | | | | | | +* |------------|------------|---------|--------|----------|---------------| +* +* Note: "<>" represents the empty string. +* +* 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. +* +* _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. +* +* 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( +* LPCSTR pszString, // No annotation required, const implies __in. +* 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 '\0' terminated +* // on exit. +* LPCSTR pszSrc, // No annotation required, +* // const implies __in. +* 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. +* +************************************************************************/ + +#if (_MSC_VER >= 1400) && !defined(__midl) && !defined(_PREFAST_) && (__SPECSTRINGS_STRICT_LEVEL > 0) +#pragma once +#include <specstrings_undef.h> +#define __ecount(size) _SAL_VERSION_CHECK(__ecount) +#define __bcount(size) _SAL_VERSION_CHECK(__bcount) +#define __xcount(size) _SAL_VERSION_CHECK(__xcount) +#define __in _SAL_VERSION_CHECK(__in) +#define __in_ecount(size) _SAL_VERSION_CHECK(__in_ecount) +#define __in_bcount(size) _SAL_VERSION_CHECK(__in_bcount) +#define __in_xcount(size) _SAL_VERSION_CHECK(__in_xcount) +#define __in_z _SAL_VERSION_CHECK(__in_z) +#define __in_ecount_z(size) _SAL_VERSION_CHECK(__in_ecount_z) +#define __in_bcount_z(size) _SAL_VERSION_CHECK(__in_bcount_z) +#define __out _SAL_VERSION_CHECK(__out) +#define __out_ecount(size) _SAL_VERSION_CHECK(__out_ecount) +#define __out_bcount(size) _SAL_VERSION_CHECK(__out_bcount) +#define __out_xcount(size) _SAL_VERSION_CHECK(__out_xcount) +#define __out_ecount_part(size,len) _SAL_VERSION_CHECK(__out_ecount_part) +#define __out_bcount_part(size,len) _SAL_VERSION_CHECK(__out_bcount_part) +#define __out_xcount_part(size,len) _SAL_VERSION_CHECK(__out_xcount_part) +#define __out_ecount_full(size) _SAL_VERSION_CHECK(__out_ecount_full) +#define __out_bcount_full(size) _SAL_VERSION_CHECK(__out_bcount_full) +#define __out_xcount_full(size) _SAL_VERSION_CHECK(__out_xcount_full) +#define __out_z _SAL_VERSION_CHECK(__out_z) +#define __out_ecount_z(size) _SAL_VERSION_CHECK(__out_ecount_z) +#define __out_bcount_z(size) _SAL_VERSION_CHECK(__out_bcount_z) +#define __inout _SAL_VERSION_CHECK(__inout) +#define __inout_ecount(size) _SAL_VERSION_CHECK(__inout_ecount) +#define __inout_bcount(size) _SAL_VERSION_CHECK(__inout_bcount) +#define __inout_xcount(size) _SAL_VERSION_CHECK(__inout_xcount) +#define __inout_ecount_part(size,len) _SAL_VERSION_CHECK(__inout_ecount_part) +#define __inout_bcount_part(size,len) _SAL_VERSION_CHECK(__inout_bcount_part) +#define __inout_xcount_part(size,len) _SAL_VERSION_CHECK(__inout_xcount_part) +#define __inout_ecount_full(size) _SAL_VERSION_CHECK(__inout_ecount_full) +#define __inout_bcount_full(size) _SAL_VERSION_CHECK(__inout_bcount_full) +#define __inout_xcount_full(size) _SAL_VERSION_CHECK(__inout_xcount_full) +#define __inout_z __allowed(on_parameter) +#define __inout_ecount_z(size) __allowed(on_parameter) +#define __inout_bcount_z(size) __allowed(on_parameter) +#define __ecount_opt(size) __allowed(on_parameter) +#define __bcount_opt(size) __allowed(on_parameter) +#define __xcount_opt(size) __allowed(on_parameter) +#define __in_opt _SAL_VERSION_CHECK(__in_opt) +#define __in_ecount_opt(size) _SAL_VERSION_CHECK(__in_ecount_opt) +#define __in_bcount_opt(size) _SAL_VERSION_CHECK(__in_bcount_opt) +#define __in_z_opt __allowed(on_parameter) +#define __in_ecount_z_opt(size) __allowed(on_parameter) +#define __in_bcount_z_opt(size) __allowed(on_parameter) +#define __in_xcount_opt(size) __allowed(on_parameter) +#define __out_opt _SAL_VERSION_CHECK(__out_opt) +#define __out_ecount_opt(size) _SAL_VERSION_CHECK(__out_ecount_opt) +#define __out_bcount_opt(size) _SAL_VERSION_CHECK(__out_bcount_opt) +#define __out_xcount_opt(size) __allowed(on_parameter) +#define __out_ecount_part_opt(size,len) __allowed(on_parameter) +#define __out_bcount_part_opt(size,len) __allowed(on_parameter) +#define __out_xcount_part_opt(size,len) __allowed(on_parameter) +#define __out_ecount_full_opt(size) __allowed(on_parameter) +#define __out_bcount_full_opt(size) __allowed(on_parameter) +#define __out_xcount_full_opt(size) __allowed(on_parameter) +#define __out_ecount_z_opt(size) __allowed(on_parameter) +#define __out_bcount_z_opt(size) __allowed(on_parameter) +#define __inout_opt _SAL_VERSION_CHECK(__inout_opt) +#define __inout_ecount_opt(size) _SAL_VERSION_CHECK(__inout_ecount_opt) +#define __inout_bcount_opt(size) _SAL_VERSION_CHECK(__inout_bcount_opt) +#define __inout_xcount_opt(size) _SAL_VERSION_CHECK(__inout_xcount_opt) +#define __inout_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_ecount_part_opt) +#define __inout_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_bcount_part_opt) +#define __inout_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_xcount_part_opt) +#define __inout_ecount_full_opt(size) _SAL_VERSION_CHECK(__inout_ecount_full_opt) +#define __inout_bcount_full_opt(size) _SAL_VERSION_CHECK(__inout_bcount_full_opt) +#define __inout_xcount_full_opt(size) _SAL_VERSION_CHECK(__inout_xcount_full_opt) +#define __inout_z_opt __allowed(on_parameter) +#define __inout_ecount_z_opt(size) __allowed(on_parameter) +#define __inout_ecount_z_opt(size) __allowed(on_parameter) +#define __inout_bcount_z_opt(size) __allowed(on_parameter) +#define __deref_ecount(size) __allowed(on_parameter) +#define __deref_bcount(size) __allowed(on_parameter) +#define __deref_xcount(size) __allowed(on_parameter) +#define __deref_in _SAL_VERSION_CHECK(__deref_in) +#define __deref_in_ecount(size) _SAL_VERSION_CHECK(__deref_in_ecount) +#define __deref_in_bcount(size) _SAL_VERSION_CHECK(__deref_in_bcount) +#define __deref_in_xcount(size) _SAL_VERSION_CHECK(__deref_in_xcount) +#define __deref_out _SAL_VERSION_CHECK(__deref_out) +#define __deref_out_ecount(size) _SAL_VERSION_CHECK(__deref_out_ecount) +#define __deref_out_bcount(size) _SAL_VERSION_CHECK(__deref_out_bcount) +#define __deref_out_xcount(size) _SAL_VERSION_CHECK(__deref_out_xcount) +#define __deref_out_ecount_part(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part) +#define __deref_out_bcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part) +#define __deref_out_xcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part) +#define __deref_out_ecount_full(size) _SAL_VERSION_CHECK(__deref_out_ecount_full) +#define __deref_out_bcount_full(size) _SAL_VERSION_CHECK(__deref_out_bcount_full) +#define __deref_out_xcount_full(size) _SAL_VERSION_CHECK(__deref_out_xcount_full) +#define __deref_out_z __allowed(on_parameter) +#define __deref_out_ecount_z(size) __allowed(on_parameter) +#define __deref_out_bcount_z(size) __allowed(on_parameter) +#define __deref_inout _SAL_VERSION_CHECK(__deref_inout) +#define __deref_inout_ecount(size) _SAL_VERSION_CHECK(__deref_inout_ecount) +#define __deref_inout_bcount(size) _SAL_VERSION_CHECK(__deref_inout_bcount) +#define __deref_inout_xcount(size) _SAL_VERSION_CHECK(__deref_inout_xcount) +#define __deref_inout_ecount_part(size,len) __allowed(on_parameter) +#define __deref_inout_bcount_part(size,len) __allowed(on_parameter) +#define __deref_inout_xcount_part(size,len) __allowed(on_parameter) +#define __deref_inout_ecount_full(size) __allowed(on_parameter) +#define __deref_inout_bcount_full(size) __allowed(on_parameter) +#define __deref_inout_xcount_full(size) __allowed(on_parameter) +#define __deref_inout_z __allowed(on_parameter) +#define __deref_inout_ecount_z(size) __allowed(on_parameter) +#define __deref_inout_bcount_z(size) __allowed(on_parameter) +#define __deref_ecount_opt(size) __allowed(on_parameter) +#define __deref_bcount_opt(size) __allowed(on_parameter) +#define __deref_xcount_opt(size) __allowed(on_parameter) +#define __deref_in_opt __allowed(on_parameter) +#define __deref_in_opt_out __allowed(on_parameter) +#define __deref_in_ecount_opt(size) __allowed(on_parameter) +#define __deref_in_bcount_opt(size) __allowed(on_parameter) +#define __deref_in_xcount_opt(size) __allowed(on_parameter) +#define __deref_out_opt _SAL_VERSION_CHECK(__deref_out_opt) +#define __deref_out_ecount_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_opt) +#define __deref_out_bcount_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_opt) +#define __deref_out_xcount_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_opt) +#define __deref_out_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part_opt) +#define __deref_out_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part_opt) +#define __deref_out_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part_opt) +#define __deref_out_ecount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_full_opt) +#define __deref_out_bcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_full_opt) +#define __deref_out_xcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_full_opt) +#define __deref_out_z_opt __allowed(on_parameter) +#define __deref_out_ecount_z_opt(size) __allowed(on_parameter) +#define __deref_out_bcount_z_opt(size) __allowed(on_parameter) +#define __deref_inout_opt __allowed(on_parameter) +#define __deref_inout_ecount_opt(size) __allowed(on_parameter) +#define __deref_inout_bcount_opt(size) __allowed(on_parameter) +#define __deref_inout_xcount_opt(size) __allowed(on_parameter) +#define __deref_inout_ecount_part_opt(size,len) __allowed(on_parameter) +#define __deref_inout_bcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_inout_xcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_inout_ecount_full_opt(size) __allowed(on_parameter) +#define __deref_inout_bcount_full_opt(size) __allowed(on_parameter) +#define __deref_inout_xcount_full_opt(size) __allowed(on_parameter) +#define __deref_inout_z_opt __allowed(on_parameter) +#define __deref_inout_ecount_z_opt(size) __allowed(on_parameter) +#define __deref_inout_bcount_z_opt(size) __allowed(on_parameter) +#define __deref_opt_ecount(size) __allowed(on_parameter) +#define __deref_opt_bcount(size) __allowed(on_parameter) +#define __deref_opt_xcount(size) __allowed(on_parameter) +#define __deref_opt_in __allowed(on_parameter) +#define __deref_opt_in_ecount(size) __allowed(on_parameter) +#define __deref_opt_in_bcount(size) __allowed(on_parameter) +#define __deref_opt_in_xcount(size) __allowed(on_parameter) +#define __deref_opt_out _SAL_VERSION_CHECK(__deref_opt_out) +#define __deref_opt_out_ecount(size) _SAL_VERSION_CHECK(__deref_opt_out_ecount) +#define __deref_opt_out_bcount(size) _SAL_VERSION_CHECK(__deref_opt_out_bcount) +#define __deref_opt_out_xcount(size) _SAL_VERSION_CHECK(__deref_opt_out_xcount) +#define __deref_opt_out_ecount_part(size,len) __allowed(on_parameter) +#define __deref_opt_out_bcount_part(size,len) __allowed(on_parameter) +#define __deref_opt_out_xcount_part(size,len) __allowed(on_parameter) +#define __deref_opt_out_ecount_full(size) __allowed(on_parameter) +#define __deref_opt_out_bcount_full(size) __allowed(on_parameter) +#define __deref_opt_out_xcount_full(size) __allowed(on_parameter) +#define __deref_opt_inout __allowed(on_parameter) +#define __deref_opt_inout_ecount(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount(size) __allowed(on_parameter) +#define __deref_opt_inout_xcount(size) __allowed(on_parameter) +#define __deref_opt_inout_ecount_part(size,len) __allowed(on_parameter) +#define __deref_opt_inout_bcount_part(size,len) __allowed(on_parameter) +#define __deref_opt_inout_xcount_part(size,len) __allowed(on_parameter) +#define __deref_opt_inout_ecount_full(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount_full(size) __allowed(on_parameter) +#define __deref_opt_inout_xcount_full(size) __allowed(on_parameter) +#define __deref_opt_inout_z __allowed(on_parameter) +#define __deref_opt_inout_ecount_z(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount_z(size) __allowed(on_parameter) +#define __deref_opt_ecount_opt(size) __allowed(on_parameter) +#define __deref_opt_bcount_opt(size) __allowed(on_parameter) +#define __deref_opt_xcount_opt(size) __allowed(on_parameter) +#define __deref_opt_in_opt __allowed(on_parameter) +#define __deref_opt_in_ecount_opt(size) __allowed(on_parameter) +#define __deref_opt_in_bcount_opt(size) __allowed(on_parameter) +#define __deref_opt_in_xcount_opt(size) __allowed(on_parameter) +#define __deref_opt_out_opt __allowed(on_parameter) +#define __deref_opt_out_ecount_opt(size) __allowed(on_parameter) +#define __deref_opt_out_bcount_opt(size) __allowed(on_parameter) +#define __deref_opt_out_xcount_opt(size) __allowed(on_parameter) +#define __deref_opt_out_ecount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_out_bcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_out_xcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_out_ecount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_out_bcount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_out_xcount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_out_z_opt __allowed(on_parameter) +#define __deref_opt_out_ecount_z_opt(size) __allowed(on_parameter) +#define __deref_opt_out_bcount_z_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_opt __allowed(on_parameter) +#define __deref_opt_inout_ecount_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_xcount_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_ecount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_inout_bcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_inout_xcount_part_opt(size,len) __allowed(on_parameter) +#define __deref_opt_inout_ecount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_xcount_full_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_z_opt __allowed(on_parameter) +#define __deref_opt_inout_ecount_z_opt(size) __allowed(on_parameter) +#define __deref_opt_inout_bcount_z_opt(size) __allowed(on_parameter) +#define __deref_in_ecount_iterator(size,incr) __allowed(on_parameter) +#define __deref_out_ecount_iterator(size,incr) __allowed(on_parameter) +#define __deref_inout_ecount_iterator(size,incr) __allowed(on_parameter) +#define __deref_realloc_bcount(insize,outsize) __allowed(on_parameter) + +/************************************************************************ +* SAL 2 _Ouptr_ family of annotations +************************************************************************/ + +#define _Outptr_ __allowed(on_parameter) +#define _Outptr_result_maybenull_ __allowed(on_parameter) +#define _Outptr_opt_ __allowed(on_parameter) +#define _Outptr_opt_result_maybenull_ __allowed(on_parameter) +#define _Outptr_result_z_ __allowed(on_parameter) +#define _Outptr_opt_result_z_ __allowed(on_parameter) +#define _Outptr_result_maybenull_z_ __allowed(on_parameter) +#define _Outptr_opt_result_maybenull_z_ __allowed(on_parameter) +#define _Outptr_result_nullonfailure_ __allowed(on_parameter) +#define _Outptr_opt_result_nullonfailure_ __allowed(on_parameter) +#define _COM_Outptr_ __allowed(on_parameter) +#define _COM_Outptr_result_maybenull_ __allowed(on_parameter) +#define _COM_Outptr_opt_ __allowed(on_parameter) +#define _COM_Outptr_opt_result_maybenull_ __allowed(on_parameter) +#define _Outptr_result_buffer_(size) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_(size) __allowed(on_parameter) +#define _Outptr_result_buffer_to_(size, count) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_to_(size, count) __allowed(on_parameter) +#define _Outptr_result_buffer_all_(size) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_all_(size) __allowed(on_parameter) +#define _Outptr_result_buffer_maybenull_(size) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_maybenull_(size) __allowed(on_parameter) +#define _Outptr_result_buffer_to_maybenull_(size, count) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_to_maybenull_(size, count) __allowed(on_parameter) +#define _Outptr_result_buffer_all_maybenull_(size) __allowed(on_parameter) +#define _Outptr_opt_result_buffer_all_maybenull_(size) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_(size) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_(size) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_to_(size, count) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_to_(size, count) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_all_(size) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_all_(size) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_maybenull_(size) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_maybenull_(size) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter) +#define _Outptr_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter) +#define _Outptr_opt_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter) + +/************************************************************************ +* Orcas SAL +************************************************************************/ +#define _Deref_out_ _SAL_VERSION_CHECK(_Deref_out_) +#define _Deref_out_opt_ _SAL_VERSION_CHECK(_Deref_out_opt_) +#define _Deref_opt_out_ _SAL_VERSION_CHECK(_Deref_opt_out_) +#define _Deref_opt_out_opt_ _SAL_VERSION_CHECK(_Deref_opt_out_opt_) +#define _In_count_(size) _SAL_VERSION_CHECK(_In_count_) +#define _In_opt_count_(size) _SAL_VERSION_CHECK(_In_opt_count_) +#define _In_bytecount_(size) _SAL_VERSION_CHECK(_In_bytecount_) +#define _In_opt_bytecount_(size) _SAL_VERSION_CHECK(_In_opt_bytecount_) +#define _Out_cap_(size) _SAL_VERSION_CHECK(_Out_cap_) +#define _Out_opt_cap_(size) _SAL_VERSION_CHECK(_Out_opt_cap_) +#define _Out_bytecap_(size) _SAL_VERSION_CHECK(_Out_bytecap_) +#define _Out_opt_bytecap_(size) _SAL_VERSION_CHECK(_Out_opt_bytecap_) +#define _Deref_post_count_(size) _SAL_VERSION_CHECK(_Deref_post_count_) +#define _Deref_post_opt_count_(size) _SAL_VERSION_CHECK(_Deref_post_opt_count_) +#define _Deref_post_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_bytecount_) +#define _Deref_post_opt_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecount_) +#define _Deref_post_cap_(size) _SAL_VERSION_CHECK(_Deref_post_cap_) +#define _Deref_post_opt_cap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_cap_) +#define _Deref_post_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_bytecap_) +#define _Deref_post_opt_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecap_) + +/************************************************************************ +* 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. +* +* _At_(expr, annotes) : annotation list annotes applies to target 'expr' +* +* _When_(expr, annotes) : annotation list annotes applies when 'expr' is true +* +* __success(expr) T 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. +* +* __out_awcount(expr, size) T *p : Pointer p is a buffer whose size may be +* given in either bytes or elements. If <expr> is true, this acts like +* __out_bcount. If <expr> is false, this acts like __out_ecount. This +* should only be used to annotate old APIs. +* +* __in_awcount(expr, size) T* p : Pointer p is a buffer whose size may be given +* in either bytes or elements. If <expr> is true, this acts like +* __in_bcount. If <expr> is false, this acts like __in_ecount. This should +* only be used to annotate old APIs. +* +* __nullterminated T* p : Pointer p is a buffer that may be read or written +* up to and including the first '\0' character or pointer. May be used on +* typedefs, which marks valid (properly initialized) instances of that type +* as being null-terminated. +* +* __nullnullterminated T* p : Pointer p is a buffer that may be read or +* written up to and including the first sequence of two '\0' characters or +* pointers. May be used on typedefs, which marks valid instances of that +* type as being double-null terminated. +* +* __reserved T v : Value v must be 0/NULL, reserved for future use. +* +* __checkReturn T f(); : Return value of f must not be ignored by callers +* of this function. +* +* __typefix(ctype) T v : Value v should be treated as an instance of ctype, +* rather than its declared type when considering validity. +* +* __override T f(); : Specify C#-style 'override' behaviour for overriding +* virtual methods. +* +* __callback T f(); : Function f can be used as a function pointer. +* +* __format_string T 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. +* +* __range(low_bnd, up_bnd) int f(): The return from the function "f" must +* be in the inclusive numeric range [low_bnd, up_bnd]. +* +* __in_range(low_bnd, up_bnd) int i : Precondition that integer i must be +* in the inclusive numeric range [low_bnd, up_bnd]. +* +* __out_range(low_bnd, up_bnd) int i : Postcondition that integer i must be +* in the inclusive numeric range [low_bnd, up_bnd]. +* +* __deref_in_range(low_bnd, up_bnd) int* pi : Precondition that integer *pi +* must be in the inclusive numeric range [low_bnd, up_bnd]. +* +* __deref_out_range(low_bnd, up_bnd) int* pi : Postcondition that integer +* *pi must be in the inclusive numeric range [low_bnd, up_bnd]. +* +* __deref_inout_range(low_bnd, up_bnd) int* pi : Invariant that the integer +* *pi must be in the inclusive numeric range [low_bnd, up_bnd]. +* +* The first argument of a range macro may also be a C relational operator +* (<,>,!=, ==, <=, >=). +* +* __range(rel_op, j) int f(): Postcondition that "f() rel_op j" must be +* true. Note that j may be a expression known only at runtime. +* +* __in_range(rel_op, j) int i : Precondition that "i rel_op j" must be +* true. Note that j may be a expression known only at runtime. +* +* __out_range(rel_op, j) int i : Postcondition that integer "i rel_op j" +* must be true. Note that j may be a expression known only at runtime. +* +* __deref_in_range(rel_op, j) int *pi : Precondition that "*pi rel_op j" +* must be true. Note that j may be a expression known only at runtime. +* +* __deref_out_range(rel_op, j) int *pi : Postcondition that "*pi rel_op j" +* must be true. Note that j may be a expression known only at runtime. +* +* __deref_inout_range(rel_op, j) int *pi : Invariant that "*pi rel_op j" +* must be true. Note that j may be a expression known only at runtime. +* +* __range_max(a, b) int f(): Postcondition f acts as 'max', returns larger +* of a and b. Note that a and b may be expressions known only at runtime. +* +* __range_min(a, b) int f(): Postcondition f acts as 'min', returns smaller +* of a and b. Note that a and b may be expressions known only at runtime. +* +* __in_bound int i : Precondition that integer i must be bound, but the +* exact range can't be specified at compile time. __in_range should be +* used if the range can be explicitly stated. +* +* __out_bound int i : Postcondition that integer i must be bound, but the +* exact range can't be specified at compile time. __out_range should be +* used if the range can be explicitly stated. +* +* __deref_out_bound int pi : Postcondition that integer *pi must be bound, +* but the exact range can't be specified at compile time. +* __deref_out_range should be used if the range can be explicitly stated. +* +* __assume_bound(expr); : Assume that the expression is bound to some known +* range. This can be used to suppress integer overflow warnings on integral +* expressions that are known to be bound due to reasons not explicit in the +* code. Use as a statement in the body of a function. +* +* __analysis_assume_nulltermianted(expr); : Assume that the expression is +* a null terminated buffer. Use this to suppress tool noise specific to +* nulltermination warnings, and capture deeper invariants tools can not +* discover. +* +* __allocator void f(): Function allocates memory using an integral size +* argument +* +* void myfree(__deallocate(Mem) void *p) : Memory is freed, no longer usable +* upon return, and p may not be null. +* +* void myfree(__deallocate_opt(Mem) void *p) : Memory is freed, no longer +* usable upon return, and p may be null. +* +* void free(__post_invalid void* x): Mark memory as untouchable when +* function returns. +* +* ---------------------------------------------------------------------------- +* Advanced Annotation Examples +* +* __success(return == TRUE) LWSTDAPI_(BOOL) +* PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath); +* // pszBuf is only guaranteed to be null-terminated when TRUE is returned. +* +* // Initialized LPWSTRs are null-terminated strings. +* typedef __nullterminated WCHAR* LPWSTR; +* +* __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. +* +************************************************************************/ +#define _At_(expr, annotes) __allowed(on_parameter_or_return) +#define _When_(expr, annotes) __allowed(on_parameter_or_return) +#define __success(expr) _SAL_VERSION_CHECK(__success) +#define __out_awcount(expr,size) __allowed(on_parameter) +#define __in_awcount(expr,size) __allowed(on_parameter) +#define __nullterminated _SAL_VERSION_CHECK(__nullterminated) +#define __nullnullterminated _SAL_VERSION_CHECK(__nullnullterminated) +#define __reserved _SAL_VERSION_CHECK(__reserved) +#define __checkReturn _SAL_VERSION_CHECK(__checkReturn) +#define __typefix(ctype) __allowed(on_parameter_or_return) +#define __override __allowed(on_function) +#define __callback __allowed(on_function) +#define __format_string __allowed(on_parameter_or_return) +#define __blocksOn(resource) __allowed(on_function) +#define __fallthrough __allowed(as_statement) +#define __range(lb,ub) __allowed(on_return) +#define __in_range(lb,ub) _SAL_VERSION_CHECK(__in_range) +#define __out_range(lb,ub) _SAL_VERSION_CHECK(__out_range) +#define __deref_in_range(lb,ub) __allowed(on_parameter) +#define __deref_out_range(lb,ub) _SAL_VERSION_CHECK(__deref_out_range) +#define __deref_inout_range(lb,ub) __allowed(on_parameter) +#define __field_range(lb,ub) _SAL_VERSION_CHECK(__field_range) +#define __range_max(a,b) __allowed(on_return) +#define __range_min(a,b) __allowed(on_return) +#define __bound __allowed(on_return) +#define __in_bound __allowed(on_parameter) +#define __out_bound __allowed(on_parameter) +#define __deref_out_bound __allowed(on_parameter) +#define __assume_bound(i) __allowed(as_statement_with_arg(i)) +#define __analysis_assume_nullterminated(x) \ + __allowed(as_statement_with_arg(x)) +#define __allocator __allowed(on_function) +#define __deallocate(kind) __allowed(on_parameter) +#define __deallocate_opt(kind) __allowed(on_parameter) +#define __post_invalid __allowed(on_parameter_or_return) +#define __post_nullnullterminated \ + __allowed(on_parameter_or_return) +/*************************************************************************** +* Expert Macros +***************************************************************************/ +#define __null __allowed(on_typedecl) +#define __notnull __allowed(on_typedecl) +#define __maybenull __allowed(on_typedecl) +#define __exceptthat __allowed(on_typedecl) +/*************************************************************************** +* Macros to classify fields of structures. +* Structure Annotations +* +* The buffer annotations are a convenient way of describing +* relationships between buffers and their size on a function by +* function basis. Very often struct or class data members have similar +* invariants, which can be expressed directly on the type. +* +* Similar to our buffer annotations we can summarize all the various +* structure annotations by one choosing an element from each column of +* this table to build a composite annotation. +* +* +--------------------------------------------------+ +* | Selector | Units | Size/Init | Optional | +* |----------+---------+------------------+----------| +* | __field | _ecount | (size) | empty | +* |----------+---------+------------------+----------| +* | __struct | _bcount | _full(size) | _opt | +* |----------+---------+------------------+----------| +* | | _xcount | _part(size,init) | | +* +--------------------------------------------------+ +* +* Note that empty represents the empty string. Sometime arguments need +* to be "floated" to the left to give us a valid annotation name. For +* example the naive combination __field_ecount(size)_opt is actually +* written as __field_ecount_opt(size). Not all possible combinations +* are currently supported or sensible. See specstrings_strict.h for +* the currently supported set. Those that are supported are documented +* below. +* +*Summary of Elements +* +* Selector +* +* __field +* The annotation should only be placed in front +* of data members of structures and classes. The +* data members are pointers to a block of data. +* The annotations describe properties about the +* size of the block of data. This can be used for +* +* __struct +* The annotation should only be placed at the +* beginning of the definition of a structure or +* class. These annotations are used when a struct +* or class is used as a "header" that is +* allocated inline with a block of data and there +* is no apparent field that represents the tail +* end of the structure. +* +* Units +* +* _ecount +* All size and initialization values are in terms +* of elements of the appropriate type +* +* _bcount +* All size and initialization values are in terms +* of raw byte sizes. +* +* _xcount +* The size or initialization values cannot be +* properly expressed as a simple byte or element +* count, and instead a place holder is used to +* document the relationship. +* +* Size/Init +* All the size/init expressions can contain references to +* other fields in the struct or class. +* +* (size) +* The size of the buffer is determined by the +* expression size. Unless, the type of the buffer +* provides more information nothing is know about +* how much of this data is initialized. For +* example, if the data member happens to be a +* string type such as LPSTR. It is assumed that +* the data is initialized to the first '\0'. +* +* _full(size) +* The size of the buffer is determined by the +* expression size and all the data in the buffer +* is guaranteed to be initialized. +* +* _part(size,init) +* The size of the buffer is determined by the +* expression size and all the data in the buffer +* is guaranteed to be initialized up to init +* elements or bytes. +* +* Optional +* +* empty +* The pointer to the block of memory is never +* NULL +* +* _opt +* The pointer to the block of memory is may be +* NULL +* +* +* // Basic Usage of Struct Annotations +* #include <stdio.h> +* #include <stdlib.h> +* struct buf_s { +* int sz; +* __field_bcount_full(sz) +* char *buf; +* }; +* void InitBuf(__out struct *buf_s b,int sz) { +* b->buf = calloc(sz,sizeof(char)); +* b->sz = sz; +* } +* void WriteBuf(__in FILE *fp,__in struct *buf_s b) { +* fwrite(b->buf,b->sz,sizeof(char),fp); +* } +* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) { +* fread(b->buf,b->sz,sizeof(char),fp); +* } +* +* +* +* // Inline Allocated Buffer +* struct buf_s { +* int sz; +* __field_bcount(sz) +* char buf[1]; +* }; +* void WriteBuf(__in FILE *fp,__in struct *buf_s b) { +* fwrite(&(b->buf),b->sz,sizeof(char),fp); +* } +* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) { +* fread(&(b->buf),b->sz,sizeof(char),fp); +* } +* +* +* +* // Embedded Header Structure +* __struct_bcount(sz) +* struct buf_s { +* int sz; +* }; +* void WriteBuf(__in FILE *fp,__in struct *buf_s b) { +* fwrite(&b,b->sz,sizeof(char),fp); +* } +* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) { +* fread(&b,b->sz,sizeof(char),fp); +* } +* +* +****************************************************************************/ +#define __field_ecount(size) _SAL_VERSION_CHECK(__field_ecount) +#define __field_bcount(size) _SAL_VERSION_CHECK(__field_bcount) +#define __field_xcount(size) __allowed(on_field) +#define __field_ecount_opt(size) __allowed(on_field) +#define __field_bcount_opt(size) __allowed(on_field) +#define __field_xcount_opt(size) __allowed(on_field) +#define __field_ecount_part(size,init) __allowed(on_field) +#define __field_bcount_part(size,init) __allowed(on_field) +#define __field_xcount_part(size,init) __allowed(on_field) +#define __field_ecount_part_opt(size,init) __allowed(on_field) +#define __field_bcount_part_opt(size,init) __allowed(on_field) +#define __field_xcount_part_opt(size,init) __allowed(on_field) +#define __field_ecount_full(size) __allowed(on_field) +#define __field_bcount_full(size) __allowed(on_field) +#define __field_xcount_full(size) __allowed(on_field) +#define __field_ecount_full_opt(size) __allowed(on_field) +#define __field_bcount_full_opt(size) __allowed(on_field) +#define __field_xcount_full_opt(size) __allowed(on_field) +#define __field_nullterminated __allowed(on_field) +#define __struct_bcount(size) __allowed(on_struct) +#define __struct_xcount(size) __allowed(on_struct) + +/*************************************************************************** +* Macros to classify the entrypoints and indicate their category. +* +* Pre-defined control point categories include: RPC, KERNEL, GDI. +* +* Pre-defined control point macros include: +* __rpc_entry, __kernel_entry, __gdi_entry. +***************************************************************************/ +#define __control_entrypoint(category) __allowed(on_function) +#define __rpc_entry __allowed(on_function) +#define __kernel_entry __allowed(on_function) +#define __gdi_entry __allowed(on_function) + +/*************************************************************************** +* Macros to track untrusted data and their validation. The list of untrusted +* sources include: +* +* FILE - File reading stream or API +* NETWORK - Socket readers +* INTERNET - WinInet and WinHttp readers +* USER_REGISTRY - HKCU portions of the registry +* USER_MODE - Parameters to kernel entry points +* RPC - Parameters to RPC entry points +* DRIVER - Device driver +***************************************************************************/ +#define __in_data_source(src_sym) __allowed(on_parameter) +#define __out_data_source(src_sym) __allowed(on_parameter) +#define __field_data_source(src_sym) __allowed(on_field) +#define __this_out_data_source(src_syn) __allowed(on_function) + +/************************************************************************** +* Macros to tag file parsing code. Predefined formats include: +* PNG - Portable Network Graphics +* JPEG - Joint Photographic Experts Group +* BMP - Bitmap +* RC_BMP - Resource bitmap +* WMF - Windows Metafile +* EMF - Windows Enhanced Metafile +* GIF - Graphics Interchange Format +* MIME_TYPE - MIME type from header tokens +* MAIL_MONIKER - MAIL information refered by URL moniker +* HTML - HyperText Markup Language +* WMPHOTO - Windows media photo +* OE_VCARD - Outlook Express virtual card +* OE_CONTACT - Outlook Express contact +* MIDI - Musical Instrument Digital Interface +* LDIF - LDAP Data Interchange Format +* AVI - Audio Visual Interchange +* ACM - Audio Compression Manager +**************************************************************************/ +#define __out_validated(filetype_sym) __allowed(on_parameter) +#define __this_out_validated(filetype_sym) __allowed(on_function) +#define __file_parser(filetype_sym) __allowed(on_function) +#define __file_parser_class(filetype_sym) __allowed(on_struct) +#define __file_parser_library(filetype_sym) __allowed(as_global_decl) + +/*************************************************************************** +* Macros to track the code content in the file. The type of code +* contents currently tracked: +* +* NDIS_DRIVER - NDIS Device driver +***************************************************************************/ +#define __source_code_content(codetype_sym) __allowed(as_global_decl) + +/*************************************************************************** +* Macros to track the code content in the class. The type of code +* contents currently tracked: +* +* DCOM - Class implementing DCOM +***************************************************************************/ +#define __class_code_content(codetype_sym) __allowed(on_struct) + +/************************************************************************* +* Macros to tag encoded function pointers +**************************************************************************/ +#define __encoded_pointer +#define __encoded_array +#define __field_encoded_pointer __allowed(on_field) +#define __field_encoded_array __allowed(on_field) + +#define __transfer(formal) __allowed(on_parameter_or_return) +#define __assume_validated(exp) __allowed(as_statement_with_arg(exp)) + +/************************************************************************* +* __analysis_assume(expr) : Expert macro use only when directed. Use this to +* tell static analysis tools like PREfix and PREfast about a non-coded +* assumption that you wish the tools to assume. The assumption will be +* understood by those tools. By default there is no dynamic checking or +* static checking of the assumption in any build. +* +* To obtain dynamic checking wrap this macro in your local version of a debug +* assert. +* Please do not put function calls in the expression because this is not +* supported by all tools: +* __analysis_assume(GetObject () != NULL); // DO NOT DO THIS +* +*************************************************************************/ +#define __analysis_assume(expr) __allowed(as_statement_with_arg(expr)) +#define __analysis_assert(expr) __allowed(as_statement_with_arg(expr)) + +/************************************************************************* +* __analysis_hint(hint_sym) : Expert macro use only when +* directed. Use this to influence certain analysis heuristics +* used by the tools. These hints do not describe the semantics +* of functions but simply direct the tools to act in a certain +* way. +* +* Current hints that are supported are: +* +* INLINE - inline this function during analysis overrides any +* default heuristics +* NOINLINE - do not inline this function during analysis overrides +* and default heuristics +*************************************************************************/ +#define __analysis_hint(hint) __allowed(on_function) + +/************************************************************************* +* Macros to encode abstract properties of values. Used by SALadt.h +*************************************************************************/ +#define __type_has_adt_prop(adt,prop) __allowed(on_typdecl) +#define __out_has_adt_prop(adt,prop) __allowed(on_parameter) +#define __out_not_has_adt_prop(adt,prop) __allowed(on_parameter) +#define __out_transfer_adt_prop(arg) __allowed(on_parameter) +#define __out_has_type_adt_props(typ) __allowed(on_parameter) + +/************************************************************************* +* Macros used by Prefast for Drivers +* +* __possibly_notnullterminated : +* +* Used for return values of parameters or functions that do not +* guarantee nulltermination in all cases. +* +*************************************************************************/ +#define __possibly_notnullterminated __allowed(on_parameter_or_return) + +/************************************************************************* +* Advanced macros +* +* __volatile +* The __volatile annotation identifies a global variable or +* structure field that: +* 1) is not declared volatile; +* 2) is accessed concurrently by multiple threads. +* +* The __deref_volatile annotation identifies a global variable +* or structure field that stores a pointer to some data that: +* 1) is not declared volatile; +* 2) is accessed concurrently by multiple threads. +* +* Prefast uses these annotations to find patterns of code that +* may result in unexpected re-fetching of the global variable +* into a local variable. +* +* We also provide two complimentary annotations __nonvolatile +* and __deref_nonvolatile that could be used to suppress Prefast +* +* re-fetching warnings on variables that are known either: +* 1) not to be in danger of being re-fetched or, +* 2) not to lead to incorrect results if they are re-fetched +* +*************************************************************************/ +#define __volatile __allowed(on_global_or_field) +#define __deref_volatile __allowed(on_global_or_field) +#define __nonvolatile __allowed(on_global_or_field) +#define __deref_nonvolatile __allowed(on_global_or_field) + +/************************************************************************* +* Macros deprecated with strict level greater then 1. +**************************************************************************/ +#if (__SPECSTRINGS_STRICT_LEVEL > 1) +/* Must come before macro defintions */ +#pragma deprecated(__in_nz) +#pragma deprecated(__in_ecount_nz) +#pragma deprecated(__in_bcount_nz) +#pragma deprecated(__out_nz) +#pragma deprecated(__out_nz_opt) +#pragma deprecated(__out_ecount_nz) +#pragma deprecated(__out_bcount_nz) +#pragma deprecated(__inout_nz) +#pragma deprecated(__inout_ecount_nz) +#pragma deprecated(__inout_bcount_nz) +#pragma deprecated(__in_nz_opt) +#pragma deprecated(__in_ecount_nz_opt) +#pragma deprecated(__in_bcount_nz_opt) +#pragma deprecated(__out_ecount_nz_opt) +#pragma deprecated(__out_bcount_nz_opt) +#pragma deprecated(__inout_nz_opt) +#pragma deprecated(__inout_ecount_nz_opt) +#pragma deprecated(__inout_bcount_nz_opt) +#pragma deprecated(__deref_out_nz) +#pragma deprecated(__deref_out_ecount_nz) +#pragma deprecated(__deref_out_bcount_nz) +#pragma deprecated(__deref_inout_nz) +#pragma deprecated(__deref_inout_ecount_nz) +#pragma deprecated(__deref_inout_bcount_nz) +#pragma deprecated(__deref_out_nz_opt) +#pragma deprecated(__deref_out_ecount_nz_opt) +#pragma deprecated(__deref_out_bcount_nz_opt) +#pragma deprecated(__deref_inout_nz_opt) +#pragma deprecated(__deref_inout_ecount_nz_opt) +#pragma deprecated(__deref_inout_bcount_nz_opt) +#pragma deprecated(__deref_opt_inout_nz) +#pragma deprecated(__deref_opt_inout_ecount_nz) +#pragma deprecated(__deref_opt_inout_bcount_nz) +#pragma deprecated(__deref_opt_out_nz_opt) +#pragma deprecated(__deref_opt_out_ecount_nz_opt) +#pragma deprecated(__deref_opt_out_bcount_nz_opt) +#pragma deprecated(__deref_opt_inout_nz_opt) +#pragma deprecated(__deref_opt_inout_ecount_nz_opt) +#pragma deprecated(__deref_opt_inout_bcount_nz_opt) +#pragma deprecated(__deref) +#pragma deprecated(__pre) +#pragma deprecated(__post) +#pragma deprecated(__readableTo) +#pragma deprecated(__writableTo) +#pragma deprecated(__maybevalid) +#pragma deprecated(__data_entrypoint) +#pragma deprecated(__inexpressible_readableTo) +#pragma deprecated(__readonly) +#pragma deprecated(__byte_writableTo) +#pragma deprecated(__byte_readableTo) +#pragma deprecated(__elem_readableTo) +#pragma deprecated(__elem_writableTo) +#pragma deprecated(__valid) +#pragma deprecated(__notvalid) +#pragma deprecated(__refparam) +#pragma deprecated(__precond) +#endif +/* Define soon to be deprecated macros to nops. */ +#define __in_nz +#define __in_ecount_nz(size) +#define __in_bcount_nz(size) +#define __out_nz +#define __out_nz_opt +#define __out_ecount_nz(size) +#define __out_bcount_nz(size) +#define __inout_nz +#define __inout_ecount_nz(size) +#define __inout_bcount_nz(size) +#define __in_nz_opt +#define __in_ecount_nz_opt(size) +#define __in_bcount_nz_opt(size) +#define __out_ecount_nz_opt(size) +#define __out_bcount_nz_opt(size) +#define __inout_nz_opt +#define __inout_ecount_nz_opt(size) +#define __inout_bcount_nz_opt(size) +#define __deref_out_nz +#define __deref_out_ecount_nz(size) +#define __deref_out_bcount_nz(size) +#define __deref_inout_nz +#define __deref_inout_ecount_nz(size) +#define __deref_inout_bcount_nz(size) +#define __deref_out_nz_opt +#define __deref_out_ecount_nz_opt(size) +#define __deref_out_bcount_nz_opt(size) +#define __deref_inout_nz_opt +#define __deref_inout_ecount_nz_opt(size) +#define __deref_inout_bcount_nz_opt(size) +#define __deref_opt_inout_nz +#define __deref_opt_inout_ecount_nz(size) +#define __deref_opt_inout_bcount_nz(size) +#define __deref_opt_out_nz_opt +#define __deref_opt_out_ecount_nz_opt(size) +#define __deref_opt_out_bcount_nz_opt(size) +#define __deref_opt_inout_nz_opt +#define __deref_opt_inout_ecount_nz_opt(size) +#define __deref_opt_inout_bcount_nz_opt(size) +#define __deref +#define __pre +#define __post +#define __readableTo(count) +#define __writableTo(count) +#define __maybevalid +#define __inexpressible_readableTo(string) +#define __data_entrypoint(category) +#define __readonly +#define __byte_writableTo(count) +#define __byte_readableTo(count) +#define __elem_readableTo(count) +#define __elem_writableTo(count) +#define __valid +#define __notvalid +#define __refparam +#define __precond(condition) + +/************************************************************************* +* Definitions to force a compile error when macros are used improperly. +* Relies on VS 2005 source annotations. +*************************************************************************/ +#if !defined(_MSC_EXTENSIONS) && !defined(_PREFAST_) && !defined(OACR) +#define __allowed(p) /* nothing */ +#else +#define __allowed(p) __$allowed_##p +#define __$allowed_as_global_decl /* empty */ +#define __$allowed_as_statement_with_arg(x) \ + __pragma(warning(push)) __pragma(warning(disable : 4548)) \ + do {__noop(x);} while((0,0) __pragma(warning(pop)) ) +#define __$allowed_as_statement __$allowed_as_statement_with_arg(1) + +/************************************************************************** +* This should go away. It's only for __success which we should split into. +* __success and __typdecl_sucess +***************************************************************************/ +#define __$allowed_on_function_or_typedecl /* empty */ +#if (__SPECSTRINGS_STRICT_LEVEL == 1) || (__SPECSTRINGS_STRICT_LEVEL == 2) +#define __$allowed_on_typedecl /* empty */ +#define __$allowed_on_return /* empty */ +#define __$allowed_on_parameter /* empty */ +#define __$allowed_on_function /* empty */ +#define __$allowed_on_struct /* empty */ +#define __$allowed_on_field /* empty */ +#define __$allowed_on_parameter_or_return /* empty */ +#define __$allowed_on_global_or_field /* empty */ +#elif __SPECSTRINGS_STRICT_LEVEL == 3 +#define __$allowed_on_typedecl /* empty */ +/* Define dummy source attributes. Still needs more testing */ +#define __$allowed_on_return [returnvalue: OnReturnOnly] +#define __$allowed_on_parameter [OnParameterOnly] +#define __$allowed_on_function [method: OnFunctionOnly] +#define __$allowed_on_struct [OnStructOnly] +#define __$allowed_on_field [OnFieldOnly] +#define __$allowed_on_parameter_or_return [OnParameterOrReturnOnly] +#define __$allowed_on_global_or_field /* empty */ +#pragma push_macro( "DECL_SA" ) +#pragma push_macro( "SA" ) +#ifdef __cplusplus +#define SA(x) x +#define DECL_SA(name,loc) \ + [repeatable] \ + [source_annotation_attribute( loc )] \ + struct name##Attribute { name##Attribute(); const char* ignored; }; +#else +#define SA(x) SA_##x +#define DECL_SA(name,loc) \ + [source_annotation_attribute( loc )] \ + struct name { const char* ignored; };\ + typedef struct name name; +#endif /* #endif __cplusplus */ +DECL_SA(OnParameterOnly,SA(Parameter)); +DECL_SA(OnReturnOnly,SA(ReturnValue)); +DECL_SA(OnFunctionOnly,SA(Method)); +DECL_SA(OnStructOnly,SA(Struct)); +DECL_SA(OnFieldOnly,SA(Field)); +DECL_SA(OnParameterOrReturnOnly,SA(Parameter) | SA(ReturnValue)); +#pragma pop_macro( "SA" ) +#pragma pop_macro( "DECL_SA" ) +#endif +#endif +#endif |