1 /*** 2 *sal.h - markers for documenting the semantics of APIs 3 * 4 * Copyright (c) Microsoft Corporation. All rights reserved. 5 * 6 *Purpose: 7 * sal.h provides a set of annotations to describe how a function uses its 8 * parameters - the assumptions it makes about them, and the guarantees it makes 9 * upon finishing. 10 * 11 * [Public] 12 * 13 ****/ 14 15 /* 16 ------------------------------------------------------------------------------- 17 Introduction 18 19 sal.h provides a set of annotations to describe how a function uses its 20 parameters - the assumptions it makes about them, and the guarantees it makes 21 upon finishing. 22 23 Annotations may be placed before either a function parameter's type or its return 24 type, and describe the function's behavior regarding the parameter or return value. 25 There are two classes of annotations: buffer annotations and advanced annotations. 26 Buffer annotations describe how functions use their pointer parameters, and 27 advanced annotations either describe complex/unusual buffer behavior, or provide 28 additional information about a parameter that is not otherwise expressible. 29 30 ------------------------------------------------------------------------------- 31 Buffer Annotations 32 33 The most important annotations in sal.h provide a consistent way to annotate 34 buffer parameters or return values for a function. Each of these annotations describes 35 a single buffer (which could be a string, a fixed-length or variable-length array, 36 or just a pointer) that the function interacts with: where it is, how large it is, 37 how much is initialized, and what the function does with it. 38 39 The appropriate macro for a given buffer can be constructed using the table below. 40 Just pick the appropriate values from each category, and combine them together 41 with a leading underscore. Some combinations of values do not make sense as buffer 42 annotations. Only meaningful annotations can be added to your code; for a list of 43 these, see the buffer annotation definitions section. 44 45 Only a single buffer annotation should be used for each parameter. 46 47 |------------|------------|---------|--------|----------|----------|---------------| 48 | Level | Usage | Size | Output | NullTerm | Optional | Parameters | 49 |------------|------------|---------|--------|----------|----------|---------------| 50 | <> | <> | <> | <> | _z | <> | <> | 51 | _deref | _in | _ecount | _full | _nz | _opt | (size) | 52 | _deref_opt | _out | _bcount | _part | | | (size,length) | 53 | | _inout | | | | | | 54 | | | | | | | | 55 |------------|------------|---------|--------|----------|----------|---------------| 56 57 Level: Describes the buffer pointer's level of indirection from the parameter or 58 return value 'p'. 59 60 <> : p is the buffer pointer. 61 _deref : *p is the buffer pointer. p must not be NULL. 62 _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of 63 the annotation is ignored. 64 65 Usage: Describes how the function uses the buffer. 66 67 <> : The buffer is not accessed. If used on the return value or with _deref, the 68 function will provide the buffer, and it will be uninitialized at exit. 69 Otherwise, the caller must provide the buffer. This should only be used 70 for alloc and free functions. 71 _in : The function will only read from the buffer. The caller must provide the 72 buffer and initialize it. Cannot be used with _deref. 73 _out : The function will only write to the buffer. If used on the return value or 74 with _deref, the function will provide the buffer and initialize it. 75 Otherwise, the caller must provide the buffer, and the function will 76 initialize it. 77 _inout : The function may freely read from and write to the buffer. The caller must 78 provide the buffer and initialize it. If used with _deref, the buffer may 79 be reallocated by the function. 80 81 Size: Describes the total size of the buffer. This may be less than the space actually 82 allocated for the buffer, in which case it describes the accessible amount. 83 84 <> : No buffer size is given. If the type specifies the buffer size (such as 85 with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one 86 element long. Must be used with _in, _out, or _inout. 87 _ecount : The buffer size is an explicit element count. 88 _bcount : The buffer size is an explicit byte count. 89 90 Output: Describes how much of the buffer will be initialized by the function. For 91 _inout buffers, this also describes how much is initialized at entry. Omit this 92 category for _in buffers; they must be fully initialized by the caller. 93 94 <> : The type specifies how much is initialized. For instance, a function initializing 95 an LPWSTR must NULL-terminate the string. 96 _full : The function initializes the entire buffer. 97 _part : The function initializes part of the buffer, and explicitly indicates how much. 98 99 NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer. 100 _z : A '\0' indicated the end of the buffer 101 _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the 102 buffer. 103 Optional: Describes if the buffer itself is optional. 104 105 <> : The pointer to the buffer must not be NULL. 106 _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced. 107 108 Parameters: Gives explicit counts for the size and length of the buffer. 109 110 <> : There is no explicit count. Use when neither _ecount nor _bcount is used. 111 (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part. 112 (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part 113 and _bcount_part. 114 115 ------------------------------------------------------------------------------- 116 Buffer Annotation Examples 117 118 LWSTDAPI_(BOOL) StrToIntExA( 119 LPCSTR pszString, -- No annotation required, const implies __in. 120 DWORD dwFlags, 121 __out int *piRet -- A pointer whose dereference will be filled in. 122 ); 123 124 void MyPaintingFunction( 125 __in HWND hwndControl, -- An initialized read-only parameter. 126 __in_opt HDC hdcOptional, -- An initialized read-only parameter that might be NULL. 127 __inout IPropertyStore *ppsStore -- An initialized parameter that may be freely used 128 -- and modified. 129 ); 130 131 LWSTDAPI_(BOOL) PathCompactPathExA( 132 __out_ecount(cchMax) LPSTR pszOut, -- A string buffer with cch elements that will 133 -- be NULL terminated on exit. 134 LPCSTR pszSrc, -- No annotation required, const implies __in. 135 UINT cchMax, 136 DWORD dwFlags 137 ); 138 139 HRESULT SHLocalAllocBytes( 140 size_t cb, 141 __deref_bcount(cb) T **ppv -- A pointer whose dereference will be set to an 142 -- uninitialized buffer with cb bytes. 143 ); 144 145 __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at 146 entry and exit, and may be written to by this function. 147 148 __out_ecount_part(count, *countOut) : A buffer with count elements that will be 149 partially initialized by this function. The function indicates how much it 150 initialized by setting *countOut. 151 152 ------------------------------------------------------------------------------- 153 Advanced Annotations 154 155 Advanced annotations describe behavior that is not expressible with the regular 156 buffer macros. These may be used either to annotate buffer parameters that involve 157 complex or conditional behavior, or to enrich existing annotations with additional 158 information. 159 160 __success(expr) f : 161 <expr> indicates whether function f succeeded or not. If <expr> is true at exit, 162 all the function's guarantees (as given by other annotations) must hold. If <expr> 163 is false at exit, the caller should not expect any of the function's guarantees 164 to hold. If not used, the function must always satisfy its guarantees. Added 165 automatically to functions that indicate success in standard ways, such as by 166 returning an HRESULT. 167 168 __nullterminated p : 169 Pointer p is a buffer that may be read or written up to and including the first 170 NULL character or pointer. May be used on typedefs, which marks valid (properly 171 initialized) instances of that type as being NULL-terminated. 172 173 __nullnullterminated p : 174 Pointer p is a buffer that may be read or written up to and including the first 175 sequence of two NULL characters or pointers. May be used on typedefs, which marks 176 valid instances of that type as being double-NULL terminated. 177 178 __reserved v : 179 Value v must be 0/NULL, reserved for future use. 180 181 __checkReturn v : 182 Return value v must not be ignored by callers of this function. 183 184 __typefix(ctype) v : 185 Value v should be treated as an instance of ctype, rather than its declared type. 186 187 __override f : 188 Specify C#-style 'override' behaviour for overriding virtual methods. 189 190 __callback f : 191 Function f can be used as a function pointer. 192 193 __format_string p : 194 Pointer p is a string that contains % markers in the style of printf. 195 196 __blocksOn(resource) f : 197 Function f blocks on the resource 'resource'. 198 199 __fallthrough : 200 Annotates switch statement labels where fall-through is desired, to distinguish 201 from forgotten break statements. 202 203 ------------------------------------------------------------------------------- 204 Advanced Annotation Examples 205 206 __success(return == TRUE) LWSTDAPI_(BOOL) 207 PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : 208 pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. 209 210 typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. 211 212 __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be 213 a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. 214 215 ------------------------------------------------------------------------------- 216 */ 217 218 #pragma once 219 220 #define __specstrings 221 222 #ifdef __cplusplus 223 #ifndef __nothrow 224 # define __nothrow __declspec(nothrow) 225 #endif 226 extern "C" { 227 #else 228 #ifndef __nothrow 229 # define __nothrow 230 #endif 231 #endif /* #ifdef __cplusplus */ 232 233 /* 234 ------------------------------------------------------------------------------- 235 Helper Macro Definitions 236 237 These express behavior common to many of the high-level annotations. 238 DO NOT USE THESE IN YOUR CODE. 239 ------------------------------------------------------------------------------- 240 */ 241 242 /* 243 The helper annotations are only understood by the compiler version used by various 244 defect detection tools. When the regular compiler is running, they are defined into 245 nothing, and do not affect the compiled code. 246 */ 247 248 #if !defined(__midl) && defined(_PREFAST_) 249 250 /* 251 In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard 252 Annotation Language. These __declspec("SAL_*") annotations are the 253 primitives the compiler understands and all high-level SpecString MACROs 254 will decompose into these primivates. 255 */ 256 257 #define SPECSTRINGIZE( x ) #x 258 259 /* 260 __null p 261 __notnull p 262 __maybenull p 263 264 Annotates a pointer p. States that pointer p is null. Commonly used 265 in the negated form __notnull or the possibly null form __maybenull. 266 */ 267 268 #define __null __declspec("SAL_null") 269 #define __notnull __declspec("SAL_notnull") 270 #define __maybenull __declspec("SAL_maybenull") 271 272 /* 273 __readonly l 274 __notreadonly l 275 __mabyereadonly l 276 277 Annotates a location l. States that location l is not modified after 278 this point. If the annotation is placed on the precondition state of 279 a function, the restriction only applies until the postcondition state 280 of the function. __maybereadonly states that the annotated location 281 may be modified, whereas __notreadonly states that a location must be 282 modified. 283 */ 284 285 #define __readonly __declspec("SAL_readonly") 286 #define __notreadonly __declspec("SAL_notreadonly") 287 #define __maybereadonly __declspec("SAL_maybereadonly") 288 289 /* 290 __valid v 291 __notvalid v 292 __maybevalid v 293 294 Annotates any value v. States that the value satisfies all properties of 295 valid values of its type. For example, for a string buffer, valid means 296 that the buffer pointer is either NULL or points to a NULL-terminated string. 297 */ 298 299 #define __valid __declspec("SAL_valid") 300 #define __notvalid __declspec("SAL_notvalid") 301 #define __maybevalid __declspec("SAL_maybevalid") 302 303 /* 304 __readableTo(extent) p 305 306 Annotates a buffer pointer p. If the buffer can be read, extent describes 307 how much of the buffer is readable. For a reader of the buffer, this is 308 an explicit permission to read up to that amount, rather than a restriction to 309 read only up to it. 310 */ 311 312 #define __readableTo(extent) __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")") 313 314 /* 315 316 __elem_readableTo(size) 317 318 Annotates a buffer pointer p as being readable to size elements. 319 */ 320 321 #define __elem_readableTo(size) __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))") 322 323 /* 324 __byte_readableTo(size) 325 326 Annotates a buffer pointer p as being readable to size bytes. 327 */ 328 #define __byte_readableTo(size) __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))") 329 330 /* 331 __writableTo(extent) p 332 333 Annotates a buffer pointer p. If the buffer can be modified, extent 334 describes how much of the buffer is writable (usually the allocation 335 size). For a writer of the buffer, this is an explicit permission to 336 write up to that amount, rather than a restriction to write only up to it. 337 */ 338 #define __writableTo(size) __declspec("SAL_writableTo("SPECSTRINGIZE(size)")") 339 340 /* 341 __elem_writableTo(size) 342 343 Annotates a buffer pointer p as being writable to size elements. 344 */ 345 #define __elem_writableTo(size) __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))") 346 347 /* 348 __byte_writableTo(size) 349 350 Annotates a buffer pointer p as being writable to size bytes. 351 */ 352 #define __byte_writableTo(size) __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))") 353 354 /* 355 __deref p 356 357 Annotates a pointer p. The next annotation applies one dereference down 358 in the type. If readableTo(p, size) then the next annotation applies to 359 all elements *(p+i) for which i satisfies the size. If p is a pointer 360 to a struct, the next annotation applies to all fields of the struct. 361 */ 362 #define __deref __declspec("SAL_deref") 363 364 /* 365 __pre __next_annotation 366 367 The next annotation applies in the precondition state 368 */ 369 #define __pre __declspec("SAL_pre") 370 371 /* 372 __post __next_annotation 373 374 The next annotation applies in the postcondition state 375 */ 376 #define __post __declspec("SAL_post") 377 378 /* 379 __precond(<expr>) 380 381 When <expr> is true, the next annotation applies in the precondition state 382 (currently not enabled) 383 */ 384 #define __precond(expr) __pre 385 386 /* 387 __postcond(<expr>) 388 389 When <expr> is true, the next annotation applies in the postcondition state 390 (currently not enabled) 391 */ 392 #define __postcond(expr) __post 393 394 /* 395 __exceptthat 396 397 Given a set of annotations Q containing __exceptthat maybeP, the effect of 398 the except clause is to erase any P or notP annotations (explicit or 399 implied) within Q at the same level of dereferencing that the except 400 clause appears, and to replace it with maybeP. 401 402 Example 1: __valid __exceptthat __maybenull on a pointer p means that the 403 pointer may be null, and is otherwise valid, thus overriding 404 the implicit notnull annotation implied by __valid on 405 pointers. 406 407 Example 2: __valid __deref __exceptthat __maybenull on an int **p means 408 that p is not null (implied by valid), but the elements 409 pointed to by p could be null, and are otherwise valid. 410 */ 411 #define __exceptthat __declspec("SAL_except") 412 #define __execeptthat __exceptthat 413 414 /* 415 _refparam 416 417 Added to all out parameter macros to indicate that they are all reference 418 parameters. 419 */ 420 #define __refparam __deref __notreadonly 421 422 /* 423 __inner_* 424 425 Helper macros that directly correspond to certain high-level annotations. 426 427 */ 428 429 /* 430 Macros to classify the entrypoints and indicate their category. 431 432 Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM. 433 434 */ 435 #define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")") 436 437 /* 438 Pre-defined data entry point categories include: Registry, File, Network. 439 */ 440 #define __inner_data_entrypoint(category) __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")") 441 442 #define __inner_success(expr) __declspec("SAL_success("SPECSTRINGIZE(expr)")") 443 #define __inner_checkReturn __declspec("SAL_checkReturn") 444 #define __inner_typefix(ctype) __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")") 445 #define __inner_override __declspec("__override") 446 #define __inner_callback __declspec("__callback") 447 #define __inner_blocksOn(resource) __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")") 448 #define __inner_fallthrough_dec __inline __nothrow void __FallThrough() {} 449 #define __inner_fallthrough __FallThrough(); 450 451 #else 452 #define __null 453 #define __notnull 454 #define __maybenull 455 #define __readonly 456 #define __notreadonly 457 #define __maybereadonly 458 #define __valid 459 #define __notvalid 460 #define __maybevalid 461 #define __readableTo(extent) 462 #define __elem_readableTo(size) 463 #define __byte_readableTo(size) 464 #define __writableTo(size) 465 #define __elem_writableTo(size) 466 #define __byte_writableTo(size) 467 #define __deref 468 #define __pre 469 #define __post 470 #define __precond(expr) 471 #define __postcond(expr) 472 #define __exceptthat 473 #define __execeptthat 474 #define __inner_success(expr) 475 #define __inner_checkReturn 476 #define __inner_typefix(ctype) 477 #define __inner_override 478 #define __inner_callback 479 #define __inner_blocksOn(resource) 480 #define __inner_fallthrough_dec 481 #define __inner_fallthrough 482 #define __refparam 483 #define __inner_control_entrypoint(category) 484 #define __inner_data_entrypoint(category) 485 #endif /* #if !defined(__midl) && defined(_PREFAST_) */ 486 487 /* 488 ------------------------------------------------------------------------------- 489 Buffer Annotation Definitions 490 491 Any of these may be used to directly annotate functions, but only one should 492 be used for each parameter. To determine which annotation to use for a given 493 buffer, use the table in the buffer annotations section. 494 ------------------------------------------------------------------------------- 495 */ 496 497 #define __ecount(size) __notnull __elem_writableTo(size) 498 #define __bcount(size) __notnull __byte_writableTo(size) 499 #define __in __pre __valid __pre __deref __readonly 500 #define __in_ecount(size) __in __pre __elem_readableTo(size) 501 #define __in_bcount(size) __in __pre __byte_readableTo(size) 502 #define __in_z __in __pre __nullterminated 503 #define __in_ecount_z(size) __in_ecount(size) __pre __nullterminated 504 #define __in_bcount_z(size) __in_bcount(size) __pre __nullterminated 505 #define __in_nz __in 506 #define __in_ecount_nz(size) __in_ecount(size) 507 #define __in_bcount_nz(size) __in_bcount(size) 508 #define __out __ecount(1) __post __valid __refparam 509 #define __out_ecount(size) __ecount(size) __post __valid __refparam 510 #define __out_bcount(size) __bcount(size) __post __valid __refparam 511 #define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length) 512 #define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length) 513 #define __out_ecount_full(size) __out_ecount_part(size,size) 514 #define __out_bcount_full(size) __out_bcount_part(size,size) 515 #define __out_z __post __valid __refparam __post __nullterminated 516 #define __out_z_opt __post __valid __refparam __post __nullterminated __exceptthat __maybenull 517 #define __out_ecount_z(size) __ecount(size) __post __valid __refparam __post __nullterminated 518 #define __out_bcount_z(size) __bcount(size) __post __valid __refparam __post __nullterminated 519 #define __out_ecount_part_z(size,length) __out_ecount_part(size,length) __post __nullterminated 520 #define __out_bcount_part_z(size,length) __out_bcount_part(size,length) __post __nullterminated 521 #define __out_ecount_full_z(size) __out_ecount_full(size) __post __nullterminated 522 #define __out_bcount_full_z(size) __out_bcount_full(size) __post __nullterminated 523 #define __out_nz __post __valid __refparam __post 524 #define __out_nz_opt __post __valid __refparam __post __exceptthat __maybenull 525 #define __out_ecount_nz(size) __ecount(size) __post __valid __refparam 526 #define __out_bcount_nz(size) __bcount(size) __post __valid __refparam 527 #define __inout __pre __valid __post __valid __refparam 528 #define __inout_ecount(size) __out_ecount(size) __pre __valid 529 #define __inout_bcount(size) __out_bcount(size) __pre __valid 530 #define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length) 531 #define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length) 532 #define __inout_ecount_full(size) __inout_ecount_part(size,size) 533 #define __inout_bcount_full(size) __inout_bcount_part(size,size) 534 #define __inout_z __inout __pre __nullterminated __post __nullterminated 535 #define __inout_ecount_z(size) __inout_ecount(size) __pre __nullterminated __post __nullterminated 536 #define __inout_bcount_z(size) __inout_bcount(size) __pre __nullterminated __post __nullterminated 537 #define __inout_nz __inout 538 #define __inout_ecount_nz(size) __inout_ecount(size) 539 #define __inout_bcount_nz(size) __inout_bcount(size) 540 #define __ecount_opt(size) __ecount(size) __exceptthat __maybenull 541 #define __bcount_opt(size) __bcount(size) __exceptthat __maybenull 542 #define __in_opt __in __exceptthat __maybenull 543 #define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull 544 #define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull 545 #define __in_z_opt __in_opt __pre __nullterminated 546 #define __in_ecount_z_opt(size) __in_ecount_opt(size) __pre __nullterminated 547 #define __in_bcount_z_opt(size) __in_bcount_opt(size) __pre __nullterminated 548 #define __in_nz_opt __in_opt 549 #define __in_ecount_nz_opt(size) __in_ecount_opt(size) 550 #define __in_bcount_nz_opt(size) __in_bcount_opt(size) 551 #define __out_opt __out __exceptthat __maybenull 552 #define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull 553 #define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull 554 #define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull 555 #define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull 556 #define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull 557 #define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull 558 #define __out_ecount_z_opt(size) __out_ecount_opt(size) __post __nullterminated 559 #define __out_bcount_z_opt(size) __out_bcount_opt(size) __post __nullterminated 560 #define __out_ecount_part_z_opt(size,length) __out_ecount_part_opt(size,length) __post __nullterminated 561 #define __out_bcount_part_z_opt(size,length) __out_bcount_part_opt(size,length) __post __nullterminated 562 #define __out_ecount_full_z_opt(size) __out_ecount_full_opt(size) __post __nullterminated 563 #define __out_bcount_full_z_opt(size) __out_bcount_full_opt(size) __post __nullterminated 564 #define __out_ecount_nz_opt(size) __out_ecount_opt(size) __post __nullterminated 565 #define __out_bcount_nz_opt(size) __out_bcount_opt(size) __post __nullterminated 566 #define __inout_opt __inout __exceptthat __maybenull 567 #define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull 568 #define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull 569 #define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull 570 #define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull 571 #define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull 572 #define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull 573 #define __inout_z_opt __inout_opt __pre __nullterminated __post __nullterminated 574 #define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated 575 #define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated 576 #define __inout_bcount_z_opt(size) __inout_bcount_opt(size) 577 #define __inout_nz_opt __inout_opt 578 #define __inout_ecount_nz_opt(size) __inout_ecount_opt(size) 579 #define __inout_bcount_nz_opt(size) __inout_bcount_opt(size) 580 #define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size) 581 #define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size) 582 #define __deref_out __deref_ecount(1) __post __deref __valid __refparam 583 #define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam 584 #define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam 585 #define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length) 586 #define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length) 587 #define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size) 588 #define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size) 589 #define __deref_out_z __post __deref __valid __refparam __post __deref __nullterminated 590 #define __deref_out_ecount_z(size) __deref_out_ecount(size) __post __deref __nullterminated 591 #define __deref_out_bcount_z(size) __deref_out_ecount(size) __post __deref __nullterminated 592 #define __deref_out_nz __deref_out 593 #define __deref_out_ecount_nz(size) __deref_out_ecount(size) 594 #define __deref_out_bcount_nz(size) __deref_out_ecount(size) 595 #define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam 596 #define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated 597 #define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size) 598 #define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size) 599 #define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length) 600 #define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length) 601 #define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size) 602 #define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size) 603 #define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated 604 #define __deref_inout_ecount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated 605 #define __deref_inout_bcount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated 606 #define __deref_inout_nz __deref_inout 607 #define __deref_inout_ecount_nz(size) __deref_inout_ecount(size) 608 #define __deref_inout_bcount_nz(size) __deref_inout_ecount(size) 609 #define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull 610 #define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull 611 #define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull 612 #define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull 613 #define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull 614 #define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull 615 #define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull 616 #define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull 617 #define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull 618 #define __deref_out_z_opt __post __deref __valid __refparam __execeptthat __maybenull __post __deref __nullterminated 619 #define __deref_out_ecount_z_opt(size) __deref_out_ecount_opt(size) __post __deref __nullterminated 620 #define __deref_out_bcount_z_opt(size) __deref_out_bcount_opt(size) __post __deref __nullterminated 621 #define __deref_out_nz_opt __deref_out_opt 622 #define __deref_out_ecount_nz_opt(size) __deref_out_ecount_opt(size) 623 #define __deref_out_bcount_nz_opt(size) __deref_out_bcount_opt(size) 624 #define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 625 #define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 626 #define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 627 #define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 628 #define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 629 #define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 630 #define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 631 #define __deref_inout_z_opt __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated 632 #define __deref_inout_ecount_z_opt(size) __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated 633 #define __deref_inout_bcount_z_opt(size) __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated 634 #define __deref_inout_nz_opt __deref_inout_opt 635 #define __deref_inout_ecount_nz_opt(size) __deref_inout_ecount_opt(size) 636 #define __deref_inout_bcount_nz_opt(size) __deref_inout_bcount_opt(size) 637 #define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull 638 #define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull 639 #define __deref_opt_out __deref_out __exceptthat __maybenull 640 #define __deref_opt_out_z __deref_opt_out __post __deref __nullterminated 641 #define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull 642 #define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull 643 #define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull 644 #define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull 645 #define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull 646 #define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull 647 #define __deref_opt_inout __deref_inout __exceptthat __maybenull 648 #define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull 649 #define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull 650 #define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull 651 #define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull 652 #define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull 653 #define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull 654 #define __deref_opt_inout_z __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated 655 #define __deref_opt_inout_ecount_z(size) __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated 656 #define __deref_opt_inout_bcount_z(size) __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated 657 #define __deref_opt_inout_nz __deref_opt_inout 658 #define __deref_opt_inout_ecount_nz(size) __deref_opt_inout_ecount(size) 659 #define __deref_opt_inout_bcount_nz(size) __deref_opt_inout_bcount(size) 660 #define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull 661 #define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull 662 #define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull 663 #define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull 664 #define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull 665 #define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull 666 #define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull 667 #define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull 668 #define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull 669 #define __deref_opt_out_z_opt __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated 670 #define __deref_opt_out_ecount_z_opt(size) __deref_opt_out_ecount_opt(size) __post __deref __nullterminated 671 #define __deref_opt_out_bcount_z_opt(size) __deref_opt_out_bcount_opt(size) __post __deref __nullterminated 672 #define __deref_opt_out_nz_opt __deref_opt_out_opt 673 #define __deref_opt_out_ecount_nz_opt(size) __deref_opt_out_ecount_opt(size) 674 #define __deref_opt_out_bcount_nz_opt(size) __deref_opt_out_bcount_opt(size) 675 #define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull 676 #define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull 677 #define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull 678 #define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull 679 #define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull 680 #define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull 681 #define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull 682 #define __deref_opt_inout_z_opt __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated 683 #define __deref_opt_inout_ecount_z_opt(size) __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated 684 #define __deref_opt_inout_bcount_z_opt(size) __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated 685 #define __deref_opt_inout_nz_opt __deref_opt_inout_opt 686 #define __deref_opt_inout_ecount_nz_opt(size) __deref_opt_inout_ecount_opt(size) 687 #define __deref_opt_inout_bcount_nz_opt(size) __deref_opt_inout_bcount_opt(size) 688 689 /* 690 ------------------------------------------------------------------------------- 691 Advanced Annotation Definitions 692 693 Any of these may be used to directly annotate functions, and may be used in 694 combination with each other or with regular buffer macros. For an explanation 695 of each annotation, see the advanced annotations section. 696 ------------------------------------------------------------------------------- 697 */ 698 699 #define __success(expr) __inner_success(expr) 700 #define __nullterminated __readableTo(sentinel(0)) 701 #define __nullnullterminated 702 #define __reserved __pre __null 703 #define __checkReturn __inner_checkReturn 704 #define __typefix(ctype) __inner_typefix(ctype) 705 #define __override __inner_override 706 #define __callback __inner_callback 707 #define __format_string 708 #define __blocksOn(resource) __inner_blocksOn(resource) 709 #define __control_entrypoint(category) __inner_control_entrypoint(category) 710 #define __data_entrypoint(category) __inner_data_entrypoint(category) 711 712 #ifndef __fallthrough 713 __inner_fallthrough_dec 714 #define __fallthrough __inner_fallthrough 715 #endif 716 717 #ifndef __analysis_assume 718 #ifdef _PREFAST_ 719 #define __analysis_assume(expr) __assume(expr) 720 #else 721 #define __analysis_assume(expr) 722 #endif 723 #endif 724 725 #ifdef __cplusplus 726 } 727 #endif 728 729 730
