2 .\" "
3 .\" " The contents of this file are subject to the terms of the
4 .\" " Common Development and Distribution License (the "License").
5 .\" " You may not use this file except in compliance with the License.
6 .\" "
7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 .\" " or http://www.opensolaris.org/os/licensing.
9 .\" " See the License for the specific language governing permissions
10 .\" " and limitations under the License.
11 .\" "
12 .\" " When distributing Covered Code, include this CDDL HEADER in each
13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 .\" " If applicable, add the following below this CDDL HEADER, with the
15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
17 .\" "
18 .\" " CDDL HEADER END
19 .\" "
20 .\" "Copyright 2008 Sun Microsystems, Inc. All rights reserved.
21 .\" "Use is subject to license terms.
22 .TH lintdump 1ONBLD "28 Mar 2008"
23 .I lintdump
24 \- dump the contents of one or more lint objects
25 .SH SYNOPSIS
26 \fBlintdump [-i] [-p 1|2|3] [-r] \fIlintobj\fP [ \fIlintobj\fP ... ]
27 .LP
28 .SH DESCRIPTION
29 .IX "OS-Net build tools" "lintdump" "" "\fBlintdump\fP"
30 .LP
31 The lintdump utility dumps the contents of one or more lint
32 objects. This is chiefly useful when trying to understand the cause of
33 unexpected or obtuse lint warnings (see EXAMPLES), but can also be used to
34 find differences between lint objects across builds or releases, or to
35 debug problems in lint itself.
36 .LP
37 A lint object is a binary file (typically suffixed with ".ln") constructed
38 from a C source file via the "-c" option to lint(1). Multiple lint
39 objects may be combined into a lint library object (typically prefixed
40 with "llib-l" and suffixed with ".ln") using the "-o" option to lint. (As
41 a convenience, lint "-o" allows a lint library object to be built directly
42 from C source files). The lintdump utility is capable of dumping both
43 traditional lint objects and lint library objects.
44 .LP
45 The format of a lint object is unstable and subject to change at any time,
46 but its current structure is summarized here in order to aid in
47 understanding the current output of lintdump. A lint object consists of
48 one or more lint modules (one per C source file). Each lint module
49 consists of a header and four sections, called PASS1, PASS2, PASS3, and
51 declarations, and PASS3 contains information on whether or how functions
52 or variables are used. The STRINGS section holds the strings for
53 printf(3C)/scanf(3C) checking.
54 .LP
55 Each PASS section consists of a sequence of binary records of assorted
56 types. The sequence of records is further partitioned by FILE records,
57 which indicate the source or header file that is responsible for the
58 records that follow. The remaining record types provide lint with
59 information about the functions, variables, and structures defined or used
60 by the object.
61 .SH OPTIONS
62 .TP 10
63 .B -i
64 Do not output structure tag IDs (see EXAMPLES).
65 .TP 10
66 .B -p 1|2|3
67 Just output the PASS1, PASS2, or PASS3 section.
68 .TP 10
69 .B -r
70 Output records using relative paths (see EXAMPLES).
71 .LP
72 .SH OUTPUT
73 .LP
74 The contents of each specified \fIlintobj\fP is dumped in command-line
75 order. For each \fIlintobj\fP, lintdump outputs a single line beginning
76 with "LINTOBJ:" that provides its name. For each lint module within that
77 object, lintdump outputs a single line beginning with "LINTMOD:" that
78 provides its module ID, the size of its PASS1, PASS2, PASS3, STRING
79 sections, and its total size, in that order.
80 .LP
81 Next, unless the -p option is used, the contents of the PASS1, PASS2, and
82 PASS3 sections are dumped, in order. Before each section is dumped,
83 lintdump outputs a single line beginning with "SECTION:" that
84 provides the name and size of the section. For each section,
85 lintdump outputs each record in order. The display format of each
86 record depends on its type:
87 .LP
88 .B FILE RECORDS
89 .RS 4
90 Each FILE record is displayed on a single line beginning with "FILE:".
91 Note that FILE records are often found in pairs, the first providing the
135 Then lintdump will produce the following output:
136 .LP
137 .nf
138 LINTOBJ: llib-la.ln
139 LINTMOD: 6484: 268+24+130+9 = 431 bytes
140 SECTION: PASS1: 268 bytes
141 FILE: /home/meem/hacks/liba.c
142 FILE: liba.c
143 extern int af(int);
144 struct as as;
145 struct as <tag 98> {
146 char as_name[];
147 int as_flag;
148 };
149 SECTION: PASS2: 24 bytes
150 SECTION: PASS3: 130 bytes
151 FILE: /home/meem/hacks/liba.c
152 FILE: liba.c
153 int af(void) <returns value>;
154 .fi
155 .LP
156 .SH RECORD PROPERTIES
157 .LP
158 As discussed in OUTPUT, some records are displayed using an extended
159 format to convey information that cannot be expressed in C. The following
160 extended information may be displayed:
161 .RE
162 .LP
163 .B <PRINTFLIKE\fIn\fP>
164 .RS 4
165 Indicates to lint that argument \fIn\fP to the variable-argument function
166 is a format string in printf(3C) format, which enhances lint's argument
167 checking.
168 .RE
169 .LP
170 .B <SCANFLIKE\fIn\fP>
171 .RS 4
172 Indicates to lint that argument \fIn\fP to the variable-argument function
173 is a format string in scanf(3C) format, which enhances lint's argument
174 checking.
175 .RE
176 .LP
177 .B <definition>
178 .RS 4
179 Indicates to lint that this record represents the definition of the given
180 variable or function (rather than a declaration).
181 .RE
185 Indicates to lint that the associated function is called in a context that
186 suggests it has side effects.
187 .RE
188 .LP
189 .B <use: return value context>
190 .RS 4
191 Indicates to lint that the associated function is called in a context where
192 its return value is used.
193 .RE
194 .LP
195 .B <use: unspecified context>
196 .RS 4
197 Indicates to lint that the associated function is used in an unspecified
198 manner.
199 .RE
200 .LP
201 .B <returns value>
202 .RS 4
203 Indicates to lint that the function returns a value.
204 .RE
205 .LP
206 .SH EXAMPLES
207 .LP
208 One common problem is that lint does not always provide sufficient
209 information to understand the reason for a type mismatch. For instance,
210 sometimes lint will confusingly report a type mismatch between
211 apparently-identical types:
212 .LP
213 .nf
214 $ lint msghdr.c -lsocket
215 function argument ( number ) used inconsistently
216 recvmsg (arg 2) llib-lsocket:socket.h(437) struct msghdr * ::
217 msghdr.c(12) struct msghdr *
218 .fi
219 .LP
220 By using lintdump, we can pinpoint the problem by examining both
221 definitions for \fIstruct msghdr\fP:
222 .LP
223 .nf
224 $ lintdump /lib/llib-lsocket.ln
225 \fI[ ... ]\fP
291 $ diff /tmp/patch-kstat.out /tmp/proj-kstat.out
292 1,2c1,2
293 < LINTMOD: 3675: 4995+26812+1045+9 = 32861 bytes
294 < SECTION: PASS1: 4995 bytes
295 ---
296 > LINTMOD: 39982: 5144+27302+1057+9 = 33512 bytes
297 > SECTION: PASS1: 5144 bytes
298 19c19
299 < unsigned char _file;
300 ---
301 > unsigned char _magic;
302 22a23,24
303 > unsigned int __extendedfd;
304 > unsigned int __xf_nocheck;
305 \fI[ ... ]\fP
306 .fi
307 .LP
308 Note that -r option removes spurious differences that would otherwise
309 arise from different absolute paths to the same source file, and the -i
310 option removes spurious differences due to ID generation inside lint.
311 .LP
312 .SH SEE ALSO
313 .LP
314 .IR lint(1),
315 .IR printf(3C),
316 .IR scanf(3C)
317 .SH NOTES
318 This utility is provided as an interim solution until a stable utility
319 can be bundled with Sun Studio. As such, any use of this utility in
320 scripts or embedded inside programs should be done with knowledge that
321 subsequent changes will be required in order to transition to the stable
322 solution.
323 .LP
324 The lint object file format does not have a way to represent bitfields. As
325 such, bitfield size information cannot be displayed by lintdump.
|
2 .\" "
3 .\" " The contents of this file are subject to the terms of the
4 .\" " Common Development and Distribution License (the "License").
5 .\" " You may not use this file except in compliance with the License.
6 .\" "
7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 .\" " or http://www.opensolaris.org/os/licensing.
9 .\" " See the License for the specific language governing permissions
10 .\" " and limitations under the License.
11 .\" "
12 .\" " When distributing Covered Code, include this CDDL HEADER in each
13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 .\" " If applicable, add the following below this CDDL HEADER, with the
15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
17 .\" "
18 .\" " CDDL HEADER END
19 .\" "
20 .\" "Copyright 2008 Sun Microsystems, Inc. All rights reserved.
21 .\" "Use is subject to license terms.
22 .TH LINTDUMP 1ONBLD "Mar 28, 2008"
23 .I lintdump
24 \- dump the contents of one or more lint objects
25 .SH SYNOPSIS
26 \fBlintdump [-i] [-p 1|2|3] [-r] \fIlintobj\fP [ \fIlintobj\fP ... ]
27 .SH DESCRIPTION
28 .LP
29 The lintdump utility dumps the contents of one or more lint
30 objects. This is chiefly useful when trying to understand the cause of
31 unexpected or obtuse lint warnings (see EXAMPLES), but can also be used to
32 find differences between lint objects across builds or releases, or to
33 debug problems in lint itself.
34 .LP
35 A lint object is a binary file (typically suffixed with ".ln") constructed
36 from a C source file via the "-c" option to lint(1). Multiple lint
37 objects may be combined into a lint library object (typically prefixed
38 with "llib-l" and suffixed with ".ln") using the "-o" option to lint. (As
39 a convenience, lint "-o" allows a lint library object to be built directly
40 from C source files). The lintdump utility is capable of dumping both
41 traditional lint objects and lint library objects.
42 .LP
43 The format of a lint object is unstable and subject to change at any time,
44 but its current structure is summarized here in order to aid in
45 understanding the current output of lintdump. A lint object consists of
46 one or more lint modules (one per C source file). Each lint module
47 consists of a header and four sections, called PASS1, PASS2, PASS3, and
49 declarations, and PASS3 contains information on whether or how functions
50 or variables are used. The STRINGS section holds the strings for
51 printf(3C)/scanf(3C) checking.
52 .LP
53 Each PASS section consists of a sequence of binary records of assorted
54 types. The sequence of records is further partitioned by FILE records,
55 which indicate the source or header file that is responsible for the
56 records that follow. The remaining record types provide lint with
57 information about the functions, variables, and structures defined or used
58 by the object.
59 .SH OPTIONS
60 .TP 10
61 .B -i
62 Do not output structure tag IDs (see EXAMPLES).
63 .TP 10
64 .B -p 1|2|3
65 Just output the PASS1, PASS2, or PASS3 section.
66 .TP 10
67 .B -r
68 Output records using relative paths (see EXAMPLES).
69 .SH OUTPUT
70 .LP
71 The contents of each specified \fIlintobj\fP is dumped in command-line
72 order. For each \fIlintobj\fP, lintdump outputs a single line beginning
73 with "LINTOBJ:" that provides its name. For each lint module within that
74 object, lintdump outputs a single line beginning with "LINTMOD:" that
75 provides its module ID, the size of its PASS1, PASS2, PASS3, STRING
76 sections, and its total size, in that order.
77 .LP
78 Next, unless the -p option is used, the contents of the PASS1, PASS2, and
79 PASS3 sections are dumped, in order. Before each section is dumped,
80 lintdump outputs a single line beginning with "SECTION:" that
81 provides the name and size of the section. For each section,
82 lintdump outputs each record in order. The display format of each
83 record depends on its type:
84 .LP
85 .B FILE RECORDS
86 .RS 4
87 Each FILE record is displayed on a single line beginning with "FILE:".
88 Note that FILE records are often found in pairs, the first providing the
132 Then lintdump will produce the following output:
133 .LP
134 .nf
135 LINTOBJ: llib-la.ln
136 LINTMOD: 6484: 268+24+130+9 = 431 bytes
137 SECTION: PASS1: 268 bytes
138 FILE: /home/meem/hacks/liba.c
139 FILE: liba.c
140 extern int af(int);
141 struct as as;
142 struct as <tag 98> {
143 char as_name[];
144 int as_flag;
145 };
146 SECTION: PASS2: 24 bytes
147 SECTION: PASS3: 130 bytes
148 FILE: /home/meem/hacks/liba.c
149 FILE: liba.c
150 int af(void) <returns value>;
151 .fi
152 .SH RECORD PROPERTIES
153 .LP
154 As discussed in OUTPUT, some records are displayed using an extended
155 format to convey information that cannot be expressed in C. The following
156 extended information may be displayed:
157 .LP
158 .B <PRINTFLIKE\fIn\fP>
159 .RS 4
160 Indicates to lint that argument \fIn\fP to the variable-argument function
161 is a format string in printf(3C) format, which enhances lint's argument
162 checking.
163 .RE
164 .LP
165 .B <SCANFLIKE\fIn\fP>
166 .RS 4
167 Indicates to lint that argument \fIn\fP to the variable-argument function
168 is a format string in scanf(3C) format, which enhances lint's argument
169 checking.
170 .RE
171 .LP
172 .B <definition>
173 .RS 4
174 Indicates to lint that this record represents the definition of the given
175 variable or function (rather than a declaration).
176 .RE
180 Indicates to lint that the associated function is called in a context that
181 suggests it has side effects.
182 .RE
183 .LP
184 .B <use: return value context>
185 .RS 4
186 Indicates to lint that the associated function is called in a context where
187 its return value is used.
188 .RE
189 .LP
190 .B <use: unspecified context>
191 .RS 4
192 Indicates to lint that the associated function is used in an unspecified
193 manner.
194 .RE
195 .LP
196 .B <returns value>
197 .RS 4
198 Indicates to lint that the function returns a value.
199 .RE
200 .SH EXAMPLES
201 .LP
202 One common problem is that lint does not always provide sufficient
203 information to understand the reason for a type mismatch. For instance,
204 sometimes lint will confusingly report a type mismatch between
205 apparently-identical types:
206 .LP
207 .nf
208 $ lint msghdr.c -lsocket
209 function argument ( number ) used inconsistently
210 recvmsg (arg 2) llib-lsocket:socket.h(437) struct msghdr * ::
211 msghdr.c(12) struct msghdr *
212 .fi
213 .LP
214 By using lintdump, we can pinpoint the problem by examining both
215 definitions for \fIstruct msghdr\fP:
216 .LP
217 .nf
218 $ lintdump /lib/llib-lsocket.ln
219 \fI[ ... ]\fP
285 $ diff /tmp/patch-kstat.out /tmp/proj-kstat.out
286 1,2c1,2
287 < LINTMOD: 3675: 4995+26812+1045+9 = 32861 bytes
288 < SECTION: PASS1: 4995 bytes
289 ---
290 > LINTMOD: 39982: 5144+27302+1057+9 = 33512 bytes
291 > SECTION: PASS1: 5144 bytes
292 19c19
293 < unsigned char _file;
294 ---
295 > unsigned char _magic;
296 22a23,24
297 > unsigned int __extendedfd;
298 > unsigned int __xf_nocheck;
299 \fI[ ... ]\fP
300 .fi
301 .LP
302 Note that -r option removes spurious differences that would otherwise
303 arise from different absolute paths to the same source file, and the -i
304 option removes spurious differences due to ID generation inside lint.
305 .SH SEE ALSO
306 .LP
307 .IR lint(1),
308 .IR printf(3C),
309 .IR scanf(3C)
310 .SH NOTES
311 This utility is provided as an interim solution until a stable utility
312 can be bundled with Sun Studio. As such, any use of this utility in
313 scripts or embedded inside programs should be done with knowledge that
314 subsequent changes will be required in order to transition to the stable
315 solution.
316 .LP
317 The lint object file format does not have a way to represent bitfields. As
318 such, bitfield size information cannot be displayed by lintdump.
|