For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
In addition to annotating function parameters and return values, you can annotate properties of the whole function.
The following annotations apply to the function as a whole and describe how it behaves or what it expects to be true.
|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.
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.
|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.|
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.
|Annotates a function that always raises a structured exception handler (SEH) exception, subject to |
_On_failure_ conditions. For more information, see Specifying When and Where an Annotation Applies.
|Annotates a function that may optionally raise an SEH exception, subject to |
|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, |
|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
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
HRESULT already have a
_Success_ annotation built into them; however, if you specify your own
_Success_ annotation on
HRESULT, it overrides the built-in annotation.
|Equivalent to |
anno_list _On_failure_(anno_list); that is, the annotations in
anno_list apply whether or not the function succeeds.
|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
|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
_Return_type_success_ cannot be used on a function or a function pointer typedef.
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
_Group_. For more information, see Specifying When and Where an Annotation Applies.
Using SAL Annotations to Reduce C/C++ Code Defects
Annotating Function Parameters and Return Values
Annotating Structs and Classes
Annotating Locking Behavior
Specifying When and Where an Annotation Applies
Best Practices and Examples