usr.bin/xlint/xlint/lint.1

   1 .\" $NetBSD: lint.1,v 1.21 2002/01/03 04:25:18 thorpej Exp $
   2 .\"
   3 .\" Copyright (c) 1996 Christopher G. Demetriou.  All Rights Reserved.
   4 .\" Copyright (c) 1994, 1995 Jochen Pohl
   5 .\" All Rights Reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"      This product includes software developed by Jochen Pohl for
  18 .\"      The NetBSD Project.
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd May 24, 2001
  36 .Dt LINT 1
  37 .Os
  38 .Sh NAME
  39 .Nm lint
  40 .Nd a C program verifier
  41 .Sh SYNOPSIS
  42 .Bk -words
  43 .Nm
  44 .Op Fl abceghprvwxzHFV
  45 .Op Fl s | t
  46 .Op Fl i | nu
  47 .Op Fl D Ar name Ns Op = Ns Ar def
  48 .Op Fl U Ar name
  49 .Op Fl I Ar directory
  50 .Op Fl d Ar directory
  51 .Op Fl L Ar directory
  52 .Op Fl l Ar library
  53 .Op Fl o Ar outputfile
  54 .Op Fl B Ar directory
  55 .Op Fl X Ar id Ns Op , Ns Ar id ...
  56 .Ar
  57 .Nm
  58 .Op Fl abceghprvwzHFV
  59 .Op Fl s | t
  60 .Fl C Ar library
  61 .Op Fl D Ar name Ns Op = Ns Ar def
  62 .Op Fl U Ar name
  63 .Op Fl I Ar directory
  64 .Op Fl d Ar directory
  65 .Op Fl B Ar directory
  66 .Op Fl X Ar id Ns Op , Ns Ar id ...
  67 .Ar
  68 .Ek
  69 .Sh DESCRIPTION
  70 The
  71 .Nm
  72 utility attempts to detect features of the named C program files
  73 that are likely to be bugs, to be non-portable, or to be
  74 wasteful.
  75 It also performs stricter type checking than does
  76 the C compiler.
  77 The
  78 .Nm
  79 utility runs the C preprocessor as its first phase, with the
  80 preprocessor symbol
  81 .Dq Dv lint
  82 defined to allow certain questionable code to be altered
  83 or skipped by
  84 .Nm .
  85 Therefore, this symbol should be thought of as a reserved
  86 word for all code that is to be checked by
  87 .Nm .
  88 .Pp
  89 Among the possible problems that are currently noted are
  90 unreachable statements, loops not entered at the top,
  91 variables declared and not used, and logical expressions
  92 with constant values.
  93 Function calls are checked for
  94 inconsistencies, such as calls to functions that return
  95 values in some places and not in others, functions called
  96 with varying numbers of arguments, function calls that
  97 pass arguments of a type other than the type the function
  98 expects to receive, functions whose values are not used,
  99 and calls to functions not returning values that use
 100 the non-existent return value of the function.
 101 .Pp
 102 Filename arguments ending with
 103 .Pa .c
 104 are taken to be C source files.
 105 Filename arguments with
 106 names ending with
 107 .Pa .ln
 108 are taken to be the result of an earlier invocation of
 109 .Nm ,
 110 with either the
 111 .Fl i , o ,
 112 or
 113 .Fl C
 114 option in effect.
 115 The
 116 .Pa .ln
 117 files are analogous to the
 118 .Pa .o
 119 (object) files produced by
 120 .Xr cc 1
 121 from
 122 .Pa .c
 123 files.
 124 The
 125 .Nm
 126 utility also accepts special libraries specified with the
 127 .Fl l
 128 option, which contain definitions of library routines and
 129 variables.
 130 .Pp
 131 The
 132 .Nm
 133 utility takes all the
 134 .Pa .c , .ln ,
 135 and
 136 .Pa llib-l Ns Ar library Ns Pa .ln
 137 (lint library) files and processes them in command-line order.
 138 By default,
 139 .Nm
 140 appends the standard C lint library
 141 .Pq Pa llib-lc.ln
 142 to the end of the list of files.
 143 When the
 144 .Fl i
 145 option is used, the
 146 .Pa .ln
 147 files are ignored.
 148 Also, when the
 149 .Fl o
 150 or
 151 .Fl i
 152 options are used, the
 153 .Pa llib-l Ns Ar library Ns Pa .ln
 154 files are ignored.
 155 When the
 156 .Fl i
 157 option is
 158 .Em omitted
 159 the second pass of
 160 .Nm
 161 checks this list of files for mutual compatibility.
 162 At this point,
 163 if a complaint stems not from a given source file, but from one of
 164 its included files, the source filename will be printed followed by
 165 a question mark.
 166 .Pp
 167 The special input file name
 168 .Dq Pa -
 169 causes
 170 .Nm
 171 to take input from standard input (until end of file) and process
 172 it as if it were a
 173 .Pa .c
 174 file.
 175 If the
 176 .Fl i
 177 flag is given and
 178 .Dq Pa -
 179 is named as one of the input files, the
 180 .Fl o
 181 flag must also be specified to provide an output file name.
 182 The options are as follows:
 183 .Bl -tag -width indent
 184 .It Fl a
 185 Report assignments of
 186 .Vt long
 187 values to variables that are not
 188 .Vt long .
 189 .It Fl aa
 190 Additional to
 191 .Fl a ,
 192 report
 193 .Em all
 194 assignments of integer values to other integer values which
 195 cause implicit narrowing conversion.
 196 .It Fl b
 197 Report
 198 .Ic break
 199 statements that cannot be reached.
 200 This is not the default
 201 because, unfortunately, most
 202 .Xr lex 1
 203 and many
 204 .Xr yacc 1
 205 outputs produce many such complaints.
 206 .It Fl c
 207 Complain about casts which have questionable portability.
 208 .It Fl e
 209 Complain about unusual operations on
 210 .Vt enum Ns -Types
 211 and combinations of
 212 .Vt enum Ns -
 213 and
 214 .Sy integer Ns -Types .
 215 .It Fl g
 216 Do not print warnings for some extensions of
 217 .Xr gcc 1
 218 to the C language.
 219 Currently these are nonconstant initializers in
 220 automatic aggregate initializations, arithmetic on pointer to void,
 221 trailing commas in
 222 .Vt enum
 223 declarations, C++ -style
 224 .Dq Li //
 225 comments,
 226 zero sized structures, subscripting of non-lvalue arrays, prototypes
 227 overriding old style function declarations and long long
 228 integer types.
 229 The
 230 .Fl g
 231 flag also turns on the keywords
 232 .Ic asm
 233 and
 234 .Ic inline
 235 (alternative keywords with leading underscores for both
 236 .Ic asm
 237 and
 238 .Ic inline
 239 are always available).
 240 .It Fl h
 241 Apply a number of heuristic tests to attempt to intuit
 242 bugs, improve style, and reduce waste.
 243 .It Fl i
 244 Produce a
 245 .Pa .ln
 246 file for every
 247 .Pa .c
 248 file on the command line.
 249 These
 250 .Pa .ln
 251 files are the product of
 252 .Nm Ns 's
 253 first pass only, and are not checked for compatibility
 254 between functions.
 255 .It Fl n
 256 Do not check compatibility against the standard library.
 257 .It Fl p
 258 Attempt to check portability of code to other dialects of C.
 259 .It Fl r
 260 In case of redeclarations report the position of the
 261 previous declaration.
 262 .It Fl s
 263 Strict ANSI C mode.
 264 Issue warnings and errors required by ANSI C.
 265 Also do not produce warnings for constructs which behave
 266 differently in traditional C and ANSI C.
 267 With the
 268 .Fl s
 269 flag,
 270 .Dv __STRICT_ANSI__
 271 is a predefined preprocessor macro.
 272 .It Fl t
 273 Traditional C mode.
 274 .Dv __STDC__
 275 is not predefined in this mode.
 276 Warnings are printed for constructs
 277 not allowed in traditional C.
 278 Warnings for constructs which behave
 279 differently in traditional C and ANSI C are suppressed.
 280 Preprocessor
 281 macros describing the machine type (e.g.,
 282 .Dv sun3 )
 283 and machine architecture (e.g.,
 284 .Dv m68k )
 285 are defined without leading and trailing underscores.
 286 The keywords
 287 .Ic const , volatile
 288 and
 289 .Ic signed
 290 are not available in traditional C mode (although the alternative
 291 keywords with leading underscores still are).
 292 .It Fl u
 293 Do not complain about functions and external variables used
 294 and not defined, or defined and not used (this is suitable
 295 for running
 296 .Nm
 297 on a subset of files comprising part of a larger program).
 298 .It Fl v
 299 Suppress complaints about unused arguments in functions.
 300 .It Fl x
 301 Report variables referred to by
 302 .Ic extern
 303 declarations, but never used.
 304 .It Fl z
 305 Do not complain about structures that are never defined
 306 (for example, using a structure pointer without knowing
 307 its contents).
 308 .It Fl B Ar path
 309 Path to use when looking for the
 310 .Pa lint1
 311 and
 312 .Pa lint2
 313 binaries.
 314 Defaults to
 315 .Pa /usr/libexec .
 316 .It Fl C Ar library
 317 Create a
 318 .Nm
 319 library with the name
 320 .Pa llib-l Ns Ar library Ns Pa .ln .
 321 This library is built from all
 322 .Pa .c
 323 and
 324 .Pa .ln
 325 input files.
 326 After all global definitions of functions and
 327 variables in these files are written to the newly created library,
 328 .Nm
 329 checks all input files, including libraries specified with the
 330 .Fl l
 331 option, for mutual compatibility.
 332 .It Fl D Ar name Ns Op = Ns Ar def
 333 Define
 334 .Ar name
 335 for
 336 .Xr cpp 1 ,
 337 as if by a
 338 .Ic #define
 339 directive.
 340 If no definition is given,
 341 .Ar name
 342 is defined as 1.
 343 .It Fl I Ar directory
 344 Add
 345 .Ar directory
 346 to the list of directories in which to search for include files.
 347 .It Fl d Ar directory
 348 Use
 349 .Ar directory
 350 instead of
 351 .Pa /usr/include
 352 as the default place to find include files.
 353 .It Fl l Ar library
 354 Include the lint library
 355 .Pa llib-l Ns Ar library Ns Pa .ln .
 356 .It Fl L Ar directory
 357 Search for lint libraries in
 358 .Ar directory
 359 and
 360 .Ar directory Ns Pa /lint
 361 before searching the standard place.
 362 .It Fl F
 363 Print pathnames of files.
 364 The
 365 .Nm
 366 utility normally prints the filename without the path.
 367 .It Fl H
 368 If a complaint stems from an included file
 369 .Nm
 370 prints the name of the included file instead of the source file name
 371 followed by a question mark.
 372 .It Fl o Ar outputfile
 373 Name the output file
 374 .Ar outputfile .
 375 The output file produced is the input that is given to
 376 .Nm Ns 's
 377 second pass.
 378 The
 379 .Fl o
 380 option simply saves this file in the named output file.
 381 If the
 382 .Fl i
 383 option is also used the files are not checked for compatibility.
 384 To produce a
 385 .Pa llib-l Ns Ar library Ns Pa .ln
 386 without extraneous messages, use of the
 387 .Fl u
 388 option is suggested.
 389 The
 390 .Fl v
 391 option is useful if the source file(s) for the lint library
 392 are just external interfaces.
 393 .It Fl U Ar name
 394 Remove any initial definition of
 395 .Ar name
 396 for the preprocessor.
 397 .It Fl V
 398 Print the command lines constructed by the controller program to
 399 run the C preprocessor and
 400 .Nm Ns 's
 401 first and second pass.
 402 .It Fl w
 403 Treat warnings as errors.
 404 .It Fl X Ar id Ns Op , Ns Ar id ...
 405 Suppress error messages identified by the list of ids.
 406 A list of messages
 407 and ids can be found in
 408 .Xr lint 7 .
 409 .El
 410 .Ss Input Grammar
 411 .Nm Ns 's
 412 first pass reads standard C source files.
 413 The
 414 .Nm
 415 utility recognizes the following C comments as commands.
 416 .Bl -tag -width indent
 417 .It Li /* ARGSUSED Ns Ar n Li */
 418 makes
 419 .Nm
 420 check only the first
 421 .Ar n
 422 arguments for usage; a missing
 423 .Ar n
 424 is taken to be 0 (this option acts like the
 425 .Fl v
 426 option for the next function).
 427 .It Li /* BITFIELDTYPE */
 428 Suppress error messages about illegal bitfield types if the type
 429 is an integer type, and suppress non-portable bitfield type warnings.
 430 .It Xo
 431 .Li /* CONSTCOND */
 432 or
 433 .Li /* CONSTANTCOND */
 434 or
 435 .Li /* CONSTANTCONDITION */
 436 .Xc
 437 suppress complaints about constant operands for the next expression.
 438 .It Xo
 439 .Li /* FALLTHRU */
 440 or
 441 .Li /* FALLTHROUGH */
 442 .Xc
 443 suppress complaints about fall through to a
 444 .Ic case
 445 or
 446 .Ic default
 447 labelled statement.
 448 This directive should be placed immediately
 449 preceding the label.
 450 .It Li /* LINTLIBRARY */
 451 At the beginning of a file, mark all functions and variables defined
 452 in this file as
 453 .Em used .
 454 Also shut off complaints about unused function arguments.
 455 .It Xo
 456 .Li /* LINTED Oo Ar comment Oc Li */
 457 or
 458 .Li /* NOSTRICT Oo Ar comment Oc Li */
 459 .Xc
 460 Suppresses any intra-file warning except those dealing with
 461 unused variables or functions.
 462 This directive should be placed
 463 on the line immediately preceding where the
 464 .Nm
 465 warning occurred.
 466 .It Li /* LONGLONG */
 467 Suppress complaints about use of long long integer types.
 468 .It Li /* NOTREACHED */
 469 At appropriate points, inhibit complaints about unreachable code.
 470 (This comment is typically placed just after calls to functions
 471 like
 472 .Xr exit 3 ) .
 473 .It Li /* PRINTFLIKE Ns Ar n Li */
 474 makes
 475 .Nm
 476 check the first
 477 .Pq Ar n Ns -1
 478 arguments as usual.
 479 The
 480 .Ar n Ns -th
 481 argument is interpreted as a
 482 .Xr printf 3
 483 format string that is used to check the remaining arguments.
 484 .It Li /* PROTOLIB Ns Ar n Li */
 485 causes
 486 .Nm
 487 to treat function declaration prototypes as function definitions
 488 if
 489 .Ar n
 490 is non-zero.
 491 This directive can only be used in conjunction with
 492 the
 493 .Li /* LINTLIBRARY */
 494 directive.
 495 If
 496 .Ar n
 497 is zero, function prototypes will be treated normally.
 498 .It Li /* SCANFLIKE Ns Ar n Li */
 499 makes
 500 .Nm
 501 check the first
 502 .Pq Ar n Ns -1
 503 arguments as usual.
 504 The
 505 .Ar n Ns -th
 506 argument is interpreted as a
 507 .Xr scanf 3
 508 format string that is used to check the remaining arguments.
 509 .It Li /* VARARGS Ns Ar n Li */
 510 Suppress the usual checking for variable numbers of arguments in
 511 the following function declaration.
 512 The data types of the first
 513 .Ar n
 514 arguments are checked; a missing
 515 .Ar n
 516 is taken to be 0.
 517 .El
 518 .Pp
 519 The behavior of the
 520 .Fl i
 521 and the
 522 .Fl o
 523 options allows for incremental use of
 524 .Nm
 525 on a set of C source files.
 526 Generally, one invokes
 527 .Nm
 528 once for each source file with the
 529 .Fl i
 530 option.
 531 Each of these invocations produces a
 532 .Pa .ln
 533 file that corresponds to the
 534 .Pa .c
 535 file, and prints all messages that are about just that
 536 source file.
 537 After all the source files have been separately
 538 run through
 539 .Nm ,
 540 it is invoked once more (without the
 541 .Fl i
 542 option), listing all the
 543 .Pa .ln
 544 files with the needed
 545 .Fl l Ar library
 546 options.
 547 This will print all the inter-file inconsistencies.
 548 This
 549 scheme works well with
 550 .Xr make 1 ;
 551 it allows
 552 .Xr make 1
 553 to be used to
 554 .Nm
 555 only the source files that have been modified since the last
 556 time the set of source files were
 557 .Nm Ns ed .
 558 .Sh ENVIRONMENT
 559 .Bl -tag -width LIBDIR
 560 .It Ev LIBDIR
 561 the directory where the lint libraries specified by the
 562 .Bk -words
 563 .Fl l Ar library
 564 .Ek
 565 option must exist.
 566 If this environment variable is undefined,
 567 then the default path
 568 .Pa /usr/libdata/lint
 569 will be used to search for the libraries.
 570 .It Ev TMPDIR
 571 usually the path for temporary files can be redefined by setting
 572 this environment variable.
 573 .It Ev CC
 574 Location of the C compiler program.
 575 Defaults to
 576 .Pa /usr/bin/cc .
 577 .El
 578 .Sh FILES
 579 .Bl -tag -width /usr/libdata/lint/llib-lc.ln -compact
 580 .It Pa /usr/libexec/lint Ns Bq Pa 12
 581 programs
 582 .It Pa /usr/libdata/lint/llib-l*.ln
 583 various prebuilt lint libraries
 584 .It Pa /tmp/lint*
 585 temporaries
 586 .El
 587 .Sh SEE ALSO
 588 .Xr cc 1 ,
 589 .Xr cpp 1 ,
 590 .Xr make 1
 591 .Sh AUTHORS
 592 .An Jochen Pohl
 593 .Sh BUGS
 594 .Bl -item
 595 .It
 596 The routines
 597 .Xr exit 3 ,
 598 .Xr longjmp 3
 599 and other functions that do not return are not understood; this
 600 causes various incorrect diagnostics.
 601 .It
 602 Static functions which are used only before their first
 603 extern declaration are reported as unused.
 604 .It
 605 Libraries created by the
 606 .Fl o
 607 option will, when used in later
 608 .Nm
 609 runs, cause certain errors that were reported when the libraries
 610 were created to be reported again, and cause line numbers and file
 611 names from the original source used to create those libraries
 612 to be reported in error messages.
 613 For these reasons, it is recommended
 614 to use the
 615 .Fl C
 616 option to create lint libraries.
 617 .El