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