The C/C++ code analysis tool helps developers identify potential defects in their source code, flagging common issues like buffer overruns and memory leaks. The Microsoft Source-Code Annotation Language (SAL) allows more detailed descriptions of function parameters and behavior, enhancing code clarity and defect detection. Using SAL annotations helps to ensure better communication of usage and safety properties within the code, making the analysis process more effective.

1. Code Analysis
for C/C++

2. Overview
 The C/C++ Code Analysis tool provides information
to developers about possible defects in their C/C++
source code. Common coding errors reported by the
tool include buffer overruns, un-initialized memory,
null pointer dereferences, and memory and resource
leaks.
5.1.2016Roman Okolovich2

3. Source-code Annotation Language (SAL)
 The Microsoft source-code annotation language (SAL)
provides a set of annotations that can be used to
describe how a function uses its parameters, the
assumptions that it makes about them, and the
guarantees that it makes when it finishes. The
annotations are defined in the header file <sal.h>.
Visual Studio code analysis for C++ uses SAL
annotations to modify its analysis of functions.
 Natively, C and C++ provide only limited ways for
developers to consistently express intent and
invariance.
 By using SAL annotations, you can describe your
functions in greater detail so that developers who are
consuming them can better understand how to use
them.
5.1.2016Roman Okolovich3

4. SAL makes code more valuable
void* memcpy(
void* dest,
const void* src,
size_t count
);
 Without SAL annotations, you'd have to rely on
documentation or code comments.
void * memcpy(
_Out_writes_bytes_all_(count) void *dest,
_In_reads_bytes_(count) const void *src,
size_t count
);
 Notice that these annotations resemble the
information in the MSDN documentation, but
they are more concise and they follow a
semantic pattern. When you read this code,
you can quickly understand the properties of
this function and how to avoid buffer overrun
security issues.
5.1.2016Roman Okolovich4

5. Find potential bugs
wchar_t * wmemcpy(
_Out_writes_all_(count) wchar_t *dest,
_In_reads_(count) const wchar_t *src,
size_t count)
{
size_t i;
for (i = 0; i <= count; i++) { // BUG: off-by-one error
dest[i] = src[i];
}
return dest;
}
 This implementation contains a common off-by-one error.
Fortunately, the code author included the SAL buffer size
annotation—a code analysis tool could catch the bug by
analyzing this function alone.
5.1.2016Roman Okolovich5

6.  Annotating Function Parameters and Return Values
 _In_, _Out_, _Inout_, _In_z_, etc
 When a pointer parameter annotation includes _opt_, it indicates that
the parameter may be null
 _In_opt_, _Out_opt_, _Inout_opt_, _In_opt_z_, etc
 Return values
 _Ret_z_, _Ret_maybenull_, _Ret_writes_to_(s,c), _Ret_notnull_, etc
 Annotating Function Behavior
 A function can fail, and when it does, its results may be incomplete or
differ from the results when the function succeeds.
 _Check_return_ - annotates a return value and states that the caller should
inspect it.
 _Always_(anno_list), _Success_(expr), etc
 Example: annotate formal parameters and return value of the
function by using the Pre and Post conditions:
[returnvalue:SA_Post(Null=SA_Maybe)]
LinkedList* AddTail([SA_Pre(Null=SA_Maybe)] LinkedList* node, int value)
5.1.2016Roman Okolovich6

7. Specify Additional Code Information
It’s possible to provide hints to
the code analysis tool for
C/C++ code that will help the
analysis process and reduce
warnings.
__analysis_assume( expr )
expr - any expression that is
assumed to evaluate to true.
#include <windows.h>
#include <codeanalysissourceannotations.h>
using namespace vc_attributes;
// calls free and sets ch to null
void FreeAndNull(char* ch);
//requires pc to be null
void f([Pre(Null=Yes)] char* pc);
void test( )
{
char *pc = (char*)malloc(5);
FreeAndNull(pc);
__analysis_assume(pc == NULL);
f(pc);
}
5.1.2016Roman Okolovich

8. When do I Annotate?
 Annotate all pointer parameters.
 Annotate value-range annotations so that Code
Analysis can ensure buffer and pointer safety.
 Annotate locking rules and locking side effects.
 Annotate driver properties and other domain-specific
properties.
 In new code, you can use SAL-based specifications
by design throughout; in older code, you can add
annotations incrementally and thereby increase the
benefits every time you update.
5.1.2016Roman Okolovich8

9. Links
 Analyzing C/C++ Code Quality by Using Code
Analysis
 How to: Set Code Analysis Properties for C/C++
Projects
 Understanding SAL
 Annotating Function Parameters and Return Values
 Annotating Locking Behavior
5.1.2016Roman Okolovich9