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