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 88/10/13
.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 does not return
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
It 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 (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
must be a local file, 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 following definitions 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 $$. 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.
.PP
.I Formats
.PP
.I Lint
recognizes conversion specifications of the form %[N|*|][.[N|*]]X where X
is an arbitrary string, given in the $$-part of the FORMAT pseudo-comment.
The latter consists of a list of format specifications, each of the form
.IR %X = type ,
where 
.I type
is the expected type in "C normal form" (like in a cast, with no superfluous
parentheses and without the use of typedefs).
.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
$ */
.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.
.br
Initializations hidden inside for statements are sometimes overlooked.
.SH AUTHOR
Frans Kunst, Vrije Universiteit, Amsterdam.
.br
Dick Grune, Vrije Universiteit, Amsterdam.
.br