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