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