NOTE and _NOTE

The NOTE interface enables you to insert information for LockLint into your source code without affecting the compiled object code. The basic syntax of a note-style annotation is either:

NOTE(NoteInfo)

or:

_NOTE(NoteInfo)

The preferred use is NOTE rather than _NOTE. Header files that are to be used in multiple, unrelated projects, should use _NOTE to avoid conflicts. If NOTE has already been used, and you do not want to change, you should define some other macro (such as ANNOTATION) using _NOTE. For example, you might define an include file (say, annotation.h) that contains the following:

#define ANNOTATION _NOTE
#include <sys/note.h>

The NoteInfo that gets passed to the NOTE interface must syntactically fit one of the following:

NoteName

NoteName(Args)

NoteName is simply an identifier indicating the type of annotation. Args can be anything, so long as it can be tokenized properly and any parenthesis tokens are matched (so that the closing parenthesis can be found). Each distinct NoteName will have its own requirements regarding arguments.

This text uses NOTE to mean both NOTE and _NOTE, unless explicitly stated otherwise.

Where NOTE May Be Used

NOTE may be invoked only at certain well-defined places in source code:

• At the top level; that is, outside of all function definitions, type and struct definitions, variable declarations, and other constructs. For example:

  ---

  struct foo { int a, b; mutex_t lock; };
  NOTE(MUTEX_PROTECTS_DATA(foo::lock, foo))
  bar() {...}

  ---

• At the top level within a block, among declarations or statements. Here too, the annotation must be outside of all type and struct definitions, variable declarations, and other constructs. For example:

  ---

  foo() { ...; NOTE(...) ...; ...; }

  ---

• At the top level within a struct or union definition, among the declarations. For example:

  ---

  struct foo { int a; NOTE(...) int b; };

  ---

Where NOTE May Not Be Used

NOTE() may be used only in the locations described above. For example, the following are invalid:

a = b NOTE(...) + 1;

typedef NOTE(...) struct foo Foo;

for (i=0; NOTE(...) i<10; i++) ...

A note-style annotation is not a statement; NOTE() may not be used inside an if/else/for/while body unless braces are used to make a block. For example, the following causes a syntax error:

if (x) NOTE(...)