libc: remove THIRDPARTYLICENSE/extract-copyright
[unleashed.git] / share / man / man3ext / NOTE.3ext
blobf858dd9d19bfbde69010021485bb86c3688f1c2b
1 '\" te
2 .\"  Copyright (c) 1994 Sun Microsystems, Inc. - All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH NOTE 3EXT "Dec 31, 1996"
7 .SH NAME
8 NOTE, _NOTE \- annotate source code with info for tools
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <note.h>
16 \fB\fR\fBNOTE\fR(\fB\fR\fINoteInfo\fR);
17 .fi
19 .LP
20 .nf
22 #include<sys/note.h>
26 \fB\fR\fB_NOTE\fR(\fB\fR\fINoteInfo\fR);
27 .fi
29 .SH DESCRIPTION
30 .sp
31 .LP
32 These macros are used to embed information for tools in program source. A use
33 of one of these macros is called an "annotation". A tool may define a set of
34 such annotations which can then be used to provide the tool with information
35 that would otherwise be unavailable from the source code.
36 .sp
37 .LP
38 Annotations should, in general, provide documentation useful to the human
39 reader. If information is of no use to a human trying to understand the code
40 but is necessary for proper operation of a tool, use another mechanism for
41 conveying that information to the tool (one which does not involve adding to
42 the source code), so as not to detract from the readability of the source. The
43 following is an example of an annotation which provides information of use to a
44 tool and to the human reader (in this case, which data are protected by a
45 particular lock, an annotation defined by the static lock analysis tool
46 \fBlock_lint\fR).
47 .sp
48 .in +2
49 .nf
50 NOTE(MUTEX_PROTECTS_DATA(foo_lock, \fBfoo_list\fR \fBFoo))\fR
51 .fi
52 .in -2
54 .sp
55 .LP
56 Such annotations do not represent executable code; they are neither statements
57 nor declarations.  They should not be followed by a semicolon. If a compiler or
58 tool that analyzes C source does not understand this annotation scheme, then
59 the tool will ignore the annotations. (For such tools,
60 \fBNOTE(\fR\fIx\fR\fB)\fR expands to nothing.)
61 .sp
62 .LP
63 Annotations may only be placed at particular places in the source.  These
64 places are where the following C constructs would be allowed:
65 .RS +4
66 .TP
67 .ie t \(bu
68 .el o
69 a top-level declaration (that is, a declaration not within a function or other
70 construct)
71 .RE
72 .RS +4
73 .TP
74 .ie t \(bu
75 .el o
76 a declaration or statement within a block (including the block which defines a
77 function)
78 .RE
79 .RS +4
80 .TP
81 .ie t \(bu
82 .el o
83 a member of a \fBstruct\fR or \fBunion\fR.
84 .RE
85 .sp
86 .LP
87 Annotations are not allowed in any other place.  For example, the following are
88 illegal:
89 .sp
90 .in +2
91 .nf
92 x = y + NOTE(...) z ;
93 typedef NOTE(...) unsigned int uint ;
94 .fi
95 .in -2
97 .sp
98 .LP
99 While \fBNOTE\fR and \fB_NOTE\fR may be used in the places described above, a
100 particular type of annotation may only be allowed in a subset of those places.
101 For example, a particular annotation may not be allowed inside a \fBstruct\fR
102 or \fBunion\fR definition.
103 .SS "NOTE vs _NOTE"
106 Ordinarily, \fBNOTE\fR should be used rather than \fB_NOTE\fR, since use of
107 \fB_NOTE\fR technically makes a program non-portable. However, it may be
108 inconvenient to use \fBNOTE\fR for this purpose in existing code if \fBNOTE\fR
109 is already heavily used for another purpose.  In this case one should use a
110 different macro and write a header file similar to \fB/usr/include/note.h\fR
111 which maps that macro to \fB_NOTE\fR in the same manner.  For example, the
112 following makes \fBFOO\fR such a macro:
114 .in +2
116 #ifndef _FOO_H
117 #define _FOO_H
118 #define FOO _NOTE
119 #include <sys/note.h>
120 #endif
122 .in -2
126 Public header files which span projects should use \fB_NOTE\fR rather than
127 \fBNOTE\fR, since \fBNOTE\fR may already be used by a program which needs to
128 include such a header file.
129 .SS "\fINoteInfo\fR\fB Argument\fR"
132 The actual \fINoteInfo\fR used in an annotation should be specified by a tool
133 that deals with program source (see the documentation for the tool to determine
134 which annotations, if any, it understands).
137 \fINoteInfo\fR must have one of the following forms:
139 .in +2
141 \fINoteName
142 NoteName\fR(\fIArgs\fR)
144 .in -2
148 where \fINoteName\fR is simply an identifier which indicates the type of
149 annotation, and \fIArgs\fR is something defined by the tool that specifies the
150 particular \fINoteName.\fR The general restrictions on \fIArgs\fR are that it
151 be compatible with an ANSI C tokenizer and that unquoted parentheses be
152 balanced (so that the end of the annotation can be determined without intimate
153 knowledge of any particular annotation).
154 .SH ATTRIBUTES
157 See \fBattributes\fR(5) for descriptions of the following attributes:
162 box;
163 c | c
164 l | l .
165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
167 MT-Level        Safe
170 .SH SEE ALSO
173 \fBnote\fR(4), \fBattributes\fR(5)