Skip to content

Commit 01d6ccd

Browse files
RastabanRastaban
committed
first pass of C6101 updates
1 parent dfd2a93 commit 01d6ccd

1 file changed

Lines changed: 56 additions & 9 deletions

File tree

‎docs/code-quality/c6101.md‎

Lines changed: 56 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,35 +4,82 @@ title: Warning C6101
44
ms.date: 08/17/2022
55
f1_keywords: ["C6101", "RETURN_UNINIT_VAR", "__WARNING_RETURN_UNINIT_VAR"]
66
helpviewer_keywords: ["C6101"]
7-
ms.assetid: 8546367c-5de5-479a-a231-c15c0aa89ef1
87
---
98
# Warning C6101
109

11-
> Returning uninitialized memory '*parameter-name*'. A successful path through the function does not set the named `_Out_` parameter.
10+
> Returning uninitialized memory '*parameter-name*'.
11+
12+
A successful path through the function does not set the `_Out_` annotated parameter.
1213

1314
## Remarks
1415

15-
This message is generated based on SAL annotations that indicate that the function in question always succeeds. A function that doesn't return a success/failure indication should set all of its `_Out_` parameters because the analyzer assumes that the `_Out_` parameter is uninitialized data before the function is called, and that the function will set the parameter so that it's no longer uninitialized. If, however, the function does indicate success/failure and failure occurs, then the `_Out_` parameter doesn't have to be set. You can then detect and avoid the uninitialized location. In either case, the objective is to avoid the reading of an uninitialized location. If the function sometimes doesn't touch an `_Out_` parameter that's later used, then the parameter should be initialized before the function call and be marked with the `_Inout_` annotation, or the more explicit `_Pre_null_` or `_Pre_satisfies_()` when appropriate. "Partial success" can be handled with the `_When_` annotation. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md).
16+
The purpose of this warning is to avoid the use of uninitialized values by callers of the function. All parameters that are annotated with `_Out_` are assumed to be uninitialized before the function call and are expected to be initialized by by it. If the function returns a value indicating it had an error or was not successful then this warning is not emitted. To fix this issue make sure the `_Out_` parameter is initialized under all successful return paths. The error message will contain the line numbers of an example path that does not initialize the parameter.
17+
18+
If the initialization behavior is by design, then this is likely a result of incorrect or missing SAL annotations. These cases can typically be resolved by either changing `_Out_` to a more appropriate annotation, or by using the `_Success_()` annotation to help define the success/error states of the function. Having correct annotations on the function is important for the static analysis tools when analyzing the call sites of the function.
19+
20+
### Fixing by changing Parameter annotations
21+
22+
If the parameter is expected to already be in an initialized state and the function conditionally modifies it, then the `_Inout_` annotation may be more appropriate. Another option is to use lower level annotations such as `_Pre_null_`/`_Pre_satisfies_()`/`_Post_satisfies_()` which provide additional flexibility and control over the expected state of the parameter. For more information on parameter annotations see [Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md).
23+
24+
### Fixing by defining successful return paths
25+
26+
This diagnostic is only emitted when the `_Out_` parameter is not initialized in the success paths of the function. If there is no `_Success_` annotation and the return type for the function is not annotated, then all return paths are considered successful. For more information on `_Success_` and other similar annotations see [Success/Failure annotations](./annotating-function-behavior.md#successfailure-annotations).
1627

1728
Code analysis name: `RETURN_UNINIT_VAR`
1829

1930
## Example
2031

21-
The following code generates this warning. This issue stems from the pointer p1 not being set despite having been annotated with `_Out_`.
32+
The following code generates this warning. Because the function returns void, all paths are considered successful. In this case, the correct fix would probably be to adjust the logic of the `if` statement, but in real world code it is typically not as straightforward and depends on the intended behavior of the function.
2233

2334
```cpp
24-
void example_func(_Out_ int *p1)
35+
#include <sal.h>
36+
void AlwaysInit(_Out_ int* output, int input) // : warning C6101: Returning uninitialized memory '*p'.: Lines: 2, 4, 9, 14, 2
2537
{
38+
if( input > 0 )
39+
{
40+
*output = input;
2641
return;
42+
}
43+
else if( input < 0 )
44+
{
45+
*output = 0;
46+
return;
47+
}
48+
return; // Oops, input was 0
2749
}
2850
```
2951
30-
To resolve the issue, you can set the value of the parameter. Or, if the value is always initialized before the function is called, change the SAL annotation to `_Inout_`. By setting the value of the parameter, the following code avoids the warning:
52+
To make the solution more interesting we assume that it is not valid to initialize `output` when `input` is `0`. One approach is to modify the function return value to a different type such as `bool` and add a `_Success_` annotation to define the successful return paths.
3153
3254
```cpp
33-
void example_func(_Out_ int *p1)
55+
_Success_(return == true)
56+
bool InitNotZero(_Out_ int* output, int input)
3457
{
35-
*p1 = 1;
36-
return;
58+
if( input > 0 )
59+
{
60+
*output = input;
61+
return true;
62+
}
63+
else if( input < 0 )
64+
{
65+
*output = 0;
66+
return true;
67+
}
68+
return false;
3769
}
3870
```
71+
72+
If this is a common pattern in the codebase, the annotation can be added to the return type. This is what error codes like HRESULT from the Windows SDK do to give the behavior of the `_Success_` annotation without needing to adding it to each function. If you already use an annotated type as a return type and want to override the behavior, then it can be done by adding the annotation to the function like the previous example.
73+
74+
```cpp
75+
using SuccessWhenTrue = _Success_(return == true) bool;
76+
77+
SuccessWhenTrue InitNotZero(_Out_ int* output, int input)
78+
{
79+
// ...
80+
```
81+
82+
## See also
83+
84+
[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\
85+
[Using SAL Annotations to Reduce C/C++ Code Defects](./using-sal-annotations-to-reduce-c-cpp-code-defects.md)

0 commit comments

Comments
 (0)