Function Return Annotations

Many functions return a status that indicates whether the function was successful. However, it is common to find code that assumes that a function call is always successful and that does not check the return value. This is often the case with memory allocators, but this is true for others as well. For example, malloc is the classic function that should be annotated to check the return value. To have PFD check the return value, use the __checkReturn annotation.

__checkReturn void *malloc(__in size_t s);

When you use the __checkReturn annotation, PFD can detect two different errors:

• If the function return value is ignored.

• If the function return value is placed into a variable and the variable is then ignored.

To avoid a PFD warning when calling a function that is annotated with __checkReturn, use the return value directly in a conditional expression or assign it to a variable that is subsequently used in a conditional expression. Although __checkReturn is traditionally applied to return values, PREfast for Drivers can detect a __checkReturn annotation that is applied to an __out parameter to insist that that value be examined.

Returning the value to a caller qualifies as successfully checking the return value; however, that parameter or the return value should itself be marked as __checkReturn so the caller checks the value.

Kernel-mode drivers should be annotated to check all memory allocations, and the driver should attempt to fail gracefully if a memory allocation should fail.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011