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