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