Print this page
new smatch
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/smatch/src/sparse.1
+++ new/usr/src/tools/smatch/src/sparse.1
1 1 .\" Sparse manpage by Josh Triplett
2 2 .TH sparse "1"
3 3 .
4 4 .SH NAME
5 5 sparse \- Semantic Parser for C
6 6 .
7 7 .SH SYNOPSIS
8 8 .B sparse
9 9 [\fIWARNING OPTIONS\fR]... \fIfile.c\fR
10 10 .
11 11 .SH DESCRIPTION
12 12 Sparse parses C source and looks for errors, producing warnings on standard
|
↓ open down ↓ |
12 lines elided |
↑ open up ↑ |
13 13 error.
14 14 .P
15 15 Sparse accepts options controlling the set of warnings to generate. To turn
16 16 on warnings Sparse does not issue by default, use the corresponding warning
17 17 option \fB\-Wsomething\fR. Sparse issues some warnings by default; to turn
18 18 off those warnings, pass the negation of the associated warning option,
19 19 \fB\-Wno\-something\fR.
20 20 .
21 21 .SH WARNING OPTIONS
22 22 .TP
23 +.B \-fmax-warnings=COUNT
24 +Set the maximum number of displayed warnings to COUNT, which should be
25 +a numerical value or 'unlimited'.
26 +The default limit is 100.
27 +.
28 +.TP
23 29 .B \-Wsparse\-all
24 30 Turn on all sparse warnings, except for those explicitly disabled via
25 31 \fB\-Wno\-something\fR.
26 32 .TP
27 33 .B \-Wsparse\-error
28 34 Turn all sparse warnings into errors.
29 35 .TP
30 36 .B \-Waddress\-space
31 37 Warn about code which mixes pointers to different address spaces.
32 38
33 39 Sparse allows an extended attribute
34 -.BI __attribute__((address_space( num )))
35 -on pointers, which designates a pointer target in address space \fInum\fR (a
36 -constant integer). With \fB\-Waddress\-space\fR, Sparse treats pointers with
37 -identical target types but different address spaces as distinct types. To
38 -override this warning, such as for functions which convert pointers between
39 -address spaces, use a type that includes \fB__attribute__((force))\fR.
40 +.BI __attribute__((address_space( id )))
41 +on pointers, which designates a pointer target in address space \fIid\fR (an
42 +identifier or a constant integer).
43 +With \fB\-Waddress\-space\fR, Sparse treats pointers with
44 +identical target types but different address spaces as distinct types and
45 +will warn accordingly.
40 46
47 +Sparse will also warn on casts which remove the address space (casts to an
48 +integer type or to a plain pointer type). An exception to this is when the
49 +destination type is \fBuintptr_t\fR (or \fBunsigned long\fR) since such casts
50 +are often used to "get a pointer value representation in an integer type" and
51 +such values are independent of the address space.
52 +
53 +To override these warnings, use a type that includes \fB__attribute__((force))\fR.
54 +
41 55 Sparse issues these warnings by default. To turn them off, use
42 56 \fB\-Wno\-address\-space\fR.
43 57 .
44 58 .TP
45 59 .B \-Wbitwise
46 60 Warn about unsupported operations or type mismatches with restricted integer
47 61 types.
48 62
49 63 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
50 64 creates a new restricted integer type from a base integer type, distinct from
51 65 the base integer type and from any other restricted integer type not declared
52 66 in the same declaration or \fBtypedef\fR. For example, this allows programs
53 67 to create \fBtypedef\fRs for integer types with specific endianness. With
54 68 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
55 69 arithmetic operations other than bitwise operations, and on any conversion of
56 70 one restricted type into another, except via a cast that includes
57 71 \fB__attribute__((force))\fR.
58 72
59 73 __bitwise ends up being a "stronger integer separation", one that
60 74 doesn't allow you to mix with non-bitwise integers, so now it's much
61 75 harder to lose the type by mistake.
62 76
63 77 __bitwise is for *unique types* that cannot be mixed with other
|
↓ open down ↓ |
13 lines elided |
↑ open up ↑ |
64 78 types, and that you'd never want to just use as a random integer (the
65 79 integer 0 is special, though, and gets silently accepted iirc - it's
66 80 kind of like "NULL" for pointers). So "gfp_t" or the "safe endianness"
67 81 types would be __bitwise: you can only operate on them by doing
68 82 specific operations that know about *that* particular type.
69 83
70 84 Sparse issues these warnings by default. To turn them off, use
71 85 \fB\-Wno\-bitwise\fR.
72 86 .
73 87 .TP
88 +.B \-Wbitwise\-pointer
89 +Same as \fB\-Wbitwise\fR but for casts to or from pointers to bitwise types.
90 +
91 +Sparse does not issue these warnings by default.
92 +.
93 +.TP
94 +.B \-Wcast\-from\-as
95 +Warn about casts which remove an address space from a pointer type.
96 +
97 +This is similar to \fB\-Waddress\-space\fR but will also warn
98 +on casts to \fBunsigned long\fR.
99 +
100 +Sparse does not issues these warnings by default.
101 +.
102 +.TP
74 103 .B \-Wcast\-to\-as
75 104 Warn about casts which add an address space to a pointer type.
76 105
77 106 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
107 +No warning is generated if the original type is \fBuintptr_t\fR
108 +(or \fBunsigned long\fR).
78 109
79 110 Sparse does not issue these warnings by default.
80 111 .
81 112 .TP
82 113 .B \-Wcast\-truncate
83 114 Warn about casts that truncate constant values.
84 115
85 116 Sparse issues these warnings by default. To turn them off, use
86 117 \fB\-Wno\-cast\-truncate\fR.
87 118 .
88 119 .TP
89 120 .B \-Wconstant\-suffix
90 121 Warn if an integer constant is larger than the maximum representable value
91 122 of the type indicated by its type suffix (if any). For example, on a
92 123 system where ints are 32-bit and longs 64-bit, the constant \fB0x100000000U\fR
93 124 is larger than can be represented by an \fBunsigned int\fR but fits in an
94 125 \fBunsigned long\fR. So its type is \fBunsigned long\fR but this is not
95 126 indicated by its suffix. In this case, the warning could be suppressed by
96 127 using the suffix \fBUL\fR: \fB0x100000000UL\fR.
97 128
98 129 Sparse does not issue these warnings by default.
99 130 .
100 131 .TP
101 132 .B \-Wconstexpr-not-const
102 133 Warn if a non-constant expression is encountered when really expecting a
103 134 constant expression instead.
104 135 Currently, this warns when initializing an object of static storage duration
105 136 with an initializer which is not a constant expression.
106 137
107 138 Sparse does not issue these warnings by default.
108 139 .
109 140 .TP
110 141 .B \-Wcontext
111 142 Warn about potential errors in synchronization or other delimited contexts.
112 143
113 144 Sparse supports several means of designating functions or statements that
114 145 delimit contexts, such as synchronization. Functions with the extended
115 146 attribute
116 147 .BI __attribute__((context( expression , in_context , out_context ))
117 148 require the context \fIexpression\fR (for instance, a lock) to have the value
118 149 \fIin_context\fR (a constant nonnegative integer) when called, and return with
119 150 the value \fIout_context\fR (a constant nonnegative integer). For APIs
120 151 defined via macros, use the statement form
121 152 .BI __context__( expression , in_value , out_value )
122 153 in the body of the macro.
123 154
124 155 With \fB-Wcontext\fR Sparse will warn when it sees a function change the
125 156 context without indicating this with a \fBcontext\fR attribute, either by
126 157 decreasing a context below zero (such as by releasing a lock without acquiring
127 158 it), or returning with a changed context (such as by acquiring a lock without
128 159 releasing it). Sparse will also warn about blocks of code which may
129 160 potentially execute with different contexts.
130 161
131 162 Sparse issues these warnings by default. To turn them off, use
132 163 \fB\-Wno\-context\fR.
133 164 .
134 165 .TP
135 166 .B \-Wdecl
136 167 Warn about any non-\fBstatic\fR variable or function definition that has no
137 168 previous declaration.
138 169
139 170 Private symbols (functions and variables) internal to a given source file
140 171 should use \fBstatic\fR, to allow additional compiler optimizations, allow
141 172 detection of unused symbols, and prevent other code from relying on these
142 173 internal symbols. Public symbols used by other source files will need
143 174 declarations visible to those other source files, such as in a header file.
144 175 All declarations should fall into one of these two categories. Thus, with
145 176 \fB-Wdecl\fR, Sparse warns about any symbol definition with neither
146 177 \fBstatic\fR nor a declaration. To fix this warning, declare private symbols
147 178 \fBstatic\fR, and ensure that the files defining public symbols have the
148 179 symbol declarations available first (such as by including the appropriate
149 180 header file).
150 181
151 182 Sparse issues these warnings by default. To turn them off, use
152 183 \fB\-Wno\-decl\fR.
153 184 .
154 185 .TP
155 186 .B \-Wdeclaration-after-statement
156 187 Warn about declarations that are not at the start of a block.
157 188
158 189 These declarations are permitted in C99 but not in C89.
159 190
160 191 Sparse issues these warnings by default only when the C dialect is
161 192 C89 (i.e. -ansi or -std=c89). To turn them off, use
162 193 \fB\-Wno\-declaration\-after\-statement\fR.
163 194 .
164 195 .TP
165 196 .B \-Wdefault\-bitfield\-sign
166 197 Warn about any bitfield with no explicit signedness.
167 198
168 199 Bitfields have no standard-specified default signedness. (C99 6.7.2) A
169 200 bitfield without an explicit \fBsigned\fR or \fBunsigned\fR creates a
170 201 portability problem for software that relies on the available range of values.
171 202 To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR
172 203 explicitly.
173 204
174 205 Sparse does not issue these warnings by default.
175 206 .
176 207 .TP
177 208 .B \-Wdesignated\-init
178 209 Warn about positional initialization of structs marked as requiring designated
179 210 initializers.
180 211
181 212 Sparse allows an attribute
182 213 .BI __attribute__((designated_init))
183 214 which marks a struct as requiring designated initializers. Sparse will warn
184 215 about positional initialization of a struct variable or struct literal of a
185 216 type that has this attribute.
186 217
187 218 Requiring designated initializers for a particular struct type will insulate
188 219 code using that struct type from changes to the layout of the type, avoiding
189 220 the need to change initializers for that type unless they initialize a removed
190 221 or incompatibly changed field.
191 222
192 223 Common examples of this type of struct include collections of function pointers
193 224 for the implementations of a class of related operations, for which the default
194 225 NULL for an unmentioned field in a designated initializer will correctly
195 226 indicate the absence of that operation.
196 227
197 228 Sparse issues these warnings by default. To turn them off, use
198 229 \fB\-Wno\-designated\-init\fR.
199 230 .
200 231 .TP
201 232 .B \-Wdo\-while
202 233 Warn about do-while loops that do not delimit the loop body with braces.
203 234
204 235 Sparse does not issue these warnings by default.
205 236 .
|
↓ open down ↓ |
118 lines elided |
↑ open up ↑ |
206 237 .TP
207 238 .B \-Wenum\-mismatch
208 239 Warn about the use of an expression of an incorrect \fBenum\fR type when
209 240 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
210 241 passing an argument to a function which expects another \fBenum\fR type.
211 242
212 243 Sparse issues these warnings by default. To turn them off, use
213 244 \fB\-Wno\-enum\-mismatch\fR.
214 245 .
215 246 .TP
216 -.B \-Wempty\-character\-constant
217 -Warn about a constant such as ''.
218 -
219 -Sparse issues these warnings by default. To turn them off, use
220 -\fB\-Wno\-empty\-character\-constant\fR.
221 -.
222 -.TP
223 247 .B \-Wexternal\-function\-has\-definition
224 248 Warn about function definitions that are declared with external linkage.
225 249
226 250 Sparse issues these warnings by default. To turn them off, use
227 251 \fB\-Wno\-external\-function\-has\-definition\fR.
228 252 .
229 253 .TP
230 254 .B \-Winit\-cstring
231 255 Warn about initialization of a char array with a too long constant C string.
232 256
233 257 If the size of the char array and the length of the string are the same,
234 258 there is no space for the last nul char of the string in the array:
235 259
236 260 .nf
237 261 char s[3] = "abc";
238 262 .fi
239 263
240 264 If the array is used as a byte array, not as C string, this
241 265 warning is just noise. However, if the array is passed to functions
242 266 dealing with C string like printf(%s) and strcmp, it may cause a
243 267 trouble.
244 268
245 269 Sparse does not issue these warnings by default.
246 270 .
247 271 .TP
248 272 .B \-Wmemcpy\-max\-count
|
↓ open down ↓ |
16 lines elided |
↑ open up ↑ |
249 273 Warn about call of \fBmemcpy()\fR, \fBmemset()\fR, \fBcopy_from_user()\fR, or
250 274 \fBcopy_to_user()\fR with a large compile-time byte count.
251 275
252 276 Sparse issues these warnings by default. To turn them off, use
253 277 \fB\-Wno\-memcpy\-max\-count\fR.
254 278
255 279 The limit can be changed with \fB\-fmemcpy\-max\-count=COUNT\fR,
256 280 the default being \fB100000\fR.
257 281 .
258 282 .TP
259 -.B \-Wnon\-ansi\-function\-declaration
260 -Warn about non-ANSI function declarations.
261 -
262 -Sparse issues these warnings by default. To turn them off, use
263 -\fB\-Wno\-non\-ansi\-function\-declaration\fR.
264 -.
265 -.TP
266 283 .B \-Wnon\-pointer\-null
267 284 Warn about the use of 0 as a NULL pointer.
268 285
269 286 0 has integer type. NULL has pointer type.
270 287
271 288 Sparse issues these warnings by default. To turn them off, use
272 289 \fB\-Wno\-non\-pointer\-null\fR.
273 290 .
274 291 .TP
275 292 .B \-Wold\-initializer
276 293 Warn about the use of the pre-C99 GCC syntax for designated initializers.
277 294
278 295 C99 provides a standard syntax for designated fields in \fBstruct\fR or
279 296 \fBunion\fR initializers:
280 297
281 298 .nf
282 299 struct structname var = { .field = value };
283 300 .fi
284 301
285 302 GCC also has an old, non-standard syntax for designated initializers which
286 303 predates C99:
287 304
288 305 .nf
289 306 struct structname var = { field: value };
290 307 .fi
291 308
292 309 Sparse will warn about the use of GCC's non-standard syntax for designated
293 310 initializers. To fix this warning, convert designated initializers to use the
294 311 standard C99 syntax.
295 312
296 313 Sparse issues these warnings by default. To turn them off, use
297 314 \fB\-Wno\-old\-initializer\fR.
298 315 .
299 316 .TP
300 317 .B \-Wone\-bit\-signed\-bitfield
301 318 Warn about any one-bit \fBsigned\fR bitfields.
302 319
303 320 A one-bit \fBsigned\fR bitfield can only have the values 0 and -1, or with
304 321 some compilers only 0; this results in unexpected behavior for programs which
305 322 expected the ability to store 0 and 1.
306 323
307 324 Sparse issues these warnings by default. To turn them off, use
308 325 \fB\-Wno\-one\-bit\-signed\-bitfield\fR.
309 326 .
310 327 .TP
311 328 .B \-Wparen\-string
312 329 Warn about the use of a parenthesized string to initialize an array.
313 330
314 331 Standard C syntax does not permit a parenthesized string as an array
315 332 initializer. GCC allows this syntax as an extension. With
316 333 \fB\-Wparen\-string\fR, Sparse will warn about this syntax.
317 334
318 335 Sparse does not issue these warnings by default.
319 336 .
320 337 .TP
321 338 .B \-Wpointer\-arith
322 339 Warn about anything that depends on the \fBsizeof\fR a void or function type.
323 340
324 341 C99 does not allow the \fBsizeof\fR operator to be applied to function types
325 342 or to incomplete types such as void. GCC allows \fBsizeof\fR to be applied to
326 343 these types as an extension and assigns these types a size of \fI1\fR. With
327 344 \fB\-pointer\-arith\fR, Sparse will warn about pointer arithmetic on void
328 345 or function pointers, as well as expressions which directly apply the
329 346 \fBsizeof\fR operator to void or function types.
330 347
331 348 Sparse does not issue these warnings by default.
332 349 .
333 350 .TP
334 351 .B \-Wptr\-subtraction\-blows
335 352 Warn when subtracting two pointers to a type with a non-power-of-two size.
336 353
337 354 Subtracting two pointers to a given type gives a difference in terms of the
338 355 number of items of that type. To generate this value, compilers will usually
339 356 need to divide the difference by the size of the type, an potentially
340 357 expensive operation for sizes other than powers of two.
341 358
342 359 Code written using pointer subtraction can often use another approach instead,
343 360 such as array indexing with an explicit array index variable, which may allow
344 361 compilers to generate more efficient code.
345 362
346 363 Sparse does not issue these warnings by default.
347 364 .
348 365 .TP
349 366 .B \-Wreturn\-void
350 367 Warn if a function with return type void returns a void expression.
351 368
352 369 C99 permits this, and in some cases this allows for more generic code in
353 370 macros that use typeof or take a type as a macro argument. However, some
354 371 programs consider this poor style, and those programs can use
355 372 \fB\-Wreturn\-void\fR to get warnings about it.
356 373
357 374 Sparse does not issue these warnings by default.
358 375 .
|
↓ open down ↓ |
83 lines elided |
↑ open up ↑ |
359 376 .TP
360 377 .B \-Wshadow
361 378 Warn when declaring a symbol which shadows a declaration with the same name in
362 379 an outer scope.
363 380
364 381 Such declarations can lead to error-prone code.
365 382
366 383 Sparse does not issue these warnings by default.
367 384 .
368 385 .TP
386 +.B \-Wshift-count-negative
387 +Warn if a shift count is negative.
388 +
389 +Sparse issues these warnings by default.
390 +.
391 +.TP
392 +.B \-Wshift-count-overflow
393 +Warn if a shift count is bigger than the operand's width.
394 +
395 +Sparse issues these warnings by default.
396 +.
397 +.TP
369 398 .B \-Wsizeof-bool
370 399 Warn when checking the sizeof a _Bool.
371 400
372 -C99 does not specify the sizeof a _Bool. gcc uses 1.
401 +C99 does not specify the size of a _Bool. GCC, by default, uses \fI1\fR.
373 402
374 403 Sparse does not issue these warnings by default.
375 404 .
376 405 .TP
377 406 .B \-Wtransparent\-union
378 407 Warn about any declaration using the GCC extension
379 408 \fB__attribute__((transparent_union))\fR.
380 409
381 410 Sparse issues these warnings by default. To turn them off, use
382 411 \fB\-Wno\-transparent\-union\fR.
383 412 .
384 413 .TP
385 414 .B \-Wtypesign
386 415 Warn when converting a pointer to an integer type into a pointer to an integer
387 416 type with different signedness.
388 417
389 418 Sparse does not issue these warnings by default.
390 419 .
391 420 .TP
392 421 .B \-Wundef
393 422 Warn about preprocessor conditionals that use the value of an undefined
394 423 preprocessor symbol.
395 424
396 425 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
397 426 symbol in preprocessor conditionals, and specifies it has a value of 0.
398 427 However, this behavior can lead to subtle errors.
399 428
400 429 Sparse does not issue these warnings by default.
401 430 .
402 431 .SH MISC OPTIONS
403 432 .TP
404 433 .B \-gcc-base-dir \fIdir\fR
|
↓ open down ↓ |
22 lines elided |
↑ open up ↑ |
405 434 Look for compiler-provided system headers in \fIdir\fR/include/ and \fIdir\fR/include-fixed/.
406 435 .
407 436 .TP
408 437 .B \-multiarch-dir \fIdir\fR
409 438 Look for system headers in the multiarch subdirectory \fIdir\fR.
410 439 The \fIdir\fR name would normally take the form of the target's
411 440 normalized GNU triplet. (e.g. i386-linux-gnu).
412 441 .
413 442 .SH DEBUG OPTIONS
414 443 .TP
415 -.B \-fdump-linearize[=only]
416 -Dump the IR code of a function directly after its linearization,
417 -before any simplifications are made. If the argument \fB=only\fR is
418 -also given no further processing is done on the function.
419 -.
420 444 .B \-fmem-report
421 445 Report some statistics about memory allocation used by the tool.
422 446 .
423 447 .SH OTHER OPTIONS
424 448 .TP
449 +.B \-fdiagnostic-prefix[=PREFIX]
450 +Prefix all diagnostics by the given PREFIX, followed by ": ".
451 +If no one is given "sparse" is used.
452 +The default is to not use a prefix at all.
453 +.
454 +.TP
425 455 .B \-fmemcpy-max-count=COUNT
426 456 Set the limit for the warnings given by \fB-Wmemcpy-max-count\fR.
427 -A COUNT of 0, useless in itself, will effectively disable the warning.
457 +A COUNT of 'unlimited' or '0' will effectively disable the warning.
428 458 The default limit is 100000.
429 459 .
430 460 .TP
431 461 .B \-ftabstop=WIDTH
432 462 Set the distance between tab stops. This helps sparse report correct
433 463 column numbers in warnings or errors. If the value is less than 1 or
434 464 greater than 100, the option is ignored. The default is 8.
435 465 .
466 +.TP
467 +.B \-f[no-]unsigned-char, \-f[no-]signed-char
468 +Let plain 'char' be unsigned or signed.
469 +By default chars are signed.
470 +.
436 471 .SH SEE ALSO
437 472 .BR cgcc (1)
438 473 .
439 474 .SH HOMEPAGE
440 475 http://www.kernel.org/pub/software/devel/sparse/
441 476 .
442 477 .SH MAILING LIST
443 478 linux-sparse@vger.kernel.org
444 479 .
445 -.SH MAINTAINER
446 -Christopher Li <sparse@chrisli.org>
480 +.SH CONTRIBUTINGS AND REPORTING BUGS
481 +Submission of patches and reporting of bugs, as well as discussions
482 +related to Sparse, should be done via the mailing list (linux-sparse@vger.kernel.org)
483 +where the development and maintenance is primarily done.
484 +You do not have to be subscribed to the list to send a message there.
485 +
486 +Bugs can also be reported and tracked via the Linux kernel's bugzilla:
487 +http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools .
488 +.
489 +.SH AUTHORS
490 +Sparse was started by Linus Torvalds.
491 +The complete list of contributors can be find at
492 +https://www.openhub.net/p/sparse/contributors .
493 +
494 +Luc Van Oostenryck is Sparse's current maintainer.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX