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