|
1 | 1 | --- |
2 | 2 | title: Annotating Function Parameters and Return Values |
3 | | -ms.date: 11/04/2016 |
| 3 | +ms.date: 07/11/2019 |
4 | 4 | ms.topic: "conceptual" |
5 | 5 | f1_keywords: |
6 | 6 | - "_Outptr_opt_result_bytebuffer_to_" |
@@ -119,6 +119,9 @@ f1_keywords: |
119 | 119 | - "_Outref_result_bytebuffer_" |
120 | 120 | - "_Result_nullonfailure_" |
121 | 121 | - "_Ret_null_" |
| 122 | + - "_Scanf_format_string_" |
| 123 | + - "_Scanf_s_format_string_" |
| 124 | + - "_Printf_format_string_" |
122 | 125 | ms.assetid: 82826a3d-0c81-421c-8ffe-4072555dca3a |
123 | 126 | author: mikeblome |
124 | 127 | ms.author: mblome |
@@ -279,6 +282,7 @@ This article describes typical uses of annotations for simple function parameter |
279 | 282 | A pointer to a null-terminated array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard. The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state. |
280 | 283 |
|
281 | 284 | ## Optional Pointer Parameters |
| 285 | + |
282 | 286 | When a pointer parameter annotation includes `_opt_`, it indicates that the parameter may be null. Otherwise, the annotation performs the same as the version that doesn't include `_opt_`. Here is a list of the `_opt_` variants of the pointer parameter annotations: |
283 | 287 |
|
284 | 288 | |||| |
@@ -378,6 +382,7 @@ This article describes typical uses of annotations for simple function parameter |
378 | 382 | The returned pointer points to a valid buffer if the function succeeds, or null if the function fails. This annotation is for a reference parameter. |
379 | 383 |
|
380 | 384 | ## Output Reference Parameters |
| 385 | + |
381 | 386 | A common use of the reference parameter is for output parameters. For simple output reference parameters—for example, `int&`—`_Out_` provides the correct semantics. However, when the output value is a pointer—for example `int *&`—the equivalent pointer annotations like `_Outptr_ int **` don't provide the correct semantics. To concisely express the semantics of output reference parameters for pointer types, use these composite annotations: |
382 | 387 |
|
383 | 388 | **Annotations and Descriptions** |
@@ -439,13 +444,65 @@ This article describes typical uses of annotations for simple function parameter |
439 | 444 | Result must be valid in post-state, but may be null in post state. Points to valid buffer of `s` bytes of valid elements. |
440 | 445 |
|
441 | 446 | ## Return Values |
| 447 | + |
442 | 448 | The return value of a function resembles an `_Out_` parameter but is at a different level of de-reference, and you don't have to consider the concept of the pointer to the result. For the following annotations, the return value is the annotated object—a scalar, a pointer to a struct, or a pointer to a buffer. These annotations have the same semantics as the corresponding `_Out_` annotation. |
443 | 449 |
|
444 | 450 | ||| |
445 | 451 | |-|-| |
446 | 452 | |`_Ret_z_`<br /><br /> `_Ret_writes_(s)`<br /><br /> `_Ret_writes_bytes_(s)`<br /><br /> `_Ret_writes_z_(s)`<br /><br /> `_Ret_writes_to_(s,c)`<br /><br /> `_Ret_writes_maybenull_(s)`<br /><br /> `_Ret_writes_to_maybenull_(s)`<br /><br /> `_Ret_writes_maybenull_z_(s)`|`_Ret_maybenull_`<br /><br /> `_Ret_maybenull_z_`<br /><br /> `_Ret_null_`<br /><br /> `_Ret_notnull_`<br /><br /> `_Ret_writes_bytes_to_`<br /><br /> `_Ret_writes_bytes_maybenull_`<br /><br /> `_Ret_writes_bytes_to_maybenull_`| |
447 | 453 |
|
| 454 | +## Format string parameters |
| 455 | + |
| 456 | +- `_Printf_format_string_` |
| 457 | + Indicates that the parameter is a format string for use in a `printf` expression. |
| 458 | + |
| 459 | + **Example** |
| 460 | + |
| 461 | + ```cpp |
| 462 | + int MyPrintF(_Printf_format_string_ const wchar_t* format, ...) |
| 463 | + { |
| 464 | + va_list args; |
| 465 | + va_start(args, format); |
| 466 | + int ret = vwprintf(format, args); |
| 467 | + va_end(args); |
| 468 | + return ret; |
| 469 | + } |
| 470 | + ``` |
| 471 | + |
| 472 | +- `_Scanf_format_string_` |
| 473 | + Indicates that the parameter is a format string for use in a `scanf` expression. |
| 474 | + |
| 475 | + **Example** |
| 476 | + |
| 477 | + ```cpp |
| 478 | + int MyScanF(_Scanf_format_string_ const wchar_t* format, ...) |
| 479 | + { |
| 480 | + va_list args; |
| 481 | + va_start(args, format); |
| 482 | + int ret = vwscanf(format, args); |
| 483 | + va_end(args); |
| 484 | + return ret; |
| 485 | + } |
| 486 | + ``` |
| 487 | + |
| 488 | +- `_Scanf_s_format_string_` |
| 489 | + Indicates that the parameter is a format string for use in a `scanf_s` expression. |
| 490 | + |
| 491 | + **Example** |
| 492 | + |
| 493 | + ```cpp |
| 494 | + int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...) |
| 495 | + { |
| 496 | + va_list args; |
| 497 | + va_start(args, format); |
| 498 | + int ret = vwscanf_s(format, args); |
| 499 | + va_end(args); |
| 500 | + return ret; |
| 501 | + } |
| 502 | + ``` |
| 503 | + |
448 | 504 | ## Other Common Annotations |
| 505 | + |
449 | 506 | **Annotations and Descriptions** |
450 | 507 |
|
451 | 508 | - `_In_range_(low, hi)` |
@@ -484,6 +541,7 @@ This article describes typical uses of annotations for simple function parameter |
484 | 541 | `min(pM->nSize, sizeof(MyStruct))` |
485 | 542 |
|
486 | 543 | ## Related Resources |
| 544 | + |
487 | 545 | [Code Analysis Team Blog](http://go.microsoft.com/fwlink/?LinkId=251197) |
488 | 546 |
|
489 | 547 | ## See Also |
|
0 commit comments