SAL – pipped at the post by Michael Howard.

I’ve been spending some time this week in the evenings thinking on how I should introduce SAL – the Standard Annotation Language – to you all. Then Michael Howard managed to do it before I could get there.

It’s been in use at Microsoft for some time now, albeit frequently rather grudgingly. I was introduced to it as a Longhorn Quality Gate – something that had to be done in order to get a piece of software approved for checking in to the Longhorn Source Control tree.

Some teams choose to have everyone add SAL annotations to their own code; others do as our team did, and assign one or two people to learn SAL as much as they can before applying annotations to every piece of code under that team’s ownership.

I very quickly discovered that, while SAL was indeed a pain in the neck to add to your code, it forcibly removes a lot of bad coding from your source tree, because there are some things that just cannot be SAL-annotated correctly – and those constructs are the ones that cause the most buffer overflows.

An example of such a construct? Sure – strcpy(). It’s been the single biggest source of buffer overflows, either in reading when the string is not null-terminated, or in writing, when the destination buffer is shorter than the source. You just can’t properly SAL-annotate strcpy, because you don’t know the sizes of either of the strings, so you’re forced to re-write it appropriately (and you get something like strcpy_s).

So can I add anything to Mike’s descriptions of SAL?

Yes – mainly just this: if you cannot find a way to specify the type in SAL, you probably should think about defining your types using typedefs, rather than inlining the whole type definition. SAL definitions carry on through a typedef – for examples, look in WinNT.h, where you’ll find definitions like PZPCWSTR: “typedef __nullterminated PCWSTR *PZPCWSTR;

Finally, make sure that you use the same SAL annotation in the header file as you do in the C/CPP file.  Otherwise, you’ll get counter-intuitive results from the /analyze switch.

If you have any questions about SAL, please post them as comments below, or email me using the “Contact” link in the top right of this blog page.

3 Responses to SAL – pipped at the post by Michael Howard.

  • Alun Jones says:

    Oh, and one last thing to note about what happens while you’re adding SAL to your own code…
    You will fall asleep through sheer tedium, you will make mistakes because it’s so boring you can’t think straight, and when you eventually get it all taken care of, your code will be so much cleaner it’ll squeak. But it’ll still have bugs in, and you’ll still have to test it to hell and back.
    Automated tools are good for finding most of the “how on earth did I write that code so badly?” mistakes. They won’t find your more subtle problems.

  • Alun Jones says:

    And another last thing – LPCSTR is your friend. It replaces “__in_z const char *” so nicely.

  • nick says:

    Related question, since you’ve got me interested….agreed that this not only makes your code more secure, it also deals with bugs. Subtle problems will enter no matter what you do, and errors in logic/a basic lack of complete mastery of the system is inevitable unless you wrote the darn thing :) But minimizing silly bugs helps save immeasurable amounts of time.

    I’m building Win32 API based IOCP servers for deployment on machines which I controlm on Visual Studio 6….in *your* experience, given the benefits of VS2005 [SAL being one of them, a few more that I know of], does it make sense for me to switch? Are there any negatives that you see?

    Asking since I’ve seen some posts of yours on related topics on usenet [IOCP/network programming] – so you may well have explored the same/similar questions.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>