huwcampbell.com
Reactos
1/*
2 * PROJECT: ReactOS PSDK
3 * LICENSE: MIT (https://spdx.org/licenses/MIT)
4 * PURPOSE: Documents all the macros approved for use in windows source
5 * COPYRIGHT: Microsoft Corporation.
6 * SOURCE: https://github.com/microsoft/ChakraCore/blob/master/pal/inc/rt/specstrings_strict.h
7 */
8//
9// Copyright (c) Microsoft. All rights reserved.
10// Licensed under the MIT license. See LICENSE file in the project root for full license information.
11//
12
13/*************************************************************************
14* This file documents all the macros approved for use in windows source
15* code. It includes some experimental macros which should only be used by
16* experts.
17*
18* DO NOT include this file directly. This file is include after
19* specstrings.h. So we can undefine every possible old definition including
20* private internal macros people should not be using, as well as macros from
21* sal.h. Macros are redefined here in a way to cause syntax errors when used
22* incorrectly during a normal build when specstrings.h is included and
23* __SPECSTRINGS_STRICT_LEVEL is defined.
24*
25* There are several levels of strictness, each level includes the behavior of
26* all previous levels.
27*
28* 0 - Disable strict checking
29* 1 - Break on unapproved macros and misuse of statement
30* macros such as __fallthrough (default)
31* 2 - Deprecated some old macros that should not be used
32* 3 - Use VS 2005 Source Annotation to make sure every macro
33* is used in the right context. For example placing __in on a return
34* parameter will result in an error.
35*
36
37*
38************************************************************************/
39#ifndef __SPECSTRINGS_STRICT_LEVEL
40#define __SPECSTRINGS_STRICT_LEVEL 1
41#endif
42/************************************************************************
43* Introduction
44*
45* specstrings.h provides a set of annotations to describe how a function uses
46* its parameters - the assumptions it makes about them, and the guarantees it
47* makes upon finishing.
48*
49* Annotations must be placed before a function parameter's type or its return
50* type. There are two basic classes of common annotations buffer annotations
51* and advanced annotations. Buffer annotations describe how functions use
52* their pointer parameters, and advanced annotations either describe
53* complex/unusual buffer behavior, or provide additional information about a
54* parameter that is not otherwise expressible.
55*
56* Buffer Annotations
57*
58* The most important annotations in SpecStrings.h provide a consistent way to
59* annotate buffer parameters or return values for a function. Each of these
60* annotations describes a single buffer (which could be a string, a
61* fixed-length or variable-length array, or just a pointer) that the function
62* interacts with: where it is, how large it is, how much is initialized, and
63* what the function does with it.
64*
65* The appropriate macro for a given buffer can be constructed using the table
66* below. Just pick the appropriate values from each category, and combine
67* them together with a leading underscore. Some combinations of values do not
68* make sense as buffer annotations. Only meaningful annotations can be added
69* to your code; for a list of these, see the buffer annotation definitions
70* section.
71*
72* Only a single buffer annotation should be used for each parameter.
73*
74* |------------|------------|---------|--------|----------|---------------|
75* | Level | Usage | Size | Output | Optional | Parameters |
76* |------------|------------|---------|--------|----------|---------------|
77* | <> | <> | <> | <> | <> | <> |
78* | _deref | _in | _ecount | _full | _opt | (size) |
79* | _deref_opt | _out | _bcount | _part | | (size,length) |
80* | | _inout | | | | |
81* | | | | | | |
82* |------------|------------|---------|--------|----------|---------------|
83*
84* Note: "<>" represents the empty string.
85*
86* Level: Describes the buffer pointer's level of indirection from the
87* parameter or return value 'p'.
88*
89* <> : p is the buffer pointer.
90* _deref : *p is the buffer pointer. p must not be NULL.
91* _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the
92* rest of the annotation is ignored.
93*
94* Usage: Describes how the function uses the buffer.
95*
96* <> : The buffer is not accessed. If used on the return value or with
97* _deref, the function will provide the buffer, and it will be uninitialized
98* at exit. Otherwise, the caller must provide the buffer. This should only
99* be used for alloc and free functions.
100*
101* _in : The function will only read from the buffer. The caller must provide
102* the buffer and initialize it.
103*
104* _out : The function will only write to the buffer. If used on the return
105* value or with _deref, the function will provide the buffer and initialize
106* it. Otherwise, the caller must provide the buffer, and the function will
107* initialize it.
108*
109* _inout : The function may freely read from and write to the buffer. The
110* caller must provide the buffer and initialize it. If used with _deref, the
111* buffer may be reallocated by the function.
112*
113* Size: Describes the total size of the buffer. This may be less than the
114* space actually allocated for the buffer, in which case it describes the
115* accessible amount.
116*
117* <> : No buffer size is given. If the type specifies the buffer size (such
118* as with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is
119* one element long. Must be used with _in, _out, or _inout.
120*
121* _ecount : The buffer size is an explicit element count.
122*
123* _bcount : The buffer size is an explicit byte count.
124*
125* Output: Describes how much of the buffer will be initialized by the
126* function. For _inout buffers, this also describes how much is initialized
127* at entry. Omit this category for _in buffers; they must be fully
128* initialized by the caller.
129*
130* <> : The type specifies how much is initialized. For instance, a function
131* initializing an LPWSTR must NULL-terminate the string.
132*
133* _full : The function initializes the entire buffer.
134*
135* _part : The function initializes part of the buffer, and explicitly
136* indicates how much.
137*
138* Optional: Describes if the buffer itself is optional.
139*
140* <> : The pointer to the buffer must not be NULL.
141*
142* _opt : The pointer to the buffer might be NULL. It will be checked before
143* being dereferenced.
144*
145* Parameters: Gives explicit counts for the size and length of the buffer.
146*
147* <> : There is no explicit count. Use when neither _ecount nor _bcount is
148* used.
149*
150* (size) : Only the buffer's total size is given. Use with _ecount or _bcount
151* but not _part.
152*
153* (size,length) : The buffer's total size and initialized length are
154* given. Use with _ecount_part and _bcount_part.
155*
156* ----------------------------------------------------------------------------
157* Buffer Annotation Examples
158*
159* LWSTDAPI_(BOOL) StrToIntExA(
160* LPCSTR pszString, // No annotation required, const implies __in.
161* DWORD dwFlags,
162* __out int *piRet // A pointer whose dereference will be filled in.
163* );
164*
165* void MyPaintingFunction(
166* __in HWND hwndControl, // An initialized read-only parameter.
167* __in_opt HDC hdcOptional, // An initialized read-only parameter that
168* // might be NULL.
169* __inout IPropertyStore *ppsStore // An initialized parameter that
170* // may be freely used and modified.
171* );
172*
173* LWSTDAPI_(BOOL) PathCompactPathExA(
174* __out_ecount(cchMax) LPSTR pszOut, // A string buffer with cch elements
175* // that will be '\0' terminated
176* // on exit.
177* LPCSTR pszSrc, // No annotation required,
178* // const implies __in.
179* UINT cchMax,
180* DWORD dwFlags
181* );
182*
183* HRESULT SHLocalAllocBytes(
184* size_t cb,
185* __deref_bcount(cb) T **ppv // A pointer whose dereference will be set
186* // to an uninitialized buffer with cb bytes.
187* );
188*
189* __inout_bcount_full(cb) : A buffer with cb elements that is fully
190* initialized at entry and exit, and may be written to by this function.
191*
192* __out_ecount_part(count, *countOut) : A buffer with count elements that
193* will be partially initialized by this function. The function indicates how
194* much it initialized by setting *countOut.
195*
196************************************************************************/
197
198#if (_MSC_VER >= 1400) && !defined(__midl) && !defined(_PREFAST_) && (__SPECSTRINGS_STRICT_LEVEL > 0)
199#pragma once
200#include <specstrings_undef.h>
201#define __ecount(size) _SAL_VERSION_CHECK(__ecount)
202#define __bcount(size) _SAL_VERSION_CHECK(__bcount)
203#define __xcount(size) _SAL_VERSION_CHECK(__xcount)
204#define __in _SAL_VERSION_CHECK(__in)
205#define __in_ecount(size) _SAL_VERSION_CHECK(__in_ecount)
206#define __in_bcount(size) _SAL_VERSION_CHECK(__in_bcount)
207#define __in_xcount(size) _SAL_VERSION_CHECK(__in_xcount)
208#define __in_z _SAL_VERSION_CHECK(__in_z)
209#define __in_ecount_z(size) _SAL_VERSION_CHECK(__in_ecount_z)
210#define __in_bcount_z(size) _SAL_VERSION_CHECK(__in_bcount_z)
211#define __out _SAL_VERSION_CHECK(__out)
212#define __out_ecount(size) _SAL_VERSION_CHECK(__out_ecount)
213#define __out_bcount(size) _SAL_VERSION_CHECK(__out_bcount)
214#define __out_xcount(size) _SAL_VERSION_CHECK(__out_xcount)
215#define __out_ecount_part(size,len) _SAL_VERSION_CHECK(__out_ecount_part)
216#define __out_bcount_part(size,len) _SAL_VERSION_CHECK(__out_bcount_part)
217#define __out_xcount_part(size,len) _SAL_VERSION_CHECK(__out_xcount_part)
218#define __out_ecount_full(size) _SAL_VERSION_CHECK(__out_ecount_full)
219#define __out_bcount_full(size) _SAL_VERSION_CHECK(__out_bcount_full)
220#define __out_xcount_full(size) _SAL_VERSION_CHECK(__out_xcount_full)
221#define __out_z _SAL_VERSION_CHECK(__out_z)
222#define __out_ecount_z(size) _SAL_VERSION_CHECK(__out_ecount_z)
223#define __out_bcount_z(size) _SAL_VERSION_CHECK(__out_bcount_z)
224#define __inout _SAL_VERSION_CHECK(__inout)
225#define __inout_ecount(size) _SAL_VERSION_CHECK(__inout_ecount)
226#define __inout_bcount(size) _SAL_VERSION_CHECK(__inout_bcount)
227#define __inout_xcount(size) _SAL_VERSION_CHECK(__inout_xcount)
228#define __inout_ecount_part(size,len) _SAL_VERSION_CHECK(__inout_ecount_part)
229#define __inout_bcount_part(size,len) _SAL_VERSION_CHECK(__inout_bcount_part)
230#define __inout_xcount_part(size,len) _SAL_VERSION_CHECK(__inout_xcount_part)
231#define __inout_ecount_full(size) _SAL_VERSION_CHECK(__inout_ecount_full)
232#define __inout_bcount_full(size) _SAL_VERSION_CHECK(__inout_bcount_full)
233#define __inout_xcount_full(size) _SAL_VERSION_CHECK(__inout_xcount_full)
234#define __inout_z __allowed(on_parameter)
235#define __inout_ecount_z(size) __allowed(on_parameter)
236#define __inout_bcount_z(size) __allowed(on_parameter)
237#define __ecount_opt(size) __allowed(on_parameter)
238#define __bcount_opt(size) __allowed(on_parameter)
239#define __xcount_opt(size) __allowed(on_parameter)
240#define __in_opt _SAL_VERSION_CHECK(__in_opt)
241#define __in_ecount_opt(size) _SAL_VERSION_CHECK(__in_ecount_opt)
242#define __in_bcount_opt(size) _SAL_VERSION_CHECK(__in_bcount_opt)
243#define __in_z_opt __allowed(on_parameter)
244#define __in_ecount_z_opt(size) __allowed(on_parameter)
245#define __in_bcount_z_opt(size) __allowed(on_parameter)
246#define __in_xcount_opt(size) __allowed(on_parameter)
247#define __out_opt _SAL_VERSION_CHECK(__out_opt)
248#define __out_ecount_opt(size) _SAL_VERSION_CHECK(__out_ecount_opt)
249#define __out_bcount_opt(size) _SAL_VERSION_CHECK(__out_bcount_opt)
250#define __out_xcount_opt(size) __allowed(on_parameter)
251#define __out_ecount_part_opt(size,len) __allowed(on_parameter)
252#define __out_bcount_part_opt(size,len) __allowed(on_parameter)
253#define __out_xcount_part_opt(size,len) __allowed(on_parameter)
254#define __out_ecount_full_opt(size) __allowed(on_parameter)
255#define __out_bcount_full_opt(size) __allowed(on_parameter)
256#define __out_xcount_full_opt(size) __allowed(on_parameter)
257#define __out_ecount_z_opt(size) __allowed(on_parameter)
258#define __out_bcount_z_opt(size) __allowed(on_parameter)
259#define __inout_opt _SAL_VERSION_CHECK(__inout_opt)
260#define __inout_ecount_opt(size) _SAL_VERSION_CHECK(__inout_ecount_opt)
261#define __inout_bcount_opt(size) _SAL_VERSION_CHECK(__inout_bcount_opt)
262#define __inout_xcount_opt(size) _SAL_VERSION_CHECK(__inout_xcount_opt)
263#define __inout_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_ecount_part_opt)
264#define __inout_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_bcount_part_opt)
265#define __inout_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_xcount_part_opt)
266#define __inout_ecount_full_opt(size) _SAL_VERSION_CHECK(__inout_ecount_full_opt)
267#define __inout_bcount_full_opt(size) _SAL_VERSION_CHECK(__inout_bcount_full_opt)
268#define __inout_xcount_full_opt(size) _SAL_VERSION_CHECK(__inout_xcount_full_opt)
269#define __inout_z_opt __allowed(on_parameter)
270#define __inout_ecount_z_opt(size) __allowed(on_parameter)
271#define __inout_ecount_z_opt(size) __allowed(on_parameter)
272#define __inout_bcount_z_opt(size) __allowed(on_parameter)
273#define __deref_ecount(size) __allowed(on_parameter)
274#define __deref_bcount(size) __allowed(on_parameter)
275#define __deref_xcount(size) __allowed(on_parameter)
276#define __deref_in _SAL_VERSION_CHECK(__deref_in)
277#define __deref_in_ecount(size) _SAL_VERSION_CHECK(__deref_in_ecount)
278#define __deref_in_bcount(size) _SAL_VERSION_CHECK(__deref_in_bcount)
279#define __deref_in_xcount(size) _SAL_VERSION_CHECK(__deref_in_xcount)
280#define __deref_out _SAL_VERSION_CHECK(__deref_out)
281#define __deref_out_ecount(size) _SAL_VERSION_CHECK(__deref_out_ecount)
282#define __deref_out_bcount(size) _SAL_VERSION_CHECK(__deref_out_bcount)
283#define __deref_out_xcount(size) _SAL_VERSION_CHECK(__deref_out_xcount)
284#define __deref_out_ecount_part(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part)
285#define __deref_out_bcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part)
286#define __deref_out_xcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part)
287#define __deref_out_ecount_full(size) _SAL_VERSION_CHECK(__deref_out_ecount_full)
288#define __deref_out_bcount_full(size) _SAL_VERSION_CHECK(__deref_out_bcount_full)
289#define __deref_out_xcount_full(size) _SAL_VERSION_CHECK(__deref_out_xcount_full)
290#define __deref_out_z __allowed(on_parameter)
291#define __deref_out_ecount_z(size) __allowed(on_parameter)
292#define __deref_out_bcount_z(size) __allowed(on_parameter)
293#define __deref_inout _SAL_VERSION_CHECK(__deref_inout)
294#define __deref_inout_ecount(size) _SAL_VERSION_CHECK(__deref_inout_ecount)
295#define __deref_inout_bcount(size) _SAL_VERSION_CHECK(__deref_inout_bcount)
296#define __deref_inout_xcount(size) _SAL_VERSION_CHECK(__deref_inout_xcount)
297#define __deref_inout_ecount_part(size,len) __allowed(on_parameter)
298#define __deref_inout_bcount_part(size,len) __allowed(on_parameter)
299#define __deref_inout_xcount_part(size,len) __allowed(on_parameter)
300#define __deref_inout_ecount_full(size) __allowed(on_parameter)
301#define __deref_inout_bcount_full(size) __allowed(on_parameter)
302#define __deref_inout_xcount_full(size) __allowed(on_parameter)
303#define __deref_inout_z __allowed(on_parameter)
304#define __deref_inout_ecount_z(size) __allowed(on_parameter)
305#define __deref_inout_bcount_z(size) __allowed(on_parameter)
306#define __deref_ecount_opt(size) __allowed(on_parameter)
307#define __deref_bcount_opt(size) __allowed(on_parameter)
308#define __deref_xcount_opt(size) __allowed(on_parameter)
309#define __deref_in_opt __allowed(on_parameter)
310#define __deref_in_opt_out __allowed(on_parameter)
311#define __deref_in_ecount_opt(size) __allowed(on_parameter)
312#define __deref_in_bcount_opt(size) __allowed(on_parameter)
313#define __deref_in_xcount_opt(size) __allowed(on_parameter)
314#define __deref_out_opt _SAL_VERSION_CHECK(__deref_out_opt)
315#define __deref_out_ecount_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_opt)
316#define __deref_out_bcount_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_opt)
317#define __deref_out_xcount_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_opt)
318#define __deref_out_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part_opt)
319#define __deref_out_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part_opt)
320#define __deref_out_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part_opt)
321#define __deref_out_ecount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_full_opt)
322#define __deref_out_bcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_full_opt)
323#define __deref_out_xcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_full_opt)
324#define __deref_out_z_opt __allowed(on_parameter)
325#define __deref_out_ecount_z_opt(size) __allowed(on_parameter)
326#define __deref_out_bcount_z_opt(size) __allowed(on_parameter)
327#define __deref_inout_opt __allowed(on_parameter)
328#define __deref_inout_ecount_opt(size) __allowed(on_parameter)
329#define __deref_inout_bcount_opt(size) __allowed(on_parameter)
330#define __deref_inout_xcount_opt(size) __allowed(on_parameter)
331#define __deref_inout_ecount_part_opt(size,len) __allowed(on_parameter)
332#define __deref_inout_bcount_part_opt(size,len) __allowed(on_parameter)
333#define __deref_inout_xcount_part_opt(size,len) __allowed(on_parameter)
334#define __deref_inout_ecount_full_opt(size) __allowed(on_parameter)
335#define __deref_inout_bcount_full_opt(size) __allowed(on_parameter)
336#define __deref_inout_xcount_full_opt(size) __allowed(on_parameter)
337#define __deref_inout_z_opt __allowed(on_parameter)
338#define __deref_inout_ecount_z_opt(size) __allowed(on_parameter)
339#define __deref_inout_bcount_z_opt(size) __allowed(on_parameter)
340#define __deref_opt_ecount(size) __allowed(on_parameter)
341#define __deref_opt_bcount(size) __allowed(on_parameter)
342#define __deref_opt_xcount(size) __allowed(on_parameter)
343#define __deref_opt_in __allowed(on_parameter)
344#define __deref_opt_in_ecount(size) __allowed(on_parameter)
345#define __deref_opt_in_bcount(size) __allowed(on_parameter)
346#define __deref_opt_in_xcount(size) __allowed(on_parameter)
347#define __deref_opt_out _SAL_VERSION_CHECK(__deref_opt_out)
348#define __deref_opt_out_ecount(size) _SAL_VERSION_CHECK(__deref_opt_out_ecount)
349#define __deref_opt_out_bcount(size) _SAL_VERSION_CHECK(__deref_opt_out_bcount)
350#define __deref_opt_out_xcount(size) _SAL_VERSION_CHECK(__deref_opt_out_xcount)
351#define __deref_opt_out_ecount_part(size,len) __allowed(on_parameter)
352#define __deref_opt_out_bcount_part(size,len) __allowed(on_parameter)
353#define __deref_opt_out_xcount_part(size,len) __allowed(on_parameter)
354#define __deref_opt_out_ecount_full(size) __allowed(on_parameter)
355#define __deref_opt_out_bcount_full(size) __allowed(on_parameter)
356#define __deref_opt_out_xcount_full(size) __allowed(on_parameter)
357#define __deref_opt_inout __allowed(on_parameter)
358#define __deref_opt_inout_ecount(size) __allowed(on_parameter)
359#define __deref_opt_inout_bcount(size) __allowed(on_parameter)
360#define __deref_opt_inout_xcount(size) __allowed(on_parameter)
361#define __deref_opt_inout_ecount_part(size,len) __allowed(on_parameter)
362#define __deref_opt_inout_bcount_part(size,len) __allowed(on_parameter)
363#define __deref_opt_inout_xcount_part(size,len) __allowed(on_parameter)
364#define __deref_opt_inout_ecount_full(size) __allowed(on_parameter)
365#define __deref_opt_inout_bcount_full(size) __allowed(on_parameter)
366#define __deref_opt_inout_xcount_full(size) __allowed(on_parameter)
367#define __deref_opt_inout_z __allowed(on_parameter)
368#define __deref_opt_inout_ecount_z(size) __allowed(on_parameter)
369#define __deref_opt_inout_bcount_z(size) __allowed(on_parameter)
370#define __deref_opt_ecount_opt(size) __allowed(on_parameter)
371#define __deref_opt_bcount_opt(size) __allowed(on_parameter)
372#define __deref_opt_xcount_opt(size) __allowed(on_parameter)
373#define __deref_opt_in_opt __allowed(on_parameter)
374#define __deref_opt_in_ecount_opt(size) __allowed(on_parameter)
375#define __deref_opt_in_bcount_opt(size) __allowed(on_parameter)
376#define __deref_opt_in_xcount_opt(size) __allowed(on_parameter)
377#define __deref_opt_out_opt __allowed(on_parameter)
378#define __deref_opt_out_ecount_opt(size) __allowed(on_parameter)
379#define __deref_opt_out_bcount_opt(size) __allowed(on_parameter)
380#define __deref_opt_out_xcount_opt(size) __allowed(on_parameter)
381#define __deref_opt_out_ecount_part_opt(size,len) __allowed(on_parameter)
382#define __deref_opt_out_bcount_part_opt(size,len) __allowed(on_parameter)
383#define __deref_opt_out_xcount_part_opt(size,len) __allowed(on_parameter)
384#define __deref_opt_out_ecount_full_opt(size) __allowed(on_parameter)
385#define __deref_opt_out_bcount_full_opt(size) __allowed(on_parameter)
386#define __deref_opt_out_xcount_full_opt(size) __allowed(on_parameter)
387#define __deref_opt_out_z_opt __allowed(on_parameter)
388#define __deref_opt_out_ecount_z_opt(size) __allowed(on_parameter)
389#define __deref_opt_out_bcount_z_opt(size) __allowed(on_parameter)
390#define __deref_opt_inout_opt __allowed(on_parameter)
391#define __deref_opt_inout_ecount_opt(size) __allowed(on_parameter)
392#define __deref_opt_inout_bcount_opt(size) __allowed(on_parameter)
393#define __deref_opt_inout_xcount_opt(size) __allowed(on_parameter)
394#define __deref_opt_inout_ecount_part_opt(size,len) __allowed(on_parameter)
395#define __deref_opt_inout_bcount_part_opt(size,len) __allowed(on_parameter)
396#define __deref_opt_inout_xcount_part_opt(size,len) __allowed(on_parameter)
397#define __deref_opt_inout_ecount_full_opt(size) __allowed(on_parameter)
398#define __deref_opt_inout_bcount_full_opt(size) __allowed(on_parameter)
399#define __deref_opt_inout_xcount_full_opt(size) __allowed(on_parameter)
400#define __deref_opt_inout_z_opt __allowed(on_parameter)
401#define __deref_opt_inout_ecount_z_opt(size) __allowed(on_parameter)
402#define __deref_opt_inout_bcount_z_opt(size) __allowed(on_parameter)
403#define __deref_in_ecount_iterator(size,incr) __allowed(on_parameter)
404#define __deref_out_ecount_iterator(size,incr) __allowed(on_parameter)
405#define __deref_inout_ecount_iterator(size,incr) __allowed(on_parameter)
406#define __deref_realloc_bcount(insize,outsize) __allowed(on_parameter)
407
408/************************************************************************
409* SAL 2 _Ouptr_ family of annotations
410************************************************************************/
411
412#define _Outptr_ __allowed(on_parameter)
413#define _Outptr_result_maybenull_ __allowed(on_parameter)
414#define _Outptr_opt_ __allowed(on_parameter)
415#define _Outptr_opt_result_maybenull_ __allowed(on_parameter)
416#define _Outptr_result_z_ __allowed(on_parameter)
417#define _Outptr_opt_result_z_ __allowed(on_parameter)
418#define _Outptr_result_maybenull_z_ __allowed(on_parameter)
419#define _Outptr_opt_result_maybenull_z_ __allowed(on_parameter)
420#define _Outptr_result_nullonfailure_ __allowed(on_parameter)
421#define _Outptr_opt_result_nullonfailure_ __allowed(on_parameter)
422#define _COM_Outptr_ __allowed(on_parameter)
423#define _COM_Outptr_result_maybenull_ __allowed(on_parameter)
424#define _COM_Outptr_opt_ __allowed(on_parameter)
425#define _COM_Outptr_opt_result_maybenull_ __allowed(on_parameter)
426#define _Outptr_result_buffer_(size) __allowed(on_parameter)
427#define _Outptr_opt_result_buffer_(size) __allowed(on_parameter)
428#define _Outptr_result_buffer_to_(size, count) __allowed(on_parameter)
429#define _Outptr_opt_result_buffer_to_(size, count) __allowed(on_parameter)
430#define _Outptr_result_buffer_all_(size) __allowed(on_parameter)
431#define _Outptr_opt_result_buffer_all_(size) __allowed(on_parameter)
432#define _Outptr_result_buffer_maybenull_(size) __allowed(on_parameter)
433#define _Outptr_opt_result_buffer_maybenull_(size) __allowed(on_parameter)
434#define _Outptr_result_buffer_to_maybenull_(size, count) __allowed(on_parameter)
435#define _Outptr_opt_result_buffer_to_maybenull_(size, count) __allowed(on_parameter)
436#define _Outptr_result_buffer_all_maybenull_(size) __allowed(on_parameter)
437#define _Outptr_opt_result_buffer_all_maybenull_(size) __allowed(on_parameter)
438#define _Outptr_result_bytebuffer_(size) __allowed(on_parameter)
439#define _Outptr_opt_result_bytebuffer_(size) __allowed(on_parameter)
440#define _Outptr_result_bytebuffer_to_(size, count) __allowed(on_parameter)
441#define _Outptr_opt_result_bytebuffer_to_(size, count) __allowed(on_parameter)
442#define _Outptr_result_bytebuffer_all_(size) __allowed(on_parameter)
443#define _Outptr_opt_result_bytebuffer_all_(size) __allowed(on_parameter)
444#define _Outptr_result_bytebuffer_maybenull_(size) __allowed(on_parameter)
445#define _Outptr_opt_result_bytebuffer_maybenull_(size) __allowed(on_parameter)
446#define _Outptr_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter)
447#define _Outptr_opt_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter)
448#define _Outptr_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter)
449#define _Outptr_opt_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter)
450
451/************************************************************************
452* Orcas SAL
453************************************************************************/
454#define _Deref_out_ _SAL_VERSION_CHECK(_Deref_out_)
455#define _Deref_out_opt_ _SAL_VERSION_CHECK(_Deref_out_opt_)
456#define _Deref_opt_out_ _SAL_VERSION_CHECK(_Deref_opt_out_)
457#define _Deref_opt_out_opt_ _SAL_VERSION_CHECK(_Deref_opt_out_opt_)
458#define _In_count_(size) _SAL_VERSION_CHECK(_In_count_)
459#define _In_opt_count_(size) _SAL_VERSION_CHECK(_In_opt_count_)
460#define _In_bytecount_(size) _SAL_VERSION_CHECK(_In_bytecount_)
461#define _In_opt_bytecount_(size) _SAL_VERSION_CHECK(_In_opt_bytecount_)
462#define _Out_cap_(size) _SAL_VERSION_CHECK(_Out_cap_)
463#define _Out_opt_cap_(size) _SAL_VERSION_CHECK(_Out_opt_cap_)
464#define _Out_bytecap_(size) _SAL_VERSION_CHECK(_Out_bytecap_)
465#define _Out_opt_bytecap_(size) _SAL_VERSION_CHECK(_Out_opt_bytecap_)
466#define _Deref_post_count_(size) _SAL_VERSION_CHECK(_Deref_post_count_)
467#define _Deref_post_opt_count_(size) _SAL_VERSION_CHECK(_Deref_post_opt_count_)
468#define _Deref_post_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_bytecount_)
469#define _Deref_post_opt_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecount_)
470#define _Deref_post_cap_(size) _SAL_VERSION_CHECK(_Deref_post_cap_)
471#define _Deref_post_opt_cap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_cap_)
472#define _Deref_post_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_bytecap_)
473#define _Deref_post_opt_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecap_)
474
475/************************************************************************
476* Advanced Annotations
477*
478* Advanced annotations describe behavior that is not expressible with the
479* regular buffer macros. These may be used either to annotate buffer
480* parameters that involve complex or conditional behavior, or to enrich
481* existing annotations with additional information.
482*
483* _At_(expr, annotes) : annotation list annotes applies to target 'expr'
484*
485* _When_(expr, annotes) : annotation list annotes applies when 'expr' is true
486*
487* __success(expr) T f() : <expr> indicates whether function f succeeded or
488* not. If <expr> is true at exit, all the function's guarantees (as given
489* by other annotations) must hold. If <expr> is false at exit, the caller
490* should not expect any of the function's guarantees to hold. If not used,
491* the function must always satisfy its guarantees. Added automatically to
492* functions that indicate success in standard ways, such as by returning an
493* HRESULT.
494*
495* __out_awcount(expr, size) T *p : Pointer p is a buffer whose size may be
496* given in either bytes or elements. If <expr> is true, this acts like
497* __out_bcount. If <expr> is false, this acts like __out_ecount. This
498* should only be used to annotate old APIs.
499*
500* __in_awcount(expr, size) T* p : Pointer p is a buffer whose size may be given
501* in either bytes or elements. If <expr> is true, this acts like
502* __in_bcount. If <expr> is false, this acts like __in_ecount. This should
503* only be used to annotate old APIs.
504*
505* __nullterminated T* p : Pointer p is a buffer that may be read or written
506* up to and including the first '\0' character or pointer. May be used on
507* typedefs, which marks valid (properly initialized) instances of that type
508* as being null-terminated.
509*
510* __nullnullterminated T* p : Pointer p is a buffer that may be read or
511* written up to and including the first sequence of two '\0' characters or
512* pointers. May be used on typedefs, which marks valid instances of that
513* type as being double-null terminated.
514*
515* __reserved T v : Value v must be 0/NULL, reserved for future use.
516*
517* __checkReturn T f(); : Return value of f must not be ignored by callers
518* of this function.
519*
520* __typefix(ctype) T v : Value v should be treated as an instance of ctype,
521* rather than its declared type when considering validity.
522*
523* __override T f(); : Specify C#-style 'override' behaviour for overriding
524* virtual methods.
525*
526* __callback T f(); : Function f can be used as a function pointer.
527*
528* __format_string T p : Pointer p is a string that contains % markers in
529* the style of printf.
530*
531* __blocksOn(resource) f(); : Function f blocks on the resource 'resource'.
532*
533* __fallthrough : Annotates switch statement labels where fall-through is
534* desired, to distinguish from forgotten break statements.
535*
536* __range(low_bnd, up_bnd) int f(): The return from the function "f" must
537* be in the inclusive numeric range [low_bnd, up_bnd].
538*
539* __in_range(low_bnd, up_bnd) int i : Precondition that integer i must be
540* in the inclusive numeric range [low_bnd, up_bnd].
541*
542* __out_range(low_bnd, up_bnd) int i : Postcondition that integer i must be
543* in the inclusive numeric range [low_bnd, up_bnd].
544*
545* __deref_in_range(low_bnd, up_bnd) int* pi : Precondition that integer *pi
546* must be in the inclusive numeric range [low_bnd, up_bnd].
547*
548* __deref_out_range(low_bnd, up_bnd) int* pi : Postcondition that integer
549* *pi must be in the inclusive numeric range [low_bnd, up_bnd].
550*
551* __deref_inout_range(low_bnd, up_bnd) int* pi : Invariant that the integer
552* *pi must be in the inclusive numeric range [low_bnd, up_bnd].
553*
554* The first argument of a range macro may also be a C relational operator
555* (<,>,!=, ==, <=, >=).
556*
557* __range(rel_op, j) int f(): Postcondition that "f() rel_op j" must be
558* true. Note that j may be a expression known only at runtime.
559*
560* __in_range(rel_op, j) int i : Precondition that "i rel_op j" must be
561* true. Note that j may be a expression known only at runtime.
562*
563* __out_range(rel_op, j) int i : Postcondition that integer "i rel_op j"
564* must be true. Note that j may be a expression known only at runtime.
565*
566* __deref_in_range(rel_op, j) int *pi : Precondition that "*pi rel_op j"
567* must be true. Note that j may be a expression known only at runtime.
568*
569* __deref_out_range(rel_op, j) int *pi : Postcondition that "*pi rel_op j"
570* must be true. Note that j may be a expression known only at runtime.
571*
572* __deref_inout_range(rel_op, j) int *pi : Invariant that "*pi rel_op j"
573* must be true. Note that j may be a expression known only at runtime.
574*
575* __range_max(a, b) int f(): Postcondition f acts as 'max', returns larger
576* of a and b. Note that a and b may be expressions known only at runtime.
577*
578* __range_min(a, b) int f(): Postcondition f acts as 'min', returns smaller
579* of a and b. Note that a and b may be expressions known only at runtime.
580*
581* __in_bound int i : Precondition that integer i must be bound, but the
582* exact range can't be specified at compile time. __in_range should be
583* used if the range can be explicitly stated.
584*
585* __out_bound int i : Postcondition that integer i must be bound, but the
586* exact range can't be specified at compile time. __out_range should be
587* used if the range can be explicitly stated.
588*
589* __deref_out_bound int pi : Postcondition that integer *pi must be bound,
590* but the exact range can't be specified at compile time.
591* __deref_out_range should be used if the range can be explicitly stated.
592*
593* __assume_bound(expr); : Assume that the expression is bound to some known
594* range. This can be used to suppress integer overflow warnings on integral
595* expressions that are known to be bound due to reasons not explicit in the
596* code. Use as a statement in the body of a function.
597*
598* __analysis_assume_nulltermianted(expr); : Assume that the expression is
599* a null terminated buffer. Use this to suppress tool noise specific to
600* nulltermination warnings, and capture deeper invariants tools can not
601* discover.
602*
603* __allocator void f(): Function allocates memory using an integral size
604* argument
605*
606* void myfree(__deallocate(Mem) void *p) : Memory is freed, no longer usable
607* upon return, and p may not be null.
608*
609* void myfree(__deallocate_opt(Mem) void *p) : Memory is freed, no longer
610* usable upon return, and p may be null.
611*
612* void free(__post_invalid void* x): Mark memory as untouchable when
613* function returns.
614*
615* ----------------------------------------------------------------------------
616* Advanced Annotation Examples
617*
618* __success(return == TRUE) LWSTDAPI_(BOOL)
619* PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath);
620* // pszBuf is only guaranteed to be null-terminated when TRUE is returned.
621*
622* // Initialized LPWSTRs are null-terminated strings.
623* typedef __nullterminated WCHAR* LPWSTR;
624*
625* __out_ecount(cch) __typefix(LPWSTR) void *psz;
626* // psz is a buffer parameter which will be a null-terminated WCHAR string
627* // at exit, and which initially contains cch WCHARs.
628*
629************************************************************************/
630#define _At_(expr, annotes) __allowed(on_parameter_or_return)
631#define _When_(expr, annotes) __allowed(on_parameter_or_return)
632#define __success(expr) _SAL_VERSION_CHECK(__success)
633#define __out_awcount(expr,size) __allowed(on_parameter)
634#define __in_awcount(expr,size) __allowed(on_parameter)
635#define __nullterminated _SAL_VERSION_CHECK(__nullterminated)
636#define __nullnullterminated _SAL_VERSION_CHECK(__nullnullterminated)
637#define __reserved _SAL_VERSION_CHECK(__reserved)
638#define __checkReturn _SAL_VERSION_CHECK(__checkReturn)
639#define __typefix(ctype) __allowed(on_parameter_or_return)
640#define __override __allowed(on_function)
641#define __callback __allowed(on_function)
642#define __format_string __allowed(on_parameter_or_return)
643#define __blocksOn(resource) __allowed(on_function)
644#define __fallthrough __allowed(as_statement)
645#define __range(lb,ub) __allowed(on_return)
646#define __in_range(lb,ub) _SAL_VERSION_CHECK(__in_range)
647#define __out_range(lb,ub) _SAL_VERSION_CHECK(__out_range)
648#define __deref_in_range(lb,ub) __allowed(on_parameter)
649#define __deref_out_range(lb,ub) _SAL_VERSION_CHECK(__deref_out_range)
650#define __deref_inout_range(lb,ub) __allowed(on_parameter)
651#define __field_range(lb,ub) _SAL_VERSION_CHECK(__field_range)
652#define __range_max(a,b) __allowed(on_return)
653#define __range_min(a,b) __allowed(on_return)
654#define __bound __allowed(on_return)
655#define __in_bound __allowed(on_parameter)
656#define __out_bound __allowed(on_parameter)
657#define __deref_out_bound __allowed(on_parameter)
658#define __assume_bound(i) __allowed(as_statement_with_arg(i))
659#define __analysis_assume_nullterminated(x) \
660 __allowed(as_statement_with_arg(x))
661#define __allocator __allowed(on_function)
662#define __deallocate(kind) __allowed(on_parameter)
663#define __deallocate_opt(kind) __allowed(on_parameter)
664#define __post_invalid __allowed(on_parameter_or_return)
665#define __post_nullnullterminated \
666 __allowed(on_parameter_or_return)
667/***************************************************************************
668* Expert Macros
669***************************************************************************/
670#define __null __allowed(on_typedecl)
671#define __notnull __allowed(on_typedecl)
672#define __maybenull __allowed(on_typedecl)
673#define __exceptthat __allowed(on_typedecl)
674/***************************************************************************
675* Macros to classify fields of structures.
676* Structure Annotations
677*
678* The buffer annotations are a convenient way of describing
679* relationships between buffers and their size on a function by
680* function basis. Very often struct or class data members have similar
681* invariants, which can be expressed directly on the type.
682*
683* Similar to our buffer annotations we can summarize all the various
684* structure annotations by one choosing an element from each column of
685* this table to build a composite annotation.
686*
687* +--------------------------------------------------+
688* | Selector | Units | Size/Init | Optional |
689* |----------+---------+------------------+----------|
690* | __field | _ecount | (size) | empty |
691* |----------+---------+------------------+----------|
692* | __struct | _bcount | _full(size) | _opt |
693* |----------+---------+------------------+----------|
694* | | _xcount | _part(size,init) | |
695* +--------------------------------------------------+
696*
697* Note that empty represents the empty string. Sometime arguments need
698* to be "floated" to the left to give us a valid annotation name. For
699* example the naive combination __field_ecount(size)_opt is actually
700* written as __field_ecount_opt(size). Not all possible combinations
701* are currently supported or sensible. See specstrings_strict.h for
702* the currently supported set. Those that are supported are documented
703* below.
704*
705*Summary of Elements
706*
707* Selector
708*
709* __field
710* The annotation should only be placed in front
711* of data members of structures and classes. The
712* data members are pointers to a block of data.
713* The annotations describe properties about the
714* size of the block of data. This can be used for
715*
716* __struct
717* The annotation should only be placed at the
718* beginning of the definition of a structure or
719* class. These annotations are used when a struct
720* or class is used as a "header" that is
721* allocated inline with a block of data and there
722* is no apparent field that represents the tail
723* end of the structure.
724*
725* Units
726*
727* _ecount
728* All size and initialization values are in terms
729* of elements of the appropriate type
730*
731* _bcount
732* All size and initialization values are in terms
733* of raw byte sizes.
734*
735* _xcount
736* The size or initialization values cannot be
737* properly expressed as a simple byte or element
738* count, and instead a place holder is used to
739* document the relationship.
740*
741* Size/Init
742* All the size/init expressions can contain references to
743* other fields in the struct or class.
744*
745* (size)
746* The size of the buffer is determined by the
747* expression size. Unless, the type of the buffer
748* provides more information nothing is know about
749* how much of this data is initialized. For
750* example, if the data member happens to be a
751* string type such as LPSTR. It is assumed that
752* the data is initialized to the first '\0'.
753*
754* _full(size)
755* The size of the buffer is determined by the
756* expression size and all the data in the buffer
757* is guaranteed to be initialized.
758*
759* _part(size,init)
760* The size of the buffer is determined by the
761* expression size and all the data in the buffer
762* is guaranteed to be initialized up to init
763* elements or bytes.
764*
765* Optional
766*
767* empty
768* The pointer to the block of memory is never
769* NULL
770*
771* _opt
772* The pointer to the block of memory is may be
773* NULL
774*
775*
776* // Basic Usage of Struct Annotations
777* #include <stdio.h>
778* #include <stdlib.h>
779* struct buf_s {
780* int sz;
781* __field_bcount_full(sz)
782* char *buf;
783* };
784* void InitBuf(__out struct *buf_s b,int sz) {
785* b->buf = calloc(sz,sizeof(char));
786* b->sz = sz;
787* }
788* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
789* fwrite(b->buf,b->sz,sizeof(char),fp);
790* }
791* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
792* fread(b->buf,b->sz,sizeof(char),fp);
793* }
794*
795*
796*
797* // Inline Allocated Buffer
798* struct buf_s {
799* int sz;
800* __field_bcount(sz)
801* char buf[1];
802* };
803* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
804* fwrite(&(b->buf),b->sz,sizeof(char),fp);
805* }
806* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
807* fread(&(b->buf),b->sz,sizeof(char),fp);
808* }
809*
810*
811*
812* // Embedded Header Structure
813* __struct_bcount(sz)
814* struct buf_s {
815* int sz;
816* };
817* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
818* fwrite(&b,b->sz,sizeof(char),fp);
819* }
820* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
821* fread(&b,b->sz,sizeof(char),fp);
822* }
823*
824*
825****************************************************************************/
826#define __field_ecount(size) _SAL_VERSION_CHECK(__field_ecount)
827#define __field_bcount(size) _SAL_VERSION_CHECK(__field_bcount)
828#define __field_xcount(size) __allowed(on_field)
829#define __field_ecount_opt(size) __allowed(on_field)
830#define __field_bcount_opt(size) __allowed(on_field)
831#define __field_xcount_opt(size) __allowed(on_field)
832#define __field_ecount_part(size,init) __allowed(on_field)
833#define __field_bcount_part(size,init) __allowed(on_field)
834#define __field_xcount_part(size,init) __allowed(on_field)
835#define __field_ecount_part_opt(size,init) __allowed(on_field)
836#define __field_bcount_part_opt(size,init) __allowed(on_field)
837#define __field_xcount_part_opt(size,init) __allowed(on_field)
838#define __field_ecount_full(size) __allowed(on_field)
839#define __field_bcount_full(size) __allowed(on_field)
840#define __field_xcount_full(size) __allowed(on_field)
841#define __field_ecount_full_opt(size) __allowed(on_field)
842#define __field_bcount_full_opt(size) __allowed(on_field)
843#define __field_xcount_full_opt(size) __allowed(on_field)
844#define __field_nullterminated __allowed(on_field)
845#define __struct_bcount(size) __allowed(on_struct)
846#define __struct_xcount(size) __allowed(on_struct)
847
848/***************************************************************************
849* Macros to classify the entrypoints and indicate their category.
850*
851* Pre-defined control point categories include: RPC, KERNEL, GDI.
852*
853* Pre-defined control point macros include:
854* __rpc_entry, __kernel_entry, __gdi_entry.
855***************************************************************************/
856#define __control_entrypoint(category) __allowed(on_function)
857#define __rpc_entry __allowed(on_function)
858#define __kernel_entry __allowed(on_function)
859#define __gdi_entry __allowed(on_function)
860
861/***************************************************************************
862* Macros to track untrusted data and their validation. The list of untrusted
863* sources include:
864*
865* FILE - File reading stream or API
866* NETWORK - Socket readers
867* INTERNET - WinInet and WinHttp readers
868* USER_REGISTRY - HKCU portions of the registry
869* USER_MODE - Parameters to kernel entry points
870* RPC - Parameters to RPC entry points
871* DRIVER - Device driver
872***************************************************************************/
873#define __in_data_source(src_sym) __allowed(on_parameter)
874#define __out_data_source(src_sym) __allowed(on_parameter)
875#define __field_data_source(src_sym) __allowed(on_field)
876#define __this_out_data_source(src_syn) __allowed(on_function)
877
878/**************************************************************************
879* Macros to tag file parsing code. Predefined formats include:
880* PNG - Portable Network Graphics
881* JPEG - Joint Photographic Experts Group
882* BMP - Bitmap
883* RC_BMP - Resource bitmap
884* WMF - Windows Metafile
885* EMF - Windows Enhanced Metafile
886* GIF - Graphics Interchange Format
887* MIME_TYPE - MIME type from header tokens
888* MAIL_MONIKER - MAIL information refered by URL moniker
889* HTML - HyperText Markup Language
890* WMPHOTO - Windows media photo
891* OE_VCARD - Outlook Express virtual card
892* OE_CONTACT - Outlook Express contact
893* MIDI - Musical Instrument Digital Interface
894* LDIF - LDAP Data Interchange Format
895* AVI - Audio Visual Interchange
896* ACM - Audio Compression Manager
897**************************************************************************/
898#define __out_validated(filetype_sym) __allowed(on_parameter)
899#define __this_out_validated(filetype_sym) __allowed(on_function)
900#define __file_parser(filetype_sym) __allowed(on_function)
901#define __file_parser_class(filetype_sym) __allowed(on_struct)
902#define __file_parser_library(filetype_sym) __allowed(as_global_decl)
903
904/***************************************************************************
905* Macros to track the code content in the file. The type of code
906* contents currently tracked:
907*
908* NDIS_DRIVER - NDIS Device driver
909***************************************************************************/
910#define __source_code_content(codetype_sym) __allowed(as_global_decl)
911
912/***************************************************************************
913* Macros to track the code content in the class. The type of code
914* contents currently tracked:
915*
916* DCOM - Class implementing DCOM
917***************************************************************************/
918#define __class_code_content(codetype_sym) __allowed(on_struct)
919
920/*************************************************************************
921* Macros to tag encoded function pointers
922**************************************************************************/
923#define __encoded_pointer
924#define __encoded_array
925#define __field_encoded_pointer __allowed(on_field)
926#define __field_encoded_array __allowed(on_field)
927
928#define __transfer(formal) __allowed(on_parameter_or_return)
929#define __assume_validated(exp) __allowed(as_statement_with_arg(exp))
930
931/*************************************************************************
932* __analysis_assume(expr) : Expert macro use only when directed. Use this to
933* tell static analysis tools like PREfix and PREfast about a non-coded
934* assumption that you wish the tools to assume. The assumption will be
935* understood by those tools. By default there is no dynamic checking or
936* static checking of the assumption in any build.
937*
938* To obtain dynamic checking wrap this macro in your local version of a debug
939* assert.
940* Please do not put function calls in the expression because this is not
941* supported by all tools:
942* __analysis_assume(GetObject () != NULL); // DO NOT DO THIS
943*
944*************************************************************************/
945#define __analysis_assume(expr) __allowed(as_statement_with_arg(expr))
946#define __analysis_assert(expr) __allowed(as_statement_with_arg(expr))
947
948/*************************************************************************
949* __analysis_hint(hint_sym) : Expert macro use only when
950* directed. Use this to influence certain analysis heuristics
951* used by the tools. These hints do not describe the semantics
952* of functions but simply direct the tools to act in a certain
953* way.
954*
955* Current hints that are supported are:
956*
957* INLINE - inline this function during analysis overrides any
958* default heuristics
959* NOINLINE - do not inline this function during analysis overrides
960* and default heuristics
961*************************************************************************/
962#define __analysis_hint(hint) __allowed(on_function)
963
964/*************************************************************************
965* Macros to encode abstract properties of values. Used by SALadt.h
966*************************************************************************/
967#define __type_has_adt_prop(adt,prop) __allowed(on_typdecl)
968#define __out_has_adt_prop(adt,prop) __allowed(on_parameter)
969#define __out_not_has_adt_prop(adt,prop) __allowed(on_parameter)
970#define __out_transfer_adt_prop(arg) __allowed(on_parameter)
971#define __out_has_type_adt_props(typ) __allowed(on_parameter)
972
973/*************************************************************************
974* Macros used by Prefast for Drivers
975*
976* __possibly_notnullterminated :
977*
978* Used for return values of parameters or functions that do not
979* guarantee nulltermination in all cases.
980*
981*************************************************************************/
982#define __possibly_notnullterminated __allowed(on_parameter_or_return)
983
984/*************************************************************************
985* Advanced macros
986*
987* __volatile
988* The __volatile annotation identifies a global variable or
989* structure field that:
990* 1) is not declared volatile;
991* 2) is accessed concurrently by multiple threads.
992*
993* The __deref_volatile annotation identifies a global variable
994* or structure field that stores a pointer to some data that:
995* 1) is not declared volatile;
996* 2) is accessed concurrently by multiple threads.
997*
998* Prefast uses these annotations to find patterns of code that
999* may result in unexpected re-fetching of the global variable
1000* into a local variable.
1001*
1002* We also provide two complimentary annotations __nonvolatile
1003* and __deref_nonvolatile that could be used to suppress Prefast
1004*
1005* re-fetching warnings on variables that are known either:
1006* 1) not to be in danger of being re-fetched or,
1007* 2) not to lead to incorrect results if they are re-fetched
1008*
1009*************************************************************************/
1010#define __volatile __allowed(on_global_or_field)
1011#define __deref_volatile __allowed(on_global_or_field)
1012#define __nonvolatile __allowed(on_global_or_field)
1013#define __deref_nonvolatile __allowed(on_global_or_field)
1014
1015/*************************************************************************
1016* Macros deprecated with strict level greater then 1.
1017**************************************************************************/
1018#if (__SPECSTRINGS_STRICT_LEVEL > 1)
1019/* Must come before macro defintions */
1020#pragma deprecated(__in_nz)
1021#pragma deprecated(__in_ecount_nz)
1022#pragma deprecated(__in_bcount_nz)
1023#pragma deprecated(__out_nz)
1024#pragma deprecated(__out_nz_opt)
1025#pragma deprecated(__out_ecount_nz)
1026#pragma deprecated(__out_bcount_nz)
1027#pragma deprecated(__inout_nz)
1028#pragma deprecated(__inout_ecount_nz)
1029#pragma deprecated(__inout_bcount_nz)
1030#pragma deprecated(__in_nz_opt)
1031#pragma deprecated(__in_ecount_nz_opt)
1032#pragma deprecated(__in_bcount_nz_opt)
1033#pragma deprecated(__out_ecount_nz_opt)
1034#pragma deprecated(__out_bcount_nz_opt)
1035#pragma deprecated(__inout_nz_opt)
1036#pragma deprecated(__inout_ecount_nz_opt)
1037#pragma deprecated(__inout_bcount_nz_opt)
1038#pragma deprecated(__deref_out_nz)
1039#pragma deprecated(__deref_out_ecount_nz)
1040#pragma deprecated(__deref_out_bcount_nz)
1041#pragma deprecated(__deref_inout_nz)
1042#pragma deprecated(__deref_inout_ecount_nz)
1043#pragma deprecated(__deref_inout_bcount_nz)
1044#pragma deprecated(__deref_out_nz_opt)
1045#pragma deprecated(__deref_out_ecount_nz_opt)
1046#pragma deprecated(__deref_out_bcount_nz_opt)
1047#pragma deprecated(__deref_inout_nz_opt)
1048#pragma deprecated(__deref_inout_ecount_nz_opt)
1049#pragma deprecated(__deref_inout_bcount_nz_opt)
1050#pragma deprecated(__deref_opt_inout_nz)
1051#pragma deprecated(__deref_opt_inout_ecount_nz)
1052#pragma deprecated(__deref_opt_inout_bcount_nz)
1053#pragma deprecated(__deref_opt_out_nz_opt)
1054#pragma deprecated(__deref_opt_out_ecount_nz_opt)
1055#pragma deprecated(__deref_opt_out_bcount_nz_opt)
1056#pragma deprecated(__deref_opt_inout_nz_opt)
1057#pragma deprecated(__deref_opt_inout_ecount_nz_opt)
1058#pragma deprecated(__deref_opt_inout_bcount_nz_opt)
1059#pragma deprecated(__deref)
1060#pragma deprecated(__pre)
1061#pragma deprecated(__post)
1062#pragma deprecated(__readableTo)
1063#pragma deprecated(__writableTo)
1064#pragma deprecated(__maybevalid)
1065#pragma deprecated(__data_entrypoint)
1066#pragma deprecated(__inexpressible_readableTo)
1067#pragma deprecated(__readonly)
1068#pragma deprecated(__byte_writableTo)
1069#pragma deprecated(__byte_readableTo)
1070#pragma deprecated(__elem_readableTo)
1071#pragma deprecated(__elem_writableTo)
1072#pragma deprecated(__valid)
1073#pragma deprecated(__notvalid)
1074#pragma deprecated(__refparam)
1075#pragma deprecated(__precond)
1076#endif
1077/* Define soon to be deprecated macros to nops. */
1078#define __in_nz
1079#define __in_ecount_nz(size)
1080#define __in_bcount_nz(size)
1081#define __out_nz
1082#define __out_nz_opt
1083#define __out_ecount_nz(size)
1084#define __out_bcount_nz(size)
1085#define __inout_nz
1086#define __inout_ecount_nz(size)
1087#define __inout_bcount_nz(size)
1088#define __in_nz_opt
1089#define __in_ecount_nz_opt(size)
1090#define __in_bcount_nz_opt(size)
1091#define __out_ecount_nz_opt(size)
1092#define __out_bcount_nz_opt(size)
1093#define __inout_nz_opt
1094#define __inout_ecount_nz_opt(size)
1095#define __inout_bcount_nz_opt(size)
1096#define __deref_out_nz
1097#define __deref_out_ecount_nz(size)
1098#define __deref_out_bcount_nz(size)
1099#define __deref_inout_nz
1100#define __deref_inout_ecount_nz(size)
1101#define __deref_inout_bcount_nz(size)
1102#define __deref_out_nz_opt
1103#define __deref_out_ecount_nz_opt(size)
1104#define __deref_out_bcount_nz_opt(size)
1105#define __deref_inout_nz_opt
1106#define __deref_inout_ecount_nz_opt(size)
1107#define __deref_inout_bcount_nz_opt(size)
1108#define __deref_opt_inout_nz
1109#define __deref_opt_inout_ecount_nz(size)
1110#define __deref_opt_inout_bcount_nz(size)
1111#define __deref_opt_out_nz_opt
1112#define __deref_opt_out_ecount_nz_opt(size)
1113#define __deref_opt_out_bcount_nz_opt(size)
1114#define __deref_opt_inout_nz_opt
1115#define __deref_opt_inout_ecount_nz_opt(size)
1116#define __deref_opt_inout_bcount_nz_opt(size)
1117#define __deref
1118#define __pre
1119#define __post
1120#define __readableTo(count)
1121#define __writableTo(count)
1122#define __maybevalid
1123#define __inexpressible_readableTo(string)
1124#define __data_entrypoint(category)
1125#define __readonly
1126#define __byte_writableTo(count)
1127#define __byte_readableTo(count)
1128#define __elem_readableTo(count)
1129#define __elem_writableTo(count)
1130#define __valid
1131#define __notvalid
1132#define __refparam
1133#define __precond(condition)
1134
1135/*************************************************************************
1136* Definitions to force a compile error when macros are used improperly.
1137* Relies on VS 2005 source annotations.
1138*************************************************************************/
1139#if !defined(_MSC_EXTENSIONS) && !defined(_PREFAST_) && !defined(OACR)
1140#define __allowed(p) /* nothing */
1141#else
1142#define __allowed(p) __$allowed_##p
1143#define __$allowed_as_global_decl /* empty */
1144#define __$allowed_as_statement_with_arg(x) \
1145 __pragma(warning(push)) __pragma(warning(disable : 4548)) \
1146 do {__noop(x);} while((0,0) __pragma(warning(pop)) )
1147#define __$allowed_as_statement __$allowed_as_statement_with_arg(1)
1148
1149/**************************************************************************
1150* This should go away. It's only for __success which we should split into.
1151* __success and __typdecl_sucess
1152***************************************************************************/
1153#define __$allowed_on_function_or_typedecl /* empty */
1154#if (__SPECSTRINGS_STRICT_LEVEL == 1) || (__SPECSTRINGS_STRICT_LEVEL == 2)
1155#define __$allowed_on_typedecl /* empty */
1156#define __$allowed_on_return /* empty */
1157#define __$allowed_on_parameter /* empty */
1158#define __$allowed_on_function /* empty */
1159#define __$allowed_on_struct /* empty */
1160#define __$allowed_on_field /* empty */
1161#define __$allowed_on_parameter_or_return /* empty */
1162#define __$allowed_on_global_or_field /* empty */
1163#elif __SPECSTRINGS_STRICT_LEVEL == 3
1164#define __$allowed_on_typedecl /* empty */
1165/* Define dummy source attributes. Still needs more testing */
1166#define __$allowed_on_return [returnvalue: OnReturnOnly]
1167#define __$allowed_on_parameter [OnParameterOnly]
1168#define __$allowed_on_function [method: OnFunctionOnly]
1169#define __$allowed_on_struct [OnStructOnly]
1170#define __$allowed_on_field [OnFieldOnly]
1171#define __$allowed_on_parameter_or_return [OnParameterOrReturnOnly]
1172#define __$allowed_on_global_or_field /* empty */
1173#pragma push_macro( "DECL_SA" )
1174#pragma push_macro( "SA" )
1175#ifdef __cplusplus
1176#define SA(x) x
1177#define DECL_SA(name,loc) \
1178 [repeatable] \
1179 [source_annotation_attribute( loc )] \
1180 struct name##Attribute { name##Attribute(); const char* ignored; };
1181#else
1182#define SA(x) SA_##x
1183#define DECL_SA(name,loc) \
1184 [source_annotation_attribute( loc )] \
1185 struct name { const char* ignored; };\
1186 typedef struct name name;
1187#endif /* #endif __cplusplus */
1188DECL_SA(OnParameterOnly,SA(Parameter));
1189DECL_SA(OnReturnOnly,SA(ReturnValue));
1190DECL_SA(OnFunctionOnly,SA(Method));
1191DECL_SA(OnStructOnly,SA(Struct));
1192DECL_SA(OnFieldOnly,SA(Field));
1193DECL_SA(OnParameterOrReturnOnly,SA(Parameter) | SA(ReturnValue));
1194#pragma pop_macro( "SA" )
1195#pragma pop_macro( "DECL_SA" )
1196#endif
1197#endif
1198#endif