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 */ 1188 DECL_SA(OnParameterOnly,SA(Parameter)); 1189 DECL_SA(OnReturnOnly,SA(ReturnValue)); 1190 DECL_SA(OnFunctionOnly,SA(Method)); 1191 DECL_SA(OnStructOnly,SA(Struct)); 1192 DECL_SA(OnFieldOnly,SA(Field)); 1193 DECL_SA(OnParameterOrReturnOnly,SA(Parameter) | SA(ReturnValue)); 1194 #pragma pop_macro( "SA" ) 1195 #pragma pop_macro( "DECL_SA" ) 1196 #endif 1197 #endif 1198 #endif 1199