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.2 2003/06/17 04:29:34 dillon 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 abceghprvxzHFV
  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 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 .It Fl t
 247 Traditional C mode.
 248 .Dv __STDC__
 249 is not predefined in this mode.
 250 Warnings are printed for constructs
 251 not allowed in traditional C.
 252 Warnings for constructs which behave
 253 differently in traditional C and ANSI C are suppressed.
 254 Preprocessor
 255 macros describing the machine type (e.g.,
 256 .Dv sun3 )
 257 and machine architecture (e.g.,
 258 .Dv m68k )
 259 are defined without leading and trailing underscores.
 260 The keywords
 261 .Ic const , volatile
 262 and
 263 .Ic signed
 264 are not available in traditional C mode (although the alternate
 265 keywords with leading underscores still are).
 266 .It Fl u
 267 Do not complain about functions and external variables used
 268 and not defined, or defined and not used (this is suitable
 269 for running
 270 .Nm
 271 on a subset of files comprising part of a larger program).
 272 .It Fl v
 273 Suppress complaints about unused arguments in functions.
 274 .It Fl x
 275 Report variables referred to by
 276 .Ic extern
 277 declarations, but never used.
 278 .It Fl z
 279 Do not complain about structures that are never defined
 280 (for example, using a structure pointer without knowing
 281 its contents).
 282 .It Fl C Ar library
 283 Create a
 284 .Nm
 285 library with the name
 286 .Pa llib-l Ns Ar library Ns Pa .ln .
 287 This library is built from all
 288 .Pa .c
 289 and
 290 .Pa .ln
 291 input files.
 292 After all global definitions of functions and
 293 variables in these files are written to the newly created library,
 294 .Nm
 295 checks all input files, including libraries specified with the
 296 .Fl l
 297 option, for mutual compatibility.
 298 .It Fl D Ar name Ns Op = Ns Ar def
 299 Define
 300 .Ar name
 301 for
 302 .Xr cpp 1 ,
 303 as if by a
 304 .Ic #define
 305 directive.
 306 If no definition is given,
 307 .Ar name
 308 is defined as 1.
 309 .It Fl I Ar directory
 310 Add
 311 .Ar directory
 312 to the list of directories in which to search for include files.
 313 .It Fl l Ar library
 314 Include the lint library
 315 .Pa llib-l Ns Ar library Ns Pa .ln .
 316 .It Fl L Ar directory
 317 Search for lint libraries in
 318 .Ar directory
 319 and
 320 .Ar directory Ns Pa /lint
 321 before searching the standard place.
 322 .It Fl F
 323 Print pathnames of files.
 324 The
 325 .Nm
 326 utility normally prints the filename without the path.
 327 .It Fl H
 328 If a complaint stems from an included file
 329 .Nm
 330 prints the name of the included file instead of the source file name
 331 followed by a question mark.
 332 .It Fl o Ar outputfile
 333 Name the output file
 334 .Ar outputfile .
 335 The output file produced is the input that is given to
 336 .Nm Ns 's
 337 second pass.
 338 The
 339 .Fl o
 340 option simply saves this file in the named output file.
 341 If the
 342 .Fl i
 343 option is also used the files are not checked for compatibility.
 344 To produce a
 345 .Pa llib-l Ns Ar library Ns Pa .ln
 346 without extraneous messages, use of the
 347 .Fl u
 348 option is suggested.
 349 The
 350 .Fl v
 351 option is useful if the source file(s) for the lint library
 352 are just external interfaces.
 353 .It Fl U Ar name
 354 Remove any initial definition of
 355 .Ar name
 356 for the preprocessor.
 357 .It Fl V
 358 Print the command lines constructed by the controller program to
 359 run the C preprocessor and
 360 .Nm Ns 's
 361 first and second pass.
 362 .El
 363 .Ss Input Grammar
 364 .Nm Ns 's
 365 first pass reads standard C source files.
 366 The
 367 .Nm
 368 utility recognizes the following C comments as commands.
 369 .Bl -tag -width indent
 370 .It Li /* ARGSUSED Ns Ar n Li */
 371 makes
 372 .Nm
 373 check only the first
 374 .Ar n
 375 arguments for usage; a missing
 376 .Ar n
 377 is taken to be 0 (this option acts like the
 378 .Fl v
 379 option for the next function).
 380 .It Xo
 381 .Li /* CONSTCOND */
 382 or
 383 .Li /* CONSTANTCOND */
 384 or
 385 .Li /* CONSTANTCONDITION */
 386 .Xc
 387 suppress complaints about constant operands for the next expression.
 388 .It Xo
 389 .Li /* FALLTHRU */
 390 or
 391 .Li /* FALLTHROUGH */
 392 .Xc
 393 suppress complaints about fall through to a
 394 .Ic case
 395 or
 396 .Ic default
 397 labelled statement.
 398 This directive should be placed immediately
 399 preceding the label.
 400 .It Li /* LINTLIBRARY */
 401 At the beginning of a file, mark all functions and variables defined
 402 in this file as
 403 .Em used .
 404 Also shut off complaints about unused function arguments.
 405 .It Xo
 406 .Li /* LINTED Oo Ar comment Oc Li */
 407 or
 408 .Li /* NOSTRICT Oo Ar comment Oc Li */
 409 .Xc
 410 Suppresses any intra-file warning except those dealing with
 411 unused variables or functions.
 412 This directive should be placed
 413 on the line immediately preceding where the
 414 .Nm
 415 warning occurred.
 416 .It Li /* LONGLONG */
 417 Suppress complaints about use of long long integer types.
 418 .It Li /* NOTREACHED */
 419 At appropriate points, inhibit complaints about unreachable code.
 420 (This comment is typically placed just after calls to functions
 421 like
 422 .Xr exit 3 ) .
 423 .It Li /* PRINTFLIKE Ns Ar n Li */
 424 makes
 425 .Nm
 426 check the first
 427 .Pq Ar n Ns -1
 428 arguments as usual.
 429 The
 430 .Ar n Ns -th
 431 argument is interpreted as a
 432 .Xr printf 3
 433 format string that is used to check the remaining arguments.
 434 .It Li /* PROTOLIB Ns Ar n Li */
 435 causes
 436 .Nm
 437 to treat function declaration prototypes as function definitions
 438 if
 439 .Ar n
 440 is non-zero.
 441 This directive can only be used in conjunction with
 442 the
 443 .Li /* LINTLIBRARY */
 444 directive.
 445 If
 446 .Ar n
 447 is zero, function prototypes will be treated normally.
 448 .It Li /* SCANFLIKE Ns Ar n Li */
 449 makes
 450 .Nm
 451 check the first
 452 .Pq Ar n Ns -1
 453 arguments as usual.
 454 The
 455 .Ar n Ns -th
 456 argument is interpreted as a
 457 .Xr scanf 3
 458 format string that is used to check the remaining arguments.
 459 .It Li /* VARARGS Ns Ar n Li */
 460 Suppress the usual checking for variable numbers of arguments in
 461 the following function declaration.
 462 The data types of the first
 463 .Ar n
 464 arguments are checked; a missing
 465 .Ar n
 466 is taken to be 0.
 467 .El
 468 .Pp
 469 The behavior of the
 470 .Fl i
 471 and the
 472 .Fl o
 473 options allows for incremental use of
 474 .Nm
 475 on a set of C source files.
 476 Generally, one invokes
 477 .Nm
 478 once for each source file with the
 479 .Fl i
 480 option.
 481 Each of these invocations produces a
 482 .Pa .ln
 483 file that corresponds to the
 484 .Pa .c
 485 file, and prints all messages that are about just that
 486 source file.
 487 After all the source files have been separately
 488 run through
 489 .Nm ,
 490 it is invoked once more (without the
 491 .Fl i
 492 option), listing all the
 493 .Pa .ln
 494 files with the needed
 495 .Fl l Ns Ar library
 496 options.
 497 This will print all the inter-file inconsistencies.
 498 This
 499 scheme works well with
 500 .Xr make 1 ;
 501 it allows
 502 .Xr make 1
 503 to be used to
 504 .Nm
 505 only the source files that have been modified since the last
 506 time the set of source files were
 507 .Nm Ns ed .
 508 .Sh ENVIRONMENT
 509 .Bl -tag -width LIBDIR
 510 .It Ev LIBDIR
 511 the directory where the lint libraries specified by the
 512 .Bk -words
 513 .Fl l Ar library
 514 .Ek
 515 option must exist.
 516 If this environment variable is undefined,
 517 then the default path
 518 .Pa /usr/libdata/lint
 519 will be used to search for the libraries.
 520 .It Ev TMPDIR
 521 usually the path for temporary files can be redefined by setting
 522 this environment variable.
 523 .El
 524 .Sh FILES
 525 .Bl -tag -width /usr/libdata/lint/llib-lc.ln -compact
 526 .It Pa /usr/libexec/lint Ns Bq Pa 12
 527 programs
 528 .It Pa /usr/libdata/lint/llib-l*.ln
 529 various prebuilt lint libraries
 530 .It Pa /tmp/lint*
 531 temporaries
 532 .El
 533 .Sh SEE ALSO
 534 .Xr cc 1 ,
 535 .Xr cpp 1 ,
 536 .Xr make 1
 537 .Sh AUTHORS
 538 .An Jochen Pohl
 539 .Sh BUGS
 540 .Bl -item
 541 .It
 542 The routines
 543 .Xr exit 3 ,
 544 .Xr longjmp 3
 545 and other functions that do not return are not understood; this
 546 causes various incorrect diagnostics.
 547 .It
 548 Static functions which are used only before their first
 549 extern declaration are reported as unused.
 550 .It
 551 Libraries created by the
 552 .Fl o
 553 option will, when used in later
 554 .Nm
 555 runs, cause certain errors that were reported when the libraries
 556 were created to be reported again, and cause line numbers and file
 557 names from the original source used to create those libraries
 558 to be reported in error messages.
 559 For these reasons, it is recommended
 560 to use the
 561 .Fl C
 562 option to create lint libraries.
 563 .El