|
| 1 | +--- |
| 2 | +title: Annotating function behavior |
| 3 | +ms.date: 11/04/2016 |
| 4 | +ms.topic: "conceptual" |
| 5 | +f1_keywords: |
| 6 | + - "_On_failure_" |
| 7 | + - "_Return_type_success_" |
| 8 | + - "_Always_" |
| 9 | + - "_Maybe_raises_SEH_exception_" |
| 10 | + - "_Raises_SEH_exception_" |
| 11 | + - "_Called_from_function_class_" |
| 12 | + - "_Function_class_" |
| 13 | + - "_Must_inspect_result_" |
| 14 | + - "_Success_" |
| 15 | + - "_Check_return_" |
| 16 | + - "_Use_decl_annotations_" |
| 17 | +ms.assetid: c0aa268d-6fa3-4ced-a8c6-f7652b152e61 |
| 18 | +--- |
| 19 | +# Annotating function behavior |
| 20 | + |
| 21 | +In addition to annotating [function parameters and return values](../code-quality/annotating-function-parameters-and-return-values.md), you can annotate properties of the whole function. |
| 22 | + |
| 23 | +## Function annotations |
| 24 | + |
| 25 | +The following annotations apply to the function as a whole and describe how it behaves or what it expects to be true. |
| 26 | + |
| 27 | +|Annotation|Description| |
| 28 | +|----------------|-----------------| |
| 29 | +|`_Called_from_function_class_(name)`|Not intended to stand alone; instead, it is a predicate to be used with the `_When_` annotation. For more information, see [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md).<br /><br /> The `name` parameter is an arbitrary string that also appears in a `_Function_class_` annotation in the declaration of some functions. `_Called_from_function_class_` returns nonzero if the function that is currently being analyzed is annotated by using `_Function_class_` that has the same value of `name`; otherwise, it returns zero.| |
| 30 | +|`_Check_return_`|Annotates a return value and states that the caller should inspect it. The checker reports an error if the function is called in a void context.| |
| 31 | +|`_Function_class_(name)`|The `name` parameter is an arbitrary string that is designated by the user. It exists in a namespace that is distinct from other namespaces. A function, function pointer, or—most usefully—a function pointer type may be designated as belonging to one or more function classes.| |
| 32 | +|`_Raises_SEH_exception_`|Annotates a function that always raises a structured exception handler (SEH) exception, subject to `_When_` and `_On_failure_` conditions. For more information, see [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md).| |
| 33 | +|`_Maybe_raises_SEH_exception_`|Annotates a function that may optionally raise an SEH exception, subject to `_When_` and `_On_failure_` conditions.| |
| 34 | +|`_Must_inspect_result_`|Annotates any output value, including the return value, parameters, and globals. The analyzer reports an error if the value in the annotated object is not subsequently inspected. "Inspection" includes whether it is used in a conditional expression, is assigned to an output parameter or global, or is passed as a parameter. For return values, `_Must_inspect_result_` implies `_Check_return_`.| |
| 35 | +|`_Use_decl_annotations_`|May be used on a function definition (also known as a function body) in place of the list of annotations in the header. When `_Use_decl_annotations_` is used, the annotations that appear on an in-scope header for the same function are used as if they are also present in the definition that has the `_Use_decl_annotations_` annotation.| |
| 36 | + |
| 37 | +## Success/failure annotations |
| 38 | + |
| 39 | +A function can fail, and when it does, its results may be incomplete or differ from the results when the function succeeds. The annotations in the following list provide ways to express the failure behavior. To use these annotations, you must enable them to determine success; therefore, a `_Success_` annotation is required. Notice that `NTSTATUS` and `HRESULT` already have a `_Success_` annotation built into them; however, if you specify your own `_Success_` annotation on `NTSTATUS` or `HRESULT`, it overrides the built-in annotation. |
| 40 | + |
| 41 | +|Annotation|Description| |
| 42 | +|----------------|-----------------| |
| 43 | +|`_Always_(anno_list)`|Equivalent to `anno_list _On_failure_(anno_list)`; that is, the annotations in `anno_list` apply whether or not the function succeeds.| |
| 44 | +|`_On_failure_(anno_list)`|To be used only when `_Success_` is also used to annotate the function—either explicitly, or implicitly through `_Return_type_success_` on a typedef. When the `_On_failure_` annotation is present on a function parameter or return value, each annotation in `anno_list` (anno) behaves as if it were coded as `_When_(!expr, anno)`, where `expr` is the parameter to the required `_Success_` annotation. This means that the implied application of `_Success_` to all post-conditions does not apply for `_On_failure_`.| |
| 45 | +|`_Return_type_success_(expr)`|May be applied to a typedef. Indicates that all functions that return that type and do not explicitly have `_Success_` are annotated as if they had `_Success_(expr)`. `_Return_type_success_` cannot be used on a function or a function pointer typedef.| |
| 46 | +|`_Success_(expr)`|`expr` is an expression that yields an rvalue. When the `_Success_` annotation is present on a function declaration or definition, each annotation (`anno`) on the function and in post-condition behaves as if it were coded as `_When_(expr, anno)`. The `_Success_` annotation may be used only on a function, not on its parameters or return type. There can be at most one `_Success_` annotation on a function, and it cannot be in any `_When_`, `_At_`, or `_Group_`. For more information, see [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md).| |
| 47 | + |
| 48 | +## See also |
| 49 | + |
| 50 | +- [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md) |
| 51 | +- [Understanding SAL](../code-quality/understanding-sal.md) |
| 52 | +- [Annotating Function Parameters and Return Values](../code-quality/annotating-function-parameters-and-return-values.md) |
| 53 | +- [Annotating Structs and Classes](../code-quality/annotating-structs-and-classes.md) |
| 54 | +- [Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md) |
| 55 | +- [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md) |
| 56 | +- [Intrinsic Functions](../code-quality/intrinsic-functions.md) |
| 57 | +- [Best Practices and Examples](../code-quality/best-practices-and-examples-sal.md) |
0 commit comments