usr.bin/xlint/xlint/lint.1

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