1NOTE(3EXT)                Extended Library Functions                NOTE(3EXT)
2
3
4

NAME

6       NOTE, _NOTE - annotate source code with info for tools
7

SYNOPSIS

9       #include <note.h>
10
11
12
13       NOTE(NoteInfo);
14
15
16       or
17       #include<sys/note.h>
18
19
20
21       _NOTE(NoteInfo);
22
23

DESCRIPTION

25       These macros are used to embed information for tools in program source.
26       A use of one of these macros is called  an  "annotation".  A  tool  may
27       define  a set of such annotations which can then be used to provide the
28       tool with information that would  otherwise  be  unavailable  from  the
29       source code.
30
31
32       Annotations  should,  in  general,  provide documentation useful to the
33       human reader. If information is of no use to a human trying  to  under‐
34       stand  the  code  but  is necessary for proper operation of a tool, use
35       another mechanism for conveying that information to the tool (one which
36       does  not involve adding to the source code), so as not to detract from
37       the readability of the source. The following is an example of an  anno‐
38       tation  which  provides  information  of use to a tool and to the human
39       reader (in this case, which data are protected by a particular lock, an
40       annotation defined by the static lock analysis tool lock_lint).
41
42         NOTE(MUTEX_PROTECTS_DATA(foo_lock, foo_list Foo))
43
44
45
46       Such  annotations  do  not  represent executable code; they are neither
47       statements nor declarations.  They should not be followed  by  a  semi‐
48       colon. If a compiler or tool that analyzes C source does not understand
49       this annotation scheme, then the tool will ignore the annotations. (For
50       such tools, NOTE(x) expands to nothing.)
51
52
53       Annotations  may  only  be  placed  at particular places in the source.
54       These places are where the following C constructs would be allowed:
55
56           o      a top-level declaration (that is, a declaration not within a
57                  function or other construct)
58
59           o      a  declaration  or  statement  within a block (including the
60                  block which defines a function)
61
62           o      a member of a struct or union.
63
64
65       Annotations are not allowed in any other place.  For example, the  fol‐
66       lowing are illegal:
67
68         x = y + NOTE(...) z ;
69         typedef NOTE(...) unsigned int uint ;
70
71
72
73       While  NOTE and _NOTE may be used in the places described above, a par‐
74       ticular type of annotation may only be allowed in  a  subset  of  those
75       places.  For example, a particular annotation may not be allowed inside
76       a struct or union definition.
77
78   NOTE vs _NOTE
79       Ordinarily, NOTE should be used rather than _NOTE, since use  of  _NOTE
80       technically  makes  a program non-portable. However, it may be inconve‐
81       nient to use NOTE for this purpose in existing code if NOTE is  already
82       heavily  used  for another purpose.  In this case one should use a dif‐
83       ferent macro and write a header  file  similar  to  /usr/include/note.h
84       which  maps  that  macro to _NOTE in the same manner.  For example, the
85       following makes FOO such a macro:
86
87         #ifndef _FOO_H
88         #define _FOO_H
89         #define FOO _NOTE
90         #include <sys/note.h>
91         #endif
92
93
94
95       Public header files which span projects should use  _NOTE  rather  than
96       NOTE,  since  NOTE  may  already  be  used  by a program which needs to
97       include such a header file.
98
99   NoteInfo Argument
100       The actual NoteInfo used in an annotation should be specified by a tool
101       that  deals  with program source (see the documentation for the tool to
102       determine which annotations, if any, it understands).
103
104
105       NoteInfo must have one of the following forms:
106
107         NoteName
108         NoteName(Args)
109
110
111
112       where NoteName is simply an identifier  which  indicates  the  type  of
113       annotation,  and  Args  is something defined by the tool that specifies
114       the particular NoteName. The general restrictions on Args are  that  it
115       be compatible with an ANSI C tokenizer and that unquoted parentheses be
116       balanced (so that the end of the annotation can be  determined  without
117       intimate knowledge of any particular annotation).
118

ATTRIBUTES

120       See attributes(5) for descriptions of the following attributes:
121
122
123
124
125       ┌─────────────────────────────┬─────────────────────────────┐
126       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │MT-Level                     │Safe                         │
129       └─────────────────────────────┴─────────────────────────────┘
130

SEE ALSO

132       note(4), attributes(5)
133
134
135
136SunOS 5.11                        31 Dec 1996                       NOTE(3EXT)
Impressum