1 /* 2 * PROJECT: ReactOS PSDK 3 * LICENSE: MIT (https://spdx.org/licenses/MIT) 4 * PURPOSE: Standard Annotation Language (SAL) definitions 5 * COPYRIGHT: Microsoft Corporation. 6 * SOURCE: https://github.com/microsoft/ChakraCore/blob/master/pal/inc/rt/sal.h 7 */ 8 // ------------------------------------------------------------ 9 // Copyright (c) Microsoft Corporation. All rights reserved. 10 // Licensed under the MIT License (MIT). See License.txt in the repo root for license information. 11 // ------------------------------------------------------------ 12 13 /*** 14 *sal.h - markers for documenting the semantics of APIs 15 * 16 17 * 18 *Purpose: 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 #pragma once 24 25 /*========================================================================== 26 27 The comments in this file are intended to give basic understanding of 28 the usage of SAL, the Microsoft Source Code Annotation Language. 29 For more details, please see https://go.microsoft.com/fwlink/?LinkID=242134 30 31 The macros are defined in 3 layers, plus the structural set: 32 33 _In_/_Out_/_Ret_ Layer: 34 ---------------------- 35 This layer provides the highest abstraction and its macros should be used 36 in most cases. These macros typically start with: 37 _In_ : input parameter to a function, unmodified by called function 38 _Out_ : output parameter, written to by called function, pointed-to 39 location not expected to be initialized prior to call 40 _Outptr_ : like _Out_ when returned variable is a pointer type 41 (so param is pointer-to-pointer type). Called function 42 provides/allocated space. 43 _Outref_ : like _Outptr_, except param is reference-to-pointer type. 44 _Inout_ : inout parameter, read from and potentially modified by 45 called function. 46 _Ret_ : for return values 47 _Field_ : class/struct field invariants 48 For common usage, this class of SAL provides the most concise annotations. 49 Note that _In_/_Out_/_Inout_/_Outptr_ annotations are designed to be used 50 with a parameter target. Using them with _At_ to specify non-parameter 51 targets may yield unexpected results. 52 53 This layer also includes a number of other properties that can be specified 54 to extend the ability of code analysis, most notably: 55 -- Designating parameters as format strings for printf/scanf/scanf_s 56 -- Requesting stricter type checking for C enum parameters 57 58 _Pre_/_Post_ Layer: 59 ------------------ 60 The macros of this layer only should be used when there is no suitable macro 61 in the _In_/_Out_ layer. Its macros start with _Pre_ or _Post_. 62 This layer provides the most flexibility for annotations. 63 64 Implementation Abstraction Layer: 65 -------------------------------- 66 Macros from this layer should never be used directly. The layer only exists 67 to hide the implementation of the annotation macros. 68 69 Structural Layer: 70 ---------------- 71 These annotations, like _At_ and _When_, are used with annotations from 72 any of the other layers as modifiers, indicating exactly when and where 73 the annotations apply. 74 75 76 Common syntactic conventions: 77 ---------------------------- 78 79 Usage: 80 ----- 81 _In_, _Out_, _Inout_, _Pre_, _Post_, are for formal parameters. 82 _Ret_, _Deref_ret_ must be used for return values. 83 84 Nullness: 85 -------- 86 If the parameter can be NULL as a precondition to the function, the 87 annotation contains _opt. If the macro does not contain '_opt' the 88 parameter cannot be NULL. 89 90 If an out/inout parameter returns a null pointer as a postcondition, this is 91 indicated by _Ret_maybenull_ or _result_maybenull_. If the macro is not 92 of this form, then the result will not be NULL as a postcondition. 93 _Outptr_ - output value is not NULL 94 _Outptr_result_maybenull_ - output value might be NULL 95 96 String Type: 97 ----------- 98 _z: NullTerminated string 99 for _In_ parameters the buffer must have the specified stringtype before the call 100 for _Out_ parameters the buffer must have the specified stringtype after the call 101 for _Inout_ parameters both conditions apply 102 103 Extent Syntax: 104 ------------- 105 Buffer sizes are expressed as element counts, unless the macro explicitly 106 contains _byte_ or _bytes_. Some annotations specify two buffer sizes, in 107 which case the second is used to indicate how much of the buffer is valid 108 as a postcondition. This table outlines the precondition buffer allocation 109 size, precondition number of valid elements, postcondition allocation size, 110 and postcondition number of valid elements for representative buffer size 111 annotations: 112 Pre | Pre | Post | Post 113 alloc | valid | alloc | valid 114 Annotation elems | elems | elems | elems 115 ---------- ------------------------------------ 116 _In_reads_(s) s | s | s | s 117 _Inout_updates_(s) s | s | s | s 118 _Inout_updates_to_(s,c) s | s | s | c 119 _Out_writes_(s) s | 0 | s | s 120 _Out_writes_to_(s,c) s | 0 | s | c 121 _Outptr_result_buffer_(s) ? | ? | s | s 122 _Outptr_result_buffer_to_(s,c) ? | ? | s | c 123 124 For the _Outptr_ annotations, the buffer in question is at one level of 125 dereference. The called function is responsible for supplying the buffer. 126 127 Success and failure: 128 ------------------- 129 The SAL concept of success allows functions to define expressions that can 130 be tested by the caller, which if it evaluates to non-zero, indicates the 131 function succeeded, which means that its postconditions are guaranteed to 132 hold. Otherwise, if the expression evaluates to zero, the function is 133 considered to have failed, and the postconditions are not guaranteed. 134 135 The success criteria can be specified with the _Success_(expr) annotation: 136 _Success_(return != FALSE) BOOL 137 PathCanonicalizeA(_Out_writes_(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : 138 pszBuf is only guaranteed to be NULL-terminated when TRUE is returned, 139 and FALSE indiates failure. In common practice, callers check for zero 140 vs. non-zero returns, so it is preferable to express the success 141 criteria in terms of zero/non-zero, not checked for exactly TRUE. 142 143 Functions can specify that some postconditions will still hold, even when 144 the function fails, using _On_failure_(anno-list), or postconditions that 145 hold regardless of success or failure using _Always_(anno-list). 146 147 The annotation _Return_type_success_(expr) may be used with a typedef to 148 give a default _Success_ criteria to all functions returning that type. 149 This is the case for common Windows API status types, including 150 HRESULT and NTSTATUS. This may be overridden on a per-function basis by 151 specifying a _Success_ annotation locally. 152 153 ============================================================================*/ 154 155 #define __ATTR_SAL 156 157 #ifndef _SAL_VERSION /*IFSTRIP=IGN*/ 158 #define _SAL_VERSION 20 159 #endif 160 161 #ifdef _PREFAST_ // [ 162 163 // choose attribute or __declspec implementation 164 #ifndef _USE_DECLSPECS_FOR_SAL // [ 165 #define _USE_DECLSPECS_FOR_SAL 1 166 #endif // ] 167 168 #if _USE_DECLSPECS_FOR_SAL // [ 169 #undef _USE_ATTRIBUTES_FOR_SAL 170 #define _USE_ATTRIBUTES_FOR_SAL 0 171 #elif !defined(_USE_ATTRIBUTES_FOR_SAL) // ][ 172 #if _MSC_VER >= 1400 /*IFSTRIP=IGN*/ // [ 173 #define _USE_ATTRIBUTES_FOR_SAL 1 174 #else // ][ 175 #define _USE_ATTRIBUTES_FOR_SAL 0 176 #endif // ] 177 #endif // ] 178 179 180 #if !_USE_DECLSPECS_FOR_SAL // [ 181 #if !_USE_ATTRIBUTES_FOR_SAL // [ 182 #if _MSC_VER >= 1400 /*IFSTRIP=IGN*/ // [ 183 #undef _USE_ATTRIBUTES_FOR_SAL 184 #define _USE_ATTRIBUTES_FOR_SAL 1 185 #else // ][ 186 #undef _USE_DECLSPECS_FOR_SAL 187 #define _USE_DECLSPECS_FOR_SAL 1 188 #endif // ] 189 #endif // ] 190 #endif // ] 191 192 #else 193 194 // Disable expansion of SAL macros in non-Prefast mode to 195 // improve compiler throughput. 196 #ifndef _USE_DECLSPECS_FOR_SAL // [ 197 #define _USE_DECLSPECS_FOR_SAL 0 198 #endif // ] 199 #ifndef _USE_ATTRIBUTES_FOR_SAL // [ 200 #define _USE_ATTRIBUTES_FOR_SAL 0 201 #endif // ] 202 203 #endif // ] 204 205 // safeguard for MIDL and RC builds 206 #if _USE_DECLSPECS_FOR_SAL && ( defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) || !defined(_PREFAST_) ) /*IFSTRIP=IGN*/ // [ 207 #undef _USE_DECLSPECS_FOR_SAL 208 #define _USE_DECLSPECS_FOR_SAL 0 209 #endif // ] 210 #if _USE_ATTRIBUTES_FOR_SAL && ( !defined(_MSC_EXTENSIONS) || defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) ) /*IFSTRIP=IGN*/ // [ 211 #undef _USE_ATTRIBUTES_FOR_SAL 212 #define _USE_ATTRIBUTES_FOR_SAL 0 213 #endif // ] 214 215 #if _USE_DECLSPECS_FOR_SAL || _USE_ATTRIBUTES_FOR_SAL 216 217 // Special enum type for Y/N/M 218 enum __SAL_YesNo {_SAL_notpresent, _SAL_no, _SAL_maybe, _SAL_yes, _SAL_default}; 219 220 #endif 221 222 #if defined(BUILD_WINDOWS) && !_USE_ATTRIBUTES_FOR_SAL /*IFSTRIP=IGN*/ 223 #define _SAL1_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1") _GrouP_(annotes _SAL_nop_impl_) 224 #define _SAL1_1_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1.1") _GrouP_(annotes _SAL_nop_impl_) 225 #define _SAL1_2_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1.2") _GrouP_(annotes _SAL_nop_impl_) 226 #define _SAL2_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "2") _GrouP_(annotes _SAL_nop_impl_) 227 #else 228 #define _SAL1_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1") _Group_(annotes _SAL_nop_impl_) 229 #define _SAL1_1_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1.1") _Group_(annotes _SAL_nop_impl_) 230 #define _SAL1_2_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "1.2") _Group_(annotes _SAL_nop_impl_) 231 #define _SAL2_Source_(Name, args, annotes) _SA_annotes3(SAL_name, #Name, "", "2") _Group_(annotes _SAL_nop_impl_) 232 #endif 233 234 //============================================================================ 235 // Structural SAL: 236 // These annotations modify the use of other annotations. They may 237 // express the annotation target (i.e. what parameter/field the annotation 238 // applies to) or the condition under which the annotation is applicable. 239 //============================================================================ 240 241 // _At_(target, annos) specifies that the annotations listed in 'annos' is to 242 // be applied to 'target' rather than to the identifier which is the current 243 // lexical target. 244 #define _At_(target, annos) _At_impl_(target, annos _SAL_nop_impl_) 245 246 // _At_buffer_(target, iter, bound, annos) is similar to _At_, except that 247 // target names a buffer, and each annotation in annos is applied to each 248 // element of target up to bound, with the variable named in iter usable 249 // by the annotations to refer to relevant offsets within target. 250 #define _At_buffer_(target, iter, bound, annos) _At_buffer_impl_(target, iter, bound, annos _SAL_nop_impl_) 251 252 // _When_(expr, annos) specifies that the annotations listed in 'annos' only 253 // apply when 'expr' evaluates to non-zero. 254 #define _When_(expr, annos) _When_impl_(expr, annos _SAL_nop_impl_) 255 #define _Group_(annos) _Group_impl_(annos _SAL_nop_impl_) 256 #define _GrouP_(annos) _GrouP_impl_(annos _SAL_nop_impl_) 257 258 // <expr> indicates whether normal post conditions apply to a function 259 #define _Success_(expr) _SAL2_Source_(_Success_, (expr), _Success_impl_(expr)) 260 261 // <expr> indicates whether post conditions apply to a function returning 262 // the type that this annotation is applied to 263 #define _Return_type_success_(expr) _SAL2_Source_(_Return_type_success_, (expr), _Success_impl_(expr)) 264 265 // Establish postconditions that apply only if the function does not succeed 266 #define _On_failure_(annos) _On_failure_impl_(annos _SAL_nop_impl_) 267 268 // Establish postconditions that apply in both success and failure cases. 269 // Only applicable with functions that have _Success_ or _Return_type_succss_. 270 #define _Always_(annos) _Always_impl_(annos _SAL_nop_impl_) 271 272 // Usable on a function defintion. Asserts that a function declaration is 273 // in scope, and its annotations are to be used. There are no other annotations 274 // allowed on the function definition. 275 #define _Use_decl_annotations_ _Use_decl_anno_impl_ 276 277 // _Notref_ may precede a _Deref_ or "real" annotation, and removes one 278 // level of dereference if the parameter is a C++ reference (&). If the 279 // net deref on a "real" annotation is negative, it is simply discarded. 280 #define _Notref_ _Notref_impl_ 281 282 // Annotations for defensive programming styles. 283 #define _Pre_defensive_ _SA_annotes0(SAL_pre_defensive) 284 #define _Post_defensive_ _SA_annotes0(SAL_post_defensive) 285 286 #define _In_defensive_(annotes) _Pre_defensive_ _Group_(annotes) 287 #define _Out_defensive_(annotes) _Post_defensive_ _Group_(annotes) 288 #define _Inout_defensive_(annotes) _Pre_defensive_ _Post_defensive_ _Group_(annotes) 289 290 //============================================================================ 291 // _In_\_Out_ Layer: 292 //============================================================================ 293 294 // Reserved pointer parameters, must always be NULL. 295 #define _Reserved_ _SAL2_Source_(_Reserved_, (), _Pre1_impl_(__null_impl)) 296 297 // _Const_ allows specification that any namable memory location is considered 298 // readonly for a given call. 299 #define _Const_ _SAL2_Source_(_Const_, (), _Pre1_impl_(__readaccess_impl_notref)) 300 301 302 // Input parameters -------------------------- 303 304 // _In_ - Annotations for parameters where data is passed into the function, but not modified. 305 // _In_ by itself can be used with non-pointer types (although it is redundant). 306 307 // e.g. void SetPoint( _In_ const POINT* pPT ); 308 #define _In_ _SAL2_Source_(_In_, (), _Pre1_impl_(__notnull_impl_notref) _Pre_valid_impl_ _Deref_pre1_impl_(__readaccess_impl_notref)) 309 #define _In_opt_ _SAL2_Source_(_In_opt_, (), _Pre1_impl_(__maybenull_impl_notref) _Pre_valid_impl_ _Deref_pre_readonly_) 310 311 // nullterminated 'in' parameters. 312 // e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); 313 #define _In_z_ _SAL2_Source_(_In_z_, (), _In_ _Pre1_impl_(__zterm_impl)) 314 #define _In_opt_z_ _SAL2_Source_(_In_opt_z_, (), _In_opt_ _Pre1_impl_(__zterm_impl)) 315 316 317 // 'input' buffers with given size 318 319 #define _In_reads_(size) _SAL2_Source_(_In_reads_, (size), _Pre_count_(size) _Deref_pre_readonly_) 320 #define _In_reads_opt_(size) _SAL2_Source_(_In_reads_opt_, (size), _Pre_opt_count_(size) _Deref_pre_readonly_) 321 #define _In_reads_bytes_(size) _SAL2_Source_(_In_reads_bytes_, (size), _Pre_bytecount_(size) _Deref_pre_readonly_) 322 #define _In_reads_bytes_opt_(size) _SAL2_Source_(_In_reads_bytes_opt_, (size), _Pre_opt_bytecount_(size) _Deref_pre_readonly_) 323 #define _In_reads_z_(size) _SAL2_Source_(_In_reads_z_, (size), _In_reads_(size) _Pre_z_) 324 #define _In_reads_opt_z_(size) _SAL2_Source_(_In_reads_opt_z_, (size), _Pre_opt_count_(size) _Deref_pre_readonly_ _Pre_opt_z_) 325 #define _In_reads_or_z_(size) _SAL2_Source_(_In_reads_or_z_, (size), _In_ _When_(_String_length_(_Curr_) < (size), _Pre_z_) _When_(_String_length_(_Curr_) >= (size), _Pre1_impl_(__count_impl(size)))) 326 #define _In_reads_or_z_opt_(size) _SAL2_Source_(_In_reads_or_z_opt_, (size), _In_opt_ _When_(_String_length_(_Curr_) < (size), _Pre_z_) _When_(_String_length_(_Curr_) >= (size), _Pre1_impl_(__count_impl(size)))) 327 328 329 // 'input' buffers valid to the given end pointer 330 331 #define _In_reads_to_ptr_(ptr) _SAL2_Source_(_In_reads_to_ptr_, (ptr), _Pre_ptrdiff_count_(ptr) _Deref_pre_readonly_) 332 #define _In_reads_to_ptr_opt_(ptr) _SAL2_Source_(_In_reads_to_ptr_opt_, (ptr), _Pre_opt_ptrdiff_count_(ptr) _Deref_pre_readonly_) 333 #define _In_reads_to_ptr_z_(ptr) _SAL2_Source_(_In_reads_to_ptr_z_, (ptr), _In_reads_to_ptr_(ptr) _Pre_z_) 334 #define _In_reads_to_ptr_opt_z_(ptr) _SAL2_Source_(_In_reads_to_ptr_opt_z_, (ptr), _Pre_opt_ptrdiff_count_(ptr) _Deref_pre_readonly_ _Pre_opt_z_) 335 336 337 338 // Output parameters -------------------------- 339 340 // _Out_ - Annotations for pointer or reference parameters where data passed back to the caller. 341 // These are mostly used where the pointer/reference is to a non-pointer type. 342 // _Outptr_/_Outref) (see below) are typically used to return pointers via parameters. 343 344 // e.g. void GetPoint( _Out_ POINT* pPT ); 345 #define _Out_ _SAL2_Source_(_Out_, (), _Out_impl_) 346 #define _Out_opt_ _SAL2_Source_(_Out_opt_, (), _Out_opt_impl_) 347 348 #define _Out_writes_(size) _SAL2_Source_(_Out_writes_, (size), _Pre_cap_(size) _Post_valid_impl_) 349 #define _Out_writes_opt_(size) _SAL2_Source_(_Out_writes_opt_, (size), _Pre_opt_cap_(size) _Post_valid_impl_) 350 #define _Out_writes_bytes_(size) _SAL2_Source_(_Out_writes_bytes_, (size), _Pre_bytecap_(size) _Post_valid_impl_) 351 #define _Out_writes_bytes_opt_(size) _SAL2_Source_(_Out_writes_bytes_opt_, (size), _Pre_opt_bytecap_(size) _Post_valid_impl_) 352 #define _Out_writes_z_(size) _SAL2_Source_(_Out_writes_z_, (size), _Pre_cap_(size) _Post_valid_impl_ _Post_z_) 353 #define _Out_writes_opt_z_(size) _SAL2_Source_(_Out_writes_opt_z_, (size), _Pre_opt_cap_(size) _Post_valid_impl_ _Post_z_) 354 355 #define _Out_writes_to_(size,count) _SAL2_Source_(_Out_writes_to_, (size,count), _Pre_cap_(size) _Post_valid_impl_ _Post_count_(count)) 356 #define _Out_writes_to_opt_(size,count) _SAL2_Source_(_Out_writes_to_opt_, (size,count), _Pre_opt_cap_(size) _Post_valid_impl_ _Post_count_(count)) 357 #define _Out_writes_all_(size) _SAL2_Source_(_Out_writes_all_, (size), _Out_writes_to_(_Old_(size), _Old_(size))) 358 #define _Out_writes_all_opt_(size) _SAL2_Source_(_Out_writes_all_opt_, (size), _Out_writes_to_opt_(_Old_(size), _Old_(size))) 359 360 #define _Out_writes_bytes_to_(size,count) _SAL2_Source_(_Out_writes_bytes_to_, (size,count), _Pre_bytecap_(size) _Post_valid_impl_ _Post_bytecount_(count)) 361 #define _Out_writes_bytes_to_opt_(size,count) _SAL2_Source_(_Out_writes_bytes_to_opt_, (size,count), _Pre_opt_bytecap_(size) _Post_valid_impl_ _Post_bytecount_(count)) 362 #define _Out_writes_bytes_all_(size) _SAL2_Source_(_Out_writes_bytes_all_, (size), _Out_writes_bytes_to_(_Old_(size), _Old_(size))) 363 #define _Out_writes_bytes_all_opt_(size) _SAL2_Source_(_Out_writes_bytes_all_opt_, (size), _Out_writes_bytes_to_opt_(_Old_(size), _Old_(size))) 364 365 #define _Out_writes_to_ptr_(ptr) _SAL2_Source_(_Out_writes_to_ptr_, (ptr), _Pre_ptrdiff_cap_(ptr) _Post_valid_impl_) 366 #define _Out_writes_to_ptr_opt_(ptr) _SAL2_Source_(_Out_writes_to_ptr_opt_, (ptr), _Pre_opt_ptrdiff_cap_(ptr) _Post_valid_impl_) 367 #define _Out_writes_to_ptr_z_(ptr) _SAL2_Source_(_Out_writes_to_ptr_z_, (ptr), _Pre_ptrdiff_cap_(ptr) _Post_valid_impl_ Post_z_) 368 #define _Out_writes_to_ptr_opt_z_(ptr) _SAL2_Source_(_Out_writes_to_ptr_opt_z_, (ptr), _Pre_opt_ptrdiff_cap_(ptr) _Post_valid_impl_ Post_z_) 369 370 371 // Inout parameters ---------------------------- 372 373 // _Inout_ - Annotations for pointer or reference parameters where data is passed in and 374 // potentially modified. 375 // void ModifyPoint( _Inout_ POINT* pPT ); 376 // void ModifyPointByRef( _Inout_ POINT& pPT ); 377 378 #define _Inout_ _SAL2_Source_(_Inout_, (), _Prepost_valid_) 379 #define _Inout_opt_ _SAL2_Source_(_Inout_opt_, (), _Prepost_opt_valid_) 380 381 // For modifying string buffers 382 // void toupper( _Inout_z_ char* sz ); 383 #define _Inout_z_ _SAL2_Source_(_Inout_z_, (), _Prepost_z_) 384 #define _Inout_opt_z_ _SAL2_Source_(_Inout_opt_z_, (), _Prepost_opt_z_) 385 386 // For modifying buffers with explicit element size 387 #define _Inout_updates_(size) _SAL2_Source_(_Inout_updates_, (size), _Pre_cap_(size) _Pre_valid_impl_ _Post_valid_impl_) 388 #define _Inout_updates_opt_(size) _SAL2_Source_(_Inout_updates_opt_, (size), _Pre_opt_cap_(size) _Pre_valid_impl_ _Post_valid_impl_) 389 #define _Inout_updates_z_(size) _SAL2_Source_(_Inout_updates_z_, (size), _Pre_cap_(size) _Pre_valid_impl_ _Post_valid_impl_ _Pre1_impl_(__zterm_impl) _Post1_impl_(__zterm_impl)) 390 #define _Inout_updates_opt_z_(size) _SAL2_Source_(_Inout_updates_opt_z_, (size), _Pre_opt_cap_(size) _Pre_valid_impl_ _Post_valid_impl_ _Pre1_impl_(__zterm_impl) _Post1_impl_(__zterm_impl)) 391 392 #define _Inout_updates_to_(size,count) _SAL2_Source_(_Inout_updates_to_, (size,count), _Out_writes_to_(size,count) _Pre_valid_impl_ _Pre1_impl_(__count_impl(count))) 393 #define _Inout_updates_to_opt_(size,count) _SAL2_Source_(_Inout_updates_to_opt_, (size,count), _Out_writes_to_opt_(size,count) _Pre_valid_impl_ _Pre1_impl_(__count_impl(count))) 394 395 #define _Inout_updates_all_(size) _SAL2_Source_(_Inout_updates_all_, (size), _Inout_updates_to_(_Old_(size), _Old_(size))) 396 #define _Inout_updates_all_opt_(size) _SAL2_Source_(_Inout_updates_all_opt_, (size), _Inout_updates_to_opt_(_Old_(size), _Old_(size))) 397 398 // For modifying buffers with explicit byte size 399 #define _Inout_updates_bytes_(size) _SAL2_Source_(_Inout_updates_bytes_, (size), _Pre_bytecap_(size) _Pre_valid_impl_ _Post_valid_impl_) 400 #define _Inout_updates_bytes_opt_(size) _SAL2_Source_(_Inout_updates_bytes_opt_, (size), _Pre_opt_bytecap_(size) _Pre_valid_impl_ _Post_valid_impl_) 401 402 #define _Inout_updates_bytes_to_(size,count) _SAL2_Source_(_Inout_updates_bytes_to_, (size,count), _Out_writes_bytes_to_(size,count) _Pre_valid_impl_ _Pre1_impl_(__bytecount_impl(count))) 403 #define _Inout_updates_bytes_to_opt_(size,count) _SAL2_Source_(_Inout_updates_bytes_to_opt_, (size,count), _Out_writes_bytes_to_opt_(size,count) _Pre_valid_impl_ _Pre1_impl_(__bytecount_impl(count))) 404 405 #define _Inout_updates_bytes_all_(size) _SAL2_Source_(_Inout_updates_bytes_all_, (size), _Inout_updates_bytes_to_(_Old_(size), _Old_(size))) 406 #define _Inout_updates_bytes_all_opt_(size) _SAL2_Source_(_Inout_updates_bytes_all_opt_, (size), _Inout_updates_bytes_to_opt_(_Old_(size), _Old_(size))) 407 408 409 // Pointer to pointer parameters ------------------------- 410 411 // _Outptr_ - Annotations for output params returning pointers 412 // These describe parameters where the called function provides the buffer: 413 // HRESULT SHStrDupW(_In_ LPCWSTR psz, _Outptr_ LPWSTR *ppwsz); 414 // The caller passes the address of an LPWSTR variable as ppwsz, and SHStrDupW allocates 415 // and initializes memory and returns the pointer to the new LPWSTR in *ppwsz. 416 // 417 // _Outptr_opt_ - describes parameters that are allowed to be NULL. 418 // _Outptr_*_result_maybenull_ - describes parameters where the called function might return NULL to the caller. 419 // 420 // Example: 421 // void MyFunc(_Outptr_opt_ int **ppData1, _Outptr_result_maybenull_ int **ppData2); 422 // Callers: 423 // MyFunc(NULL, NULL); // error: parameter 2, ppData2, should not be NULL 424 // MyFunc(&pData1, &pData2); // ok: both non-NULL 425 // if (*pData1 == *pData2) ... // error: pData2 might be NULL after call 426 427 #define _Outptr_ _SAL2_Source_(_Outptr_, (), _Out_impl_ _Deref_post2_impl_(__notnull_impl_notref, __count_impl(1))) 428 #define _Outptr_result_maybenull_ _SAL2_Source_(_Outptr_result_maybenull_, (), _Out_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __count_impl(1))) 429 #define _Outptr_opt_ _SAL2_Source_(_Outptr_opt_, (), _Out_opt_impl_ _Deref_post2_impl_(__notnull_impl_notref, __count_impl(1))) 430 #define _Outptr_opt_result_maybenull_ _SAL2_Source_(_Outptr_opt_result_maybenull_, (), _Out_opt_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __count_impl(1))) 431 432 // Annotations for _Outptr_ parameters returning pointers to null terminated strings. 433 434 #define _Outptr_result_z_ _SAL2_Source_(_Outptr_result_z_, (), _Out_impl_ _Deref_post_z_) 435 #define _Outptr_opt_result_z_ _SAL2_Source_(_Outptr_opt_result_z_, (), _Out_opt_impl_ _Deref_post_z_) 436 #define _Outptr_result_maybenull_z_ _SAL2_Source_(_Outptr_result_maybenull_z_, (), _Out_impl_ _Deref_post_opt_z_) 437 #define _Outptr_opt_result_maybenull_z_ _SAL2_Source_(_Outptr_opt_result_maybenull_z_, (), _Out_opt_impl_ _Deref_post_opt_z_) 438 439 // Annotations for _Outptr_ parameters where the output pointer is set to NULL if the function fails. 440 441 #define _Outptr_result_nullonfailure_ _SAL2_Source_(_Outptr_result_nullonfailure_, (), _Outptr_ _On_failure_(_Deref_post_null_)) 442 #define _Outptr_opt_result_nullonfailure_ _SAL2_Source_(_Outptr_opt_result_nullonfailure_, (), _Outptr_opt_ _On_failure_(_Deref_post_null_)) 443 444 // Annotations for _Outptr_ parameters which return a pointer to a ref-counted COM object, 445 // following the COM convention of setting the output to NULL on failure. 446 // The current implementation is identical to _Outptr_result_nullonfailure_. 447 // For pointers to types that are not COM objects, _Outptr_result_nullonfailure_ is preferred. 448 449 #define _COM_Outptr_ _SAL2_Source_(_COM_Outptr_, (), _Outptr_ _On_failure_(_Deref_post_null_)) 450 #define _COM_Outptr_result_maybenull_ _SAL2_Source_(_COM_Outptr_result_maybenull_, (), _Outptr_result_maybenull_ _On_failure_(_Deref_post_null_)) 451 #define _COM_Outptr_opt_ _SAL2_Source_(_COM_Outptr_opt_, (), _Outptr_opt_ _On_failure_(_Deref_post_null_)) 452 #define _COM_Outptr_opt_result_maybenull_ _SAL2_Source_(_COM_Outptr_opt_result_maybenull_, (), _Outptr_opt_result_maybenull_ _On_failure_(_Deref_post_null_)) 453 454 // Annotations for _Outptr_ parameters returning a pointer to buffer with a specified number of elements/bytes 455 456 #define _Outptr_result_buffer_(size) _SAL2_Source_(_Outptr_result_buffer_, (size), _Out_impl_ _Deref_post2_impl_(__notnull_impl_notref, __cap_impl(size))) 457 #define _Outptr_opt_result_buffer_(size) _SAL2_Source_(_Outptr_opt_result_buffer_, (size), _Out_opt_impl_ _Deref_post2_impl_(__notnull_impl_notref, __cap_impl(size))) 458 #define _Outptr_result_buffer_to_(size, count) _SAL2_Source_(_Outptr_result_buffer_to_, (size, count), _Out_impl_ _Deref_post3_impl_(__notnull_impl_notref, __cap_impl(size), __count_impl(count))) 459 #define _Outptr_opt_result_buffer_to_(size, count) _SAL2_Source_(_Outptr_opt_result_buffer_to_, (size, count), _Out_opt_impl_ _Deref_post3_impl_(__notnull_impl_notref, __cap_impl(size), __count_impl(count))) 460 461 #define _Outptr_result_buffer_all_(size) _SAL2_Source_(_Outptr_result_buffer_all_, (size), _Out_impl_ _Deref_post2_impl_(__notnull_impl_notref, __count_impl(size))) 462 #define _Outptr_opt_result_buffer_all_(size) _SAL2_Source_(_Outptr_opt_result_buffer_all_, (size), _Out_opt_impl_ _Deref_post2_impl_(__notnull_impl_notref, __count_impl(size))) 463 464 #define _Outptr_result_buffer_maybenull_(size) _SAL2_Source_(_Outptr_result_buffer_maybenull_, (size), _Out_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __cap_impl(size))) 465 #define _Outptr_opt_result_buffer_maybenull_(size) _SAL2_Source_(_Outptr_opt_result_buffer_maybenull_, (size), _Out_opt_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __cap_impl(size))) 466 #define _Outptr_result_buffer_to_maybenull_(size, count) _SAL2_Source_(_Outptr_result_buffer_to_maybenull_, (size, count), _Out_impl_ _Deref_post3_impl_(__maybenull_impl_notref, __cap_impl(size), __count_impl(count))) 467 #define _Outptr_opt_result_buffer_to_maybenull_(size, count) _SAL2_Source_(_Outptr_opt_result_buffer_to_maybenull_, (size, count), _Out_opt_impl_ _Deref_post3_impl_(__maybenull_impl_notref, __cap_impl(size), __count_impl(count))) 468 469 #define _Outptr_result_buffer_all_maybenull_(size) _SAL2_Source_(_Outptr_result_buffer_all_maybenull_, (size), _Out_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __count_impl(size))) 470 #define _Outptr_opt_result_buffer_all_maybenull_(size) _SAL2_Source_(_Outptr_opt_result_buffer_all_maybenull_, (size), _Out_opt_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __count_impl(size))) 471 472 #define _Outptr_result_bytebuffer_(size) _SAL2_Source_(_Outptr_result_bytebuffer_, (size), _Out_impl_ _Deref_post2_impl_(__notnull_impl_notref, __bytecap_impl(size))) 473 #define _Outptr_opt_result_bytebuffer_(size) _SAL2_Source_(_Outptr_opt_result_bytebuffer_, (size), _Out_opt_impl_ _Deref_post2_impl_(__notnull_impl_notref, __bytecap_impl(size))) 474 #define _Outptr_result_bytebuffer_to_(size, count) _SAL2_Source_(_Outptr_result_bytebuffer_to_, (size, count), _Out_impl_ _Deref_post3_impl_(__notnull_impl_notref, __bytecap_impl(size), __bytecount_impl(count))) 475 #define _Outptr_opt_result_bytebuffer_to_(size, count) _SAL2_Source_(_Outptr_opt_result_bytebuffer_to_, (size, count), _Out_opt_impl_ _Deref_post3_impl_(__notnull_impl_notref, __bytecap_impl(size), __bytecount_impl(count))) 476 477 #define _Outptr_result_bytebuffer_all_(size) _SAL2_Source_(_Outptr_result_bytebuffer_all_, (size), _Out_impl_ _Deref_post2_impl_(__notnull_impl_notref, __bytecount_impl(size))) 478 #define _Outptr_opt_result_bytebuffer_all_(size) _SAL2_Source_(_Outptr_opt_result_bytebuffer_all_, (size), _Out_opt_impl_ _Deref_post2_impl_(__notnull_impl_notref, __bytecount_impl(size))) 479 480 #define _Outptr_result_bytebuffer_maybenull_(size) _SAL2_Source_(_Outptr_result_bytebuffer_maybenull_, (size), _Out_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __bytecap_impl(size))) 481 #define _Outptr_opt_result_bytebuffer_maybenull_(size) _SAL2_Source_(_Outptr_opt_result_bytebuffer_maybenull_, (size), _Out_opt_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __bytecap_impl(size))) 482 #define _Outptr_result_bytebuffer_to_maybenull_(size, count) _SAL2_Source_(_Outptr_result_bytebuffer_to_maybenull_, (size, count), _Out_impl_ _Deref_post3_impl_(__maybenull_impl_notref, __bytecap_impl(size), __bytecount_impl(count))) 483 #define _Outptr_opt_result_bytebuffer_to_maybenull_(size, count) _SAL2_Source_(_Outptr_opt_result_bytebuffer_to_maybenull_, (size, count), _Out_opt_impl_ _Deref_post3_impl_(__maybenull_impl_notref, __bytecap_impl(size), __bytecount_impl(count))) 484 485 #define _Outptr_result_bytebuffer_all_maybenull_(size) _SAL2_Source_(_Outptr_result_bytebuffer_all_maybenull_, (size), _Out_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __bytecount_impl(size))) 486 #define _Outptr_opt_result_bytebuffer_all_maybenull_(size) _SAL2_Source_(_Outptr_opt_result_bytebuffer_all_maybenull_, (size), _Out_opt_impl_ _Deref_post2_impl_(__maybenull_impl_notref, __bytecount_impl(size))) 487 488 // Annotations for output reference to pointer parameters. 489 490 #define _Outref_ _SAL2_Source_(_Outref_, (), _Out_impl_ _Post_notnull_) 491 #define _Outref_result_maybenull_ _SAL2_Source_(_Outref_result_maybenull_, (), _Pre2_impl_(__notnull_impl_notref, __cap_c_one_notref_impl) _Post_maybenull_ _Post_valid_impl_) 492 493 #define _Outref_result_buffer_(size) _SAL2_Source_(_Outref_result_buffer_, (size), _Outref_ _Post1_impl_(__cap_impl(size))) 494 #define _Outref_result_bytebuffer_(size) _SAL2_Source_(_Outref_result_bytebuffer_, (size), _Outref_ _Post1_impl_(__bytecap_impl(size))) 495 #define _Outref_result_buffer_to_(size, count) _SAL2_Source_(_Outref_result_buffer_to_, (size, count), _Outref_result_buffer_(size) _Post1_impl_(__count_impl(count))) 496 #define _Outref_result_bytebuffer_to_(size, count) _SAL2_Source_(_Outref_result_bytebuffer_to_, (size, count), _Outref_result_bytebuffer_(size) _Post1_impl_(__bytecount_impl(count))) 497 #define _Outref_result_buffer_all_(size) _SAL2_Source_(_Outref_result_buffer_all_, (size), _Outref_result_buffer_to_(size, _Old_(size))) 498 #define _Outref_result_bytebuffer_all_(size) _SAL2_Source_(_Outref_result_bytebuffer_all_, (size), _Outref_result_bytebuffer_to_(size, _Old_(size))) 499 500 #define _Outref_result_buffer_maybenull_(size) _SAL2_Source_(_Outref_result_buffer_maybenull_, (size), _Outref_result_maybenull_ _Post1_impl_(__cap_impl(size))) 501 #define _Outref_result_bytebuffer_maybenull_(size) _SAL2_Source_(_Outref_result_bytebuffer_maybenull_, (size), _Outref_result_maybenull_ _Post1_impl_(__bytecap_impl(size))) 502 #define _Outref_result_buffer_to_maybenull_(size, count) _SAL2_Source_(_Outref_result_buffer_to_maybenull_, (size, count), _Outref_result_buffer_maybenull_(size) _Post1_impl_(__count_impl(count))) 503 #define _Outref_result_bytebuffer_to_maybenull_(size, count) _SAL2_Source_(_Outref_result_bytebuffer_to_maybenull_, (size, count), _Outref_result_bytebuffer_maybenull_(size) _Post1_impl_(__bytecount_impl(count))) 504 #define _Outref_result_buffer_all_maybenull_(size) _SAL2_Source_(_Outref_result_buffer_all_maybenull_, (size), _Outref_result_buffer_to_maybenull_(size, _Old_(size))) 505 #define _Outref_result_bytebuffer_all_maybenull_(size) _SAL2_Source_(_Outref_result_bytebuffer_all_maybenull_, (size), _Outref_result_bytebuffer_to_maybenull_(size, _Old_(size))) 506 507 // Annotations for output reference to pointer parameters that guarantee 508 // that the pointer is set to NULL on failure. 509 #define _Outref_result_nullonfailure_ _SAL2_Source_(_Outref_result_nullonfailure_, (), _Outref_ _On_failure_(_Post_null_)) 510 511 // Generic annotations to set output value of a by-pointer or by-reference parameter to null/zero on failure. 512 #define _Result_nullonfailure_ _SAL2_Source_(_Result_nullonfailure_, (), _On_failure_(_Notref_impl_ _Deref_impl_ _Post_null_)) 513 #define _Result_zeroonfailure_ _SAL2_Source_(_Result_zeroonfailure_, (), _On_failure_(_Notref_impl_ _Deref_impl_ _Out_range_(==, 0))) 514 515 516 // return values ------------------------------- 517 518 // 519 // _Ret_ annotations 520 // 521 // describing conditions that hold for return values after the call 522 523 // e.g. _Ret_z_ CString::operator const WCHAR*() const throw(); 524 #define _Ret_z_ _SAL2_Source_(_Ret_z_, (), _Ret2_impl_(__notnull_impl, __zterm_impl) _Ret_valid_impl_) 525 #define _Ret_maybenull_z_ _SAL2_Source_(_Ret_maybenull_z_, (), _Ret2_impl_(__maybenull_impl,__zterm_impl) _Ret_valid_impl_) 526 527 // used with allocated but not yet initialized objects 528 #define _Ret_notnull_ _SAL2_Source_(_Ret_notnull_, (), _Ret1_impl_(__notnull_impl)) 529 #define _Ret_maybenull_ _SAL2_Source_(_Ret_maybenull_, (), _Ret1_impl_(__maybenull_impl)) 530 #define _Ret_null_ _SAL2_Source_(_Ret_null_, (), _Ret1_impl_(__null_impl)) 531 532 // used with allocated and initialized objects 533 // returns single valid object 534 #define _Ret_valid_ _SAL2_Source_(_Ret_valid_, (), _Ret1_impl_(__notnull_impl_notref) _Ret_valid_impl_) 535 536 // returns pointer to initialized buffer of specified size 537 #define _Ret_writes_(size) _SAL2_Source_(_Ret_writes_, (size), _Ret2_impl_(__notnull_impl, __count_impl(size)) _Ret_valid_impl_) 538 #define _Ret_writes_z_(size) _SAL2_Source_(_Ret_writes_z_, (size), _Ret3_impl_(__notnull_impl, __count_impl(size), __zterm_impl) _Ret_valid_impl_) 539 #define _Ret_writes_bytes_(size) _SAL2_Source_(_Ret_writes_bytes_, (size), _Ret2_impl_(__notnull_impl, __bytecount_impl(size)) _Ret_valid_impl_) 540 #define _Ret_writes_maybenull_(size) _SAL2_Source_(_Ret_writes_maybenull_, (size), _Ret2_impl_(__maybenull_impl,__count_impl(size)) _Ret_valid_impl_) 541 #define _Ret_writes_maybenull_z_(size) _SAL2_Source_(_Ret_writes_maybenull_z_, (size), _Ret3_impl_(__maybenull_impl,__count_impl(size),__zterm_impl) _Ret_valid_impl_) 542 #define _Ret_writes_bytes_maybenull_(size) _SAL2_Source_(_Ret_writes_bytes_maybenull_, (size), _Ret2_impl_(__maybenull_impl,__bytecount_impl(size)) _Ret_valid_impl_) 543 544 // returns pointer to partially initialized buffer, with total size 'size' and initialized size 'count' 545 #define _Ret_writes_to_(size,count) _SAL2_Source_(_Ret_writes_to_, (size,count), _Ret3_impl_(__notnull_impl, __cap_impl(size), __count_impl(count)) _Ret_valid_impl_) 546 #define _Ret_writes_bytes_to_(size,count) _SAL2_Source_(_Ret_writes_bytes_to_, (size,count), _Ret3_impl_(__notnull_impl, __bytecap_impl(size), __bytecount_impl(count)) _Ret_valid_impl_) 547 #define _Ret_writes_to_maybenull_(size,count) _SAL2_Source_(_Ret_writes_to_maybenull_, (size,count), _Ret3_impl_(__maybenull_impl, __cap_impl(size), __count_impl(count)) _Ret_valid_impl_) 548 #define _Ret_writes_bytes_to_maybenull_(size,count) _SAL2_Source_(_Ret_writes_bytes_to_maybenull_, (size,count), _Ret3_impl_(__maybenull_impl, __bytecap_impl(size), __bytecount_impl(count)) _Ret_valid_impl_) 549 550 551 // Annotations for strict type checking 552 #define _Points_to_data_ _SAL2_Source_(_Points_to_data_, (), _Pre_ _Points_to_data_impl_) 553 #define _Literal_ _SAL2_Source_(_Literal_, (), _Pre_ _Literal_impl_) 554 #define _Notliteral_ _SAL2_Source_(_Notliteral_, (), _Pre_ _Notliteral_impl_) 555 556 // Check the return value of a function e.g. _Check_return_ ErrorCode Foo(); 557 #define _Check_return_ _SAL2_Source_(_Check_return_, (), _Check_return_impl_) 558 #define _Must_inspect_result_ _SAL2_Source_(_Must_inspect_result_, (), _Must_inspect_impl_ _Check_return_impl_) 559 560 // e.g. MyPrintF( _Printf_format_string_ const WCHAR* wzFormat, ... ); 561 #define _Printf_format_string_ _SAL2_Source_(_Printf_format_string_, (), _Printf_format_string_impl_) 562 #define _Scanf_format_string_ _SAL2_Source_(_Scanf_format_string_, (), _Scanf_format_string_impl_) 563 #define _Scanf_s_format_string_ _SAL2_Source_(_Scanf_s_format_string_, (), _Scanf_s_format_string_impl_) 564 565 #define _Format_string_impl_(kind,where) _SA_annotes2(SAL_IsFormatString2, kind, where) 566 #define _Printf_format_string_params_(x) _SAL2_Source_(_Printf_format_string_params_, (x), _Format_string_impl_("printf", x)) 567 #define _Scanf_format_string_params_(x) _SAL2_Source_(_Scanf_format_string_params_, (x), _Format_string_impl_("scanf", x)) 568 #define _Scanf_s_format_string_params_(x) _SAL2_Source_(_Scanf_s_format_string_params_, (x), _Format_string_impl_("scanf_s", x)) 569 570 // annotations to express value of integral or pointer parameter 571 #define _In_range_(lb,ub) _SAL2_Source_(_In_range_, (lb,ub), _In_range_impl_(lb,ub)) 572 #define _Out_range_(lb,ub) _SAL2_Source_(_Out_range_, (lb,ub), _Out_range_impl_(lb,ub)) 573 #define _Ret_range_(lb,ub) _SAL2_Source_(_Ret_range_, (lb,ub), _Ret_range_impl_(lb,ub)) 574 #define _Deref_in_range_(lb,ub) _SAL2_Source_(_Deref_in_range_, (lb,ub), _Deref_in_range_impl_(lb,ub)) 575 #define _Deref_out_range_(lb,ub) _SAL2_Source_(_Deref_out_range_, (lb,ub), _Deref_out_range_impl_(lb,ub)) 576 #define _Deref_ret_range_(lb,ub) _SAL2_Source_(_Deref_ret_range_, (lb,ub), _Deref_ret_range_impl_(lb,ub)) 577 #define _Pre_equal_to_(expr) _SAL2_Source_(_Pre_equal_to_, (expr), _In_range_(==, expr)) 578 #define _Post_equal_to_(expr) _SAL2_Source_(_Post_equal_to_, (expr), _Out_range_(==, expr)) 579 580 // annotation to express that a value (usually a field of a mutable class) 581 // is not changed by a function call 582 #define _Unchanged_(e) _SAL2_Source_(_Unchanged_, (e), _At_(e, _Post_equal_to_(_Old_(e)) _Const_)) 583 584 // Annotations to allow expressing generalized pre and post conditions. 585 // 'cond' may be any valid SAL expression that is considered to be true as a precondition 586 // or postcondition (respsectively). 587 #define _Pre_satisfies_(cond) _SAL2_Source_(_Pre_satisfies_, (cond), _Pre_satisfies_impl_(cond)) 588 #define _Post_satisfies_(cond) _SAL2_Source_(_Post_satisfies_, (cond), _Post_satisfies_impl_(cond)) 589 590 // Annotations to express struct, class and field invariants 591 #define _Struct_size_bytes_(size) _SAL2_Source_(_Struct_size_bytes_, (size), _Writable_bytes_(size)) 592 593 #define _Field_size_(size) _SAL2_Source_(_Field_size_, (size), _Notnull_ _Writable_elements_(size)) 594 #define _Field_size_opt_(size) _SAL2_Source_(_Field_size_opt_, (size), _Maybenull_ _Writable_elements_(size)) 595 #define _Field_size_part_(size, count) _SAL2_Source_(_Field_size_part_, (size, count), _Notnull_ _Writable_elements_(size) _Readable_elements_(count)) 596 #define _Field_size_part_opt_(size, count) _SAL2_Source_(_Field_size_part_opt_, (size, count), _Maybenull_ _Writable_elements_(size) _Readable_elements_(count)) 597 #define _Field_size_full_(size) _SAL2_Source_(_Field_size_full_, (size), _Field_size_part_(size, size)) 598 #define _Field_size_full_opt_(size) _SAL2_Source_(_Field_size_full_opt_, (size), _Field_size_part_opt_(size, size)) 599 600 #define _Field_size_bytes_(size) _SAL2_Source_(_Field_size_bytes_, (size), _Notnull_ _Writable_bytes_(size)) 601 #define _Field_size_bytes_opt_(size) _SAL2_Source_(_Field_size_bytes_opt_, (size), _Maybenull_ _Writable_bytes_(size)) 602 #define _Field_size_bytes_part_(size, count) _SAL2_Source_(_Field_size_bytes_part_, (size, count), _Notnull_ _Writable_bytes_(size) _Readable_bytes_(count)) 603 #define _Field_size_bytes_part_opt_(size, count) _SAL2_Source_(_Field_size_bytes_part_opt_, (size, count), _Maybenull_ _Writable_bytes_(size) _Readable_bytes_(count)) 604 #define _Field_size_bytes_full_(size) _SAL2_Source_(_Field_size_bytes_full_, (size), _Field_size_bytes_part_(size, size)) 605 #define _Field_size_bytes_full_opt_(size) _SAL2_Source_(_Field_size_bytes_full_opt_, (size), _Field_size_bytes_part_opt_(size, size)) 606 607 #define _Field_z_ _SAL2_Source_(_Field_z_, (), _Null_terminated_) 608 609 #define _Field_range_(min,max) _SAL2_Source_(_Field_range_, (min,max), _Field_range_impl_(min,max)) 610 611 //============================================================================ 612 // _Pre_\_Post_ Layer: 613 //============================================================================ 614 615 // 616 // Raw Pre/Post for declaring custom pre/post conditions 617 // 618 619 #define _Pre_ _Pre_impl_ 620 #define _Post_ _Post_impl_ 621 622 // 623 // Validity property 624 // 625 626 #define _Valid_ _Valid_impl_ 627 #define _Notvalid_ _Notvalid_impl_ 628 #define _Maybevalid_ _Maybevalid_impl_ 629 630 // 631 // Buffer size properties 632 // 633 634 // Expressing buffer sizes without specifying pre or post condition 635 #define _Readable_bytes_(size) _SAL2_Source_(_Readable_bytes_, (size), _Readable_bytes_impl_(size)) 636 #define _Readable_elements_(size) _SAL2_Source_(_Readable_elements_, (size), _Readable_elements_impl_(size)) 637 #define _Writable_bytes_(size) _SAL2_Source_(_Writable_bytes_, (size), _Writable_bytes_impl_(size)) 638 #define _Writable_elements_(size) _SAL2_Source_(_Writable_elements_, (size), _Writable_elements_impl_(size)) 639 640 #define _Null_terminated_ _SAL2_Source_(_Null_terminated_, (), _Null_terminated_impl_) 641 #define _NullNull_terminated_ _SAL2_Source_(_NullNull_terminated_, (), _NullNull_terminated_impl_) 642 643 // Expressing buffer size as pre or post condition 644 #define _Pre_readable_size_(size) _SAL2_Source_(_Pre_readable_size_, (size), _Pre1_impl_(__count_impl(size)) _Pre_valid_impl_) 645 #define _Pre_writable_size_(size) _SAL2_Source_(_Pre_writable_size_, (size), _Pre1_impl_(__cap_impl(size))) 646 #define _Pre_readable_byte_size_(size) _SAL2_Source_(_Pre_readable_byte_size_, (size), _Pre1_impl_(__bytecount_impl(size)) _Pre_valid_impl_) 647 #define _Pre_writable_byte_size_(size) _SAL2_Source_(_Pre_writable_byte_size_, (size), _Pre1_impl_(__bytecap_impl(size))) 648 649 #define _Post_readable_size_(size) _SAL2_Source_(_Post_readable_size_, (size), _Post1_impl_(__count_impl(size)) _Post_valid_impl_) 650 #define _Post_writable_size_(size) _SAL2_Source_(_Post_writable_size_, (size), _Post1_impl_(__cap_impl(size))) 651 #define _Post_readable_byte_size_(size) _SAL2_Source_(_Post_readable_byte_size_, (size), _Post1_impl_(__bytecount_impl(size)) _Post_valid_impl_) 652 #define _Post_writable_byte_size_(size) _SAL2_Source_(_Post_writable_byte_size_, (size), _Post1_impl_(__bytecap_impl(size))) 653 654 // 655 // Pointer null-ness properties 656 // 657 #define _Null_ _Null_impl_ 658 #define _Notnull_ _Notnull_impl_ 659 #define _Maybenull_ _Maybenull_impl_ 660 661 // 662 // _Pre_ annotations --- 663 // 664 // describing conditions that must be met before the call of the function 665 666 // e.g. int strlen( _Pre_z_ const char* sz ); 667 // buffer is a zero terminated string 668 #define _Pre_z_ _SAL2_Source_(_Pre_z_, (), _Pre1_impl_(__zterm_impl) _Pre_valid_impl_) 669 670 // valid size unknown or indicated by type (e.g.:LPSTR) 671 #define _Pre_valid_ _SAL2_Source_(_Pre_valid_, (), _Pre1_impl_(__notnull_impl_notref) _Pre_valid_impl_) 672 #define _Pre_opt_valid_ _SAL2_Source_(_Pre_opt_valid_, (), _Pre1_impl_(__maybenull_impl_notref) _Pre_valid_impl_) 673 674 #define _Pre_invalid_ _SAL2_Source_(_Pre_invalid_, (), _Deref_pre1_impl_(__notvalid_impl)) 675 676 // Overrides recursive valid when some field is not yet initialized when using _Inout_ 677 #define _Pre_unknown_ _SAL2_Source_(_Pre_unknown_, (), _Pre1_impl_(__maybevalid_impl)) 678 679 // used with allocated but not yet initialized objects 680 #define _Pre_notnull_ _SAL2_Source_(_Pre_notnull_, (), _Pre1_impl_(__notnull_impl_notref)) 681 #define _Pre_maybenull_ _SAL2_Source_(_Pre_maybenull_, (), _Pre1_impl_(__maybenull_impl_notref)) 682 #define _Pre_null_ _SAL2_Source_(_Pre_null_, (), _Pre1_impl_(__null_impl_notref)) 683 684 // 685 // _Post_ annotations --- 686 // 687 // describing conditions that hold after the function call 688 689 // void CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_ char* szFrom, size_t cchFrom ); 690 // buffer will be a zero-terminated string after the call 691 #define _Post_z_ _SAL2_Source_(_Post_z_, (), _Post1_impl_(__zterm_impl) _Post_valid_impl_) 692 693 // e.g. HRESULT InitStruct( _Post_valid_ Struct* pobj ); 694 #define _Post_valid_ _SAL2_Source_(_Post_valid_, (), _Post_valid_impl_) 695 #define _Post_invalid_ _SAL2_Source_(_Post_invalid_, (), _Deref_post1_impl_(__notvalid_impl)) 696 697 // e.g. void free( _Post_ptr_invalid_ void* pv ); 698 #define _Post_ptr_invalid_ _SAL2_Source_(_Post_ptr_invalid_, (), _Post1_impl_(__notvalid_impl)) 699 700 // e.g. void ThrowExceptionIfNull( _Post_notnull_ const void* pv ); 701 #define _Post_notnull_ _SAL2_Source_(_Post_notnull_, (), _Post1_impl_(__notnull_impl)) 702 703 // e.g. HRESULT GetObject(_Outptr_ _On_failure_(_At_(*p, _Post_null_)) T **p); 704 #define _Post_null_ _SAL2_Source_(_Post_null_, (), _Post1_impl_(__null_impl)) 705 706 #define _Post_maybenull_ _SAL2_Source_(_Post_maybenull_, (), _Post1_impl_(__maybenull_impl)) 707 708 #define _Prepost_z_ _SAL2_Source_(_Prepost_z_, (), _Pre_z_ _Post_z_) 709 710 711 // #pragma region Input Buffer SAL 1 compatibility macros 712 713 /*========================================================================== 714 715 This section contains definitions for macros defined for VS2010 and earlier. 716 Usage of these macros is still supported, but the SAL 2 macros defined above 717 are recommended instead. This comment block is retained to assist in 718 understanding SAL that still uses the older syntax. 719 720 The macros are defined in 3 layers: 721 722 _In_\_Out_ Layer: 723 ---------------- 724 This layer provides the highest abstraction and its macros should be used 725 in most cases. Its macros start with _In_, _Out_ or _Inout_. For the 726 typical case they provide the most concise annotations. 727 728 _Pre_\_Post_ Layer: 729 ------------------ 730 The macros of this layer only should be used when there is no suitable macro 731 in the _In_\_Out_ layer. Its macros start with _Pre_, _Post_, _Ret_, 732 _Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most 733 flexibility for annotations. 734 735 Implementation Abstraction Layer: 736 -------------------------------- 737 Macros from this layer should never be used directly. The layer only exists 738 to hide the implementation of the annotation macros. 739 740 741 Annotation Syntax: 742 |--------------|----------|----------------|-----------------------------| 743 | Usage | Nullness | ZeroTerminated | Extent | 744 |--------------|----------|----------------|-----------------------------| 745 | _In_ | <> | <> | <> | 746 | _Out_ | opt_ | z_ | [byte]cap_[c_|x_]( size ) | 747 | _Inout_ | | | [byte]count_[c_|x_]( size ) | 748 | _Deref_out_ | | | ptrdiff_cap_( ptr ) | 749 |--------------| | | ptrdiff_count_( ptr ) | 750 | _Ret_ | | | | 751 | _Deref_ret_ | | | | 752 |--------------| | | | 753 | _Pre_ | | | | 754 | _Post_ | | | | 755 | _Deref_pre_ | | | | 756 | _Deref_post_ | | | | 757 |--------------|----------|----------------|-----------------------------| 758 759 Usage: 760 ----- 761 _In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for 762 formal parameters. 763 _Ret_, _Deref_ret_ must be used for return values. 764 765 Nullness: 766 -------- 767 If the pointer can be NULL the annotation contains _opt. If the macro 768 does not contain '_opt' the pointer may not be NULL. 769 770 String Type: 771 ----------- 772 _z: NullTerminated string 773 for _In_ parameters the buffer must have the specified stringtype before the call 774 for _Out_ parameters the buffer must have the specified stringtype after the call 775 for _Inout_ parameters both conditions apply 776 777 Extent Syntax: 778 |------|---------------|---------------| 779 | Unit | Writ\Readable | Argument Type | 780 |------|---------------|---------------| 781 | <> | cap_ | <> | 782 | byte | count_ | c_ | 783 | | | x_ | 784 |------|---------------|---------------| 785 786 'cap' (capacity) describes the writable size of the buffer and is typically used 787 with _Out_. The default unit is elements. Use 'bytecap' if the size is given in bytes 788 'count' describes the readable size of the buffer and is typically used with _In_. 789 The default unit is elements. Use 'bytecount' if the size is given in bytes. 790 791 Argument syntax for cap_, bytecap_, count_, bytecount_: 792 (<parameter>|return)[+n] e.g. cch, return, cb+2 793 794 If the buffer size is a constant expression use the c_ postfix. 795 E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16) 796 797 If the buffer size is given by a limiting pointer use the ptrdiff_ versions 798 of the macros. 799 800 If the buffer size is neither a parameter nor a constant expression use the x_ 801 postfix. e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string. 802 No analysis can be done for x_ annotations but they at least tell the tool that 803 the buffer has some sort of extent description. x_ annotations might be supported 804 by future compiler versions. 805 806 ============================================================================*/ 807 808 // e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) 809 // valid buffer extent described by another parameter 810 #define _In_count_(size) _SAL1_1_Source_(_In_count_, (size), _Pre_count_(size) _Deref_pre_readonly_) 811 #define _In_opt_count_(size) _SAL1_1_Source_(_In_opt_count_, (size), _Pre_opt_count_(size) _Deref_pre_readonly_) 812 #define _In_bytecount_(size) _SAL1_1_Source_(_In_bytecount_, (size), _Pre_bytecount_(size) _Deref_pre_readonly_) 813 #define _In_opt_bytecount_(size) _SAL1_1_Source_(_In_opt_bytecount_, (size), _Pre_opt_bytecount_(size) _Deref_pre_readonly_) 814 815 // valid buffer extent described by a constant extression 816 #define _In_count_c_(size) _SAL1_1_Source_(_In_count_c_, (size), _Pre_count_c_(size) _Deref_pre_readonly_) 817 #define _In_opt_count_c_(size) _SAL1_1_Source_(_In_opt_count_c_, (size), _Pre_opt_count_c_(size) _Deref_pre_readonly_) 818 #define _In_bytecount_c_(size) _SAL1_1_Source_(_In_bytecount_c_, (size), _Pre_bytecount_c_(size) _Deref_pre_readonly_) 819 #define _In_opt_bytecount_c_(size) _SAL1_1_Source_(_In_opt_bytecount_c_, (size), _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_) 820 821 // nullterminated 'input' buffers with given size 822 823 // e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) 824 // nullterminated valid buffer extent described by another parameter 825 #define _In_z_count_(size) _SAL1_1_Source_(_In_z_count_, (size), _Pre_z_ _Pre_count_(size) _Deref_pre_readonly_) 826 #define _In_opt_z_count_(size) _SAL1_1_Source_(_In_opt_z_count_, (size), _Pre_opt_z_ _Pre_opt_count_(size) _Deref_pre_readonly_) 827 #define _In_z_bytecount_(size) _SAL1_1_Source_(_In_z_bytecount_, (size), _Pre_z_ _Pre_bytecount_(size) _Deref_pre_readonly_) 828 #define _In_opt_z_bytecount_(size) _SAL1_1_Source_(_In_opt_z_bytecount_, (size), _Pre_opt_z_ _Pre_opt_bytecount_(size) _Deref_pre_readonly_) 829 830 // nullterminated valid buffer extent described by a constant extression 831 #define _In_z_count_c_(size) _SAL1_1_Source_(_In_z_count_c_, (size), _Pre_z_ _Pre_count_c_(size) _Deref_pre_readonly_) 832 #define _In_opt_z_count_c_(size) _SAL1_1_Source_(_In_opt_z_count_c_, (size), _Pre_opt_z_ _Pre_opt_count_c_(size) _Deref_pre_readonly_) 833 #define _In_z_bytecount_c_(size) _SAL1_1_Source_(_In_z_bytecount_c_, (size), _Pre_z_ _Pre_bytecount_c_(size) _Deref_pre_readonly_) 834 #define _In_opt_z_bytecount_c_(size) _SAL1_1_Source_(_In_opt_z_bytecount_c_, (size), _Pre_opt_z_ _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_) 835 836 // buffer capacity is described by another pointer 837 // e.g. void Foo( _In_ptrdiff_count_(pchMax) const char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } 838 #define _In_ptrdiff_count_(size) _SAL1_1_Source_(_In_ptrdiff_count_, (size), _Pre_ptrdiff_count_(size) _Deref_pre_readonly_) 839 #define _In_opt_ptrdiff_count_(size) _SAL1_1_Source_(_In_opt_ptrdiff_count_, (size), _Pre_opt_ptrdiff_count_(size) _Deref_pre_readonly_) 840 841 // 'x' version for complex expressions that are not supported by the current compiler version 842 // e.g. void Set3ColMatrix( _In_count_x_(3*cRows) const Elem* matrix, int cRows ); 843 #define _In_count_x_(size) _SAL1_1_Source_(_In_count_x_, (size), _Pre_count_x_(size) _Deref_pre_readonly_) 844 #define _In_opt_count_x_(size) _SAL1_1_Source_(_In_opt_count_x_, (size), _Pre_opt_count_x_(size) _Deref_pre_readonly_) 845 #define _In_bytecount_x_(size) _SAL1_1_Source_(_In_bytecount_x_, (size), _Pre_bytecount_x_(size) _Deref_pre_readonly_) 846 #define _In_opt_bytecount_x_(size) _SAL1_1_Source_(_In_opt_bytecount_x_, (size), _Pre_opt_bytecount_x_(size) _Deref_pre_readonly_) 847 848 849 // 'out' with buffer size 850 // e.g. void GetIndeces( _Out_cap_(cIndeces) int* rgIndeces, size_t cIndices ); 851 // buffer capacity is described by another parameter 852 #define _Out_cap_(size) _SAL1_1_Source_(_Out_cap_, (size), _Pre_cap_(size) _Post_valid_impl_) 853 #define _Out_opt_cap_(size) _SAL1_1_Source_(_Out_opt_cap_, (size), _Pre_opt_cap_(size) _Post_valid_impl_) 854 #define _Out_bytecap_(size) _SAL1_1_Source_(_Out_bytecap_, (size), _Pre_bytecap_(size) _Post_valid_impl_) 855 #define _Out_opt_bytecap_(size) _SAL1_1_Source_(_Out_opt_bytecap_, (size), _Pre_opt_bytecap_(size) _Post_valid_impl_) 856 857 // buffer capacity is described by a constant expression 858 #define _Out_cap_c_(size) _SAL1_1_Source_(_Out_cap_c_, (size), _Pre_cap_c_(size) _Post_valid_impl_) 859 #define _Out_opt_cap_c_(size) _SAL1_1_Source_(_Out_opt_cap_c_, (size), _Pre_opt_cap_c_(size) _Post_valid_impl_) 860 #define _Out_bytecap_c_(size) _SAL1_1_Source_(_Out_bytecap_c_, (size), _Pre_bytecap_c_(size) _Post_valid_impl_) 861 #define _Out_opt_bytecap_c_(size) _SAL1_1_Source_(_Out_opt_bytecap_c_, (size), _Pre_opt_bytecap_c_(size) _Post_valid_impl_) 862 863 // buffer capacity is described by another parameter multiplied by a constant expression 864 #define _Out_cap_m_(mult,size) _SAL1_1_Source_(_Out_cap_m_, (mult,size), _Pre_cap_m_(mult,size) _Post_valid_impl_) 865 #define _Out_opt_cap_m_(mult,size) _SAL1_1_Source_(_Out_opt_cap_m_, (mult,size), _Pre_opt_cap_m_(mult,size) _Post_valid_impl_) 866 #define _Out_z_cap_m_(mult,size) _SAL1_1_Source_(_Out_z_cap_m_, (mult,size), _Pre_cap_m_(mult,size) _Post_valid_impl_ _Post_z_) 867 #define _Out_opt_z_cap_m_(mult,size) _SAL1_1_Source_(_Out_opt_z_cap_m_, (mult,size), _Pre_opt_cap_m_(mult,size) _Post_valid_impl_ _Post_z_) 868 869 // buffer capacity is described by another pointer 870 // e.g. void Foo( _Out_ptrdiff_cap_(pchMax) char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } 871 #define _Out_ptrdiff_cap_(size) _SAL1_1_Source_(_Out_ptrdiff_cap_, (size), _Pre_ptrdiff_cap_(size) _Post_valid_impl_) 872 #define _Out_opt_ptrdiff_cap_(size) _SAL1_1_Source_(_Out_opt_ptrdiff_cap_, (size), _Pre_opt_ptrdiff_cap_(size) _Post_valid_impl_) 873 874 // buffer capacity is described by a complex expression 875 #define _Out_cap_x_(size) _SAL1_1_Source_(_Out_cap_x_, (size), _Pre_cap_x_(size) _Post_valid_impl_) 876 #define _Out_opt_cap_x_(size) _SAL1_1_Source_(_Out_opt_cap_x_, (size), _Pre_opt_cap_x_(size) _Post_valid_impl_) 877 #define _Out_bytecap_x_(size) _SAL1_1_Source_(_Out_bytecap_x_, (size), _Pre_bytecap_x_(size) _Post_valid_impl_) 878 #define _Out_opt_bytecap_x_(size) _SAL1_1_Source_(_Out_opt_bytecap_x_, (size), _Pre_opt_bytecap_x_(size) _Post_valid_impl_) 879 880 // a zero terminated string is filled into a buffer of given capacity 881 // e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); 882 // buffer capacity is described by another parameter 883 #define _Out_z_cap_(size) _SAL1_1_Source_(_Out_z_cap_, (size), _Pre_cap_(size) _Post_valid_impl_ _Post_z_) 884 #define _Out_opt_z_cap_(size) _SAL1_1_Source_(_Out_opt_z_cap_, (size), _Pre_opt_cap_(size) _Post_valid_impl_ _Post_z_) 885 #define _Out_z_bytecap_(size) _SAL1_1_Source_(_Out_z_bytecap_, (size), _Pre_bytecap_(size) _Post_valid_impl_ _Post_z_) 886 #define _Out_opt_z_bytecap_(size) _SAL1_1_Source_(_Out_opt_z_bytecap_, (size), _Pre_opt_bytecap_(size) _Post_valid_impl_ _Post_z_) 887 888 // buffer capacity is described by a constant expression 889 #define _Out_z_cap_c_(size) _SAL1_1_Source_(_Out_z_cap_c_, (size), _Pre_cap_c_(size) _Post_valid_impl_ _Post_z_) 890 #define _Out_opt_z_cap_c_(size) _SAL1_1_Source_(_Out_opt_z_cap_c_, (size), _Pre_opt_cap_c_(size) _Post_valid_impl_ _Post_z_) 891 #define _Out_z_bytecap_c_(size) _SAL1_1_Source_(_Out_z_bytecap_c_, (size), _Pre_bytecap_c_(size) _Post_valid_impl_ _Post_z_) 892 #define _Out_opt_z_bytecap_c_(size) _SAL1_1_Source_(_Out_opt_z_bytecap_c_, (size), _Pre_opt_bytecap_c_(size) _Post_valid_impl_ _Post_z_) 893 894 // buffer capacity is described by a complex expression 895 #define _Out_z_cap_x_(size) _SAL1_1_Source_(_Out_z_cap_x_, (size), _Pre_cap_x_(size) _Post_valid_impl_ _Post_z_) 896 #define _Out_opt_z_cap_x_(size) _SAL1_1_Source_(_Out_opt_z_cap_x_, (size), _Pre_opt_cap_x_(size) _Post_valid_impl_ _Post_z_) 897 #define _Out_z_bytecap_x_(size) _SAL1_1_Source_(_Out_z_bytecap_x_, (size), _Pre_bytecap_x_(size) _Post_valid_impl_ _Post_z_) 898 #define _Out_opt_z_bytecap_x_(size) _SAL1_1_Source_(_Out_opt_z_bytecap_x_, (size), _Pre_opt_bytecap_x_(size) _Post_valid_impl_ _Post_z_) 899 900 // a zero terminated string is filled into a buffer of given capacity 901 // e.g. size_t CopyCharRange( _In_count_(cchFrom) const char* rgchFrom, size_t cchFrom, _Out_cap_post_count_(cchTo,return)) char* rgchTo, size_t cchTo ); 902 #define _Out_cap_post_count_(cap,count) _SAL1_1_Source_(_Out_cap_post_count_, (cap,count), _Pre_cap_(cap) _Post_valid_impl_ _Post_count_(count)) 903 #define _Out_opt_cap_post_count_(cap,count) _SAL1_1_Source_(_Out_opt_cap_post_count_, (cap,count), _Pre_opt_cap_(cap) _Post_valid_impl_ _Post_count_(count)) 904 #define _Out_bytecap_post_bytecount_(cap,count) _SAL1_1_Source_(_Out_bytecap_post_bytecount_, (cap,count), _Pre_bytecap_(cap) _Post_valid_impl_ _Post_bytecount_(count)) 905 #define _Out_opt_bytecap_post_bytecount_(cap,count) _SAL1_1_Source_(_Out_opt_bytecap_post_bytecount_, (cap,count), _Pre_opt_bytecap_(cap) _Post_valid_impl_ _Post_bytecount_(count)) 906 907 // a zero terminated string is filled into a buffer of given capacity 908 // e.g. size_t CopyStr( _In_z_ const char* szFrom, _Out_z_cap_post_count_(cchTo,return+1) char* szTo, size_t cchTo ); 909 #define _Out_z_cap_post_count_(cap,count) _SAL1_1_Source_(_Out_z_cap_post_count_, (cap,count), _Pre_cap_(cap) _Post_valid_impl_ _Post_z_count_(count)) 910 #define _Out_opt_z_cap_post_count_(cap,count) _SAL1_1_Source_(_Out_opt_z_cap_post_count_, (cap,count), _Pre_opt_cap_(cap) _Post_valid_impl_ _Post_z_count_(count)) 911 #define _Out_z_bytecap_post_bytecount_(cap,count) _SAL1_1_Source_(_Out_z_bytecap_post_bytecount_, (cap,count), _Pre_bytecap_(cap) _Post_valid_impl_ _Post_z_bytecount_(count)) 912 #define _Out_opt_z_bytecap_post_bytecount_(cap,count) _SAL1_1_Source_(_Out_opt_z_bytecap_post_bytecount_, (cap,count), _Pre_opt_bytecap_(cap) _Post_valid_impl_ _Post_z_bytecount_(count)) 913 914 // only use with dereferenced arguments e.g. '*pcch' 915 #define _Out_capcount_(capcount) _SAL1_1_Source_(_Out_capcount_, (capcount), _Pre_cap_(capcount) _Post_valid_impl_ _Post_count_(capcount)) 916 #define _Out_opt_capcount_(capcount) _SAL1_1_Source_(_Out_opt_capcount_, (capcount), _Pre_opt_cap_(capcount) _Post_valid_impl_ _Post_count_(capcount)) 917 #define _Out_bytecapcount_(capcount) _SAL1_1_Source_(_Out_bytecapcount_, (capcount), _Pre_bytecap_(capcount) _Post_valid_impl_ _Post_bytecount_(capcount)) 918 #define _Out_opt_bytecapcount_(capcount) _SAL1_1_Source_(_Out_opt_bytecapcount_, (capcount), _Pre_opt_bytecap_(capcount) _Post_valid_impl_ _Post_bytecount_(capcount)) 919 920 #define _Out_capcount_x_(capcount) _SAL1_1_Source_(_Out_capcount_x_, (capcount), _Pre_cap_x_(capcount) _Post_valid_impl_ _Post_count_x_(capcount)) 921 #define _Out_opt_capcount_x_(capcount) _SAL1_1_Source_(_Out_opt_capcount_x_, (capcount), _Pre_opt_cap_x_(capcount) _Post_valid_impl_ _Post_count_x_(capcount)) 922 #define _Out_bytecapcount_x_(capcount) _SAL1_1_Source_(_Out_bytecapcount_x_, (capcount), _Pre_bytecap_x_(capcount) _Post_valid_impl_ _Post_bytecount_x_(capcount)) 923 #define _Out_opt_bytecapcount_x_(capcount) _SAL1_1_Source_(_Out_opt_bytecapcount_x_, (capcount), _Pre_opt_bytecap_x_(capcount) _Post_valid_impl_ _Post_bytecount_x_(capcount)) 924 925 // e.g. GetString( _Out_z_capcount_(*pLen+1) char* sz, size_t* pLen ); 926 #define _Out_z_capcount_(capcount) _SAL1_1_Source_(_Out_z_capcount_, (capcount), _Pre_cap_(capcount) _Post_valid_impl_ _Post_z_count_(capcount)) 927 #define _Out_opt_z_capcount_(capcount) _SAL1_1_Source_(_Out_opt_z_capcount_, (capcount), _Pre_opt_cap_(capcount) _Post_valid_impl_ _Post_z_count_(capcount)) 928 #define _Out_z_bytecapcount_(capcount) _SAL1_1_Source_(_Out_z_bytecapcount_, (capcount), _Pre_bytecap_(capcount) _Post_valid_impl_ _Post_z_bytecount_(capcount)) 929 #define _Out_opt_z_bytecapcount_(capcount) _SAL1_1_Source_(_Out_opt_z_bytecapcount_, (capcount), _Pre_opt_bytecap_(capcount) _Post_valid_impl_ _Post_z_bytecount_(capcount)) 930 931 932 // 'inout' buffers with initialized elements before and after the call 933 // e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); 934 #define _Inout_count_(size) _SAL1_1_Source_(_Inout_count_, (size), _Prepost_count_(size)) 935 #define _Inout_opt_count_(size) _SAL1_1_Source_(_Inout_opt_count_, (size), _Prepost_opt_count_(size)) 936 #define _Inout_bytecount_(size) _SAL1_1_Source_(_Inout_bytecount_, (size), _Prepost_bytecount_(size)) 937 #define _Inout_opt_bytecount_(size) _SAL1_1_Source_(_Inout_opt_bytecount_, (size), _Prepost_opt_bytecount_(size)) 938 939 #define _Inout_count_c_(size) _SAL1_1_Source_(_Inout_count_c_, (size), _Prepost_count_c_(size)) 940 #define _Inout_opt_count_c_(size) _SAL1_1_Source_(_Inout_opt_count_c_, (size), _Prepost_opt_count_c_(size)) 941 #define _Inout_bytecount_c_(size) _SAL1_1_Source_(_Inout_bytecount_c_, (size), _Prepost_bytecount_c_(size)) 942 #define _Inout_opt_bytecount_c_(size) _SAL1_1_Source_(_Inout_opt_bytecount_c_, (size), _Prepost_opt_bytecount_c_(size)) 943 944 // nullterminated 'inout' buffers with initialized elements before and after the call 945 // e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); 946 #define _Inout_z_count_(size) _SAL1_1_Source_(_Inout_z_count_, (size), _Prepost_z_ _Prepost_count_(size)) 947 #define _Inout_opt_z_count_(size) _SAL1_1_Source_(_Inout_opt_z_count_, (size), _Prepost_z_ _Prepost_opt_count_(size)) 948 #define _Inout_z_bytecount_(size) _SAL1_1_Source_(_Inout_z_bytecount_, (size), _Prepost_z_ _Prepost_bytecount_(size)) 949 #define _Inout_opt_z_bytecount_(size) _SAL1_1_Source_(_Inout_opt_z_bytecount_, (size), _Prepost_z_ _Prepost_opt_bytecount_(size)) 950 951 #define _Inout_z_count_c_(size) _SAL1_1_Source_(_Inout_z_count_c_, (size), _Prepost_z_ _Prepost_count_c_(size)) 952 #define _Inout_opt_z_count_c_(size) _SAL1_1_Source_(_Inout_opt_z_count_c_, (size), _Prepost_z_ _Prepost_opt_count_c_(size)) 953 #define _Inout_z_bytecount_c_(size) _SAL1_1_Source_(_Inout_z_bytecount_c_, (size), _Prepost_z_ _Prepost_bytecount_c_(size)) 954 #define _Inout_opt_z_bytecount_c_(size) _SAL1_1_Source_(_Inout_opt_z_bytecount_c_, (size), _Prepost_z_ _Prepost_opt_bytecount_c_(size)) 955 956 #define _Inout_ptrdiff_count_(size) _SAL1_1_Source_(_Inout_ptrdiff_count_, (size), _Pre_ptrdiff_count_(size)) 957 #define _Inout_opt_ptrdiff_count_(size) _SAL1_1_Source_(_Inout_opt_ptrdiff_count_, (size), _Pre_opt_ptrdiff_count_(size)) 958 959 #define _Inout_count_x_(size) _SAL1_1_Source_(_Inout_count_x_, (size), _Prepost_count_x_(size)) 960 #define _Inout_opt_count_x_(size) _SAL1_1_Source_(_Inout_opt_count_x_, (size), _Prepost_opt_count_x_(size)) 961 #define _Inout_bytecount_x_(size) _SAL1_1_Source_(_Inout_bytecount_x_, (size), _Prepost_bytecount_x_(size)) 962 #define _Inout_opt_bytecount_x_(size) _SAL1_1_Source_(_Inout_opt_bytecount_x_, (size), _Prepost_opt_bytecount_x_(size)) 963 964 // e.g. void AppendToLPSTR( _In_ LPCSTR szFrom, _Inout_cap_(cchTo) LPSTR* szTo, size_t cchTo ); 965 #define _Inout_cap_(size) _SAL1_1_Source_(_Inout_cap_, (size), _Pre_valid_cap_(size) _Post_valid_) 966 #define _Inout_opt_cap_(size) _SAL1_1_Source_(_Inout_opt_cap_, (size), _Pre_opt_valid_cap_(size) _Post_valid_) 967 #define _Inout_bytecap_(size) _SAL1_1_Source_(_Inout_bytecap_, (size), _Pre_valid_bytecap_(size) _Post_valid_) 968 #define _Inout_opt_bytecap_(size) _SAL1_1_Source_(_Inout_opt_bytecap_, (size), _Pre_opt_valid_bytecap_(size) _Post_valid_) 969 970 #define _Inout_cap_c_(size) _SAL1_1_Source_(_Inout_cap_c_, (size), _Pre_valid_cap_c_(size) _Post_valid_) 971 #define _Inout_opt_cap_c_(size) _SAL1_1_Source_(_Inout_opt_cap_c_, (size), _Pre_opt_valid_cap_c_(size) _Post_valid_) 972 #define _Inout_bytecap_c_(size) _SAL1_1_Source_(_Inout_bytecap_c_, (size), _Pre_valid_bytecap_c_(size) _Post_valid_) 973 #define _Inout_opt_bytecap_c_(size) _SAL1_1_Source_(_Inout_opt_bytecap_c_, (size), _Pre_opt_valid_bytecap_c_(size) _Post_valid_) 974 975 #define _Inout_cap_x_(size) _SAL1_1_Source_(_Inout_cap_x_, (size), _Pre_valid_cap_x_(size) _Post_valid_) 976 #define _Inout_opt_cap_x_(size) _SAL1_1_Source_(_Inout_opt_cap_x_, (size), _Pre_opt_valid_cap_x_(size) _Post_valid_) 977 #define _Inout_bytecap_x_(size) _SAL1_1_Source_(_Inout_bytecap_x_, (size), _Pre_valid_bytecap_x_(size) _Post_valid_) 978 #define _Inout_opt_bytecap_x_(size) _SAL1_1_Source_(_Inout_opt_bytecap_x_, (size), _Pre_opt_valid_bytecap_x_(size) _Post_valid_) 979 980 // inout string buffers with writable size 981 // e.g. void AppendStr( _In_z_ const char* szFrom, _Inout_z_cap_(cchTo) char* szTo, size_t cchTo ); 982 #define _Inout_z_cap_(size) _SAL1_1_Source_(_Inout_z_cap_, (size), _Pre_z_cap_(size) _Post_z_) 983 #define _Inout_opt_z_cap_(size) _SAL1_1_Source_(_Inout_opt_z_cap_, (size), _Pre_opt_z_cap_(size) _Post_z_) 984 #define _Inout_z_bytecap_(size) _SAL1_1_Source_(_Inout_z_bytecap_, (size), _Pre_z_bytecap_(size) _Post_z_) 985 #define _Inout_opt_z_bytecap_(size) _SAL1_1_Source_(_Inout_opt_z_bytecap_, (size), _Pre_opt_z_bytecap_(size) _Post_z_) 986 987 #define _Inout_z_cap_c_(size) _SAL1_1_Source_(_Inout_z_cap_c_, (size), _Pre_z_cap_c_(size) _Post_z_) 988 #define _Inout_opt_z_cap_c_(size) _SAL1_1_Source_(_Inout_opt_z_cap_c_, (size), _Pre_opt_z_cap_c_(size) _Post_z_) 989 #define _Inout_z_bytecap_c_(size) _SAL1_1_Source_(_Inout_z_bytecap_c_, (size), _Pre_z_bytecap_c_(size) _Post_z_) 990 #define _Inout_opt_z_bytecap_c_(size) _SAL1_1_Source_(_Inout_opt_z_bytecap_c_, (size), _Pre_opt_z_bytecap_c_(size) _Post_z_) 991 992 #define _Inout_z_cap_x_(size) _SAL1_1_Source_(_Inout_z_cap_x_, (size), _Pre_z_cap_x_(size) _Post_z_) 993 #define _Inout_opt_z_cap_x_(size) _SAL1_1_Source_(_Inout_opt_z_cap_x_, (size), _Pre_opt_z_cap_x_(size) _Post_z_) 994 #define _Inout_z_bytecap_x_(size) _SAL1_1_Source_(_Inout_z_bytecap_x_, (size), _Pre_z_bytecap_x_(size) _Post_z_) 995 #define _Inout_opt_z_bytecap_x_(size) _SAL1_1_Source_(_Inout_opt_z_bytecap_x_, (size), _Pre_opt_z_bytecap_x_(size) _Post_z_) 996 997 998 // returning pointers to valid objects 999 #define _Ret_ _SAL1_1_Source_(_Ret_, (), _Ret_valid_) 1000 #define _Ret_opt_ _SAL1_1_Source_(_Ret_opt_, (), _Ret_opt_valid_) 1001 1002 // annotations to express 'boundedness' of integral value parameter 1003 #define _In_bound_ _SAL1_1_Source_(_In_bound_, (), _In_bound_impl_) 1004 #define _Out_bound_ _SAL1_1_Source_(_Out_bound_, (), _Out_bound_impl_) 1005 #define _Ret_bound_ _SAL1_1_Source_(_Ret_bound_, (), _Ret_bound_impl_) 1006 #define _Deref_in_bound_ _SAL1_1_Source_(_Deref_in_bound_, (), _Deref_in_bound_impl_) 1007 #define _Deref_out_bound_ _SAL1_1_Source_(_Deref_out_bound_, (), _Deref_out_bound_impl_) 1008 #define _Deref_inout_bound_ _SAL1_1_Source_(_Deref_inout_bound_, (), _Deref_in_bound_ _Deref_out_bound_) 1009 #define _Deref_ret_bound_ _SAL1_1_Source_(_Deref_ret_bound_, (), _Deref_ret_bound_impl_) 1010 1011 // e.g. HRESULT HrCreatePoint( _Deref_out_opt_ POINT** ppPT ); 1012 #define _Deref_out_ _SAL1_1_Source_(_Deref_out_, (), _Out_ _Deref_post_valid_) 1013 #define _Deref_out_opt_ _SAL1_1_Source_(_Deref_out_opt_, (), _Out_ _Deref_post_opt_valid_) 1014 #define _Deref_opt_out_ _SAL1_1_Source_(_Deref_opt_out_, (), _Out_opt_ _Deref_post_valid_) 1015 #define _Deref_opt_out_opt_ _SAL1_1_Source_(_Deref_opt_out_opt_, (), _Out_opt_ _Deref_post_opt_valid_) 1016 1017 // e.g. void CloneString( _In_z_ const WCHAR* wzFrom, _Deref_out_z_ WCHAR** pWzTo ); 1018 #define _Deref_out_z_ _SAL1_1_Source_(_Deref_out_z_, (), _Out_ _Deref_post_z_) 1019 #define _Deref_out_opt_z_ _SAL1_1_Source_(_Deref_out_opt_z_, (), _Out_ _Deref_post_opt_z_) 1020 #define _Deref_opt_out_z_ _SAL1_1_Source_(_Deref_opt_out_z_, (), _Out_opt_ _Deref_post_z_) 1021 #define _Deref_opt_out_opt_z_ _SAL1_1_Source_(_Deref_opt_out_opt_z_, (), _Out_opt_ _Deref_post_opt_z_) 1022 1023 // 1024 // _Deref_pre_ --- 1025 // 1026 // describing conditions for array elements of dereferenced pointer parameters that must be met before the call 1027 1028 // e.g. void SaveStringArray( _In_count_(cStrings) _Deref_pre_z_ const WCHAR* const rgpwch[] ); 1029 #define _Deref_pre_z_ _SAL1_1_Source_(_Deref_pre_z_, (), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__zterm_impl) _Pre_valid_impl_) 1030 #define _Deref_pre_opt_z_ _SAL1_1_Source_(_Deref_pre_opt_z_, (), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__zterm_impl) _Pre_valid_impl_) 1031 1032 // e.g. void FillInArrayOfStr32( _In_count_(cStrings) _Deref_pre_cap_c_(32) _Deref_post_z_ WCHAR* const rgpwch[] ); 1033 // buffer capacity is described by another parameter 1034 #define _Deref_pre_cap_(size) _SAL1_1_Source_(_Deref_pre_cap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_impl(size))) 1035 #define _Deref_pre_opt_cap_(size) _SAL1_1_Source_(_Deref_pre_opt_cap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_impl(size))) 1036 #define _Deref_pre_bytecap_(size) _SAL1_1_Source_(_Deref_pre_bytecap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_impl(size))) 1037 #define _Deref_pre_opt_bytecap_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_impl(size))) 1038 1039 // buffer capacity is described by a constant expression 1040 #define _Deref_pre_cap_c_(size) _SAL1_1_Source_(_Deref_pre_cap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_c_impl(size))) 1041 #define _Deref_pre_opt_cap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_cap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_c_impl(size))) 1042 #define _Deref_pre_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_bytecap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_c_impl(size))) 1043 #define _Deref_pre_opt_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_c_impl(size))) 1044 1045 // buffer capacity is described by a complex condition 1046 #define _Deref_pre_cap_x_(size) _SAL1_1_Source_(_Deref_pre_cap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_x_impl(size))) 1047 #define _Deref_pre_opt_cap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_cap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_x_impl(size))) 1048 #define _Deref_pre_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_bytecap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_x_impl(size))) 1049 #define _Deref_pre_opt_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_x_impl(size))) 1050 1051 // convenience macros for nullterminated buffers with given capacity 1052 #define _Deref_pre_z_cap_(size) _SAL1_1_Source_(_Deref_pre_z_cap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_impl(size)) _Pre_valid_impl_) 1053 #define _Deref_pre_opt_z_cap_(size) _SAL1_1_Source_(_Deref_pre_opt_z_cap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_impl(size)) _Pre_valid_impl_) 1054 #define _Deref_pre_z_bytecap_(size) _SAL1_1_Source_(_Deref_pre_z_bytecap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_impl(size)) _Pre_valid_impl_) 1055 #define _Deref_pre_opt_z_bytecap_(size) _SAL1_1_Source_(_Deref_pre_opt_z_bytecap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_impl(size)) _Pre_valid_impl_) 1056 1057 #define _Deref_pre_z_cap_c_(size) _SAL1_1_Source_(_Deref_pre_z_cap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_c_impl(size)) _Pre_valid_impl_) 1058 #define _Deref_pre_opt_z_cap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_z_cap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_c_impl(size)) _Pre_valid_impl_) 1059 #define _Deref_pre_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_z_bytecap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Pre_valid_impl_) 1060 #define _Deref_pre_opt_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_z_bytecap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Pre_valid_impl_) 1061 1062 #define _Deref_pre_z_cap_x_(size) _SAL1_1_Source_(_Deref_pre_z_cap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_x_impl(size)) _Pre_valid_impl_) 1063 #define _Deref_pre_opt_z_cap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_z_cap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__cap_x_impl(size)) _Pre_valid_impl_) 1064 #define _Deref_pre_z_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_z_bytecap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Pre_valid_impl_) 1065 #define _Deref_pre_opt_z_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_z_bytecap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Pre_valid_impl_) 1066 1067 // known capacity and valid but unknown readable extent 1068 #define _Deref_pre_valid_cap_(size) _SAL1_1_Source_(_Deref_pre_valid_cap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_impl(size)) _Pre_valid_impl_) 1069 #define _Deref_pre_opt_valid_cap_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_cap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_impl(size)) _Pre_valid_impl_) 1070 #define _Deref_pre_valid_bytecap_(size) _SAL1_1_Source_(_Deref_pre_valid_bytecap_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_impl(size)) _Pre_valid_impl_) 1071 #define _Deref_pre_opt_valid_bytecap_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_bytecap_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_impl(size)) _Pre_valid_impl_) 1072 1073 #define _Deref_pre_valid_cap_c_(size) _SAL1_1_Source_(_Deref_pre_valid_cap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_c_impl(size)) _Pre_valid_impl_) 1074 #define _Deref_pre_opt_valid_cap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_cap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_c_impl(size)) _Pre_valid_impl_) 1075 #define _Deref_pre_valid_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_valid_bytecap_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_c_impl(size)) _Pre_valid_impl_) 1076 #define _Deref_pre_opt_valid_bytecap_c_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_bytecap_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_c_impl(size)) _Pre_valid_impl_) 1077 1078 #define _Deref_pre_valid_cap_x_(size) _SAL1_1_Source_(_Deref_pre_valid_cap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__cap_x_impl(size)) _Pre_valid_impl_) 1079 #define _Deref_pre_opt_valid_cap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_cap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__cap_x_impl(size)) _Pre_valid_impl_) 1080 #define _Deref_pre_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_valid_bytecap_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecap_x_impl(size)) _Pre_valid_impl_) 1081 #define _Deref_pre_opt_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_pre_opt_valid_bytecap_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecap_x_impl(size)) _Pre_valid_impl_) 1082 1083 // e.g. void SaveMatrix( _In_count_(n) _Deref_pre_count_(n) const Elem** matrix, size_t n ); 1084 // valid buffer extent is described by another parameter 1085 #define _Deref_pre_count_(size) _SAL1_1_Source_(_Deref_pre_count_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__count_impl(size)) _Pre_valid_impl_) 1086 #define _Deref_pre_opt_count_(size) _SAL1_1_Source_(_Deref_pre_opt_count_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__count_impl(size)) _Pre_valid_impl_) 1087 #define _Deref_pre_bytecount_(size) _SAL1_1_Source_(_Deref_pre_bytecount_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecount_impl(size)) _Pre_valid_impl_) 1088 #define _Deref_pre_opt_bytecount_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecount_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecount_impl(size)) _Pre_valid_impl_) 1089 1090 // valid buffer extent is described by a constant expression 1091 #define _Deref_pre_count_c_(size) _SAL1_1_Source_(_Deref_pre_count_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__count_c_impl(size)) _Pre_valid_impl_) 1092 #define _Deref_pre_opt_count_c_(size) _SAL1_1_Source_(_Deref_pre_opt_count_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__count_c_impl(size)) _Pre_valid_impl_) 1093 #define _Deref_pre_bytecount_c_(size) _SAL1_1_Source_(_Deref_pre_bytecount_c_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecount_c_impl(size)) _Pre_valid_impl_) 1094 #define _Deref_pre_opt_bytecount_c_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecount_c_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecount_c_impl(size)) _Pre_valid_impl_) 1095 1096 // valid buffer extent is described by a complex expression 1097 #define _Deref_pre_count_x_(size) _SAL1_1_Source_(_Deref_pre_count_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__count_x_impl(size)) _Pre_valid_impl_) 1098 #define _Deref_pre_opt_count_x_(size) _SAL1_1_Source_(_Deref_pre_opt_count_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__count_x_impl(size)) _Pre_valid_impl_) 1099 #define _Deref_pre_bytecount_x_(size) _SAL1_1_Source_(_Deref_pre_bytecount_x_, (size), _Deref_pre1_impl_(__notnull_impl_notref) _Deref_pre1_impl_(__bytecount_x_impl(size)) _Pre_valid_impl_) 1100 #define _Deref_pre_opt_bytecount_x_(size) _SAL1_1_Source_(_Deref_pre_opt_bytecount_x_, (size), _Deref_pre1_impl_(__maybenull_impl_notref) _Deref_pre1_impl_(__bytecount_x_impl(size)) _Pre_valid_impl_) 1101 1102 // e.g. void PrintStringArray( _In_count_(cElems) _Deref_pre_valid_ LPCSTR rgStr[], size_t cElems ); 1103 #define _Deref_pre_valid_ _SAL1_1_Source_(_Deref_pre_valid_, (), _Deref_pre1_impl_(__notnull_impl_notref) _Pre_valid_impl_) 1104 #define _Deref_pre_opt_valid_ _SAL1_1_Source_(_Deref_pre_opt_valid_, (), _Deref_pre1_impl_(__maybenull_impl_notref) _Pre_valid_impl_) 1105 #define _Deref_pre_invalid_ _SAL1_1_Source_(_Deref_pre_invalid_, (), _Deref_pre1_impl_(__notvalid_impl)) 1106 1107 #define _Deref_pre_notnull_ _SAL1_1_Source_(_Deref_pre_notnull_, (), _Deref_pre1_impl_(__notnull_impl_notref)) 1108 #define _Deref_pre_maybenull_ _SAL1_1_Source_(_Deref_pre_maybenull_, (), _Deref_pre1_impl_(__maybenull_impl_notref)) 1109 #define _Deref_pre_null_ _SAL1_1_Source_(_Deref_pre_null_, (), _Deref_pre1_impl_(__null_impl_notref)) 1110 1111 // restrict access rights 1112 #define _Deref_pre_readonly_ _SAL1_1_Source_(_Deref_pre_readonly_, (), _Deref_pre1_impl_(__readaccess_impl_notref)) 1113 #define _Deref_pre_writeonly_ _SAL1_1_Source_(_Deref_pre_writeonly_, (), _Deref_pre1_impl_(__writeaccess_impl_notref)) 1114 1115 // 1116 // _Deref_post_ --- 1117 // 1118 // describing conditions for array elements or dereferenced pointer parameters that hold after the call 1119 1120 // e.g. void CloneString( _In_z_ const Wchar_t* wzIn _Out_ _Deref_post_z_ WCHAR** pWzOut ); 1121 #define _Deref_post_z_ _SAL1_1_Source_(_Deref_post_z_, (), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__zterm_impl) _Post_valid_impl_) 1122 #define _Deref_post_opt_z_ _SAL1_1_Source_(_Deref_post_opt_z_, (), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__zterm_impl) _Post_valid_impl_) 1123 1124 // e.g. HRESULT HrAllocateMemory( size_t cb, _Out_ _Deref_post_bytecap_(cb) void** ppv ); 1125 // buffer capacity is described by another parameter 1126 #define _Deref_post_cap_(size) _SAL1_1_Source_(_Deref_post_cap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_impl(size))) 1127 #define _Deref_post_opt_cap_(size) _SAL1_1_Source_(_Deref_post_opt_cap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_impl(size))) 1128 #define _Deref_post_bytecap_(size) _SAL1_1_Source_(_Deref_post_bytecap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_impl(size))) 1129 #define _Deref_post_opt_bytecap_(size) _SAL1_1_Source_(_Deref_post_opt_bytecap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_impl(size))) 1130 1131 // buffer capacity is described by a constant expression 1132 #define _Deref_post_cap_c_(size) _SAL1_1_Source_(_Deref_post_cap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_c_impl(size))) 1133 #define _Deref_post_opt_cap_c_(size) _SAL1_1_Source_(_Deref_post_opt_cap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_c_impl(size))) 1134 #define _Deref_post_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_bytecap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_c_impl(size))) 1135 #define _Deref_post_opt_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_opt_bytecap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_c_impl(size))) 1136 1137 // buffer capacity is described by a complex expression 1138 #define _Deref_post_cap_x_(size) _SAL1_1_Source_(_Deref_post_cap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_x_impl(size))) 1139 #define _Deref_post_opt_cap_x_(size) _SAL1_1_Source_(_Deref_post_opt_cap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_x_impl(size))) 1140 #define _Deref_post_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_bytecap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_x_impl(size))) 1141 #define _Deref_post_opt_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_opt_bytecap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_x_impl(size))) 1142 1143 // convenience macros for nullterminated buffers with given capacity 1144 #define _Deref_post_z_cap_(size) _SAL1_1_Source_(_Deref_post_z_cap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_impl(size)) _Post_valid_impl_) 1145 #define _Deref_post_opt_z_cap_(size) _SAL1_1_Source_(_Deref_post_opt_z_cap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_impl(size)) _Post_valid_impl_) 1146 #define _Deref_post_z_bytecap_(size) _SAL1_1_Source_(_Deref_post_z_bytecap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_impl(size)) _Post_valid_impl_) 1147 #define _Deref_post_opt_z_bytecap_(size) _SAL1_1_Source_(_Deref_post_opt_z_bytecap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_impl(size)) _Post_valid_impl_) 1148 1149 #define _Deref_post_z_cap_c_(size) _SAL1_1_Source_(_Deref_post_z_cap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_c_impl(size)) _Post_valid_impl_) 1150 #define _Deref_post_opt_z_cap_c_(size) _SAL1_1_Source_(_Deref_post_opt_z_cap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_c_impl(size)) _Post_valid_impl_) 1151 #define _Deref_post_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_z_bytecap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Post_valid_impl_) 1152 #define _Deref_post_opt_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_opt_z_bytecap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Post_valid_impl_) 1153 1154 #define _Deref_post_z_cap_x_(size) _SAL1_1_Source_(_Deref_post_z_cap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_x_impl(size)) _Post_valid_impl_) 1155 #define _Deref_post_opt_z_cap_x_(size) _SAL1_1_Source_(_Deref_post_opt_z_cap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__cap_x_impl(size)) _Post_valid_impl_) 1156 #define _Deref_post_z_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_z_bytecap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Post_valid_impl_) 1157 #define _Deref_post_opt_z_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_opt_z_bytecap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Post_valid_impl_) 1158 1159 // known capacity and valid but unknown readable extent 1160 #define _Deref_post_valid_cap_(size) _SAL1_1_Source_(_Deref_post_valid_cap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_impl(size)) _Post_valid_impl_) 1161 #define _Deref_post_opt_valid_cap_(size) _SAL1_1_Source_(_Deref_post_opt_valid_cap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_impl(size)) _Post_valid_impl_) 1162 #define _Deref_post_valid_bytecap_(size) _SAL1_1_Source_(_Deref_post_valid_bytecap_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_impl(size)) _Post_valid_impl_) 1163 #define _Deref_post_opt_valid_bytecap_(size) _SAL1_1_Source_(_Deref_post_opt_valid_bytecap_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_impl(size)) _Post_valid_impl_) 1164 1165 #define _Deref_post_valid_cap_c_(size) _SAL1_1_Source_(_Deref_post_valid_cap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_c_impl(size)) _Post_valid_impl_) 1166 #define _Deref_post_opt_valid_cap_c_(size) _SAL1_1_Source_(_Deref_post_opt_valid_cap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_c_impl(size)) _Post_valid_impl_) 1167 #define _Deref_post_valid_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_valid_bytecap_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_c_impl(size)) _Post_valid_impl_) 1168 #define _Deref_post_opt_valid_bytecap_c_(size) _SAL1_1_Source_(_Deref_post_opt_valid_bytecap_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_c_impl(size)) _Post_valid_impl_) 1169 1170 #define _Deref_post_valid_cap_x_(size) _SAL1_1_Source_(_Deref_post_valid_cap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__cap_x_impl(size)) _Post_valid_impl_) 1171 #define _Deref_post_opt_valid_cap_x_(size) _SAL1_1_Source_(_Deref_post_opt_valid_cap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__cap_x_impl(size)) _Post_valid_impl_) 1172 #define _Deref_post_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_valid_bytecap_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecap_x_impl(size)) _Post_valid_impl_) 1173 #define _Deref_post_opt_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_post_opt_valid_bytecap_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecap_x_impl(size)) _Post_valid_impl_) 1174 1175 // e.g. HRESULT HrAllocateZeroInitializedMemory( size_t cb, _Out_ _Deref_post_bytecount_(cb) void** ppv ); 1176 // valid buffer extent is described by another parameter 1177 #define _Deref_post_count_(size) _SAL1_1_Source_(_Deref_post_count_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__count_impl(size)) _Post_valid_impl_) 1178 #define _Deref_post_opt_count_(size) _SAL1_1_Source_(_Deref_post_opt_count_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__count_impl(size)) _Post_valid_impl_) 1179 #define _Deref_post_bytecount_(size) _SAL1_1_Source_(_Deref_post_bytecount_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecount_impl(size)) _Post_valid_impl_) 1180 #define _Deref_post_opt_bytecount_(size) _SAL1_1_Source_(_Deref_post_opt_bytecount_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecount_impl(size)) _Post_valid_impl_) 1181 1182 // buffer capacity is described by a constant expression 1183 #define _Deref_post_count_c_(size) _SAL1_1_Source_(_Deref_post_count_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__count_c_impl(size)) _Post_valid_impl_) 1184 #define _Deref_post_opt_count_c_(size) _SAL1_1_Source_(_Deref_post_opt_count_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__count_c_impl(size)) _Post_valid_impl_) 1185 #define _Deref_post_bytecount_c_(size) _SAL1_1_Source_(_Deref_post_bytecount_c_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecount_c_impl(size)) _Post_valid_impl_) 1186 #define _Deref_post_opt_bytecount_c_(size) _SAL1_1_Source_(_Deref_post_opt_bytecount_c_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecount_c_impl(size)) _Post_valid_impl_) 1187 1188 // buffer capacity is described by a complex expression 1189 #define _Deref_post_count_x_(size) _SAL1_1_Source_(_Deref_post_count_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__count_x_impl(size)) _Post_valid_impl_) 1190 #define _Deref_post_opt_count_x_(size) _SAL1_1_Source_(_Deref_post_opt_count_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__count_x_impl(size)) _Post_valid_impl_) 1191 #define _Deref_post_bytecount_x_(size) _SAL1_1_Source_(_Deref_post_bytecount_x_, (size), _Deref_post1_impl_(__notnull_impl_notref) _Deref_post1_impl_(__bytecount_x_impl(size)) _Post_valid_impl_) 1192 #define _Deref_post_opt_bytecount_x_(size) _SAL1_1_Source_(_Deref_post_opt_bytecount_x_, (size), _Deref_post1_impl_(__maybenull_impl_notref) _Deref_post1_impl_(__bytecount_x_impl(size)) _Post_valid_impl_) 1193 1194 // e.g. void GetStrings( _Out_count_(cElems) _Deref_post_valid_ LPSTR const rgStr[], size_t cElems ); 1195 #define _Deref_post_valid_ _SAL1_1_Source_(_Deref_post_valid_, (), _Deref_post1_impl_(__notnull_impl_notref) _Post_valid_impl_) 1196 #define _Deref_post_opt_valid_ _SAL1_1_Source_(_Deref_post_opt_valid_, (), _Deref_post1_impl_(__maybenull_impl_notref) _Post_valid_impl_) 1197 1198 #define _Deref_post_notnull_ _SAL1_1_Source_(_Deref_post_notnull_, (), _Deref_post1_impl_(__notnull_impl_notref)) 1199 #define _Deref_post_maybenull_ _SAL1_1_Source_(_Deref_post_maybenull_, (), _Deref_post1_impl_(__maybenull_impl_notref)) 1200 #define _Deref_post_null_ _SAL1_1_Source_(_Deref_post_null_, (), _Deref_post1_impl_(__null_impl_notref)) 1201 1202 // 1203 // _Deref_ret_ --- 1204 // 1205 1206 #define _Deref_ret_z_ _SAL1_1_Source_(_Deref_ret_z_, (), _Deref_ret1_impl_(__notnull_impl_notref) _Deref_ret1_impl_(__zterm_impl)) 1207 #define _Deref_ret_opt_z_ _SAL1_1_Source_(_Deref_ret_opt_z_, (), _Deref_ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__zterm_impl)) 1208 1209 // 1210 // special _Deref_ --- 1211 // 1212 #define _Deref2_pre_readonly_ _SAL1_1_Source_(_Deref2_pre_readonly_, (), _Deref2_pre1_impl_(__readaccess_impl_notref)) 1213 1214 // 1215 // _Ret_ --- 1216 // 1217 1218 // e.g. _Ret_opt_valid_ LPSTR void* CloneSTR( _Pre_valid_ LPSTR src ); 1219 #define _Ret_opt_valid_ _SAL1_1_Source_(_Ret_opt_valid_, (), _Ret1_impl_(__maybenull_impl_notref) _Ret_valid_impl_) 1220 #define _Ret_opt_z_ _SAL1_1_Source_(_Ret_opt_z_, (), _Ret2_impl_(__maybenull_impl,__zterm_impl) _Ret_valid_impl_) 1221 1222 // e.g. _Ret_opt_bytecap_(cb) void* AllocateMemory( size_t cb ); 1223 // Buffer capacity is described by another parameter 1224 #define _Ret_cap_(size) _SAL1_1_Source_(_Ret_cap_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__cap_impl(size))) 1225 #define _Ret_opt_cap_(size) _SAL1_1_Source_(_Ret_opt_cap_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__cap_impl(size))) 1226 #define _Ret_bytecap_(size) _SAL1_1_Source_(_Ret_bytecap_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecap_impl(size))) 1227 #define _Ret_opt_bytecap_(size) _SAL1_1_Source_(_Ret_opt_bytecap_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecap_impl(size))) 1228 1229 // Buffer capacity is described by a constant expression 1230 #define _Ret_cap_c_(size) _SAL1_1_Source_(_Ret_cap_c_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__cap_c_impl(size))) 1231 #define _Ret_opt_cap_c_(size) _SAL1_1_Source_(_Ret_opt_cap_c_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__cap_c_impl(size))) 1232 #define _Ret_bytecap_c_(size) _SAL1_1_Source_(_Ret_bytecap_c_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecap_c_impl(size))) 1233 #define _Ret_opt_bytecap_c_(size) _SAL1_1_Source_(_Ret_opt_bytecap_c_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecap_c_impl(size))) 1234 1235 // Buffer capacity is described by a complex condition 1236 #define _Ret_cap_x_(size) _SAL1_1_Source_(_Ret_cap_x_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__cap_x_impl(size))) 1237 #define _Ret_opt_cap_x_(size) _SAL1_1_Source_(_Ret_opt_cap_x_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__cap_x_impl(size))) 1238 #define _Ret_bytecap_x_(size) _SAL1_1_Source_(_Ret_bytecap_x_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecap_x_impl(size))) 1239 #define _Ret_opt_bytecap_x_(size) _SAL1_1_Source_(_Ret_opt_bytecap_x_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecap_x_impl(size))) 1240 1241 // return value is nullterminated and capacity is given by another parameter 1242 #define _Ret_z_cap_(size) _SAL1_1_Source_(_Ret_z_cap_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret2_impl_(__zterm_impl,__cap_impl(size)) _Ret_valid_impl_) 1243 #define _Ret_opt_z_cap_(size) _SAL1_1_Source_(_Ret_opt_z_cap_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret2_impl_(__zterm_impl,__cap_impl(size)) _Ret_valid_impl_) 1244 #define _Ret_z_bytecap_(size) _SAL1_1_Source_(_Ret_z_bytecap_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret2_impl_(__zterm_impl,__bytecap_impl(size)) _Ret_valid_impl_) 1245 #define _Ret_opt_z_bytecap_(size) _SAL1_1_Source_(_Ret_opt_z_bytecap_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret2_impl_(__zterm_impl,__bytecap_impl(size)) _Ret_valid_impl_) 1246 1247 // e.g. _Ret_opt_bytecount_(cb) void* AllocateZeroInitializedMemory( size_t cb ); 1248 // Valid Buffer extent is described by another parameter 1249 #define _Ret_count_(size) _SAL1_1_Source_(_Ret_count_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__count_impl(size)) _Ret_valid_impl_) 1250 #define _Ret_opt_count_(size) _SAL1_1_Source_(_Ret_opt_count_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__count_impl(size)) _Ret_valid_impl_) 1251 #define _Ret_bytecount_(size) _SAL1_1_Source_(_Ret_bytecount_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecount_impl(size)) _Ret_valid_impl_) 1252 #define _Ret_opt_bytecount_(size) _SAL1_1_Source_(_Ret_opt_bytecount_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecount_impl(size)) _Ret_valid_impl_) 1253 1254 // Valid Buffer extent is described by a constant expression 1255 #define _Ret_count_c_(size) _SAL1_1_Source_(_Ret_count_c_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__count_c_impl(size)) _Ret_valid_impl_) 1256 #define _Ret_opt_count_c_(size) _SAL1_1_Source_(_Ret_opt_count_c_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__count_c_impl(size)) _Ret_valid_impl_) 1257 #define _Ret_bytecount_c_(size) _SAL1_1_Source_(_Ret_bytecount_c_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecount_c_impl(size)) _Ret_valid_impl_) 1258 #define _Ret_opt_bytecount_c_(size) _SAL1_1_Source_(_Ret_opt_bytecount_c_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecount_c_impl(size)) _Ret_valid_impl_) 1259 1260 // Valid Buffer extent is described by a complex expression 1261 #define _Ret_count_x_(size) _SAL1_1_Source_(_Ret_count_x_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__count_x_impl(size)) _Ret_valid_impl_) 1262 #define _Ret_opt_count_x_(size) _SAL1_1_Source_(_Ret_opt_count_x_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__count_x_impl(size)) _Ret_valid_impl_) 1263 #define _Ret_bytecount_x_(size) _SAL1_1_Source_(_Ret_bytecount_x_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret1_impl_(__bytecount_x_impl(size)) _Ret_valid_impl_) 1264 #define _Ret_opt_bytecount_x_(size) _SAL1_1_Source_(_Ret_opt_bytecount_x_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret1_impl_(__bytecount_x_impl(size)) _Ret_valid_impl_) 1265 1266 // return value is nullterminated and length is given by another parameter 1267 #define _Ret_z_count_(size) _SAL1_1_Source_(_Ret_z_count_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret2_impl_(__zterm_impl,__count_impl(size)) _Ret_valid_impl_) 1268 #define _Ret_opt_z_count_(size) _SAL1_1_Source_(_Ret_opt_z_count_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret2_impl_(__zterm_impl,__count_impl(size)) _Ret_valid_impl_) 1269 #define _Ret_z_bytecount_(size) _SAL1_1_Source_(_Ret_z_bytecount_, (size), _Ret1_impl_(__notnull_impl_notref) _Ret2_impl_(__zterm_impl,__bytecount_impl(size)) _Ret_valid_impl_) 1270 #define _Ret_opt_z_bytecount_(size) _SAL1_1_Source_(_Ret_opt_z_bytecount_, (size), _Ret1_impl_(__maybenull_impl_notref) _Ret2_impl_(__zterm_impl,__bytecount_impl(size)) _Ret_valid_impl_) 1271 1272 1273 // _Pre_ annotations --- 1274 #define _Pre_opt_z_ _SAL1_1_Source_(_Pre_opt_z_, (), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__zterm_impl) _Pre_valid_impl_) 1275 1276 // restrict access rights 1277 #define _Pre_readonly_ _SAL1_1_Source_(_Pre_readonly_, (), _Pre1_impl_(__readaccess_impl_notref)) 1278 #define _Pre_writeonly_ _SAL1_1_Source_(_Pre_writeonly_, (), _Pre1_impl_(__writeaccess_impl_notref)) 1279 1280 // e.g. void FreeMemory( _Pre_bytecap_(cb) _Post_ptr_invalid_ void* pv, size_t cb ); 1281 // buffer capacity described by another parameter 1282 #define _Pre_cap_(size) _SAL1_1_Source_(_Pre_cap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_impl(size))) 1283 #define _Pre_opt_cap_(size) _SAL1_1_Source_(_Pre_opt_cap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_impl(size))) 1284 #define _Pre_bytecap_(size) _SAL1_1_Source_(_Pre_bytecap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_impl(size))) 1285 #define _Pre_opt_bytecap_(size) _SAL1_1_Source_(_Pre_opt_bytecap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_impl(size))) 1286 1287 // buffer capacity described by a constant expression 1288 #define _Pre_cap_c_(size) _SAL1_1_Source_(_Pre_cap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_c_impl(size))) 1289 #define _Pre_opt_cap_c_(size) _SAL1_1_Source_(_Pre_opt_cap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_c_impl(size))) 1290 #define _Pre_bytecap_c_(size) _SAL1_1_Source_(_Pre_bytecap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_c_impl(size))) 1291 #define _Pre_opt_bytecap_c_(size) _SAL1_1_Source_(_Pre_opt_bytecap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_c_impl(size))) 1292 #define _Pre_cap_c_one_ _SAL1_1_Source_(_Pre_cap_c_one_, (), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_c_one_notref_impl)) 1293 #define _Pre_opt_cap_c_one_ _SAL1_1_Source_(_Pre_opt_cap_c_one_, (), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_c_one_notref_impl)) 1294 1295 // buffer capacity is described by another parameter multiplied by a constant expression 1296 #define _Pre_cap_m_(mult,size) _SAL1_1_Source_(_Pre_cap_m_, (mult,size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__mult_impl(mult,size))) 1297 #define _Pre_opt_cap_m_(mult,size) _SAL1_1_Source_(_Pre_opt_cap_m_, (mult,size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__mult_impl(mult,size))) 1298 1299 // buffer capacity described by size of other buffer, only used by dangerous legacy APIs 1300 // e.g. int strcpy(_Pre_cap_for_(src) char* dst, const char* src); 1301 #define _Pre_cap_for_(param) _SAL1_1_Source_(_Pre_cap_for_, (param), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_for_impl(param))) 1302 #define _Pre_opt_cap_for_(param) _SAL1_1_Source_(_Pre_opt_cap_for_, (param), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_for_impl(param))) 1303 1304 // buffer capacity described by a complex condition 1305 #define _Pre_cap_x_(size) _SAL1_1_Source_(_Pre_cap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_x_impl(size))) 1306 #define _Pre_opt_cap_x_(size) _SAL1_1_Source_(_Pre_opt_cap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_x_impl(size))) 1307 #define _Pre_bytecap_x_(size) _SAL1_1_Source_(_Pre_bytecap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_x_impl(size))) 1308 #define _Pre_opt_bytecap_x_(size) _SAL1_1_Source_(_Pre_opt_bytecap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_x_impl(size))) 1309 1310 // buffer capacity described by the difference to another pointer parameter 1311 #define _Pre_ptrdiff_cap_(ptr) _SAL1_1_Source_(_Pre_ptrdiff_cap_, (ptr), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_x_impl(__ptrdiff(ptr)))) 1312 #define _Pre_opt_ptrdiff_cap_(ptr) _SAL1_1_Source_(_Pre_opt_ptrdiff_cap_, (ptr), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_x_impl(__ptrdiff(ptr)))) 1313 1314 // e.g. void AppendStr( _Pre_z_ const char* szFrom, _Pre_z_cap_(cchTo) _Post_z_ char* szTo, size_t cchTo ); 1315 #define _Pre_z_cap_(size) _SAL1_1_Source_(_Pre_z_cap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_impl(size)) _Pre_valid_impl_) 1316 #define _Pre_opt_z_cap_(size) _SAL1_1_Source_(_Pre_opt_z_cap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_impl(size)) _Pre_valid_impl_) 1317 #define _Pre_z_bytecap_(size) _SAL1_1_Source_(_Pre_z_bytecap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_impl(size)) _Pre_valid_impl_) 1318 #define _Pre_opt_z_bytecap_(size) _SAL1_1_Source_(_Pre_opt_z_bytecap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_impl(size)) _Pre_valid_impl_) 1319 1320 #define _Pre_z_cap_c_(size) _SAL1_1_Source_(_Pre_z_cap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_c_impl(size)) _Pre_valid_impl_) 1321 #define _Pre_opt_z_cap_c_(size) _SAL1_1_Source_(_Pre_opt_z_cap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_c_impl(size)) _Pre_valid_impl_) 1322 #define _Pre_z_bytecap_c_(size) _SAL1_1_Source_(_Pre_z_bytecap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Pre_valid_impl_) 1323 #define _Pre_opt_z_bytecap_c_(size) _SAL1_1_Source_(_Pre_opt_z_bytecap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_c_impl(size)) _Pre_valid_impl_) 1324 1325 #define _Pre_z_cap_x_(size) _SAL1_1_Source_(_Pre_z_cap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_x_impl(size)) _Pre_valid_impl_) 1326 #define _Pre_opt_z_cap_x_(size) _SAL1_1_Source_(_Pre_opt_z_cap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__cap_x_impl(size)) _Pre_valid_impl_) 1327 #define _Pre_z_bytecap_x_(size) _SAL1_1_Source_(_Pre_z_bytecap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Pre_valid_impl_) 1328 #define _Pre_opt_z_bytecap_x_(size) _SAL1_1_Source_(_Pre_opt_z_bytecap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre2_impl_(__zterm_impl,__bytecap_x_impl(size)) _Pre_valid_impl_) 1329 1330 // known capacity and valid but unknown readable extent 1331 #define _Pre_valid_cap_(size) _SAL1_1_Source_(_Pre_valid_cap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_impl(size)) _Pre_valid_impl_) 1332 #define _Pre_opt_valid_cap_(size) _SAL1_1_Source_(_Pre_opt_valid_cap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_impl(size)) _Pre_valid_impl_) 1333 #define _Pre_valid_bytecap_(size) _SAL1_1_Source_(_Pre_valid_bytecap_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_impl(size)) _Pre_valid_impl_) 1334 #define _Pre_opt_valid_bytecap_(size) _SAL1_1_Source_(_Pre_opt_valid_bytecap_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_impl(size)) _Pre_valid_impl_) 1335 1336 #define _Pre_valid_cap_c_(size) _SAL1_1_Source_(_Pre_valid_cap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_c_impl(size)) _Pre_valid_impl_) 1337 #define _Pre_opt_valid_cap_c_(size) _SAL1_1_Source_(_Pre_opt_valid_cap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_c_impl(size)) _Pre_valid_impl_) 1338 #define _Pre_valid_bytecap_c_(size) _SAL1_1_Source_(_Pre_valid_bytecap_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_c_impl(size)) _Pre_valid_impl_) 1339 #define _Pre_opt_valid_bytecap_c_(size) _SAL1_1_Source_(_Pre_opt_valid_bytecap_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_c_impl(size)) _Pre_valid_impl_) 1340 1341 #define _Pre_valid_cap_x_(size) _SAL1_1_Source_(_Pre_valid_cap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_x_impl(size)) _Pre_valid_impl_) 1342 #define _Pre_opt_valid_cap_x_(size) _SAL1_1_Source_(_Pre_opt_valid_cap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_x_impl(size)) _Pre_valid_impl_) 1343 #define _Pre_valid_bytecap_x_(size) _SAL1_1_Source_(_Pre_valid_bytecap_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecap_x_impl(size)) _Pre_valid_impl_) 1344 #define _Pre_opt_valid_bytecap_x_(size) _SAL1_1_Source_(_Pre_opt_valid_bytecap_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecap_x_impl(size)) _Pre_valid_impl_) 1345 1346 // e.g. void AppendCharRange( _Pre_count_(cchFrom) const char* rgFrom, size_t cchFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); 1347 // Valid buffer extent described by another parameter 1348 #define _Pre_count_(size) _SAL1_1_Source_(_Pre_count_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__count_impl(size)) _Pre_valid_impl_) 1349 #define _Pre_opt_count_(size) _SAL1_1_Source_(_Pre_opt_count_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__count_impl(size)) _Pre_valid_impl_) 1350 #define _Pre_bytecount_(size) _SAL1_1_Source_(_Pre_bytecount_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecount_impl(size)) _Pre_valid_impl_) 1351 #define _Pre_opt_bytecount_(size) _SAL1_1_Source_(_Pre_opt_bytecount_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecount_impl(size)) _Pre_valid_impl_) 1352 1353 // Valid buffer extent described by a constant expression 1354 #define _Pre_count_c_(size) _SAL1_1_Source_(_Pre_count_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__count_c_impl(size)) _Pre_valid_impl_) 1355 #define _Pre_opt_count_c_(size) _SAL1_1_Source_(_Pre_opt_count_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__count_c_impl(size)) _Pre_valid_impl_) 1356 #define _Pre_bytecount_c_(size) _SAL1_1_Source_(_Pre_bytecount_c_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecount_c_impl(size)) _Pre_valid_impl_) 1357 #define _Pre_opt_bytecount_c_(size) _SAL1_1_Source_(_Pre_opt_bytecount_c_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecount_c_impl(size)) _Pre_valid_impl_) 1358 1359 // Valid buffer extent described by a complex expression 1360 #define _Pre_count_x_(size) _SAL1_1_Source_(_Pre_count_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__count_x_impl(size)) _Pre_valid_impl_) 1361 #define _Pre_opt_count_x_(size) _SAL1_1_Source_(_Pre_opt_count_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__count_x_impl(size)) _Pre_valid_impl_) 1362 #define _Pre_bytecount_x_(size) _SAL1_1_Source_(_Pre_bytecount_x_, (size), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__bytecount_x_impl(size)) _Pre_valid_impl_) 1363 #define _Pre_opt_bytecount_x_(size) _SAL1_1_Source_(_Pre_opt_bytecount_x_, (size), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__bytecount_x_impl(size)) _Pre_valid_impl_) 1364 1365 // Valid buffer extent described by the difference to another pointer parameter 1366 #define _Pre_ptrdiff_count_(ptr) _SAL1_1_Source_(_Pre_ptrdiff_count_, (ptr), _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__count_x_impl(__ptrdiff(ptr))) _Pre_valid_impl_) 1367 #define _Pre_opt_ptrdiff_count_(ptr) _SAL1_1_Source_(_Pre_opt_ptrdiff_count_, (ptr), _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__count_x_impl(__ptrdiff(ptr))) _Pre_valid_impl_) 1368 1369 1370 // char * strncpy(_Out_cap_(_Count) _Post_maybez_ char * _Dest, _In_z_ const char * _Source, _In_ size_t _Count) 1371 // buffer maybe zero-terminated after the call 1372 #define _Post_maybez_ _SAL1_1_Source_(_Post_maybez_, (), _Post1_impl_(__maybezterm_impl)) 1373 1374 // e.g. SIZE_T HeapSize( _In_ HANDLE hHeap, DWORD dwFlags, _Pre_notnull_ _Post_bytecap_(return) LPCVOID lpMem ); 1375 #define _Post_cap_(size) _SAL1_1_Source_(_Post_cap_, (size), _Post1_impl_(__cap_impl(size))) 1376 #define _Post_bytecap_(size) _SAL1_1_Source_(_Post_bytecap_, (size), _Post1_impl_(__bytecap_impl(size))) 1377 1378 // e.g. int strlen( _In_z_ _Post_count_(return+1) const char* sz ); 1379 #define _Post_count_(size) _SAL1_1_Source_(_Post_count_, (size), _Post1_impl_(__count_impl(size)) _Post_valid_impl_) 1380 #define _Post_bytecount_(size) _SAL1_1_Source_(_Post_bytecount_, (size), _Post1_impl_(__bytecount_impl(size)) _Post_valid_impl_) 1381 #define _Post_count_c_(size) _SAL1_1_Source_(_Post_count_c_, (size), _Post1_impl_(__count_c_impl(size)) _Post_valid_impl_) 1382 #define _Post_bytecount_c_(size) _SAL1_1_Source_(_Post_bytecount_c_, (size), _Post1_impl_(__bytecount_c_impl(size)) _Post_valid_impl_) 1383 #define _Post_count_x_(size) _SAL1_1_Source_(_Post_count_x_, (size), _Post1_impl_(__count_x_impl(size)) _Post_valid_impl_) 1384 #define _Post_bytecount_x_(size) _SAL1_1_Source_(_Post_bytecount_x_, (size), _Post1_impl_(__bytecount_x_impl(size)) _Post_valid_impl_) 1385 1386 // e.g. size_t CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_count_(return+1) char* szFrom, size_t cchFrom ); 1387 #define _Post_z_count_(size) _SAL1_1_Source_(_Post_z_count_, (size), _Post2_impl_(__zterm_impl,__count_impl(size)) _Post_valid_impl_) 1388 #define _Post_z_bytecount_(size) _SAL1_1_Source_(_Post_z_bytecount_, (size), _Post2_impl_(__zterm_impl,__bytecount_impl(size)) _Post_valid_impl_) 1389 #define _Post_z_count_c_(size) _SAL1_1_Source_(_Post_z_count_c_, (size), _Post2_impl_(__zterm_impl,__count_c_impl(size)) _Post_valid_impl_) 1390 #define _Post_z_bytecount_c_(size) _SAL1_1_Source_(_Post_z_bytecount_c_, (size), _Post2_impl_(__zterm_impl,__bytecount_c_impl(size)) _Post_valid_impl_) 1391 #define _Post_z_count_x_(size) _SAL1_1_Source_(_Post_z_count_x_, (size), _Post2_impl_(__zterm_impl,__count_x_impl(size)) _Post_valid_impl_) 1392 #define _Post_z_bytecount_x_(size) _SAL1_1_Source_(_Post_z_bytecount_x_, (size), _Post2_impl_(__zterm_impl,__bytecount_x_impl(size)) _Post_valid_impl_) 1393 1394 // 1395 // _Prepost_ --- 1396 // 1397 // describing conditions that hold before and after the function call 1398 1399 #define _Prepost_opt_z_ _SAL1_1_Source_(_Prepost_opt_z_, (), _Pre_opt_z_ _Post_z_) 1400 1401 #define _Prepost_count_(size) _SAL1_1_Source_(_Prepost_count_, (size), _Pre_count_(size) _Post_count_(size)) 1402 #define _Prepost_opt_count_(size) _SAL1_1_Source_(_Prepost_opt_count_, (size), _Pre_opt_count_(size) _Post_count_(size)) 1403 #define _Prepost_bytecount_(size) _SAL1_1_Source_(_Prepost_bytecount_, (size), _Pre_bytecount_(size) _Post_bytecount_(size)) 1404 #define _Prepost_opt_bytecount_(size) _SAL1_1_Source_(_Prepost_opt_bytecount_, (size), _Pre_opt_bytecount_(size) _Post_bytecount_(size)) 1405 #define _Prepost_count_c_(size) _SAL1_1_Source_(_Prepost_count_c_, (size), _Pre_count_c_(size) _Post_count_c_(size)) 1406 #define _Prepost_opt_count_c_(size) _SAL1_1_Source_(_Prepost_opt_count_c_, (size), _Pre_opt_count_c_(size) _Post_count_c_(size)) 1407 #define _Prepost_bytecount_c_(size) _SAL1_1_Source_(_Prepost_bytecount_c_, (size), _Pre_bytecount_c_(size) _Post_bytecount_c_(size)) 1408 #define _Prepost_opt_bytecount_c_(size) _SAL1_1_Source_(_Prepost_opt_bytecount_c_, (size), _Pre_opt_bytecount_c_(size) _Post_bytecount_c_(size)) 1409 #define _Prepost_count_x_(size) _SAL1_1_Source_(_Prepost_count_x_, (size), _Pre_count_x_(size) _Post_count_x_(size)) 1410 #define _Prepost_opt_count_x_(size) _SAL1_1_Source_(_Prepost_opt_count_x_, (size), _Pre_opt_count_x_(size) _Post_count_x_(size)) 1411 #define _Prepost_bytecount_x_(size) _SAL1_1_Source_(_Prepost_bytecount_x_, (size), _Pre_bytecount_x_(size) _Post_bytecount_x_(size)) 1412 #define _Prepost_opt_bytecount_x_(size) _SAL1_1_Source_(_Prepost_opt_bytecount_x_, (size), _Pre_opt_bytecount_x_(size) _Post_bytecount_x_(size)) 1413 1414 #define _Prepost_valid_ _SAL1_1_Source_(_Prepost_valid_, (), _Pre_valid_ _Post_valid_) 1415 #define _Prepost_opt_valid_ _SAL1_1_Source_(_Prepost_opt_valid_, (), _Pre_opt_valid_ _Post_valid_) 1416 1417 // 1418 // _Deref_<both> --- 1419 // 1420 // short version for _Deref_pre_<ann> _Deref_post_<ann> 1421 // describing conditions for array elements or dereferenced pointer parameters that hold before and after the call 1422 1423 #define _Deref_prepost_z_ _SAL1_1_Source_(_Deref_prepost_z_, (), _Deref_pre_z_ _Deref_post_z_) 1424 #define _Deref_prepost_opt_z_ _SAL1_1_Source_(_Deref_prepost_opt_z_, (), _Deref_pre_opt_z_ _Deref_post_opt_z_) 1425 1426 #define _Deref_prepost_cap_(size) _SAL1_1_Source_(_Deref_prepost_cap_, (size), _Deref_pre_cap_(size) _Deref_post_cap_(size)) 1427 #define _Deref_prepost_opt_cap_(size) _SAL1_1_Source_(_Deref_prepost_opt_cap_, (size), _Deref_pre_opt_cap_(size) _Deref_post_opt_cap_(size)) 1428 #define _Deref_prepost_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_bytecap_, (size), _Deref_pre_bytecap_(size) _Deref_post_bytecap_(size)) 1429 #define _Deref_prepost_opt_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_opt_bytecap_, (size), _Deref_pre_opt_bytecap_(size) _Deref_post_opt_bytecap_(size)) 1430 1431 #define _Deref_prepost_cap_x_(size) _SAL1_1_Source_(_Deref_prepost_cap_x_, (size), _Deref_pre_cap_x_(size) _Deref_post_cap_x_(size)) 1432 #define _Deref_prepost_opt_cap_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_cap_x_, (size), _Deref_pre_opt_cap_x_(size) _Deref_post_opt_cap_x_(size)) 1433 #define _Deref_prepost_bytecap_x_(size) _SAL1_1_Source_(_Deref_prepost_bytecap_x_, (size), _Deref_pre_bytecap_x_(size) _Deref_post_bytecap_x_(size)) 1434 #define _Deref_prepost_opt_bytecap_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_bytecap_x_, (size), _Deref_pre_opt_bytecap_x_(size) _Deref_post_opt_bytecap_x_(size)) 1435 1436 #define _Deref_prepost_z_cap_(size) _SAL1_1_Source_(_Deref_prepost_z_cap_, (size), _Deref_pre_z_cap_(size) _Deref_post_z_cap_(size)) 1437 #define _Deref_prepost_opt_z_cap_(size) _SAL1_1_Source_(_Deref_prepost_opt_z_cap_, (size), _Deref_pre_opt_z_cap_(size) _Deref_post_opt_z_cap_(size)) 1438 #define _Deref_prepost_z_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_z_bytecap_, (size), _Deref_pre_z_bytecap_(size) _Deref_post_z_bytecap_(size)) 1439 #define _Deref_prepost_opt_z_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_opt_z_bytecap_, (size), _Deref_pre_opt_z_bytecap_(size) _Deref_post_opt_z_bytecap_(size)) 1440 1441 #define _Deref_prepost_valid_cap_(size) _SAL1_1_Source_(_Deref_prepost_valid_cap_, (size), _Deref_pre_valid_cap_(size) _Deref_post_valid_cap_(size)) 1442 #define _Deref_prepost_opt_valid_cap_(size) _SAL1_1_Source_(_Deref_prepost_opt_valid_cap_, (size), _Deref_pre_opt_valid_cap_(size) _Deref_post_opt_valid_cap_(size)) 1443 #define _Deref_prepost_valid_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_valid_bytecap_, (size), _Deref_pre_valid_bytecap_(size) _Deref_post_valid_bytecap_(size)) 1444 #define _Deref_prepost_opt_valid_bytecap_(size) _SAL1_1_Source_(_Deref_prepost_opt_valid_bytecap_, (size), _Deref_pre_opt_valid_bytecap_(size) _Deref_post_opt_valid_bytecap_(size)) 1445 1446 #define _Deref_prepost_valid_cap_x_(size) _SAL1_1_Source_(_Deref_prepost_valid_cap_x_, (size), _Deref_pre_valid_cap_x_(size) _Deref_post_valid_cap_x_(size)) 1447 #define _Deref_prepost_opt_valid_cap_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_valid_cap_x_, (size), _Deref_pre_opt_valid_cap_x_(size) _Deref_post_opt_valid_cap_x_(size)) 1448 #define _Deref_prepost_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_prepost_valid_bytecap_x_, (size), _Deref_pre_valid_bytecap_x_(size) _Deref_post_valid_bytecap_x_(size)) 1449 #define _Deref_prepost_opt_valid_bytecap_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_valid_bytecap_x_, (size), _Deref_pre_opt_valid_bytecap_x_(size) _Deref_post_opt_valid_bytecap_x_(size)) 1450 1451 #define _Deref_prepost_count_(size) _SAL1_1_Source_(_Deref_prepost_count_, (size), _Deref_pre_count_(size) _Deref_post_count_(size)) 1452 #define _Deref_prepost_opt_count_(size) _SAL1_1_Source_(_Deref_prepost_opt_count_, (size), _Deref_pre_opt_count_(size) _Deref_post_opt_count_(size)) 1453 #define _Deref_prepost_bytecount_(size) _SAL1_1_Source_(_Deref_prepost_bytecount_, (size), _Deref_pre_bytecount_(size) _Deref_post_bytecount_(size)) 1454 #define _Deref_prepost_opt_bytecount_(size) _SAL1_1_Source_(_Deref_prepost_opt_bytecount_, (size), _Deref_pre_opt_bytecount_(size) _Deref_post_opt_bytecount_(size)) 1455 1456 #define _Deref_prepost_count_x_(size) _SAL1_1_Source_(_Deref_prepost_count_x_, (size), _Deref_pre_count_x_(size) _Deref_post_count_x_(size)) 1457 #define _Deref_prepost_opt_count_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_count_x_, (size), _Deref_pre_opt_count_x_(size) _Deref_post_opt_count_x_(size)) 1458 #define _Deref_prepost_bytecount_x_(size) _SAL1_1_Source_(_Deref_prepost_bytecount_x_, (size), _Deref_pre_bytecount_x_(size) _Deref_post_bytecount_x_(size)) 1459 #define _Deref_prepost_opt_bytecount_x_(size) _SAL1_1_Source_(_Deref_prepost_opt_bytecount_x_, (size), _Deref_pre_opt_bytecount_x_(size) _Deref_post_opt_bytecount_x_(size)) 1460 1461 #define _Deref_prepost_valid_ _SAL1_1_Source_(_Deref_prepost_valid_, (), _Deref_pre_valid_ _Deref_post_valid_) 1462 #define _Deref_prepost_opt_valid_ _SAL1_1_Source_(_Deref_prepost_opt_valid_, (), _Deref_pre_opt_valid_ _Deref_post_opt_valid_) 1463 1464 // 1465 // _Deref_<miscellaneous> 1466 // 1467 // used with references to arrays 1468 1469 #define _Deref_out_z_cap_c_(size) _SAL1_1_Source_(_Deref_out_z_cap_c_, (size), _Deref_pre_cap_c_(size) _Deref_post_z_) 1470 #define _Deref_inout_z_cap_c_(size) _SAL1_1_Source_(_Deref_inout_z_cap_c_, (size), _Deref_pre_z_cap_c_(size) _Deref_post_z_) 1471 #define _Deref_out_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_out_z_bytecap_c_, (size), _Deref_pre_bytecap_c_(size) _Deref_post_z_) 1472 #define _Deref_inout_z_bytecap_c_(size) _SAL1_1_Source_(_Deref_inout_z_bytecap_c_, (size), _Deref_pre_z_bytecap_c_(size) _Deref_post_z_) 1473 #define _Deref_inout_z_ _SAL1_1_Source_(_Deref_inout_z_, (), _Deref_prepost_z_) 1474 1475 // #pragma endregion Input Buffer SAL 1 compatibility macros 1476 1477 1478 //============================================================================ 1479 // Implementation Layer: 1480 //============================================================================ 1481 1482 1483 // Naming conventions: 1484 // A symbol the begins with _SA_ is for the machinery of creating any 1485 // annotations; many of those come from sourceannotations.h in the case 1486 // of attributes. 1487 1488 // A symbol that ends with _impl is the very lowest level macro. It is 1489 // not required to be a legal standalone annotation, and in the case 1490 // of attribute annotations, usually is not. (In the case of some declspec 1491 // annotations, it might be, but it should not be assumed so.) Those 1492 // symols will be used in the _PreN..., _PostN... and _RetN... annotations 1493 // to build up more complete annotations. 1494 1495 // A symbol ending in _impl_ is reserved to the implementation as well, 1496 // but it does form a complete annotation; usually they are used to build 1497 // up even higher level annotations. 1498 1499 1500 #if _USE_ATTRIBUTES_FOR_SAL || _USE_DECLSPECS_FOR_SAL // [ 1501 // Sharable "_impl" macros: these can be shared between the various annotation 1502 // forms but are part of the implementation of the macros. These are collected 1503 // here to assure that only necessary differences in the annotations 1504 // exist. 1505 1506 #define _Always_impl_(annos) _Group_(annos _SAL_nop_impl_) _On_failure_impl_(annos _SAL_nop_impl_) 1507 #define _Bound_impl_ _SA_annotes0(SAL_bound) 1508 #define _Field_range_impl_(min,max) _Range_impl_(min,max) 1509 #define _Literal_impl_ _SA_annotes1(SAL_constant, __yes) 1510 #define _Maybenull_impl_ _SA_annotes1(SAL_null, __maybe) 1511 #define _Maybevalid_impl_ _SA_annotes1(SAL_valid, __maybe) 1512 #define _Must_inspect_impl_ _Post_impl_ _SA_annotes0(SAL_mustInspect) 1513 #define _Notliteral_impl_ _SA_annotes1(SAL_constant, __no) 1514 #define _Notnull_impl_ _SA_annotes1(SAL_null, __no) 1515 #define _Notvalid_impl_ _SA_annotes1(SAL_valid, __no) 1516 #define _NullNull_terminated_impl_ _Group_(_SA_annotes1(SAL_nullTerminated, __yes) _SA_annotes1(SAL_readableTo,inexpressibleCount("NullNull terminated string"))) 1517 #define _Null_impl_ _SA_annotes1(SAL_null, __yes) 1518 #define _Null_terminated_impl_ _SA_annotes1(SAL_nullTerminated, __yes) 1519 #define _Out_impl_ _Pre1_impl_(__notnull_impl_notref) _Pre1_impl_(__cap_c_one_notref_impl) _Post_valid_impl_ 1520 #define _Out_opt_impl_ _Pre1_impl_(__maybenull_impl_notref) _Pre1_impl_(__cap_c_one_notref_impl) _Post_valid_impl_ 1521 #define _Points_to_data_impl_ _At_(*_Curr_, _SA_annotes1(SAL_mayBePointer, __no)) 1522 #define _Post_satisfies_impl_(cond) _Post_impl_ _Satisfies_impl_(cond) 1523 #define _Post_valid_impl_ _Post1_impl_(__valid_impl) 1524 #define _Pre_satisfies_impl_(cond) _Pre_impl_ _Satisfies_impl_(cond) 1525 #define _Pre_valid_impl_ _Pre1_impl_(__valid_impl) 1526 #define _Range_impl_(min,max) _SA_annotes2(SAL_range, min, max) 1527 #define _Readable_bytes_impl_(size) _SA_annotes1(SAL_readableTo, byteCount(size)) 1528 #define _Readable_elements_impl_(size) _SA_annotes1(SAL_readableTo, elementCount(size)) 1529 #define _Ret_valid_impl_ _Ret1_impl_(__valid_impl) 1530 #define _Satisfies_impl_(cond) _SA_annotes1(SAL_satisfies, cond) 1531 #define _Valid_impl_ _SA_annotes1(SAL_valid, __yes) 1532 #define _Writable_bytes_impl_(size) _SA_annotes1(SAL_writableTo, byteCount(size)) 1533 #define _Writable_elements_impl_(size) _SA_annotes1(SAL_writableTo, elementCount(size)) 1534 1535 #define _In_range_impl_(min,max) _Pre_impl_ _Range_impl_(min,max) 1536 #define _Out_range_impl_(min,max) _Post_impl_ _Range_impl_(min,max) 1537 #define _Ret_range_impl_(min,max) _Post_impl_ _Range_impl_(min,max) 1538 #define _Deref_in_range_impl_(min,max) _Deref_pre_impl_ _Range_impl_(min,max) 1539 #define _Deref_out_range_impl_(min,max) _Deref_post_impl_ _Range_impl_(min,max) 1540 #define _Deref_ret_range_impl_(min,max) _Deref_post_impl_ _Range_impl_(min,max) 1541 1542 #define _Deref_pre_impl_ _Pre_impl_ _Notref_impl_ _Deref_impl_ 1543 #define _Deref_post_impl_ _Post_impl_ _Notref_impl_ _Deref_impl_ 1544 1545 // The following are for the implementation machinery, and are not 1546 // suitable for annotating general code. 1547 // We're tying to phase this out, someday. The parser quotes the param. 1548 #define __AuToQuOtE _SA_annotes0(SAL_AuToQuOtE) 1549 1550 // Normally the parser does some simple type checking of annotation params, 1551 // defer that check to the plugin. 1552 #define __deferTypecheck _SA_annotes0(SAL_deferTypecheck) 1553 1554 #define _SA_SPECSTRIZE( x ) #x 1555 #define _SAL_nop_impl_ /* nothing */ 1556 #define __nop_impl(x) x 1557 #endif 1558 1559 1560 #if _USE_ATTRIBUTES_FOR_SAL // [ 1561 1562 // Using attributes for sal 1563 1564 #include "codeanalysis\sourceannotations.h" 1565 1566 1567 #define _SA_annotes0(n) [SAL_annotes(Name=#n)] 1568 #define _SA_annotes1(n,pp1) [SAL_annotes(Name=#n, p1=_SA_SPECSTRIZE(pp1))] 1569 #define _SA_annotes2(n,pp1,pp2) [SAL_annotes(Name=#n, p1=_SA_SPECSTRIZE(pp1), p2=_SA_SPECSTRIZE(pp2))] 1570 #define _SA_annotes3(n,pp1,pp2,pp3) [SAL_annotes(Name=#n, p1=_SA_SPECSTRIZE(pp1), p2=_SA_SPECSTRIZE(pp2), p3=_SA_SPECSTRIZE(pp3))] 1571 1572 #define _Pre_impl_ [SAL_pre] 1573 #define _Post_impl_ [SAL_post] 1574 #define _Deref_impl_ [SAL_deref] 1575 #define _Notref_impl_ [SAL_notref] 1576 1577 1578 // Declare a function to be an annotation or primop (respectively). 1579 // Done this way so that they don't appear in the regular compiler's 1580 // namespace. 1581 #define __ANNOTATION(fun) _SA_annotes0(SAL_annotation) void __SA_##fun; 1582 #define __PRIMOP(type, fun) _SA_annotes0(SAL_primop) type __SA_##fun; 1583 #define __QUALIFIER(fun) _SA_annotes0(SAL_qualifier) void __SA_##fun; 1584 1585 // Benign declspec needed here for WindowsPREfast 1586 #define __In_impl_ [SA_Pre(Valid=SA_Yes)] [SA_Pre(Deref=1, Notref=1, Access=SA_Read)] __declspec("SAL_pre SAL_valid") 1587 1588 #elif _USE_DECLSPECS_FOR_SAL // ][ 1589 1590 // Using declspecs for sal 1591 1592 #define _SA_annotes0(n) __declspec(#n) 1593 #define _SA_annotes1(n,pp1) __declspec(#n "(" _SA_SPECSTRIZE(pp1) ")" ) 1594 #define _SA_annotes2(n,pp1,pp2) __declspec(#n "(" _SA_SPECSTRIZE(pp1) "," _SA_SPECSTRIZE(pp2) ")") 1595 #define _SA_annotes3(n,pp1,pp2,pp3) __declspec(#n "(" _SA_SPECSTRIZE(pp1) "," _SA_SPECSTRIZE(pp2) "," _SA_SPECSTRIZE(pp3) ")") 1596 1597 #define _Pre_impl_ _SA_annotes0(SAL_pre) 1598 #define _Post_impl_ _SA_annotes0(SAL_post) 1599 #define _Deref_impl_ _SA_annotes0(SAL_deref) 1600 #define _Notref_impl_ _SA_annotes0(SAL_notref) 1601 1602 // Declare a function to be an annotation or primop (respectively). 1603 // Done this way so that they don't appear in the regular compiler's 1604 // namespace. 1605 #define __ANNOTATION(fun) _SA_annotes0(SAL_annotation) void __SA_##fun 1606 1607 #define __PRIMOP(type, fun) _SA_annotes0(SAL_primop) type __SA_##fun 1608 1609 #define __QUALIFIER(fun) _SA_annotes0(SAL_qualifier) void __SA_##fun; 1610 1611 #define __In_impl_ _Pre_impl_ _SA_annotes0(SAL_valid) _Pre_impl_ _Deref_impl_ _Notref_impl_ _SA_annotes0(SAL_readonly) 1612 1613 #else // ][ 1614 1615 // Using "nothing" for sal 1616 1617 #define _SA_annotes0(n) 1618 #define _SA_annotes1(n,pp1) 1619 #define _SA_annotes2(n,pp1,pp2) 1620 #define _SA_annotes3(n,pp1,pp2,pp3) 1621 1622 #define __ANNOTATION(fun) 1623 #define __PRIMOP(type, fun) 1624 #define __QUALIFIER(type, fun) 1625 1626 #endif // ] 1627 1628 #if _USE_ATTRIBUTES_FOR_SAL || _USE_DECLSPECS_FOR_SAL // [ 1629 1630 // Declare annotations that need to be declared. 1631 __ANNOTATION(SAL_useHeader(void)); 1632 __ANNOTATION(SAL_bound(void)); 1633 __ANNOTATION(SAL_allocator(void)); //??? resolve with PFD 1634 __ANNOTATION(SAL_file_parser(__AuToQuOtE __In_impl_ char *, __In_impl_ char *)); 1635 __ANNOTATION(SAL_source_code_content(__In_impl_ char *)); 1636 __ANNOTATION(SAL_analysisHint(__AuToQuOtE __In_impl_ char *)); 1637 __ANNOTATION(SAL_untrusted_data_source(__AuToQuOtE __In_impl_ char *)); 1638 __ANNOTATION(SAL_untrusted_data_source_this(__AuToQuOtE __In_impl_ char *)); 1639 __ANNOTATION(SAL_validated(__AuToQuOtE __In_impl_ char *)); 1640 __ANNOTATION(SAL_validated_this(__AuToQuOtE __In_impl_ char *)); 1641 __ANNOTATION(SAL_encoded(void)); 1642 __ANNOTATION(SAL_adt(__AuToQuOtE __In_impl_ char *, __AuToQuOtE __In_impl_ char *)); 1643 __ANNOTATION(SAL_add_adt_property(__AuToQuOtE __In_impl_ char *, __AuToQuOtE __In_impl_ char *)); 1644 __ANNOTATION(SAL_remove_adt_property(__AuToQuOtE __In_impl_ char *, __AuToQuOtE __In_impl_ char *)); 1645 __ANNOTATION(SAL_transfer_adt_property_from(__AuToQuOtE __In_impl_ char *)); 1646 __ANNOTATION(SAL_post_type(__AuToQuOtE __In_impl_ char *)); 1647 __ANNOTATION(SAL_volatile(void)); 1648 __ANNOTATION(SAL_nonvolatile(void)); 1649 __ANNOTATION(SAL_entrypoint(__AuToQuOtE __In_impl_ char *, __AuToQuOtE __In_impl_ char *)); 1650 __ANNOTATION(SAL_blocksOn(__In_impl_ void*)); 1651 __ANNOTATION(SAL_mustInspect(void)); 1652 1653 // Only appears in model files, but needs to be declared. 1654 __ANNOTATION(SAL_TypeName(__AuToQuOtE __In_impl_ char *)); 1655 1656 // To be declared well-known soon. 1657 __ANNOTATION(SAL_interlocked(void);) 1658 1659 #pragma warning (suppress: 28227 28241) 1660 __ANNOTATION(SAL_name(__In_impl_ char *, __In_impl_ char *, __In_impl_ char *);) 1661 1662 __PRIMOP(char *, _Macro_value_(__In_impl_ char *)); 1663 __PRIMOP(int, _Macro_defined_(__In_impl_ char *)); 1664 __PRIMOP(char *, _Strstr_(__In_impl_ char *, __In_impl_ char *)); 1665 1666 #endif // ] 1667 1668 #if _USE_ATTRIBUTES_FOR_SAL // [ 1669 1670 #define _Check_return_impl_ [SA_Post(MustCheck=SA_Yes)] 1671 1672 #define _Success_impl_(expr) [SA_Success(Condition=#expr)] 1673 #define _On_failure_impl_(annos) [SAL_context(p1="SAL_failed")] _Group_(_Post_impl_ _Group_(annos _SAL_nop_impl_)) 1674 1675 #define _Printf_format_string_impl_ [SA_FormatString(Style="printf")] 1676 #define _Scanf_format_string_impl_ [SA_FormatString(Style="scanf")] 1677 #define _Scanf_s_format_string_impl_ [SA_FormatString(Style="scanf_s")] 1678 1679 #define _In_bound_impl_ [SA_PreBound(Deref=0)] 1680 #define _Out_bound_impl_ [SA_PostBound(Deref=0)] 1681 #define _Ret_bound_impl_ [SA_PostBound(Deref=0)] 1682 #define _Deref_in_bound_impl_ [SA_PreBound(Deref=1)] 1683 #define _Deref_out_bound_impl_ [SA_PostBound(Deref=1)] 1684 #define _Deref_ret_bound_impl_ [SA_PostBound(Deref=1)] 1685 1686 #define __valid_impl Valid=SA_Yes 1687 #define __maybevalid_impl Valid=SA_Maybe 1688 #define __notvalid_impl Valid=SA_No 1689 1690 #define __null_impl Null=SA_Yes 1691 #define __maybenull_impl Null=SA_Maybe 1692 #define __notnull_impl Null=SA_No 1693 1694 #define __null_impl_notref Null=SA_Yes,Notref=1 1695 #define __maybenull_impl_notref Null=SA_Maybe,Notref=1 1696 #define __notnull_impl_notref Null=SA_No,Notref=1 1697 1698 #define __zterm_impl NullTerminated=SA_Yes 1699 #define __maybezterm_impl NullTerminated=SA_Maybe 1700 #define __maybzterm_impl NullTerminated=SA_Maybe 1701 #define __notzterm_impl NullTerminated=SA_No 1702 1703 #define __readaccess_impl Access=SA_Read 1704 #define __writeaccess_impl Access=SA_Write 1705 #define __allaccess_impl Access=SA_ReadWrite 1706 1707 #define __readaccess_impl_notref Access=SA_Read,Notref=1 1708 #define __writeaccess_impl_notref Access=SA_Write,Notref=1 1709 #define __allaccess_impl_notref Access=SA_ReadWrite,Notref=1 1710 1711 #if _MSC_VER >= 1610 /*IFSTRIP=IGN*/ // [ 1712 1713 // For SAL2, we need to expect general expressions. 1714 1715 #define __cap_impl(size) WritableElements="\n"#size 1716 #define __bytecap_impl(size) WritableBytes="\n"#size 1717 #define __bytecount_impl(size) ValidBytes="\n"#size 1718 #define __count_impl(size) ValidElements="\n"#size 1719 1720 #else // ][ 1721 1722 #define __cap_impl(size) WritableElements=#size 1723 #define __bytecap_impl(size) WritableBytes=#size 1724 #define __bytecount_impl(size) ValidBytes=#size 1725 #define __count_impl(size) ValidElements=#size 1726 1727 #endif // ] 1728 1729 #define __cap_c_impl(size) WritableElementsConst=size 1730 #define __cap_c_one_notref_impl WritableElementsConst=1,Notref=1 1731 #define __cap_for_impl(param) WritableElementsLength=#param 1732 #define __cap_x_impl(size) WritableElements="\n@"#size 1733 1734 #define __bytecap_c_impl(size) WritableBytesConst=size 1735 #define __bytecap_x_impl(size) WritableBytes="\n@"#size 1736 1737 #define __mult_impl(mult,size) __cap_impl((mult)*(size)) 1738 1739 #define __count_c_impl(size) ValidElementsConst=size 1740 #define __count_x_impl(size) ValidElements="\n@"#size 1741 1742 #define __bytecount_c_impl(size) ValidBytesConst=size 1743 #define __bytecount_x_impl(size) ValidBytes="\n@"#size 1744 1745 1746 #define _At_impl_(target, annos) [SAL_at(p1=#target)] _Group_(annos) 1747 #define _At_buffer_impl_(target, iter, bound, annos) [SAL_at_buffer(p1=#target, p2=#iter, p3=#bound)] _Group_(annos) 1748 #define _When_impl_(expr, annos) [SAL_when(p1=#expr)] _Group_(annos) 1749 1750 #define _Group_impl_(annos) [SAL_begin] annos [SAL_end] 1751 #define _GrouP_impl_(annos) [SAL_BEGIN] annos [SAL_END] 1752 1753 #define _Use_decl_anno_impl_ _SA_annotes0(SAL_useHeader) // this is a special case! 1754 1755 #define _Pre1_impl_(p1) [SA_Pre(p1)] 1756 #define _Pre2_impl_(p1,p2) [SA_Pre(p1,p2)] 1757 #define _Pre3_impl_(p1,p2,p3) [SA_Pre(p1,p2,p3)] 1758 1759 #define _Post1_impl_(p1) [SA_Post(p1)] 1760 #define _Post2_impl_(p1,p2) [SA_Post(p1,p2)] 1761 #define _Post3_impl_(p1,p2,p3) [SA_Post(p1,p2,p3)] 1762 1763 #define _Ret1_impl_(p1) [SA_Post(p1)] 1764 #define _Ret2_impl_(p1,p2) [SA_Post(p1,p2)] 1765 #define _Ret3_impl_(p1,p2,p3) [SA_Post(p1,p2,p3)] 1766 1767 #define _Deref_pre1_impl_(p1) [SA_Pre(Deref=1,p1)] 1768 #define _Deref_pre2_impl_(p1,p2) [SA_Pre(Deref=1,p1,p2)] 1769 #define _Deref_pre3_impl_(p1,p2,p3) [SA_Pre(Deref=1,p1,p2,p3)] 1770 1771 1772 #define _Deref_post1_impl_(p1) [SA_Post(Deref=1,p1)] 1773 #define _Deref_post2_impl_(p1,p2) [SA_Post(Deref=1,p1,p2)] 1774 #define _Deref_post3_impl_(p1,p2,p3) [SA_Post(Deref=1,p1,p2,p3)] 1775 1776 #define _Deref_ret1_impl_(p1) [SA_Post(Deref=1,p1)] 1777 #define _Deref_ret2_impl_(p1,p2) [SA_Post(Deref=1,p1,p2)] 1778 #define _Deref_ret3_impl_(p1,p2,p3) [SA_Post(Deref=1,p1,p2,p3)] 1779 1780 #define _Deref2_pre1_impl_(p1) [SA_Pre(Deref=2,Notref=1,p1)] 1781 #define _Deref2_post1_impl_(p1) [SA_Post(Deref=2,Notref=1,p1)] 1782 #define _Deref2_ret1_impl_(p1) [SA_Post(Deref=2,Notref=1,p1)] 1783 1784 // Obsolete -- may be needed for transition to attributes. 1785 #define __inner_typefix(ctype) [SAL_typefix(p1=_SA_SPECSTRIZE(ctype))] 1786 #define __inner_exceptthat [SAL_except] 1787 1788 1789 #elif _USE_DECLSPECS_FOR_SAL // ][ 1790 1791 #define _Check_return_impl_ __post _SA_annotes0(SAL_checkReturn) 1792 1793 #define _Success_impl_(expr) _SA_annotes1(SAL_success, expr) 1794 #define _On_failure_impl_(annos) _SA_annotes1(SAL_context, SAL_failed) _Group_(_Post_impl_ _Group_(_SAL_nop_impl_ annos)) 1795 1796 #define _Printf_format_string_impl_ _SA_annotes1(SAL_IsFormatString, "printf") 1797 #define _Scanf_format_string_impl_ _SA_annotes1(SAL_IsFormatString, "scanf") 1798 #define _Scanf_s_format_string_impl_ _SA_annotes1(SAL_IsFormatString, "scanf_s") 1799 1800 #define _In_bound_impl_ _Pre_impl_ _Bound_impl_ 1801 #define _Out_bound_impl_ _Post_impl_ _Bound_impl_ 1802 #define _Ret_bound_impl_ _Post_impl_ _Bound_impl_ 1803 #define _Deref_in_bound_impl_ _Deref_pre_impl_ _Bound_impl_ 1804 #define _Deref_out_bound_impl_ _Deref_post_impl_ _Bound_impl_ 1805 #define _Deref_ret_bound_impl_ _Deref_post_impl_ _Bound_impl_ 1806 1807 1808 #define __null_impl _SA_annotes0(SAL_null) // _SA_annotes1(SAL_null, __yes) 1809 #define __notnull_impl _SA_annotes0(SAL_notnull) // _SA_annotes1(SAL_null, __no) 1810 #define __maybenull_impl _SA_annotes0(SAL_maybenull) // _SA_annotes1(SAL_null, __maybe) 1811 1812 #define __valid_impl _SA_annotes0(SAL_valid) // _SA_annotes1(SAL_valid, __yes) 1813 #define __notvalid_impl _SA_annotes0(SAL_notvalid) // _SA_annotes1(SAL_valid, __no) 1814 #define __maybevalid_impl _SA_annotes0(SAL_maybevalid) // _SA_annotes1(SAL_valid, __maybe) 1815 1816 #define __null_impl_notref _Notref_ _Null_impl_ 1817 #define __maybenull_impl_notref _Notref_ _Maybenull_impl_ 1818 #define __notnull_impl_notref _Notref_ _Notnull_impl_ 1819 1820 #define __zterm_impl _SA_annotes1(SAL_nullTerminated, __yes) 1821 #define __maybezterm_impl _SA_annotes1(SAL_nullTerminated, __maybe) 1822 #define __maybzterm_impl _SA_annotes1(SAL_nullTerminated, __maybe) 1823 #define __notzterm_impl _SA_annotes1(SAL_nullTerminated, __no) 1824 1825 #define __readaccess_impl _SA_annotes1(SAL_access, 0x1) 1826 #define __writeaccess_impl _SA_annotes1(SAL_access, 0x2) 1827 #define __allaccess_impl _SA_annotes1(SAL_access, 0x3) 1828 1829 #define __readaccess_impl_notref _Notref_ _SA_annotes1(SAL_access, 0x1) 1830 #define __writeaccess_impl_notref _Notref_ _SA_annotes1(SAL_access, 0x2) 1831 #define __allaccess_impl_notref _Notref_ _SA_annotes1(SAL_access, 0x3) 1832 1833 #define __cap_impl(size) _SA_annotes1(SAL_writableTo,elementCount(size)) 1834 #define __cap_c_impl(size) _SA_annotes1(SAL_writableTo,elementCount(size)) 1835 #define __cap_c_one_notref_impl _Notref_ _SA_annotes1(SAL_writableTo,elementCount(1)) 1836 #define __cap_for_impl(param) _SA_annotes1(SAL_writableTo,inexpressibleCount(sizeof(param))) 1837 #define __cap_x_impl(size) _SA_annotes1(SAL_writableTo,inexpressibleCount(#size)) 1838 1839 #define __bytecap_impl(size) _SA_annotes1(SAL_writableTo,byteCount(size)) 1840 #define __bytecap_c_impl(size) _SA_annotes1(SAL_writableTo,byteCount(size)) 1841 #define __bytecap_x_impl(size) _SA_annotes1(SAL_writableTo,inexpressibleCount(#size)) 1842 1843 #define __mult_impl(mult,size) _SA_annotes1(SAL_writableTo,(mult)*(size)) 1844 1845 #define __count_impl(size) _SA_annotes1(SAL_readableTo,elementCount(size)) 1846 #define __count_c_impl(size) _SA_annotes1(SAL_readableTo,elementCount(size)) 1847 #define __count_x_impl(size) _SA_annotes1(SAL_readableTo,inexpressibleCount(#size)) 1848 1849 #define __bytecount_impl(size) _SA_annotes1(SAL_readableTo,byteCount(size)) 1850 #define __bytecount_c_impl(size) _SA_annotes1(SAL_readableTo,byteCount(size)) 1851 #define __bytecount_x_impl(size) _SA_annotes1(SAL_readableTo,inexpressibleCount(#size)) 1852 1853 #define _At_impl_(target, annos) _SA_annotes0(SAL_at(target)) _Group_(annos) 1854 #define _At_buffer_impl_(target, iter, bound, annos) _SA_annotes3(SAL_at_buffer, target, iter, bound) _Group_(annos) 1855 #define _Group_impl_(annos) _SA_annotes0(SAL_begin) annos _SA_annotes0(SAL_end) 1856 #define _GrouP_impl_(annos) _SA_annotes0(SAL_BEGIN) annos _SA_annotes0(SAL_END) 1857 #define _When_impl_(expr, annos) _SA_annotes0(SAL_when(expr)) _Group_(annos) 1858 1859 #define _Use_decl_anno_impl_ __declspec("SAL_useHeader()") // this is a special case! 1860 1861 #define _Pre1_impl_(p1) _Pre_impl_ p1 1862 #define _Pre2_impl_(p1,p2) _Pre_impl_ p1 _Pre_impl_ p2 1863 #define _Pre3_impl_(p1,p2,p3) _Pre_impl_ p1 _Pre_impl_ p2 _Pre_impl_ p3 1864 1865 #define _Post1_impl_(p1) _Post_impl_ p1 1866 #define _Post2_impl_(p1,p2) _Post_impl_ p1 _Post_impl_ p2 1867 #define _Post3_impl_(p1,p2,p3) _Post_impl_ p1 _Post_impl_ p2 _Post_impl_ p3 1868 1869 #define _Ret1_impl_(p1) _Post_impl_ p1 1870 #define _Ret2_impl_(p1,p2) _Post_impl_ p1 _Post_impl_ p2 1871 #define _Ret3_impl_(p1,p2,p3) _Post_impl_ p1 _Post_impl_ p2 _Post_impl_ p3 1872 1873 #define _Deref_pre1_impl_(p1) _Deref_pre_impl_ p1 1874 #define _Deref_pre2_impl_(p1,p2) _Deref_pre_impl_ p1 _Deref_pre_impl_ p2 1875 #define _Deref_pre3_impl_(p1,p2,p3) _Deref_pre_impl_ p1 _Deref_pre_impl_ p2 _Deref_pre_impl_ p3 1876 1877 #define _Deref_post1_impl_(p1) _Deref_post_impl_ p1 1878 #define _Deref_post2_impl_(p1,p2) _Deref_post_impl_ p1 _Deref_post_impl_ p2 1879 #define _Deref_post3_impl_(p1,p2,p3) _Deref_post_impl_ p1 _Deref_post_impl_ p2 _Deref_post_impl_ p3 1880 1881 #define _Deref_ret1_impl_(p1) _Deref_post_impl_ p1 1882 #define _Deref_ret2_impl_(p1,p2) _Deref_post_impl_ p1 _Deref_post_impl_ p2 1883 #define _Deref_ret3_impl_(p1,p2,p3) _Deref_post_impl_ p1 _Deref_post_impl_ p2 _Deref_post_impl_ p3 1884 1885 #define _Deref2_pre1_impl_(p1) _Deref_pre_impl_ _Notref_impl_ _Deref_impl_ p1 1886 #define _Deref2_post1_impl_(p1) _Deref_post_impl_ _Notref_impl_ _Deref_impl_ p1 1887 #define _Deref2_ret1_impl_(p1) _Deref_post_impl_ _Notref_impl_ _Deref_impl_ p1 1888 1889 #define __inner_typefix(ctype) _SA_annotes1(SAL_typefix, ctype) 1890 #define __inner_exceptthat _SA_annotes0(SAL_except) 1891 1892 #elif defined(_MSC_EXTENSIONS) && !defined( MIDL_PASS ) && !defined(__midl) && !defined(RC_INVOKED) && defined(_PFT_VER) && _MSC_VER >= 1400 /*IFSTRIP=IGN*/ // ][ 1893 1894 // minimum attribute expansion for foreground build 1895 1896 #pragma push_macro( "SA" ) 1897 #pragma push_macro( "REPEATABLE" ) 1898 1899 #ifdef __cplusplus // [ 1900 #define SA( id ) id 1901 #define REPEATABLE [repeatable] 1902 #else // !__cplusplus // ][ 1903 #define SA( id ) SA_##id 1904 #define REPEATABLE 1905 #endif // !__cplusplus // ] 1906 1907 REPEATABLE 1908 [source_annotation_attribute( SA( Parameter ) )] 1909 struct __P_impl 1910 { 1911 #ifdef __cplusplus // [ 1912 __P_impl(); 1913 #endif // ] 1914 int __d_; 1915 }; 1916 typedef struct __P_impl __P_impl; 1917 1918 REPEATABLE 1919 [source_annotation_attribute( SA( ReturnValue ) )] 1920 struct __R_impl 1921 { 1922 #ifdef __cplusplus // [ 1923 __R_impl(); 1924 #endif // ] 1925 int __d_; 1926 }; 1927 typedef struct __R_impl __R_impl; 1928 1929 [source_annotation_attribute( SA( Method ) )] 1930 struct __M_ 1931 { 1932 #ifdef __cplusplus // [ 1933 __M_(); 1934 #endif // ] 1935 int __d_; 1936 }; 1937 typedef struct __M_ __M_; 1938 1939 [source_annotation_attribute( SA( All ) )] 1940 struct __A_ 1941 { 1942 #ifdef __cplusplus // [ 1943 __A_(); 1944 #endif // ] 1945 int __d_; 1946 }; 1947 typedef struct __A_ __A_; 1948 1949 [source_annotation_attribute( SA( Field ) )] 1950 struct __F_ 1951 { 1952 #ifdef __cplusplus // [ 1953 __F_(); 1954 #endif // ] 1955 int __d_; 1956 }; 1957 typedef struct __F_ __F_; 1958 1959 #pragma pop_macro( "REPEATABLE" ) 1960 #pragma pop_macro( "SA" ) 1961 1962 1963 #define _SAL_nop_impl_ 1964 1965 #define _At_impl_(target, annos) [__A_(__d_=0)] 1966 #define _At_buffer_impl_(target, iter, bound, annos) [__A_(__d_=0)] 1967 #define _When_impl_(expr, annos) annos 1968 #define _Group_impl_(annos) annos 1969 #define _GrouP_impl_(annos) annos 1970 #define _Use_decl_anno_impl_ [__M_(__d_=0)] 1971 1972 #define _Points_to_data_impl_ [__P_impl(__d_=0)] 1973 #define _Literal_impl_ [__P_impl(__d_=0)] 1974 #define _Notliteral_impl_ [__P_impl(__d_=0)] 1975 1976 #define _Pre_valid_impl_ [__P_impl(__d_=0)] 1977 #define _Post_valid_impl_ [__P_impl(__d_=0)] 1978 #define _Ret_valid_impl_ [__R_impl(__d_=0)] 1979 1980 #define _Check_return_impl_ [__R_impl(__d_=0)] 1981 #define _Must_inspect_impl_ [__R_impl(__d_=0)] 1982 1983 #define _Success_impl_(expr) [__M_(__d_=0)] 1984 #define _On_failure_impl_(expr) [__M_(__d_=0)] 1985 #define _Always_impl_(expr) [__M_(__d_=0)] 1986 1987 #define _Printf_format_string_impl_ [__P_impl(__d_=0)] 1988 #define _Scanf_format_string_impl_ [__P_impl(__d_=0)] 1989 #define _Scanf_s_format_string_impl_ [__P_impl(__d_=0)] 1990 1991 #define _Raises_SEH_exception_impl_ [__M_(__d_=0)] 1992 #define _Maybe_raises_SEH_exception_impl_ [__M_(__d_=0)] 1993 1994 #define _In_bound_impl_ [__P_impl(__d_=0)] 1995 #define _Out_bound_impl_ [__P_impl(__d_=0)] 1996 #define _Ret_bound_impl_ [__R_impl(__d_=0)] 1997 #define _Deref_in_bound_impl_ [__P_impl(__d_=0)] 1998 #define _Deref_out_bound_impl_ [__P_impl(__d_=0)] 1999 #define _Deref_ret_bound_impl_ [__R_impl(__d_=0)] 2000 2001 #define _Range_impl_(min,max) [__P_impl(__d_=0)] 2002 #define _In_range_impl_(min,max) [__P_impl(__d_=0)] 2003 #define _Out_range_impl_(min,max) [__P_impl(__d_=0)] 2004 #define _Ret_range_impl_(min,max) [__R_impl(__d_=0)] 2005 #define _Deref_in_range_impl_(min,max) [__P_impl(__d_=0)] 2006 #define _Deref_out_range_impl_(min,max) [__P_impl(__d_=0)] 2007 #define _Deref_ret_range_impl_(min,max) [__R_impl(__d_=0)] 2008 2009 #define _Field_range_impl_(min,max) [__F_(__d_=0)] 2010 2011 #define _Pre_satisfies_impl_(cond) [__A_(__d_=0)] 2012 #define _Post_satisfies_impl_(cond) [__A_(__d_=0)] 2013 #define _Satisfies_impl_(cond) [__A_(__d_=0)] 2014 2015 #define _Null_impl_ [__A_(__d_=0)] 2016 #define _Notnull_impl_ [__A_(__d_=0)] 2017 #define _Maybenull_impl_ [__A_(__d_=0)] 2018 2019 #define _Valid_impl_ [__A_(__d_=0)] 2020 #define _Notvalid_impl_ [__A_(__d_=0)] 2021 #define _Maybevalid_impl_ [__A_(__d_=0)] 2022 2023 #define _Readable_bytes_impl_(size) [__A_(__d_=0)] 2024 #define _Readable_elements_impl_(size) [__A_(__d_=0)] 2025 #define _Writable_bytes_impl_(size) [__A_(__d_=0)] 2026 #define _Writable_elements_impl_(size) [__A_(__d_=0)] 2027 2028 #define _Null_terminated_impl_ [__A_(__d_=0)] 2029 #define _NullNull_terminated_impl_ [__A_(__d_=0)] 2030 2031 #define _Pre_impl_ [__P_impl(__d_=0)] 2032 #define _Pre1_impl_(p1) [__P_impl(__d_=0)] 2033 #define _Pre2_impl_(p1,p2) [__P_impl(__d_=0)] 2034 #define _Pre3_impl_(p1,p2,p3) [__P_impl(__d_=0)] 2035 2036 #define _Post_impl_ [__P_impl(__d_=0)] 2037 #define _Post1_impl_(p1) [__P_impl(__d_=0)] 2038 #define _Post2_impl_(p1,p2) [__P_impl(__d_=0)] 2039 #define _Post3_impl_(p1,p2,p3) [__P_impl(__d_=0)] 2040 2041 #define _Ret1_impl_(p1) [__R_impl(__d_=0)] 2042 #define _Ret2_impl_(p1,p2) [__R_impl(__d_=0)] 2043 #define _Ret3_impl_(p1,p2,p3) [__R_impl(__d_=0)] 2044 2045 #define _Deref_pre1_impl_(p1) [__P_impl(__d_=0)] 2046 #define _Deref_pre2_impl_(p1,p2) [__P_impl(__d_=0)] 2047 #define _Deref_pre3_impl_(p1,p2,p3) [__P_impl(__d_=0)] 2048 2049 #define _Deref_post1_impl_(p1) [__P_impl(__d_=0)] 2050 #define _Deref_post2_impl_(p1,p2) [__P_impl(__d_=0)] 2051 #define _Deref_post3_impl_(p1,p2,p3) [__P_impl(__d_=0)] 2052 2053 #define _Deref_ret1_impl_(p1) [__R_impl(__d_=0)] 2054 #define _Deref_ret2_impl_(p1,p2) [__R_impl(__d_=0)] 2055 #define _Deref_ret3_impl_(p1,p2,p3) [__R_impl(__d_=0)] 2056 2057 #define _Deref2_pre1_impl_(p1) //[__P_impl(__d_=0)] 2058 #define _Deref2_post1_impl_(p1) //[__P_impl(__d_=0)] 2059 #define _Deref2_ret1_impl_(p1) //[__P_impl(__d_=0)] 2060 2061 #else // ][ 2062 2063 2064 #define _SAL_nop_impl_ X 2065 2066 #define _At_impl_(target, annos) 2067 #define _When_impl_(expr, annos) 2068 #define _Group_impl_(annos) 2069 #define _GrouP_impl_(annos) 2070 #define _At_buffer_impl_(target, iter, bound, annos) 2071 #define _Use_decl_anno_impl_ 2072 #define _Points_to_data_impl_ 2073 #define _Literal_impl_ 2074 #define _Notliteral_impl_ 2075 #define _Notref_impl_ 2076 2077 #define _Pre_valid_impl_ 2078 #define _Post_valid_impl_ 2079 #define _Ret_valid_impl_ 2080 2081 #define _Check_return_impl_ 2082 #define _Must_inspect_impl_ 2083 2084 #define _Success_impl_(expr) 2085 #define _On_failure_impl_(annos) 2086 #define _Always_impl_(annos) 2087 2088 #define _Printf_format_string_impl_ 2089 #define _Scanf_format_string_impl_ 2090 #define _Scanf_s_format_string_impl_ 2091 2092 #define _In_bound_impl_ 2093 #define _Out_bound_impl_ 2094 #define _Ret_bound_impl_ 2095 #define _Deref_in_bound_impl_ 2096 #define _Deref_out_bound_impl_ 2097 #define _Deref_ret_bound_impl_ 2098 2099 #define _Range_impl_(min,max) 2100 #define _In_range_impl_(min,max) 2101 #define _Out_range_impl_(min,max) 2102 #define _Ret_range_impl_(min,max) 2103 #define _Deref_in_range_impl_(min,max) 2104 #define _Deref_out_range_impl_(min,max) 2105 #define _Deref_ret_range_impl_(min,max) 2106 2107 #define _Satisfies_impl_(expr) 2108 #define _Pre_satisfies_impl_(expr) 2109 #define _Post_satisfies_impl_(expr) 2110 2111 #define _Null_impl_ 2112 #define _Notnull_impl_ 2113 #define _Maybenull_impl_ 2114 2115 #define _Valid_impl_ 2116 #define _Notvalid_impl_ 2117 #define _Maybevalid_impl_ 2118 2119 #define _Field_range_impl_(min,max) 2120 2121 #define _Pre_impl_ 2122 #define _Pre1_impl_(p1) 2123 #define _Pre2_impl_(p1,p2) 2124 #define _Pre3_impl_(p1,p2,p3) 2125 2126 #define _Post_impl_ 2127 #define _Post1_impl_(p1) 2128 #define _Post2_impl_(p1,p2) 2129 #define _Post3_impl_(p1,p2,p3) 2130 2131 #define _Ret1_impl_(p1) 2132 #define _Ret2_impl_(p1,p2) 2133 #define _Ret3_impl_(p1,p2,p3) 2134 2135 #define _Deref_pre1_impl_(p1) 2136 #define _Deref_pre2_impl_(p1,p2) 2137 #define _Deref_pre3_impl_(p1,p2,p3) 2138 2139 #define _Deref_post1_impl_(p1) 2140 #define _Deref_post2_impl_(p1,p2) 2141 #define _Deref_post3_impl_(p1,p2,p3) 2142 2143 #define _Deref_ret1_impl_(p1) 2144 #define _Deref_ret2_impl_(p1,p2) 2145 #define _Deref_ret3_impl_(p1,p2,p3) 2146 2147 #define _Deref2_pre1_impl_(p1) 2148 #define _Deref2_post1_impl_(p1) 2149 #define _Deref2_ret1_impl_(p1) 2150 2151 #define _Readable_bytes_impl_(size) 2152 #define _Readable_elements_impl_(size) 2153 #define _Writable_bytes_impl_(size) 2154 #define _Writable_elements_impl_(size) 2155 2156 #define _Null_terminated_impl_ 2157 #define _NullNull_terminated_impl_ 2158 2159 // Obsolete -- may be needed for transition to attributes. 2160 #define __inner_typefix(ctype) 2161 #define __inner_exceptthat 2162 2163 #endif // ] 2164 2165 // This section contains the deprecated annotations 2166 2167 /* 2168 ------------------------------------------------------------------------------- 2169 Introduction 2170 2171 sal.h provides a set of annotations to describe how a function uses its 2172 parameters - the assumptions it makes about them, and the guarantees it makes 2173 upon finishing. 2174 2175 Annotations may be placed before either a function parameter's type or its return 2176 type, and describe the function's behavior regarding the parameter or return value. 2177 There are two classes of annotations: buffer annotations and advanced annotations. 2178 Buffer annotations describe how functions use their pointer parameters, and 2179 advanced annotations either describe complex/unusual buffer behavior, or provide 2180 additional information about a parameter that is not otherwise expressible. 2181 2182 ------------------------------------------------------------------------------- 2183 Buffer Annotations 2184 2185 The most important annotations in sal.h provide a consistent way to annotate 2186 buffer parameters or return values for a function. Each of these annotations describes 2187 a single buffer (which could be a string, a fixed-length or variable-length array, 2188 or just a pointer) that the function interacts with: where it is, how large it is, 2189 how much is initialized, and what the function does with it. 2190 2191 The appropriate macro for a given buffer can be constructed using the table below. 2192 Just pick the appropriate values from each category, and combine them together 2193 with a leading underscore. Some combinations of values do not make sense as buffer 2194 annotations. Only meaningful annotations can be added to your code; for a list of 2195 these, see the buffer annotation definitions section. 2196 2197 Only a single buffer annotation should be used for each parameter. 2198 2199 |------------|------------|---------|--------|----------|----------|---------------| 2200 | Level | Usage | Size | Output | NullTerm | Optional | Parameters | 2201 |------------|------------|---------|--------|----------|----------|---------------| 2202 | <> | <> | <> | <> | _z | <> | <> | 2203 | _deref | _in | _ecount | _full | _nz | _opt | (size) | 2204 | _deref_opt | _out | _bcount | _part | | | (size,length) | 2205 | | _inout | | | | | | 2206 | | | | | | | | 2207 |------------|------------|---------|--------|----------|----------|---------------| 2208 2209 Level: Describes the buffer pointer's level of indirection from the parameter or 2210 return value 'p'. 2211 2212 <> : p is the buffer pointer. 2213 _deref : *p is the buffer pointer. p must not be NULL. 2214 _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of 2215 the annotation is ignored. 2216 2217 Usage: Describes how the function uses the buffer. 2218 2219 <> : The buffer is not accessed. If used on the return value or with _deref, the 2220 function will provide the buffer, and it will be uninitialized at exit. 2221 Otherwise, the caller must provide the buffer. This should only be used 2222 for alloc and free functions. 2223 _in : The function will only read from the buffer. The caller must provide the 2224 buffer and initialize it. Cannot be used with _deref. 2225 _out : The function will only write to the buffer. If used on the return value or 2226 with _deref, the function will provide the buffer and initialize it. 2227 Otherwise, the caller must provide the buffer, and the function will 2228 initialize it. 2229 _inout : The function may freely read from and write to the buffer. The caller must 2230 provide the buffer and initialize it. If used with _deref, the buffer may 2231 be reallocated by the function. 2232 2233 Size: Describes the total size of the buffer. This may be less than the space actually 2234 allocated for the buffer, in which case it describes the accessible amount. 2235 2236 <> : No buffer size is given. If the type specifies the buffer size (such as 2237 with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one 2238 element long. Must be used with _in, _out, or _inout. 2239 _ecount : The buffer size is an explicit element count. 2240 _bcount : The buffer size is an explicit byte count. 2241 2242 Output: Describes how much of the buffer will be initialized by the function. For 2243 _inout buffers, this also describes how much is initialized at entry. Omit this 2244 category for _in buffers; they must be fully initialized by the caller. 2245 2246 <> : The type specifies how much is initialized. For instance, a function initializing 2247 an LPWSTR must NULL-terminate the string. 2248 _full : The function initializes the entire buffer. 2249 _part : The function initializes part of the buffer, and explicitly indicates how much. 2250 2251 NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer. 2252 _z : A '\0' indicated the end of the buffer 2253 _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the 2254 buffer. 2255 Optional: Describes if the buffer itself is optional. 2256 2257 <> : The pointer to the buffer must not be NULL. 2258 _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced. 2259 2260 Parameters: Gives explicit counts for the size and length of the buffer. 2261 2262 <> : There is no explicit count. Use when neither _ecount nor _bcount is used. 2263 (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part. 2264 (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part 2265 and _bcount_part. 2266 2267 ------------------------------------------------------------------------------- 2268 Buffer Annotation Examples 2269 2270 LWSTDAPI_(BOOL) StrToIntExA( 2271 __in LPCSTR pszString, 2272 DWORD dwFlags, 2273 __out int *piRet -- A pointer whose dereference will be filled in. 2274 ); 2275 2276 void MyPaintingFunction( 2277 __in HWND hwndControl, -- An initialized read-only parameter. 2278 __in_opt HDC hdcOptional, -- An initialized read-only parameter that might be NULL. 2279 __inout IPropertyStore *ppsStore -- An initialized parameter that may be freely used 2280 -- and modified. 2281 ); 2282 2283 LWSTDAPI_(BOOL) PathCompactPathExA( 2284 __out_ecount(cchMax) LPSTR pszOut, -- A string buffer with cch elements that will 2285 -- be NULL terminated on exit. 2286 __in LPCSTR pszSrc, 2287 UINT cchMax, 2288 DWORD dwFlags 2289 ); 2290 2291 HRESULT SHLocalAllocBytes( 2292 size_t cb, 2293 __deref_bcount(cb) T **ppv -- A pointer whose dereference will be set to an 2294 -- uninitialized buffer with cb bytes. 2295 ); 2296 2297 __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at 2298 entry and exit, and may be written to by this function. 2299 2300 __out_ecount_part(count, *countOut) : A buffer with count elements that will be 2301 partially initialized by this function. The function indicates how much it 2302 initialized by setting *countOut. 2303 2304 ------------------------------------------------------------------------------- 2305 Advanced Annotations 2306 2307 Advanced annotations describe behavior that is not expressible with the regular 2308 buffer macros. These may be used either to annotate buffer parameters that involve 2309 complex or conditional behavior, or to enrich existing annotations with additional 2310 information. 2311 2312 __success(expr) f : 2313 <expr> indicates whether function f succeeded or not. If <expr> is true at exit, 2314 all the function's guarantees (as given by other annotations) must hold. If <expr> 2315 is false at exit, the caller should not expect any of the function's guarantees 2316 to hold. If not used, the function must always satisfy its guarantees. Added 2317 automatically to functions that indicate success in standard ways, such as by 2318 returning an HRESULT. 2319 2320 __nullterminated p : 2321 Pointer p is a buffer that may be read or written up to and including the first 2322 NULL character or pointer. May be used on typedefs, which marks valid (properly 2323 initialized) instances of that type as being NULL-terminated. 2324 2325 __nullnullterminated p : 2326 Pointer p is a buffer that may be read or written up to and including the first 2327 sequence of two NULL characters or pointers. May be used on typedefs, which marks 2328 valid instances of that type as being double-NULL terminated. 2329 2330 __reserved v : 2331 Value v must be 0/NULL, reserved for future use. 2332 2333 __checkReturn v : 2334 Return value v must not be ignored by callers of this function. 2335 2336 __typefix(ctype) v : 2337 Value v should be treated as an instance of ctype, rather than its declared type. 2338 2339 __override f : 2340 Specify C#-style 'override' behaviour for overriding virtual methods. 2341 2342 __callback f : 2343 Function f can be used as a function pointer. 2344 2345 __format_string p : 2346 Pointer p is a string that contains % markers in the style of printf. 2347 2348 __blocksOn(resource) f : 2349 Function f blocks on the resource 'resource'. 2350 2351 __fallthrough : 2352 Annotates switch statement labels where fall-through is desired, to distinguish 2353 from forgotten break statements. 2354 2355 ------------------------------------------------------------------------------- 2356 Advanced Annotation Examples 2357 2358 __success(return != FALSE) LWSTDAPI_(BOOL) 2359 PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : 2360 pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. 2361 2362 typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. 2363 2364 __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be 2365 a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. 2366 2367 ------------------------------------------------------------------------------- 2368 */ 2369 2370 #define __specstrings 2371 2372 #ifdef __cplusplus // [ 2373 #ifndef __nothrow // [ 2374 # define __nothrow __declspec(nothrow) 2375 #endif // ] 2376 extern "C" { 2377 #else // ][ 2378 #ifndef __nothrow // [ 2379 # define __nothrow 2380 #endif // ] 2381 #endif /* #ifdef __cplusplus */ // ] 2382 2383 2384 /* 2385 ------------------------------------------------------------------------------- 2386 Helper Macro Definitions 2387 2388 These express behavior common to many of the high-level annotations. 2389 DO NOT USE THESE IN YOUR CODE. 2390 ------------------------------------------------------------------------------- 2391 */ 2392 2393 /* 2394 The helper annotations are only understood by the compiler version used by 2395 various defect detection tools. When the regular compiler is running, they 2396 are defined into nothing, and do not affect the compiled code. 2397 */ 2398 2399 #if !defined(__midl) && defined(_PREFAST_) // [ 2400 2401 /* 2402 In the primitive "SAL_*" annotations "SAL" stands for Standard 2403 Annotation Language. These "SAL_*" annotations are the 2404 primitives the compiler understands and high-level MACROs 2405 will decompose into these primivates. 2406 */ 2407 2408 #define _SA_SPECSTRIZE( x ) #x 2409 2410 /* 2411 __null p 2412 __notnull p 2413 __maybenull p 2414 2415 Annotates a pointer p. States that pointer p is null. Commonly used 2416 in the negated form __notnull or the possibly null form __maybenull. 2417 */ 2418 2419 #ifndef PAL_STDCPP_COMPAT 2420 #define __null _Null_impl_ 2421 #define __notnull _Notnull_impl_ 2422 #define __maybenull _Maybenull_impl_ 2423 #endif // !PAL_STDCPP_COMPAT 2424 2425 /* 2426 __readonly l 2427 __notreadonly l 2428 __mabyereadonly l 2429 2430 Annotates a location l. States that location l is not modified after 2431 this point. If the annotation is placed on the precondition state of 2432 a function, the restriction only applies until the postcondition state 2433 of the function. __maybereadonly states that the annotated location 2434 may be modified, whereas __notreadonly states that a location must be 2435 modified. 2436 */ 2437 2438 #define __readonly _Pre1_impl_(__readaccess_impl) 2439 #define __notreadonly _Pre1_impl_(__allaccess_impl) 2440 #define __maybereadonly _Pre1_impl_(__readaccess_impl) 2441 2442 /* 2443 __valid v 2444 __notvalid v 2445 __maybevalid v 2446 2447 Annotates any value v. States that the value satisfies all properties of 2448 valid values of its type. For example, for a string buffer, valid means 2449 that the buffer pointer is either NULL or points to a NULL-terminated string. 2450 */ 2451 2452 #define __valid _Valid_impl_ 2453 #define __notvalid _Notvalid_impl_ 2454 #define __maybevalid _Maybevalid_impl_ 2455 2456 /* 2457 __readableTo(extent) p 2458 2459 Annotates a buffer pointer p. If the buffer can be read, extent describes 2460 how much of the buffer is readable. For a reader of the buffer, this is 2461 an explicit permission to read up to that amount, rather than a restriction to 2462 read only up to it. 2463 */ 2464 2465 #define __readableTo(extent) _SA_annotes1(SAL_readableTo, extent) 2466 2467 /* 2468 2469 __elem_readableTo(size) 2470 2471 Annotates a buffer pointer p as being readable to size elements. 2472 */ 2473 2474 #define __elem_readableTo(size) _SA_annotes1(SAL_readableTo, elementCount( size )) 2475 2476 /* 2477 __byte_readableTo(size) 2478 2479 Annotates a buffer pointer p as being readable to size bytes. 2480 */ 2481 #define __byte_readableTo(size) _SA_annotes1(SAL_readableTo, byteCount(size)) 2482 2483 /* 2484 __writableTo(extent) p 2485 2486 Annotates a buffer pointer p. If the buffer can be modified, extent 2487 describes how much of the buffer is writable (usually the allocation 2488 size). For a writer of the buffer, this is an explicit permission to 2489 write up to that amount, rather than a restriction to write only up to it. 2490 */ 2491 #define __writableTo(size) _SA_annotes1(SAL_writableTo, size) 2492 2493 /* 2494 __elem_writableTo(size) 2495 2496 Annotates a buffer pointer p as being writable to size elements. 2497 */ 2498 #define __elem_writableTo(size) _SA_annotes1(SAL_writableTo, elementCount( size )) 2499 2500 /* 2501 __byte_writableTo(size) 2502 2503 Annotates a buffer pointer p as being writable to size bytes. 2504 */ 2505 #define __byte_writableTo(size) _SA_annotes1(SAL_writableTo, byteCount( size)) 2506 2507 /* 2508 __deref p 2509 2510 Annotates a pointer p. The next annotation applies one dereference down 2511 in the type. If readableTo(p, size) then the next annotation applies to 2512 all elements *(p+i) for which i satisfies the size. If p is a pointer 2513 to a struct, the next annotation applies to all fields of the struct. 2514 */ 2515 #define __deref _Deref_impl_ 2516 2517 /* 2518 __pre __next_annotation 2519 2520 The next annotation applies in the precondition state 2521 */ 2522 #define __pre _Pre_impl_ 2523 2524 /* 2525 __post __next_annotation 2526 2527 The next annotation applies in the postcondition state 2528 */ 2529 #define __post _Post_impl_ 2530 2531 /* 2532 __precond(<expr>) 2533 2534 When <expr> is true, the next annotation applies in the precondition state 2535 (currently not enabled) 2536 */ 2537 #define __precond(expr) __pre 2538 2539 /* 2540 __postcond(<expr>) 2541 2542 When <expr> is true, the next annotation applies in the postcondition state 2543 (currently not enabled) 2544 */ 2545 #define __postcond(expr) __post 2546 2547 /* 2548 __exceptthat 2549 2550 Given a set of annotations Q containing __exceptthat maybeP, the effect of 2551 the except clause is to erase any P or notP annotations (explicit or 2552 implied) within Q at the same level of dereferencing that the except 2553 clause appears, and to replace it with maybeP. 2554 2555 Example 1: __valid __pre_except_maybenull on a pointer p means that the 2556 pointer may be null, and is otherwise valid, thus overriding 2557 the implicit notnull annotation implied by __valid on 2558 pointers. 2559 2560 Example 2: __valid __deref __pre_except_maybenull on an int **p means 2561 that p is not null (implied by valid), but the elements 2562 pointed to by p could be null, and are otherwise valid. 2563 */ 2564 #define __exceptthat __inner_exceptthat 2565 2566 /* 2567 _refparam 2568 2569 Added to all out parameter macros to indicate that they are all reference 2570 parameters. 2571 */ 2572 #define __refparam _Notref_ __deref __notreadonly 2573 2574 /* 2575 __inner_* 2576 2577 Helper macros that directly correspond to certain high-level annotations. 2578 2579 */ 2580 2581 /* 2582 Macros to classify the entrypoints and indicate their category. 2583 2584 Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM. 2585 2586 */ 2587 #define __inner_control_entrypoint(category) _SA_annotes2(SAL_entrypoint, controlEntry, category) 2588 2589 2590 /* 2591 Pre-defined data entry point categories include: Registry, File, Network. 2592 */ 2593 #define __inner_data_entrypoint(category) _SA_annotes2(SAL_entrypoint, dataEntry, category) 2594 2595 #define __inner_override _SA_annotes0(__override) 2596 #define __inner_callback _SA_annotes0(__callback) 2597 #define __inner_blocksOn(resource) _SA_annotes1(SAL_blocksOn, resource) 2598 #define __inner_fallthrough_dec __inline __nothrow void __FallThrough() {} 2599 #define __inner_fallthrough __FallThrough(); 2600 2601 #define __post_except_maybenull __post __inner_exceptthat _Maybenull_impl_ 2602 #define __pre_except_maybenull __pre __inner_exceptthat _Maybenull_impl_ 2603 2604 #define __post_deref_except_maybenull __post __deref __inner_exceptthat _Maybenull_impl_ 2605 #define __pre_deref_except_maybenull __pre __deref __inner_exceptthat _Maybenull_impl_ 2606 2607 #define __inexpressible_readableTo(size) _Readable_elements_impl_(_Inexpressible_(size)) 2608 #define __inexpressible_writableTo(size) _Writable_elements_impl_(_Inexpressible_(size)) 2609 2610 2611 #else // ][ 2612 #ifndef PAL_STDCPP_COMPAT 2613 #define __null 2614 #define __notnull 2615 #endif // !PAL_STDCPP_COMPAT 2616 #define __maybenull 2617 #define __readonly 2618 #define __notreadonly 2619 #define __maybereadonly 2620 #define __valid 2621 #define __notvalid 2622 #define __maybevalid 2623 #define __readableTo(extent) 2624 #define __elem_readableTo(size) 2625 #define __byte_readableTo(size) 2626 #define __writableTo(size) 2627 #define __elem_writableTo(size) 2628 #define __byte_writableTo(size) 2629 #define __deref 2630 #define __pre 2631 #define __post 2632 #define __precond(expr) 2633 #define __postcond(expr) 2634 #define __exceptthat 2635 #define __inner_override 2636 #define __inner_callback 2637 #define __inner_blocksOn(resource) 2638 #define __inner_fallthrough_dec 2639 #define __inner_fallthrough 2640 #define __refparam 2641 #define __inner_control_entrypoint(category) 2642 #define __inner_data_entrypoint(category) 2643 2644 #define __post_except_maybenull 2645 #define __pre_except_maybenull 2646 #define __post_deref_except_maybenull 2647 #define __pre_deref_except_maybenull 2648 2649 #define __inexpressible_readableTo(size) 2650 #define __inexpressible_writableTo(size) 2651 2652 #endif /* #if !defined(__midl) && defined(_PREFAST_) */ // ] 2653 2654 /* 2655 ------------------------------------------------------------------------------- 2656 Buffer Annotation Definitions 2657 2658 Any of these may be used to directly annotate functions, but only one should 2659 be used for each parameter. To determine which annotation to use for a given 2660 buffer, use the table in the buffer annotations section. 2661 ------------------------------------------------------------------------------- 2662 */ 2663 2664 // These macros conflict with c++ headers. 2665 #ifndef PAL_STDCPP_COMPAT 2666 #define __in _SAL1_Source_(__in, (), _In_) 2667 #define __out _SAL1_Source_(__out, (), _Out_) 2668 #endif // !PAL_STDCPP_COMPAT 2669 2670 #define __ecount(size) _SAL1_Source_(__ecount, (size), __notnull __elem_writableTo(size)) 2671 #define __bcount(size) _SAL1_Source_(__bcount, (size), __notnull __byte_writableTo(size)) 2672 #define __in_ecount(size) _SAL1_Source_(__in_ecount, (size), _In_reads_(size)) 2673 #define __in_bcount(size) _SAL1_Source_(__in_bcount, (size), _In_reads_bytes_(size)) 2674 #define __in_z _SAL1_Source_(__in_z, (), _In_z_) 2675 #define __in_ecount_z(size) _SAL1_Source_(__in_ecount_z, (size), _In_reads_z_(size)) 2676 #define __in_bcount_z(size) _SAL1_Source_(__in_bcount_z, (size), __in_bcount(size) __pre __nullterminated) 2677 #define __in_nz _SAL1_Source_(__in_nz, (), __in) 2678 #define __in_ecount_nz(size) _SAL1_Source_(__in_ecount_nz, (size), __in_ecount(size)) 2679 #define __in_bcount_nz(size) _SAL1_Source_(__in_bcount_nz, (size), __in_bcount(size)) 2680 #define __out_ecount(size) _SAL1_Source_(__out_ecount, (size), _Out_writes_(size)) 2681 #define __out_bcount(size) _SAL1_Source_(__out_bcount, (size), _Out_writes_bytes_(size)) 2682 #define __out_ecount_part(size,length) _SAL1_Source_(__out_ecount_part, (size,length), _Out_writes_to_(size,length)) 2683 #define __out_bcount_part(size,length) _SAL1_Source_(__out_bcount_part, (size,length), _Out_writes_bytes_to_(size,length)) 2684 #define __out_ecount_full(size) _SAL1_Source_(__out_ecount_full, (size), _Out_writes_all_(size)) 2685 #define __out_bcount_full(size) _SAL1_Source_(__out_bcount_full, (size), _Out_writes_bytes_all_(size)) 2686 #define __out_z _SAL1_Source_(__out_z, (), __post __valid __refparam __post __nullterminated) 2687 #define __out_z_opt _SAL1_Source_(__out_z_opt, (), __post __valid __refparam __post __nullterminated __pre_except_maybenull) 2688 #define __out_ecount_z(size) _SAL1_Source_(__out_ecount_z, (size), __ecount(size) __post __valid __refparam __post __nullterminated) 2689 #define __out_bcount_z(size) _SAL1_Source_(__out_bcount_z, (size), __bcount(size) __post __valid __refparam __post __nullterminated) 2690 #define __out_ecount_part_z(size,length) _SAL1_Source_(__out_ecount_part_z, (size,length), __out_ecount_part(size,length) __post __nullterminated) 2691 #define __out_bcount_part_z(size,length) _SAL1_Source_(__out_bcount_part_z, (size,length), __out_bcount_part(size,length) __post __nullterminated) 2692 #define __out_ecount_full_z(size) _SAL1_Source_(__out_ecount_full_z, (size), __out_ecount_full(size) __post __nullterminated) 2693 #define __out_bcount_full_z(size) _SAL1_Source_(__out_bcount_full_z, (size), __out_bcount_full(size) __post __nullterminated) 2694 #define __out_nz _SAL1_Source_(__out_nz, (), __post __valid __refparam) 2695 #define __out_nz_opt _SAL1_Source_(__out_nz_opt, (), __post __valid __refparam __post_except_maybenull_) 2696 #define __out_ecount_nz(size) _SAL1_Source_(__out_ecount_nz, (size), __ecount(size) __post __valid __refparam) 2697 #define __out_bcount_nz(size) _SAL1_Source_(__out_bcount_nz, (size), __bcount(size) __post __valid __refparam) 2698 #define __inout _SAL1_Source_(__inout, (), _Inout_) 2699 #define __inout_ecount(size) _SAL1_Source_(__inout_ecount, (size), _Inout_updates_(size)) 2700 #define __inout_bcount(size) _SAL1_Source_(__inout_bcount, (size), _Inout_updates_bytes_(size)) 2701 #define __inout_ecount_part(size,length) _SAL1_Source_(__inout_ecount_part, (size,length), _Inout_updates_to_(size,length)) 2702 #define __inout_bcount_part(size,length) _SAL1_Source_(__inout_bcount_part, (size,length), _Inout_updates_bytes_to_(size,length)) 2703 #define __inout_ecount_full(size) _SAL1_Source_(__inout_ecount_full, (size), _Inout_updates_all_(size)) 2704 #define __inout_bcount_full(size) _SAL1_Source_(__inout_bcount_full, (size), _Inout_updates_bytes_all_(size)) 2705 #define __inout_z _SAL1_Source_(__inout_z, (), _Inout_z_) 2706 #define __inout_ecount_z(size) _SAL1_Source_(__inout_ecount_z, (size), _Inout_updates_z_(size)) 2707 #define __inout_bcount_z(size) _SAL1_Source_(__inout_bcount_z, (size), __inout_bcount(size) __pre __nullterminated __post __nullterminated) 2708 #define __inout_nz _SAL1_Source_(__inout_nz, (), __inout) 2709 #define __inout_ecount_nz(size) _SAL1_Source_(__inout_ecount_nz, (size), __inout_ecount(size)) 2710 #define __inout_bcount_nz(size) _SAL1_Source_(__inout_bcount_nz, (size), __inout_bcount(size)) 2711 #define __ecount_opt(size) _SAL1_Source_(__ecount_opt, (size), __ecount(size) __pre_except_maybenull) 2712 #define __bcount_opt(size) _SAL1_Source_(__bcount_opt, (size), __bcount(size) __pre_except_maybenull) 2713 #define __in_opt _SAL1_Source_(__in_opt, (), _In_opt_) 2714 #define __in_ecount_opt(size) _SAL1_Source_(__in_ecount_opt, (size), _In_reads_opt_(size)) 2715 #define __in_bcount_opt(size) _SAL1_Source_(__in_bcount_opt, (size), _In_reads_bytes_opt_(size)) 2716 #define __in_z_opt _SAL1_Source_(__in_z_opt, (), _In_opt_z_) 2717 #define __in_ecount_z_opt(size) _SAL1_Source_(__in_ecount_z_opt, (size), __in_ecount_opt(size) __pre __nullterminated) 2718 #define __in_bcount_z_opt(size) _SAL1_Source_(__in_bcount_z_opt, (size), __in_bcount_opt(size) __pre __nullterminated) 2719 #define __in_nz_opt _SAL1_Source_(__in_nz_opt, (), __in_opt) 2720 #define __in_ecount_nz_opt(size) _SAL1_Source_(__in_ecount_nz_opt, (size), __in_ecount_opt(size)) 2721 #define __in_bcount_nz_opt(size) _SAL1_Source_(__in_bcount_nz_opt, (size), __in_bcount_opt(size)) 2722 #define __out_opt _SAL1_Source_(__out_opt, (), _Out_opt_) 2723 #define __out_ecount_opt(size) _SAL1_Source_(__out_ecount_opt, (size), _Out_writes_opt_(size)) 2724 #define __out_bcount_opt(size) _SAL1_Source_(__out_bcount_opt, (size), _Out_writes_bytes_opt_(size)) 2725 #define __out_ecount_part_opt(size,length) _SAL1_Source_(__out_ecount_part_opt, (size,length), __out_ecount_part(size,length) __pre_except_maybenull) 2726 #define __out_bcount_part_opt(size,length) _SAL1_Source_(__out_bcount_part_opt, (size,length), __out_bcount_part(size,length) __pre_except_maybenull) 2727 #define __out_ecount_full_opt(size) _SAL1_Source_(__out_ecount_full_opt, (size), __out_ecount_full(size) __pre_except_maybenull) 2728 #define __out_bcount_full_opt(size) _SAL1_Source_(__out_bcount_full_opt, (size), __out_bcount_full(size) __pre_except_maybenull) 2729 #define __out_ecount_z_opt(size) _SAL1_Source_(__out_ecount_z_opt, (size), __out_ecount_opt(size) __post __nullterminated) 2730 #define __out_bcount_z_opt(size) _SAL1_Source_(__out_bcount_z_opt, (size), __out_bcount_opt(size) __post __nullterminated) 2731 #define __out_ecount_part_z_opt(size,length) _SAL1_Source_(__out_ecount_part_z_opt, (size,length), __out_ecount_part_opt(size,length) __post __nullterminated) 2732 #define __out_bcount_part_z_opt(size,length) _SAL1_Source_(__out_bcount_part_z_opt, (size,length), __out_bcount_part_opt(size,length) __post __nullterminated) 2733 #define __out_ecount_full_z_opt(size) _SAL1_Source_(__out_ecount_full_z_opt, (size), __out_ecount_full_opt(size) __post __nullterminated) 2734 #define __out_bcount_full_z_opt(size) _SAL1_Source_(__out_bcount_full_z_opt, (size), __out_bcount_full_opt(size) __post __nullterminated) 2735 #define __out_ecount_nz_opt(size) _SAL1_Source_(__out_ecount_nz_opt, (size), __out_ecount_opt(size) __post __nullterminated) 2736 #define __out_bcount_nz_opt(size) _SAL1_Source_(__out_bcount_nz_opt, (size), __out_bcount_opt(size) __post __nullterminated) 2737 #define __inout_opt _SAL1_Source_(__inout_opt, (), _Inout_opt_) 2738 #define __inout_ecount_opt(size) _SAL1_Source_(__inout_ecount_opt, (size), __inout_ecount(size) __pre_except_maybenull) 2739 #define __inout_bcount_opt(size) _SAL1_Source_(__inout_bcount_opt, (size), __inout_bcount(size) __pre_except_maybenull) 2740 #define __inout_ecount_part_opt(size,length) _SAL1_Source_(__inout_ecount_part_opt, (size,length), __inout_ecount_part(size,length) __pre_except_maybenull) 2741 #define __inout_bcount_part_opt(size,length) _SAL1_Source_(__inout_bcount_part_opt, (size,length), __inout_bcount_part(size,length) __pre_except_maybenull) 2742 #define __inout_ecount_full_opt(size) _SAL1_Source_(__inout_ecount_full_opt, (size), __inout_ecount_full(size) __pre_except_maybenull) 2743 #define __inout_bcount_full_opt(size) _SAL1_Source_(__inout_bcount_full_opt, (size), __inout_bcount_full(size) __pre_except_maybenull) 2744 #define __inout_z_opt _SAL1_Source_(__inout_z_opt, (), __inout_opt __pre __nullterminated __post __nullterminated) 2745 #define __inout_ecount_z_opt(size) _SAL1_Source_(__inout_ecount_z_opt, (size), __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated) 2746 #define __inout_ecount_z_opt(size) _SAL1_Source_(__inout_ecount_z_opt, (size), __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated) 2747 #define __inout_bcount_z_opt(size) _SAL1_Source_(__inout_bcount_z_opt, (size), __inout_bcount_opt(size)) 2748 #define __inout_nz_opt _SAL1_Source_(__inout_nz_opt, (), __inout_opt) 2749 #define __inout_ecount_nz_opt(size) _SAL1_Source_(__inout_ecount_nz_opt, (size), __inout_ecount_opt(size)) 2750 #define __inout_bcount_nz_opt(size) _SAL1_Source_(__inout_bcount_nz_opt, (size), __inout_bcount_opt(size)) 2751 #define __deref_ecount(size) _SAL1_Source_(__deref_ecount, (size), _Notref_ __ecount(1) __post _Notref_ __elem_readableTo(1) __post _Notref_ __deref _Notref_ __notnull __post __deref __elem_writableTo(size)) 2752 #define __deref_bcount(size) _SAL1_Source_(__deref_bcount, (size), _Notref_ __ecount(1) __post _Notref_ __elem_readableTo(1) __post _Notref_ __deref _Notref_ __notnull __post __deref __byte_writableTo(size)) 2753 #define __deref_out _SAL1_Source_(__deref_out, (), _Outptr_) 2754 #define __deref_out_ecount(size) _SAL1_Source_(__deref_out_ecount, (size), _Outptr_result_buffer_(size)) 2755 #define __deref_out_bcount(size) _SAL1_Source_(__deref_out_bcount, (size), _Outptr_result_bytebuffer_(size)) 2756 #define __deref_out_ecount_part(size,length) _SAL1_Source_(__deref_out_ecount_part, (size,length), _Outptr_result_buffer_to_(size,length)) 2757 #define __deref_out_bcount_part(size,length) _SAL1_Source_(__deref_out_bcount_part, (size,length), _Outptr_result_bytebuffer_to_(size,length)) 2758 #define __deref_out_ecount_full(size) _SAL1_Source_(__deref_out_ecount_full, (size), __deref_out_ecount_part(size,size)) 2759 #define __deref_out_bcount_full(size) _SAL1_Source_(__deref_out_bcount_full, (size), __deref_out_bcount_part(size,size)) 2760 #define __deref_out_z _SAL1_Source_(__deref_out_z, (), _Outptr_result_z_) 2761 #define __deref_out_ecount_z(size) _SAL1_Source_(__deref_out_ecount_z, (size), __deref_out_ecount(size) __post __deref __nullterminated) 2762 #define __deref_out_bcount_z(size) _SAL1_Source_(__deref_out_bcount_z, (size), __deref_out_bcount(size) __post __deref __nullterminated) 2763 #define __deref_out_nz _SAL1_Source_(__deref_out_nz, (), __deref_out) 2764 #define __deref_out_ecount_nz(size) _SAL1_Source_(__deref_out_ecount_nz, (size), __deref_out_ecount(size)) 2765 #define __deref_out_bcount_nz(size) _SAL1_Source_(__deref_out_bcount_nz, (size), __deref_out_ecount(size)) 2766 #define __deref_inout _SAL1_Source_(__deref_inout, (), _Notref_ __notnull _Notref_ __elem_readableTo(1) __pre __deref __valid __post _Notref_ __deref __valid __refparam) 2767 #define __deref_inout_z _SAL1_Source_(__deref_inout_z, (), __deref_inout __pre __deref __nullterminated __post _Notref_ __deref __nullterminated) 2768 #define __deref_inout_ecount(size) _SAL1_Source_(__deref_inout_ecount, (size), __deref_inout __pre __deref __elem_writableTo(size) __post _Notref_ __deref __elem_writableTo(size)) 2769 #define __deref_inout_bcount(size) _SAL1_Source_(__deref_inout_bcount, (size), __deref_inout __pre __deref __byte_writableTo(size) __post _Notref_ __deref __byte_writableTo(size)) 2770 #define __deref_inout_ecount_part(size,length) _SAL1_Source_(__deref_inout_ecount_part, (size,length), __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length)) 2771 #define __deref_inout_bcount_part(size,length) _SAL1_Source_(__deref_inout_bcount_part, (size,length), __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length)) 2772 #define __deref_inout_ecount_full(size) _SAL1_Source_(__deref_inout_ecount_full, (size), __deref_inout_ecount_part(size,size)) 2773 #define __deref_inout_bcount_full(size) _SAL1_Source_(__deref_inout_bcount_full, (size), __deref_inout_bcount_part(size,size)) 2774 #define __deref_inout_ecount_z(size) _SAL1_Source_(__deref_inout_ecount_z, (size), __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated) 2775 #define __deref_inout_bcount_z(size) _SAL1_Source_(__deref_inout_bcount_z, (size), __deref_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated) 2776 #define __deref_inout_nz _SAL1_Source_(__deref_inout_nz, (), __deref_inout) 2777 #define __deref_inout_ecount_nz(size) _SAL1_Source_(__deref_inout_ecount_nz, (size), __deref_inout_ecount(size)) 2778 #define __deref_inout_bcount_nz(size) _SAL1_Source_(__deref_inout_bcount_nz, (size), __deref_inout_ecount(size)) 2779 #define __deref_ecount_opt(size) _SAL1_Source_(__deref_ecount_opt, (size), __deref_ecount(size) __post_deref_except_maybenull) 2780 #define __deref_bcount_opt(size) _SAL1_Source_(__deref_bcount_opt, (size), __deref_bcount(size) __post_deref_except_maybenull) 2781 #define __deref_out_opt _SAL1_Source_(__deref_out_opt, (), __deref_out __post_deref_except_maybenull) 2782 #define __deref_out_ecount_opt(size) _SAL1_Source_(__deref_out_ecount_opt, (size), __deref_out_ecount(size) __post_deref_except_maybenull) 2783 #define __deref_out_bcount_opt(size) _SAL1_Source_(__deref_out_bcount_opt, (size), __deref_out_bcount(size) __post_deref_except_maybenull) 2784 #define __deref_out_ecount_part_opt(size,length) _SAL1_Source_(__deref_out_ecount_part_opt, (size,length), __deref_out_ecount_part(size,length) __post_deref_except_maybenull) 2785 #define __deref_out_bcount_part_opt(size,length) _SAL1_Source_(__deref_out_bcount_part_opt, (size,length), __deref_out_bcount_part(size,length) __post_deref_except_maybenull) 2786 #define __deref_out_ecount_full_opt(size) _SAL1_Source_(__deref_out_ecount_full_opt, (size), __deref_out_ecount_full(size) __post_deref_except_maybenull) 2787 #define __deref_out_bcount_full_opt(size) _SAL1_Source_(__deref_out_bcount_full_opt, (size), __deref_out_bcount_full(size) __post_deref_except_maybenull) 2788 #define __deref_out_z_opt _SAL1_Source_(__deref_out_z_opt, (), _Outptr_result_maybenull_z_) 2789 #define __deref_out_ecount_z_opt(size) _SAL1_Source_(__deref_out_ecount_z_opt, (size), __deref_out_ecount_opt(size) __post __deref __nullterminated) 2790 #define __deref_out_bcount_z_opt(size) _SAL1_Source_(__deref_out_bcount_z_opt, (size), __deref_out_bcount_opt(size) __post __deref __nullterminated) 2791 #define __deref_out_nz_opt _SAL1_Source_(__deref_out_nz_opt, (), __deref_out_opt) 2792 #define __deref_out_ecount_nz_opt(size) _SAL1_Source_(__deref_out_ecount_nz_opt, (size), __deref_out_ecount_opt(size)) 2793 #define __deref_out_bcount_nz_opt(size) _SAL1_Source_(__deref_out_bcount_nz_opt, (size), __deref_out_bcount_opt(size)) 2794 #define __deref_inout_opt _SAL1_Source_(__deref_inout_opt, (), __deref_inout __pre_deref_except_maybenull __post_deref_except_maybenull) 2795 #define __deref_inout_ecount_opt(size) _SAL1_Source_(__deref_inout_ecount_opt, (size), __deref_inout_ecount(size) __pre_deref_except_maybenull __post_deref_except_maybenull) 2796 #define __deref_inout_bcount_opt(size) _SAL1_Source_(__deref_inout_bcount_opt, (size), __deref_inout_bcount(size) __pre_deref_except_maybenull __post_deref_except_maybenull) 2797 #define __deref_inout_ecount_part_opt(size,length) _SAL1_Source_(__deref_inout_ecount_part_opt, (size,length), __deref_inout_ecount_part(size,length) __pre_deref_except_maybenull __post_deref_except_maybenull) 2798 #define __deref_inout_bcount_part_opt(size,length) _SAL1_Source_(__deref_inout_bcount_part_opt, (size,length), __deref_inout_bcount_part(size,length) __pre_deref_except_maybenull __post_deref_except_maybenull) 2799 #define __deref_inout_ecount_full_opt(size) _SAL1_Source_(__deref_inout_ecount_full_opt, (size), __deref_inout_ecount_full(size) __pre_deref_except_maybenull __post_deref_except_maybenull) 2800 #define __deref_inout_bcount_full_opt(size) _SAL1_Source_(__deref_inout_bcount_full_opt, (size), __deref_inout_bcount_full(size) __pre_deref_except_maybenull __post_deref_except_maybenull) 2801 #define __deref_inout_z_opt _SAL1_Source_(__deref_inout_z_opt, (), __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated) 2802 #define __deref_inout_ecount_z_opt(size) _SAL1_Source_(__deref_inout_ecount_z_opt, (size), __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated) 2803 #define __deref_inout_bcount_z_opt(size) _SAL1_Source_(__deref_inout_bcount_z_opt, (size), __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated) 2804 #define __deref_inout_nz_opt _SAL1_Source_(__deref_inout_nz_opt, (), __deref_inout_opt) 2805 #define __deref_inout_ecount_nz_opt(size) _SAL1_Source_(__deref_inout_ecount_nz_opt, (size), __deref_inout_ecount_opt(size)) 2806 #define __deref_inout_bcount_nz_opt(size) _SAL1_Source_(__deref_inout_bcount_nz_opt, (size), __deref_inout_bcount_opt(size)) 2807 #define __deref_opt_ecount(size) _SAL1_Source_(__deref_opt_ecount, (size), __deref_ecount(size) __pre_except_maybenull) 2808 #define __deref_opt_bcount(size) _SAL1_Source_(__deref_opt_bcount, (size), __deref_bcount(size) __pre_except_maybenull) 2809 #define __deref_opt_out _SAL1_Source_(__deref_opt_out, (), _Outptr_opt_) 2810 #define __deref_opt_out_z _SAL1_Source_(__deref_opt_out_z, (), _Outptr_opt_result_z_) 2811 #define __deref_opt_out_ecount(size) _SAL1_Source_(__deref_opt_out_ecount, (size), __deref_out_ecount(size) __pre_except_maybenull) 2812 #define __deref_opt_out_bcount(size) _SAL1_Source_(__deref_opt_out_bcount, (size), __deref_out_bcount(size) __pre_except_maybenull) 2813 #define __deref_opt_out_ecount_part(size,length) _SAL1_Source_(__deref_opt_out_ecount_part, (size,length), __deref_out_ecount_part(size,length) __pre_except_maybenull) 2814 #define __deref_opt_out_bcount_part(size,length) _SAL1_Source_(__deref_opt_out_bcount_part, (size,length), __deref_out_bcount_part(size,length) __pre_except_maybenull) 2815 #define __deref_opt_out_ecount_full(size) _SAL1_Source_(__deref_opt_out_ecount_full, (size), __deref_out_ecount_full(size) __pre_except_maybenull) 2816 #define __deref_opt_out_bcount_full(size) _SAL1_Source_(__deref_opt_out_bcount_full, (size), __deref_out_bcount_full(size) __pre_except_maybenull) 2817 #define __deref_opt_inout _SAL1_Source_(__deref_opt_inout, (), _Inout_opt_) 2818 #define __deref_opt_inout_ecount(size) _SAL1_Source_(__deref_opt_inout_ecount, (size), __deref_inout_ecount(size) __pre_except_maybenull) 2819 #define __deref_opt_inout_bcount(size) _SAL1_Source_(__deref_opt_inout_bcount, (size), __deref_inout_bcount(size) __pre_except_maybenull) 2820 #define __deref_opt_inout_ecount_part(size,length) _SAL1_Source_(__deref_opt_inout_ecount_part, (size,length), __deref_inout_ecount_part(size,length) __pre_except_maybenull) 2821 #define __deref_opt_inout_bcount_part(size,length) _SAL1_Source_(__deref_opt_inout_bcount_part, (size,length), __deref_inout_bcount_part(size,length) __pre_except_maybenull) 2822 #define __deref_opt_inout_ecount_full(size) _SAL1_Source_(__deref_opt_inout_ecount_full, (size), __deref_inout_ecount_full(size) __pre_except_maybenull) 2823 #define __deref_opt_inout_bcount_full(size) _SAL1_Source_(__deref_opt_inout_bcount_full, (size), __deref_inout_bcount_full(size) __pre_except_maybenull) 2824 #define __deref_opt_inout_z _SAL1_Source_(__deref_opt_inout_z, (), __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated) 2825 #define __deref_opt_inout_ecount_z(size) _SAL1_Source_(__deref_opt_inout_ecount_z, (size), __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated) 2826 #define __deref_opt_inout_bcount_z(size) _SAL1_Source_(__deref_opt_inout_bcount_z, (size), __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated) 2827 #define __deref_opt_inout_nz _SAL1_Source_(__deref_opt_inout_nz, (), __deref_opt_inout) 2828 #define __deref_opt_inout_ecount_nz(size) _SAL1_Source_(__deref_opt_inout_ecount_nz, (size), __deref_opt_inout_ecount(size)) 2829 #define __deref_opt_inout_bcount_nz(size) _SAL1_Source_(__deref_opt_inout_bcount_nz, (size), __deref_opt_inout_bcount(size)) 2830 #define __deref_opt_ecount_opt(size) _SAL1_Source_(__deref_opt_ecount_opt, (size), __deref_ecount_opt(size) __pre_except_maybenull) 2831 #define __deref_opt_bcount_opt(size) _SAL1_Source_(__deref_opt_bcount_opt, (size), __deref_bcount_opt(size) __pre_except_maybenull) 2832 #define __deref_opt_out_opt _SAL1_Source_(__deref_opt_out_opt, (), _Outptr_opt_result_maybenull_) 2833 #define __deref_opt_out_ecount_opt(size) _SAL1_Source_(__deref_opt_out_ecount_opt, (size), __deref_out_ecount_opt(size) __pre_except_maybenull) 2834 #define __deref_opt_out_bcount_opt(size) _SAL1_Source_(__deref_opt_out_bcount_opt, (size), __deref_out_bcount_opt(size) __pre_except_maybenull) 2835 #define __deref_opt_out_ecount_part_opt(size,length) _SAL1_Source_(__deref_opt_out_ecount_part_opt, (size,length), __deref_out_ecount_part_opt(size,length) __pre_except_maybenull) 2836 #define __deref_opt_out_bcount_part_opt(size,length) _SAL1_Source_(__deref_opt_out_bcount_part_opt, (size,length), __deref_out_bcount_part_opt(size,length) __pre_except_maybenull) 2837 #define __deref_opt_out_ecount_full_opt(size) _SAL1_Source_(__deref_opt_out_ecount_full_opt, (size), __deref_out_ecount_full_opt(size) __pre_except_maybenull) 2838 #define __deref_opt_out_bcount_full_opt(size) _SAL1_Source_(__deref_opt_out_bcount_full_opt, (size), __deref_out_bcount_full_opt(size) __pre_except_maybenull) 2839 #define __deref_opt_out_z_opt _SAL1_Source_(__deref_opt_out_z_opt, (), __post __deref __valid __refparam __pre_except_maybenull __pre_deref_except_maybenull __post_deref_except_maybenull __post __deref __nullterminated) 2840 #define __deref_opt_out_ecount_z_opt(size) _SAL1_Source_(__deref_opt_out_ecount_z_opt, (size), __deref_opt_out_ecount_opt(size) __post __deref __nullterminated) 2841 #define __deref_opt_out_bcount_z_opt(size) _SAL1_Source_(__deref_opt_out_bcount_z_opt, (size), __deref_opt_out_bcount_opt(size) __post __deref __nullterminated) 2842 #define __deref_opt_out_nz_opt _SAL1_Source_(__deref_opt_out_nz_opt, (), __deref_opt_out_opt) 2843 #define __deref_opt_out_ecount_nz_opt(size) _SAL1_Source_(__deref_opt_out_ecount_nz_opt, (size), __deref_opt_out_ecount_opt(size)) 2844 #define __deref_opt_out_bcount_nz_opt(size) _SAL1_Source_(__deref_opt_out_bcount_nz_opt, (size), __deref_opt_out_bcount_opt(size)) 2845 #define __deref_opt_inout_opt _SAL1_Source_(__deref_opt_inout_opt, (), __deref_inout_opt __pre_except_maybenull) 2846 #define __deref_opt_inout_ecount_opt(size) _SAL1_Source_(__deref_opt_inout_ecount_opt, (size), __deref_inout_ecount_opt(size) __pre_except_maybenull) 2847 #define __deref_opt_inout_bcount_opt(size) _SAL1_Source_(__deref_opt_inout_bcount_opt, (size), __deref_inout_bcount_opt(size) __pre_except_maybenull) 2848 #define __deref_opt_inout_ecount_part_opt(size,length) _SAL1_Source_(__deref_opt_inout_ecount_part_opt, (size,length), __deref_inout_ecount_part_opt(size,length) __pre_except_maybenull) 2849 #define __deref_opt_inout_bcount_part_opt(size,length) _SAL1_Source_(__deref_opt_inout_bcount_part_opt, (size,length), __deref_inout_bcount_part_opt(size,length) __pre_except_maybenull) 2850 #define __deref_opt_inout_ecount_full_opt(size) _SAL1_Source_(__deref_opt_inout_ecount_full_opt, (size), __deref_inout_ecount_full_opt(size) __pre_except_maybenull) 2851 #define __deref_opt_inout_bcount_full_opt(size) _SAL1_Source_(__deref_opt_inout_bcount_full_opt, (size), __deref_inout_bcount_full_opt(size) __pre_except_maybenull) 2852 #define __deref_opt_inout_z_opt _SAL1_Source_(__deref_opt_inout_z_opt, (), __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated) 2853 #define __deref_opt_inout_ecount_z_opt(size) _SAL1_Source_(__deref_opt_inout_ecount_z_opt, (size), __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated) 2854 #define __deref_opt_inout_bcount_z_opt(size) _SAL1_Source_(__deref_opt_inout_bcount_z_opt, (size), __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated) 2855 #define __deref_opt_inout_nz_opt _SAL1_Source_(__deref_opt_inout_nz_opt, (), __deref_opt_inout_opt) 2856 #define __deref_opt_inout_ecount_nz_opt(size) _SAL1_Source_(__deref_opt_inout_ecount_nz_opt, (size), __deref_opt_inout_ecount_opt(size)) 2857 #define __deref_opt_inout_bcount_nz_opt(size) _SAL1_Source_(__deref_opt_inout_bcount_nz_opt, (size), __deref_opt_inout_bcount_opt(size)) 2858 2859 /* 2860 ------------------------------------------------------------------------------- 2861 Advanced Annotation Definitions 2862 2863 Any of these may be used to directly annotate functions, and may be used in 2864 combination with each other or with regular buffer macros. For an explanation 2865 of each annotation, see the advanced annotations section. 2866 ------------------------------------------------------------------------------- 2867 */ 2868 2869 #define __success(expr) _Success_(expr) 2870 #define __nullterminated _Null_terminated_ 2871 #define __nullnullterminated 2872 #define __reserved _SAL1_Source_(__reserved, (), _Reserved_) 2873 #define __checkReturn _SAL1_Source_(__checkReturn, (), _Check_return_) 2874 #define __typefix(ctype) _SAL1_Source_(__typefix, (ctype), __inner_typefix(ctype)) 2875 #define __override __inner_override 2876 #define __callback __inner_callback 2877 #define __format_string _Printf_format_string_ 2878 #define __blocksOn(resource) __inner_blocksOn(resource) 2879 #define __control_entrypoint(category) __inner_control_entrypoint(category) 2880 #define __data_entrypoint(category) __inner_data_entrypoint(category) 2881 #define __useHeader _Use_decl_anno_impl_ 2882 #define __on_failure(annotes) _On_failure_impl_(annotes _SAL_nop_impl_) 2883 2884 #ifndef __fallthrough // [ 2885 __inner_fallthrough_dec 2886 #define __fallthrough __inner_fallthrough 2887 #endif // ] 2888 2889 #ifndef __analysis_assume // [ 2890 #ifdef _PREFAST_ // [ 2891 #define __analysis_assume(expr) __assume(expr) 2892 #else // ][ 2893 #define __analysis_assume(expr) 2894 #endif // ] 2895 #endif // ] 2896 2897 #ifndef _Analysis_assume_ // [ 2898 #ifdef _PREFAST_ // [ 2899 #define _Analysis_assume_(expr) __assume(expr) 2900 #else // ][ 2901 #define _Analysis_assume_(expr) 2902 #endif // ] 2903 #endif // ] 2904 2905 #define _Analysis_noreturn_ _SAL2_Source_(_Analysis_noreturn_, (), _SA_annotes0(SAL_terminates)) 2906 2907 #ifdef _PREFAST_ // [ 2908 __inline __nothrow 2909 void __AnalysisAssumeNullterminated(_Post_ __nullterminated void *p); 2910 2911 #define _Analysis_assume_nullterminated_(x) __AnalysisAssumeNullterminated(x) 2912 #else // ][ 2913 #define _Analysis_assume_nullterminated_(x) 2914 #endif // ] 2915 2916 // 2917 // Set the analysis mode (global flags to analysis). 2918 // They take effect at the point of declaration; use at global scope 2919 // as a declaration. 2920 // 2921 2922 // Synthesize a unique symbol. 2923 #define ___MKID(x, y) x ## y 2924 #define __MKID(x, y) ___MKID(x, y) 2925 #define __GENSYM(x) __MKID(x, __COUNTER__) 2926 2927 __ANNOTATION(SAL_analysisMode(__AuToQuOtE __In_impl_ char *mode);) 2928 2929 #define _Analysis_mode_impl_(mode) _SA_annotes1(SAL_analysisMode, #mode) 2930 2931 #define _Analysis_mode_(mode) \ 2932 typedef _Analysis_mode_impl_(mode) int \ 2933 __GENSYM(__prefast_analysis_mode_flag); 2934 2935 // The following are predefined: 2936 // _Analysis_operator_new_throw_ (operator new throws) 2937 // _Analysis_operator_new_null_ (operator new returns null) 2938 // _Analysis_operator_new_never_fails_ (operator new never fails) 2939 // 2940 2941 // Function class annotations. 2942 __ANNOTATION(SAL_functionClassNew(__In_impl_ char*);) 2943 __PRIMOP(int, _In_function_class_(__In_impl_ char*);) 2944 #define _In_function_class_(x) _In_function_class_(#x) 2945 2946 #define _Function_class_(x) _SA_annotes1(SAL_functionClassNew, #x) 2947 2948 /* 2949 * interlocked operand used in interlocked instructions 2950 */ 2951 #define _Interlocked_operand_ _Pre_ _SA_annotes0(SAL_interlocked) 2952 2953 #define _Enum_is_bitflag_ _SA_annotes0(SAL_enumIsBitflag) 2954 #define _Strict_type_match_ _SA_annotes0(SAL_strictType2) 2955 2956 #define _Maybe_raises_SEH_exception_ _Pre_ _SA_annotes1(SAL_inTry,__yes) 2957 #define _Raises_SEH_exception_ _Group_(_Maybe_raises_SEH_exception_ _Analysis_noreturn_) 2958 2959 #ifdef __cplusplus // [ 2960 } 2961 #endif // ] 2962 2963 // Rotor doesn't need concurrency sal. 2964 // #include <ConcurrencySal.h> 2965 2966