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