PageRenderTime 28ms CodeModel.GetById 16ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/usr.bin/xlint/xlint/lint.1

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