summaryrefslogtreecommitdiff
path: root/src/pal/inc/rt/specstrings_strict.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/pal/inc/rt/specstrings_strict.h')
-rw-r--r--src/pal/inc/rt/specstrings_strict.h1190
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