Manual Pages for UNIX Operating System command usage for man NOTE

Extended Library Functions                             NOTE(3EXT)



NAME
     NOTE, _NOTE - annotate source code with info for tools

SYNOPSIS
     #include 

     NOTE(NoteInfo);


     #include

     _NOTE(NoteInfo);


DESCRIPTION
     These macros are used to embed information for tools in pro-
     gram  source.  A  use  of  one  of these macros is called an
     "annotation". A tool may define a set  of  such  annotations
     which  can then be used to provide the tool with information
     that would otherwise be unavailable from the source code.


     Annotations should, in general, provide documentation useful
     to  the human reader. If information is of no use to a human
     trying to understand the code but is  necessary  for  proper
     operation  of  a  tool,  use another mechanism for conveying
     that information to the tool (one  which  does  not  involve
     adding  to  the  source code), so as not to detract from the
     readability of the source. The following is an example of an
     annotation  which  provides information of use to a tool and
     to the human reader (in this case, which data are  protected
     by  a  particular  lock, an annotation defined by the static
     lock analysis tool lock_lint).

       NOTE(MUTEX_PROTECTS_DATA(foo_lock, foo_list Foo))



     Such annotations do not represent executable code; they  are
     neither  statements  nor  declarations.   They should not be
     followed by a semicolon. If a compiler or tool that analyzes
     C  source  does  not understand this annotation scheme, then
     the tool will  ignore  the  annotations.  (For  such  tools,
     NOTE(x) expands to nothing.)


     Annotations may only be placed at particular places  in  the
     source.


     These places are where the following C constructs  would  be
     allowed:



SunOS 5.11          Last change: 31 Dec 1996                    1






Extended Library Functions                             NOTE(3EXT)



         o    a top-level declaration (that is, a declaration not
              within a function or other construct)

         o    a declaration or statement within a block  (includ-
              ing the block which defines a function)

         o    a member of a struct or union.


     Annotations are not allowed in any other place.   For  exam-
     ple, the following are illegal:

       x = y + NOTE(...) z ;
       typedef NOTE(...) unsigned int uint ;



     While NOTE and _NOTE may be used  in  the  places  described
     above,  a  particular type of annotation may only be allowed
     in a subset of those places. For example, a particular anno-
     tation  may  not be allowed inside a struct or union defini-
     tion.

  NOTE vs _NOTE
     Ordinarily, NOTE should be used rather than _NOTE, since use
     of  _NOTE technically makes a program non-portable. However,
     it may be inconvenient to  use  NOTE  for  this  purpose  in
     existing  code  if  NOTE is already heavily used for another
     purpose.  In this case one should use a different macro  and
     write  a  header  file  similar to /usr/include/note.h which
     maps that macro to _NOTE in the same manner.   For  example,
     the following makes FOO such a macro:

       #ifndef _FOO_H
       #define _FOO_H
       #define FOO _NOTE
       #include 
       #endif



     Public header files which span  projects  should  use  _NOTE
     rather  than  NOTE, since NOTE may already be used by a pro-
     gram which needs to include such a header file.

  NoteInfo Argument
     The actual NoteInfo used in an annotation should  be  speci-
     fied by a tool that deals with program source (see the docu-
     mentation for the tool to determine  which  annotations,  if
     any, it understands).





SunOS 5.11          Last change: 31 Dec 1996                    2






Extended Library Functions                             NOTE(3EXT)



     NoteInfo must have one of the following forms:

       NoteName
       NoteName(Args)



     where NoteName is simply an identifier which  indicates  the
     type  of  annotation,  and  Args is something defined by the
     tool that specifies the  particular  NoteName.  The  general
     restrictions  on Args are that it be compatible with an ANSI
     C tokenizer and that unquoted parentheses  be  balanced  (so
     that  the  end  of  the annotation can be determined without
     intimate knowledge of any particular annotation).

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     note(4), attributes(5)

























SunOS 5.11          Last change: 31 Dec 1996                    3