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