ack/lang/cem/lint/lpass2/lint.1

.\" (c) copyright 1987 by the Vrije Universiteit, Amsterdam, The Netherlands.
.\" See the copyright notice in the ACK home directory, in the file "Copyright".
.\"
.\" $Header$
.TH LINT 1 89/10/04
.SH NAME
lint \- a C program checker
.SH SYNOPSIS
.B lint
[
.B \-abhuvx \-KR
]
[file | libname
.BR \-l xxx
] ...
.br
.B lint
.BR \-L libname
[file | libname2
.BR \-l xxx
] ...
.br
.SH DESCRIPTION
.I Lint
does an extensive consistency and plausibility check on a set of C
program files.
When it detects a doubtful construction
(which need not be an error) it gives a warning.
.PP
It does a full flow-of-control check, except that
.BR goto s
are not followed and that the fact that a function never returns
is not propagated.
If, however, no
.BR goto s
are used, each call of a non-returning function is followed by
/*NOTREACHED*/ and each switch has a default clause (possibly consisting
of /*NOTREACHED*/), the initialization state of all local variables will
be checked correctly.
.PP
.I Lint
checks the types of the arguments implied by the format in a call of
.IR printf() ,
.IR scanf()
and family, if the format string is a direct argument in the call.
Formats of user functions can be indicated using a FORMAT pseudo-comment; see
below.
.PP
.I Libraries
.PP
The second command (using the
.BR \-L -option)
is used to maintain lint libraries; these are ASCII files
that contain the output of the first pass.
A library name ends in
.BR .llb .
A lint user library can be created and updated by using the
.B \-L
option.  The
.I libname
end in
.BR .llb ,
and can be passed to
.I lint
again as a normal argument.
.PP
Standard libraries are searched by default or by explicitly giving the
.B \-l
option; their format is identical to that of the user library files.
Possibilities are
.BR \-lm ,
.B \-ltermcap
and 
.BR \-lcurses .
.B \-lc
is default; a single
.B \-l
tells
.I lint
not to use the standard C library.
The standard libraries are searched for in the standard lint directory or
in the directory given in the environment variable LINTLIB, if present.
.PP
.I Options
.PP
The
.BR \-D ,
.B \-U
and
.B \-I
options are recognized as separate arguments and conform to those of
.IR cc .
The
.B \-KR
option tells
.I lint
to check strictly according to Kernighan & Ritchie; since
.I lint
is trying to be helpful rather than obnoxious, this is not the default.
.PP
.I Lint
understands the following additional options:
.TP
.B a
Warn about conversions that may cause a loss of precision.
.TP
.B b
Do not report not-reachable 
.I break
statements.
This flag may be useful when
.I lint
is run on a generated source file.
.TP
.B h
Apply several heuristics:
signal "null effects", possible pointer alignment problems and odd
constructs; report definitions of variables that have a scope wider than
necessary: extern variables that are used in one file only, automatic
variables that could be more local.
.TP
.B u
Do not complain about unused and undefined functions and global variables.
.TP
.B v
Do not warn about unused arguments of functions.
.TP
.B x
Complain about unused external variables.
.PP
.I Pseudo-comments
.PP
The following pseudo-comments can be used to influence the behaviour of
.IR lint:
.TP
/*\ ARGSUSED\ */
Do not warn about arguments not used in the next function
(see also the \-\fBv\fR option).
.TP
/*\ NOTREACHED\ */
This tells
.I lint
that the flow of control "cannot reach" this comment.
This is a way to tell
.I lint
that a statement never "returns".
.TP
/*\ LINTLIBRARY\ */
The definitions following this pseudo-comment are assumed to be part of a
library.
It suppresses complaints about unused functions and variables
and is used in the creation of lint libraries.
It implies /*\ ARGSUSED\ */.
.TP
/*\ VARARGS\fIn\fR\ */
The next function can be called with a variable number of
arguments.
Only check the types of the first \fIn\fR arguments.
The \fIn\fR must follow the word VARARGS immediately.
/*\ VARARGS0\ */ may be abbreviated to /*\ VARARGS\ */.
.TP
/*\ FORMAT\fIn\fR $ ... $\ */
The \fIn\fP-th argument (counting from 0) of the  next function declaration
corresponds to a
.IR printf -like
format string.  Details about the format are given between the $$; see below.
A missing $$ repeats the latest format.
The \fIn\fR must follow the word FORMAT immediately.
/*\ FORMAT\fIn\fR $ ... $\ */ implies /*\ VARARGS\fIn+1\fP\ */; if the format
is followed by more required arguments, a separate /*\ VARARGS\fIm\fP\ */
must be given after the FORMAT pseudo-comment.
.IP
If the printf-like heading also has to conform to some varargs.h convention,
error messages may result; these can be suppressed by appending the letter v
to the word FORMAT\fIn\fR without intervening space.
.PP
.I Formats
.PP
The $$-part of the FORMAT pseudo-comment consists of a list of format
specifications, each of the form
.IR %T = type ,
where
.I T
is an arbitrary (short) string and
.I type
is the expected type in "C normal form" (like in a cast, with no superfluous
parentheses and without the use of typedefs). E.g., %ld=long indicates that
the format string ld corresponds to a parameter of type long. For a shorter
notation see the example below.
.I Lint
recognizes conversion specifications of the form %[N|*|][.[N|*]]T where N is
a number, the * is itself and T is a string as defined above. For the above
example this would include %ld, %5.2ld, %.*ld, etc.
.PP
Example: the FORMAT pseudo-comment for
.I printf()
is:
.br
/*\ FORMAT0 $
.br
	%[dox] = int		%l[dox] = long		%[DOX] = long
.br
	%u = unsigned int	%lu = unsigned long	%U = unsigned long
.br
	%[feg] = double
.br
	%c = int			%s = char *
.br
$\ */
.PP
.I Output
.PP
Some users feel it is a good idea to pipe the output of
.I lint
through the command
.br
	sort \-t' ' +0d \-1 +2n \-3
.br
where the character between the apostrophes is a space.
.SH "ENVIRONMENT VARIABLES"
LINTFLAGS		additional flag arguments (e.g. LINTFLAGS=\-h)
.br
LINTLIB		directory in which the standard libraries are looked up
.SH FILES
.IP ???/lnt 24
first pass
.IP ???/lpass2/lpass2
second pass
.IP ???/llib/*.llb
lint libraries
.SH SEE ALSO
cem(1)
.br
Frans Kunst,
.I Lint, a C Program Checker
.SH BUGS
Conflicting options in the command line are not detected.
.br
After a label, all automatic variables are assumed initialized.
.SH AUTHOR
Frans Kunst, Vrije Universiteit, Amsterdam.
.br
Dick Grune, Vrije Universiteit, Amsterdam.
.br