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