Print this page
6205 onbld manuals should be declared as 1onbld
Reviewed by: Dan McDonald <danmcd@omniti.com>
Reviewed by: Josef Sipek <jeffpc@josefsipek.net>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/lintdump/lintdump.1
+++ new/usr/src/tools/lintdump/lintdump.1onbld
1 -.\" ident "%Z%%M% %I% %E% SMI"
2 1 .\" " CDDL HEADER START
3 2 .\" "
4 3 .\" " The contents of this file are subject to the terms of the
5 4 .\" " Common Development and Distribution License (the "License").
6 5 .\" " You may not use this file except in compliance with the License.
7 6 .\" "
8 7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 8 .\" " or http://www.opensolaris.org/os/licensing.
10 9 .\" " See the License for the specific language governing permissions
11 10 .\" " and limitations under the License.
12 11 .\" "
|
↓ open down ↓ |
1 lines elided |
↑ open up ↑ |
13 12 .\" " When distributing Covered Code, include this CDDL HEADER in each
14 13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 14 .\" " If applicable, add the following below this CDDL HEADER, with the
16 15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
17 16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
18 17 .\" "
19 18 .\" " CDDL HEADER END
20 19 .\" "
21 20 .\" "Copyright 2008 Sun Microsystems, Inc. All rights reserved.
22 21 .\" "Use is subject to license terms.
23 -.TH lintdump 1 "28 Mar 2008"
22 +.TH lintdump 1ONBLD "28 Mar 2008"
24 23 .I lintdump
25 24 \- dump the contents of one or more lint objects
26 25 .SH SYNOPSIS
27 26 \fBlintdump [-i] [-p 1|2|3] [-r] \fIlintobj\fP [ \fIlintobj\fP ... ]
28 27 .LP
29 28 .SH DESCRIPTION
30 29 .IX "OS-Net build tools" "lintdump" "" "\fBlintdump\fP"
31 30 .LP
32 31 The lintdump utility dumps the contents of one or more lint
33 32 objects. This is chiefly useful when trying to understand the cause of
34 33 unexpected or obtuse lint warnings (see EXAMPLES), but can also be used to
35 34 find differences between lint objects across builds or releases, or to
36 35 debug problems in lint itself.
37 36 .LP
38 37 A lint object is a binary file (typically suffixed with ".ln") constructed
39 38 from a C source file via the "-c" option to lint(1). Multiple lint
40 39 objects may be combined into a lint library object (typically prefixed
41 40 with "llib-l" and suffixed with ".ln") using the "-o" option to lint. (As
42 41 a convenience, lint "-o" allows a lint library object to be built directly
43 42 from C source files). The lintdump utility is capable of dumping both
44 43 traditional lint objects and lint library objects.
45 44 .LP
46 45 The format of a lint object is unstable and subject to change at any time,
47 46 but its current structure is summarized here in order to aid in
48 47 understanding the current output of lintdump. A lint object consists of
49 48 one or more lint modules (one per C source file). Each lint module
50 49 consists of a header and four sections, called PASS1, PASS2, PASS3, and
51 50 STRINGS. Generally speaking, PASS1 contains definitions, PASS2 contains
52 51 declarations, and PASS3 contains information on whether or how functions
53 52 or variables are used. The STRINGS section holds the strings for
54 53 printf(3C)/scanf(3C) checking.
55 54 .LP
56 55 Each PASS section consists of a sequence of binary records of assorted
57 56 types. The sequence of records is further partitioned by FILE records,
58 57 which indicate the source or header file that is responsible for the
59 58 records that follow. The remaining record types provide lint with
60 59 information about the functions, variables, and structures defined or used
61 60 by the object.
62 61 .SH OPTIONS
63 62 .TP 10
64 63 .B -i
65 64 Do not output structure tag IDs (see EXAMPLES).
66 65 .TP 10
67 66 .B -p 1|2|3
68 67 Just output the PASS1, PASS2, or PASS3 section.
69 68 .TP 10
70 69 .B -r
71 70 Output records using relative paths (see EXAMPLES).
72 71 .LP
73 72 .SH OUTPUT
74 73 .LP
75 74 The contents of each specified \fIlintobj\fP is dumped in command-line
76 75 order. For each \fIlintobj\fP, lintdump outputs a single line beginning
77 76 with "LINTOBJ:" that provides its name. For each lint module within that
78 77 object, lintdump outputs a single line beginning with "LINTMOD:" that
79 78 provides its module ID, the size of its PASS1, PASS2, PASS3, STRING
80 79 sections, and its total size, in that order.
81 80 .LP
82 81 Next, unless the -p option is used, the contents of the PASS1, PASS2, and
83 82 PASS3 sections are dumped, in order. Before each section is dumped,
84 83 lintdump outputs a single line beginning with "SECTION:" that
85 84 provides the name and size of the section. For each section,
86 85 lintdump outputs each record in order. The display format of each
87 86 record depends on its type:
88 87 .LP
89 88 .B FILE RECORDS
90 89 .RS 4
91 90 Each FILE record is displayed on a single line beginning with "FILE:".
92 91 Note that FILE records are often found in pairs, the first providing the
93 92 absolute path to the file. FILE records containing absolute paths are
94 93 omitted if -r is used. Other record types following a FILE record are
95 94 indented to show their relationship to the FILE record.
96 95 .RE
97 96 .LP
98 97 .B FUNCTION AND VARIABLE RECORDS
99 98 .RS 4
100 99 Each function or variable record is displayed on a single line using an
101 100 extended version of the format used in The C Programming Language, Second
102 101 Edition. In particular, properties contained in the record that cannot be
103 102 conveyed in C are displayed in angle brackets following definition or
104 103 declaration; a full list of these and their meanings are given below in
105 104 RECORD PROPERTIES. In addition, note that some structures or unions may
106 105 only be known by a numeric \fIID\fP, and thus output as "struct <tag
107 106 \fIID\fP>". This ID can be used to pair the structure with its definition
108 107 via structure records. If -i is used, then "struct <anon>" is printed
109 108 instead.
110 109 .RE
111 110 .LP
112 111 .B STRUCTURE AND UNION RECORDS
113 112 .RS 4
114 113 Each structure or union record is displayed using an extended version of
115 114 the standard multi-line format used in The C Programming Language, Second
116 115 Edition. In particular, to facilitate problem analysis, unless -i is
117 116 used, each structure or union definition includes a numeric ID enclosed in
118 117 angle-brackets, such as "struct FILE <tag 1298> {".
119 118 .RE
120 119 .LP
121 120 To illustrate each of the common record formats, suppose the following
122 121 lint library is built:
123 122 .LP
124 123 .nf
125 124 $ cat > liba.c
126 125 /* LINTLIBRARY */
127 126 /* PROTOLIB1 */
128 127 int af(int);
129 128 struct as {
130 129 char as_name[32];
131 130 int as_flag;
132 131 } as;
133 132 $ lint -oa liba.c
134 133 .fi
135 134 .LP
136 135 Then lintdump will produce the following output:
137 136 .LP
138 137 .nf
139 138 LINTOBJ: llib-la.ln
140 139 LINTMOD: 6484: 268+24+130+9 = 431 bytes
141 140 SECTION: PASS1: 268 bytes
142 141 FILE: /home/meem/hacks/liba.c
143 142 FILE: liba.c
144 143 extern int af(int);
145 144 struct as as;
146 145 struct as <tag 98> {
147 146 char as_name[];
148 147 int as_flag;
149 148 };
150 149 SECTION: PASS2: 24 bytes
151 150 SECTION: PASS3: 130 bytes
152 151 FILE: /home/meem/hacks/liba.c
153 152 FILE: liba.c
154 153 int af(void) <returns value>;
155 154 .fi
156 155 .LP
157 156 .SH RECORD PROPERTIES
158 157 .LP
159 158 As discussed in OUTPUT, some records are displayed using an extended
160 159 format to convey information that cannot be expressed in C. The following
161 160 extended information may be displayed:
162 161 .RE
163 162 .LP
164 163 .B <PRINTFLIKE\fIn\fP>
165 164 .RS 4
166 165 Indicates to lint that argument \fIn\fP to the variable-argument function
167 166 is a format string in printf(3C) format, which enhances lint's argument
168 167 checking.
169 168 .RE
170 169 .LP
171 170 .B <SCANFLIKE\fIn\fP>
172 171 .RS 4
173 172 Indicates to lint that argument \fIn\fP to the variable-argument function
174 173 is a format string in scanf(3C) format, which enhances lint's argument
175 174 checking.
176 175 .RE
177 176 .LP
178 177 .B <definition>
179 178 .RS 4
180 179 Indicates to lint that this record represents the definition of the given
181 180 variable or function (rather than a declaration).
182 181 .RE
183 182 .LP
184 183 .B <use: side-effects context>
185 184 .RS 4
186 185 Indicates to lint that the associated function is called in a context that
187 186 suggests it has side effects.
188 187 .RE
189 188 .LP
190 189 .B <use: return value context>
191 190 .RS 4
192 191 Indicates to lint that the associated function is called in a context where
193 192 its return value is used.
194 193 .RE
195 194 .LP
196 195 .B <use: unspecified context>
197 196 .RS 4
198 197 Indicates to lint that the associated function is used in an unspecified
199 198 manner.
200 199 .RE
201 200 .LP
202 201 .B <returns value>
203 202 .RS 4
204 203 Indicates to lint that the function returns a value.
205 204 .RE
206 205 .LP
207 206 .SH EXAMPLES
208 207 .LP
209 208 One common problem is that lint does not always provide sufficient
210 209 information to understand the reason for a type mismatch. For instance,
211 210 sometimes lint will confusingly report a type mismatch between
212 211 apparently-identical types:
213 212 .LP
214 213 .nf
215 214 $ lint msghdr.c -lsocket
216 215 function argument ( number ) used inconsistently
217 216 recvmsg (arg 2) llib-lsocket:socket.h(437) struct msghdr * ::
218 217 msghdr.c(12) struct msghdr *
219 218 .fi
220 219 .LP
221 220 By using lintdump, we can pinpoint the problem by examining both
222 221 definitions for \fIstruct msghdr\fP:
223 222 .LP
224 223 .nf
225 224 $ lintdump /lib/llib-lsocket.ln
226 225 \fI[ ... ]\fP
227 226 FILE: llib-lsocket:socket.h
228 227 struct msghdr <tag 4532> {
229 228 void *msg_name;
230 229 unsigned int msg_namelen;
231 230 struct iovec *msg_iov;
232 231 int msg_iovlen;
233 232 \fBchar *msg_accrights;\fP
234 233 \fBint msg_accrightslen;\fP
235 234 };
236 235 .fi
237 236 .LP
238 237 .nf
239 238 $ lint -omsghdr msghdr.c -lsocket
240 239 $ lintdump llib-lmsghdr.ln
241 240 \fI[ ... ]\fP
242 241 FILE: socket.h
243 242 struct msghdr <tag 1315> {
244 243 void *msg_name;
245 244 unsigned int msg_namelen;
246 245 struct iovec *msg_iov;
247 246 int msg_iovlen;
248 247 \fBvoid *msg_control;\fP
249 248 \fBunsigned int msg_controllen;\fP
250 249 \fBint msg_flags;\fP
251 250 };
252 251 .fi
253 252 .LP
254 253 Looking at <sys/socket.h>, the problem becomes apparent: the structure
255 254 changes depending on compile-time options, which clearly differ between
256 255 the application and the library:
257 256 .LP
258 257 .nf
259 258 struct msghdr {
260 259 void *msg_name;
261 260 socklen_t msg_namelen;
262 261 struct iovec *msg_iov;
263 262 int msg_iovlen;
264 263
265 264 #if defined(_XPG4_2) || defined(_KERNEL)
266 265 void *msg_control;
267 266 socklen_t msg_controllen;
268 267 int msg_flags;
269 268 #else
270 269 caddr_t msg_accrights;
271 270 int msg_accrightslen;
272 271 #endif /* defined(_XPG4_2) || defined(_KERNEL) */
273 272 };
274 273 .fi
275 274 .LP
276 275 Another use of lintdump is to compare two versions of a lint object to
277 276 see whether anything of significance has changed. For instance, lintdump
278 277 can be used to understand why a lint library is different between a
279 278 project gate and a patch gate, and thus to determine whether the library
280 279 will need to be redelivered in the patch including the project:
281 280 .LP
282 281 .nf
283 282 $ PATCHROOT=/ws/on10-patch/proto/root_i386
284 283 $ diff llib-lkstat.ln $PATCHROOT/lib/llib-lkstat.ln
285 284 Binary files llib-lkstat.ln and
286 285 /ws/on10-patch/proto/root_i386/lib/llib-lkstat.ln differ
287 286 $ lintdump -ir llib-lkstat.ln > /tmp/proj-kstat.out
288 287 $ lintdump -ir $PATCHROOT/lib/llib-lkstat.ln > /tmp/patch-kstat.out
289 288 .fi
290 289 .LP
291 290 .nf
292 291 $ diff /tmp/patch-kstat.out /tmp/proj-kstat.out
293 292 1,2c1,2
294 293 < LINTMOD: 3675: 4995+26812+1045+9 = 32861 bytes
295 294 < SECTION: PASS1: 4995 bytes
296 295 ---
297 296 > LINTMOD: 39982: 5144+27302+1057+9 = 33512 bytes
298 297 > SECTION: PASS1: 5144 bytes
299 298 19c19
300 299 < unsigned char _file;
301 300 ---
302 301 > unsigned char _magic;
303 302 22a23,24
304 303 > unsigned int __extendedfd;
305 304 > unsigned int __xf_nocheck;
306 305 \fI[ ... ]\fP
307 306 .fi
308 307 .LP
309 308 Note that -r option removes spurious differences that would otherwise
310 309 arise from different absolute paths to the same source file, and the -i
311 310 option removes spurious differences due to ID generation inside lint.
312 311 .LP
313 312 .SH SEE ALSO
314 313 .LP
315 314 .IR lint(1),
316 315 .IR printf(3C),
317 316 .IR scanf(3C)
318 317 .SH NOTES
319 318 This utility is provided as an interim solution until a stable utility
320 319 can be bundled with Sun Studio. As such, any use of this utility in
321 320 scripts or embedded inside programs should be done with knowledge that
322 321 subsequent changes will be required in order to transition to the stable
323 322 solution.
324 323 .LP
325 324 The lint object file format does not have a way to represent bitfields. As
326 325 such, bitfield size information cannot be displayed by lintdump.
|
↓ open down ↓ |
293 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX