usr.bin/xlint/xlint/lint.1

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