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