Hi, Michael here.

A while back I wrote a blog post explaining the Standard Annotation Language (SAL) which is a technology we use to help static analysis tools find more bugs, including security vulnerabilities, in C and C++ code. If you look closely at VC++ 2005 and VC++ 2008, you’ll notice that almost all function prototypes are SAL annotated, which means you get the benefit of all the SAL work we did. But you might have also notice that the annotation style between the two compiler versions is different.

For example, in Visual C++ 2005, realloc() is annotated like this:

__checkReturn __bcount_opt(_NewSize) 
    void * __cdecl realloc(
        __in_opt void * _Memory, 
        __in size_t _NewSize);

But in VC++ 2008, realloc() is annotated like this:

_Check_return_ _Ret_opt_bytecap_(_NewSize) 
    void * __cdecl realloc(
        _In_opt_ void * _Memory, 
        _In_ size_t _NewSize);

void Foo( 
    __in_bcount(cb) BYTE* pBuf, 
    size_t cb );

void Foo( 
    _In_bytecount_(cb) BYTE* pBuf, 
    size_t cb );

Aren’t you happy we created macros for the low-level primitives!? You should never have to use the low-level primitives in your code: the table is to show you why the two SAL formats got their names.

So why a new SAL syntax? I have good news and really good news. First, the good news: other than a simple macro syntax change, there is not a lot new to learn in part because the macros are similar (not identical, however) and the major difference, the low-level primitives, are abstracted away.

Now for the really good news. Attribute SAL is much more rigorous than declspec SAL, which means analysis tools can find more bugs with lower false positives (‘noise’). For example, declspec SAL is often silent in the face of an incorrect annotation.

The introduction of attribute SAL does not mean declspec SAL is dead, but it does mean that we will not be investing any more resources into declspec SAL, all our energy improving SAL and our analysis tools use of SAL will be in attribute SAL. At a pragmatic level, this means:

· If you have already invested in using declspec SAL you should migrate over to attribute SAL as time allows, and use new attribute SAL for new functions. Both syntaxes can co-exist.

· If you have never used SAL, you should use attribute SAL. As far as you’re concerned, declspec SAL never existed.

One noticeable difference in macro names is the use of declspec SAL’s “count” and attribute SAL’s “cap” and “count.” The former is a buffer size in elements or bytes, but the latter two are the buffer’s writing capacity and the size of the buffer for reading, respectively.

An important addition to attribute SAL is _Printf_format_string_ which can be used to find many printf-related format-matching ills.

The following table shows some of the major differences:

As noted in the table above, there is one minor drawback to using attribute SAL. If you use constant expressions as count or cap arguments, you must use a special set of macros, which is a little less elegant than declspec SAL:

void Foo( _In_count_c_( 8 ) int* rgInt );

versus

void Foo( __in_count( 8 ) int* rgInt );

Note the _c_ portion of the attribute syntax, which is not needed when using declspec macros. With that said, attribute syntax supports accept any C++ conformant constant expression including enums and template arguments, but decspec SAL supports only simple expressions.

An Example

To put his altogether, let’s look at some simple code, and see how the VC++ 2008 /analyze static analysis performs when faced with the different SAL types.

First, declspec SAL:

   1: #include "stdafx.h"

   2:  

   3: struct SomeStruct {

   4:     int x;

   5:     float f;

   6: };

   7:  

   8: bool FuncOne(__in_z_opt const char* filename);

   9: void FuncTwo(const char *pFormat, ...);

  10: void FuncThree( __in const SomeStruct* setup );

  11: void FuncFour(__in HWND h, __in char *sz); 

  12:  

  13: void TestWarnings() {

  14:     char b;

  15:     FuncOne(&b); 

  16:     FuncTwo("%d %p %d", 10.0, "Hello");

  17:     FuncThree(0); 

  18:     SomeStruct blah;

  19:     FuncThree(&blah);

  20:  

  21:     char buff[100];

  22:     FuncFour(NULL,buff);

  23: }

When compiled with /W4 /analyze, the compiler gives us:

warning C6309: Argument '1' is null: this does not adhere to function 
specification of 'FuncThree'
warning C6309: Argument '1' is null: this does not adhere to function 
specification of 'FuncFour'
warning C6387: 'argument 1' might be '0': this does not adhere to the 
specification for the function 'FuncThree': Lines: 14, 15, 16, 17
warning C6387: 'argument 1' might be '0': this does not adhere to the 
specification for the function 'FuncFour': Lines: 14, 15, 16, 17, 18, 19, 21, 
22

Now, let’s take the same code, but decorate the function prototypes with attribute SAL rather than declspec SAL.

   1: #include "stdafx.h"

   2:  

   3: struct SomeStruct {

   4:     int x;

   5:     float f;

   6: };

   7:  

   8: bool FuncOne(_In_opt_z_ const char* filename);

   9: void FuncTwo(_Printf_format_string_ const char *pFormat, ...);

  10: void FuncThree(_In_ const SomeStruct* setup );

  11: void FuncFour(_In_ HWND h, _In_ char *sz); 

  12:  

  13: void TestWarnings() {

  14:     char b;

  15:     FuncOne(&b); 

  16:     FuncTwo("%d %p %d", 10.0, "Hello");

  17:     FuncThree(0); 

  18:     SomeStruct blah;

  19:     FuncThree(&blah);

  20:     

  21:     char buff[100];

  22:     FuncFour(NULL,buff);

  23: }

warning C6273: Non-integer passed as parameter '2' when integer is required 
in call to 'FuncTwo': if a pointer value is being passed, %p should be used
warning C6064: Missing integer argument to 'FuncTwo' that corresponds to 
conversion specifier '3'
warning C6309: Argument '1' is null: this does not adhere to function 
specification of 'FuncThree'
warning C6309: Argument '1' is null: this does not adhere to function 
specification of 'FuncFour'
warning C6001: Using uninitialized memory 'b': Lines: 14, 15
warning C6387: 'argument 1' might be '0': this does not adhere to the 
specification for the function 'FuncThree': Lines: 14, 15, 16, 17
warning C6001: Using uninitialized memory 'blah': Lines: 14, 15, 16, 17, 18, 
19
warning C6387: 'argument 1' might be '0': this does not adhere to the 
specification for the function 'FuncFour': Lines: 14, 15, 16, 17, 18, 19, 21, 
22

As you can see, using attribute SAL found many more code bugs, and all of them are real. I’ll let you sift through the list to see what attribute SAL found over and above declspec SAL! There are some duplicate bugs, however.

If you want to learn more about SAL, I would recommend you simply open sal.h and read the comments and examples.

The Rosetta Stone

Below is a partial Rosetta Stone to help you convert between the two SAL syntaxes if you need to do so.

Acknowledgments