The :link reftype=hd res=18.:font facename='System VIO' size=14x8.-weak:font facename=default size=0x0.:elink. flag is a mode
flag that sets many checking parameters to select weaker checking than
is done in the default mode&per. Other LCLint flags will be introduced in the following sections; a complete list is given in :link reftype=hd res=18.Appendix C:elink.&per.
.br
:font facename='Helv' size=20x12.
.br
2&per.1 Messages
:font facename=default size=0x0.
.br
.br
The format and content of messages printed by LCLint can be customized by the
user&per. A typical message is&colon.
:p.
:p.
:cgraphic.
sample&per.c&colon. (in function faucet)
sample&per.c&colon.11,12&colon. Fresh storage x not released before return
A memory leak has been detected&per. Newly-allocated or only-qualified storage
is not released before the last reference to is it lost&per. Use -mustfree to
suppress message&per.
sample&per.c&colon.5,47&colon. Fresh storage x allocated
:ecgraphic.
The first line gives the name of the function in which the error is found&per.
This is printed before the first message reported for a function&per. (The
function context is not printed if :font facename='System VIO' size=14x8.-showfunc:font facename=default size=0x0. is used&per.)
:p.
:p.
The second line is the text of the message&per. This message reports a memory leak
- storage allocated in a function is not deallocated before the function
returns&per. The text is preceded by the file name, line and column number where
the error is located&per. The column numbers are used by the emacs mode (see
:link reftype=hd res=23.Appendix H:elink.) to jump to the
appropriate line and column location&per. (Column numbers are not printed
if :link reftype=hd res=18.:font facename='System VIO' size=14x8.-showcolumn:font facename=default size=0x0.:elink. is used&per.)
:p.
:p.
The next line is a hint giving more information about the suspected error&per.
Most hints also include information on how the message may be suppressed&per. For
this message, setting the :font facename='System VIO' size=14x8.-mustfree:font facename=default size=0x0. flag would
prevent the message from being reported&per. Hints may be turned off by
using :link reftype=hd res=18.:font facename='System VIO' size=14x8.-hints:font facename=default size=0x0.:elink.&per. Normally, a hint is given only the first time a class of error is reported&per.
To have LCLint print a hint for every message regardless, use :link reftype=hd res=18.:font facename='System VIO' size=14x8.+forcehints:font facename=default size=0x0.:elink.&per.
:p.
:p.
The final line of the message gives additional location information&per. For this
message, it tells where the leaking storage is allocated&per.
:p.
:p.
The generic message format is (parts enclosed in square brackets are
<file>&colon.<line>,<column>&colon. :hp1.extra location information, if appopriate:ehp1.
:p.
:ecgraphic.
The text of messages and hints may be longer than one line&per. They are split
into lines of length less than the value set using :link reftype=hd res=18.:font facename='System VIO' size=14x8.-linelen:font facename=default size=0x0.:elink.
:hp1.<number>:ehp1.&per. The default line length is 80 characters&per. LCLint
attempts to split lines in a sensible place as near to the line length limit as
possible&per.
.br
:font facename='Helv' size=20x12.
.br
2&per.2 Flags
:font facename=default size=0x0.
.br
.br
So that many programming styles can be supported, LCLint provides over 300
flags for controlling checking and message reporting&per. Some of the flags are
introduced in the body of this document&per. :link reftype=hd res=18.Apppendix C:elink. describes every flag&per.
Modes and shortcut flags are provided for setting many flags at once&per.
Individual flags can override the mode settings&per.
:p.
:p.
Flags are preceded by + or -&per. When a flag is preceded by + we say it is
:hp1.on:ehp1.; when it is preceded by - it is :hp1.off:ehp1.&per. The precise meaning of on
and off depends on the type of flag&per.
:p.
:p.
The +/- flag settings are used for consistency and clarity, but contradict
standard UNIX usage and is easy to accidentally use the wrong one&per. To reduce
the likelihood of using the wrong flag, LCLint issues warnings when a flag is
set in an unusual way&per. Warnings are issued when a flag is redundantly set to
the value it already had (these errors are not reported if the flag is set
using a stylized comment), if a mode flag or special flag is set after a more
specific flag that will be set by the general flag was already set, if value
flags are given unreasonable values, of if flags are set in an inconsistent
way&per. The :link reftype=hd res=18.:font facename='System VIO' size=14x8.-warnflags:font facename=default size=0x0.:elink. flag suppresses these warnings&per.
:p.
:p.
Default flag settings will be read from :font facename='System VIO' size=14x8.~/&per.lclintrc:font facename=default size=0x0. if it is readable&per. If
there is a :font facename='System VIO' size=14x8.&per.lclintrc:font facename=default size=0x0. file in the working directory, settings in this file will
be read next and its settings will override those in :font facename='System VIO' size=14x8.~/&per.lclintrc:font facename=default size=0x0.&per. Command-line
flags override settings in either file&per. The syntax of the :font facename='System VIO' size=14x8.&per.lclintrc:font facename=default size=0x0. file is
the same as that of command-line flags, except that flags may be on separate
lines and the :font facename='System VIO' size=14x8.#:font facename=default size=0x0. character may be used to indicate that the remainder of the
line is a comment&per. The :link reftype=hd res=18.:font facename='System VIO' size=14x8.-nof:font facename=default size=0x0.:elink.
flag prevents the :font facename='System VIO' size=14x8.~/&per.lclintrc:font facename=default size=0x0. file from being
loaded&per. The :link reftype=hd res=18.:font facename='System VIO' size=14x8.-f:font facename=default size=0x0.:elink. :hp1.<filename>:ehp1. flag loads options from :hp1.filename:ehp1.&per.
.br
:font facename='Helv' size=20x12.
.br
2&per.3 Stylized Comments
:font facename=default size=0x0.
.br
.br
Stylized comments are used to provide extra information about a type, variable
or function interface to improve checking, or to control flag settings
locally&per.
:p.
:p.
All stylized comments begin with :font facename='System VIO' size=14x8./*@:font facename=default size=0x0. and are closed by the end of the comment&per.
The role of the :font facename='System VIO' size=14x8.@:font facename=default size=0x0. may be played by any printable character&per. Use :link reftype=hd res=18.:font facename='System VIO' size=14x8.-commentchar:font facename=default size=0x0.:elink.
:hp1.<char>:ehp1. to select a different stylized comment marker&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
2&per.3&per.1 Annotations
:font facename=default size=0x0.
.br
.br
Annotations are stylized comments that follow a definite syntax&per. Although they
are comments, they may only be used in fixed grammatical contexts (e&per.g&per., like a
type qualifier)&per.
:p.
:p.
Syntactic comments for function interfaces are described in Section 4; comments for declaring constants
in :link reftype=hd res=11.Section 8&per.1&per.:elink. and comments for
declaring iterators in :link reftype=hd res=11.Section 8&per.4&per.:elink.
Sections 3-8 include descriptions of annotations for expressing
assumptions about variables, parameters, return values, structure fields
and type definitions&per. A summary of annotations is found in Apppendix D&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
2&per.3&per.2 Control Comments
:font facename=default size=0x0.
.br
.br
Unlike annotations, control comments may appear between any two tokens in a C
program&per.:link reftype=hd res=5.[3]:elink. Syntactically, they are no
different from standard comments&per. Control comments are used to provide
source-level control of LCLint checking&per. They may be used to suppress spurious
messages, set flags, and control checking locally in other ways&per. A complete
description of control comments is found in :link reftype=hd res=20.Apppendix E:elink.&per.
:p.
:p.
Most flags (all except those characterized as "global" in :link reftype=hd res=18.Apppendix C:elink.) can be
set locally using control comments&per. A control comment can set flags locally to
override the command line settings&per. The original flag settings are restored
before processing the next file&per. The syntax for setting flags in control
comments is the same as that of the command line, except that flags may also be
preceded by = to restore their setting to the original command-line value&per. For
Traditionally, programming books wax mathematical when they arrive at the topic
of abstract data typesà Such books make it seem as if you'd never actually
use an abstract data type except as a sleep aid&per. :ehp3.
:p.
- Steve McConnell
:p.
Information hiding is a technique for handling complexity&per. By hiding
implementation details, programs can be understood and developed in distinct
modules and the effects of a change can be localized&per. One technique for
information hiding is data abstraction&per. An abstract type is used to represent
some natural program abstraction&per. It provides functions for manipulating
instances of the type&per. The module that implements these functions is called
the :hp1.implementation:ehp1. module&per. We call the functions that are part of the
implementation of an abstract type the :hp1.operations:ehp1. of the type&per. Other
modules that use the abstract type are called :hp1.clients:ehp1.&per.
:p.
:p.
Clients may use the type name and operations, but should not manipulate or rely
on the actual representation of the type&per. Only the implementation module may
manipulate the representation of an abstract type&per. This hides information,
since implementers and maintainers of client modules should not need to know
anything about how the abstract type is implemented&per. It provides modularity,
since the representation of an abstract type can be changed without having to
change any client code&per.
:p.
:p.
LCLint supports abstract types by detecting places where client code depends on
the concrete representation of an abstract type&per.
:p.
To declare an abstract type, the abstract annotation is added to a typedef&per.
For example (in :font facename='System VIO' size=14x8.mstring&per.h:font facename=default size=0x0.),
:cgraphic.
typedef /*@abstract@*/ char *mstring;
:ecgraphic.
declares :font facename='System VIO' size=14x8.mstring:font facename=default size=0x0. as an abstract type&per. It is implemented using a :font facename='System VIO' size=14x8.char *:font facename=default size=0x0., but
clients of the type should not depend on or need to be aware of this&per. If it
later becomes apparent that a better representation such as a string table
should be used, we should be able to change the implementation of mstring
without having to change or inspect any client code&per.
:p.
:p.
In a client module, abstract types are checked by name, not structure&per. LCLint
reports an error if an instance of mstring is passed as a char * (for instance,
as an argument to strlen), since the correctness of this call depends on the
representation of the abstract type&per. LCLint also reports errors if any C
operator except assignment (=) or sizeof is used on an abstract type&per. The
assignment operator is allowed since its semantics do not depend on the
representation of the type&per.:link reftype=hd res=5.[4]:elink.
The use of :font facename='System VIO' size=14x8.sizeof:font facename=default size=0x0. is also permitted, since this is the only way for clients
to allocate pointers to the abstract type&per. Type casting objects to or from
abstract types in a client module is an abstraction violation and will generate
a warning message&per.
:p.
:p.
Normally, LCLint will assume a type definition is not abstract unless the
:font facename='System VIO' size=14x8./*@abstract@*/:font facename=default size=0x0. qualifier is used&per. If instead you want all user-defined types
to be abstract types unless they are marked as concrete, the :link reftype=hd res=18.:font facename='System VIO' size=14x8.+impabstract:font facename=default size=0x0.:elink. flag
can be used&per. This adds an implicit abstract annotation to any typedef that is
not marked with :font facename='System VIO' size=14x8./*@concrete@*/:font facename=default size=0x0.&per.
:p.
:p.
Some examples of abstraction violations detected by LCLint are shown in
:link reftype=hd res=44.Figure 2:elink.&per.
:p.
.br
:font facename='Helv' size=20x12.
.br
3&per.1 Access
:font facename=default size=0x0.
.br
.br
Where code may manipulate the representation of an abstract type, we say the
code has :hp1.access:ehp1. to that type&per. If code has access to an abstract type,
the representation of the type and the abstract type are indistinguishable&per.
Usually, an abstract type is implemented by a single program module that is the
only code that has access to the type representation&per. Sometimes, more
complicated access control is desired if the implementation of an abstract type
is split across program files, or particular client code needs to access the
representation&per.
:p.
:p.
There are a several ways of selecting what code has access the representation
of an abstract type&colon.
:p.
:ul compact.
:li.Modules&per. An abstract type defined in :hp1.M:ehp1.&per.h is accessible in
:hp1.M:ehp1.&per.c&per. Controlled by the accessmodule flag&per. This means when accessmodule
is on, as it is by default, the module access rule is in effect&per. If
accessmodule is off (when :link reftype=hd res=18.:font facename='System VIO' size=14x8.-accessmodule:font facename=default size=0x0.:elink. is used), the module access rule is not
in effect and an abstract type defined in :hp1.M:ehp1.&per.h is not necessarily
accessible in :hp1.M:ehp1.&per.c
:p.
:li.File names&per. An abstract type named :hp1.type:ehp1. is accessible in files
named :hp1.type:ehp1.&per.:hp1.<extenstion>:ehp1.&per. For example, the representation
of mstring is be accessible in mstring&per.h and mstring&per.c&per. Controlled by the
:li.Function names&per. An abstract type named :hp1.type:ehp1. may be accessible in
a function named :hp1.type:ehp1._:hp1.name:ehp1. or :hp1.typeName:ehp1.&per. For example,
mstring_length and mstringLength would have access to the mstring abstract
type&per. Controlled by the naming convention (see Section 9)&per.
:p.
:li.Access control comments&per. The syntax /*@access :hp1.type:ehp1.,+@*/[6] allows the following code to access the
representation of :hp1.type:ehp1.&per. Similarly, /*@noaccess :hp1.type:ehp1.,+@*/
restricts access to the representation of :hp1.type:ehp1.&per. The type in a noaccess
comment must have been declared as an abstract type&per.
:eul.
.br
:font facename='Helv' size=20x12.
.br
3&per.2 Mutability
:font facename=default size=0x0.
.br
.br
We can view types as being :hp1.mutable:ehp1. or :hp1.immutable:ehp1.&per. A type is
mutable if the value of an instance of the type can be changed by passing it as
a parameter to a function call&per.:link reftype=hd res=5.[7]:elink. For example, the
primitive type :font facename='System VIO' size=14x8.int:font facename=default size=0x0. is immutable&per. If i is a local variable of type int and
no variables point to the location where i is stored, the value of i must be
the same before and after the call f(i)&per. Structure and union types are also
immutable, since they are copied when they are passed as arguments&per. On the
other hand, pointer types are mutable&per. If x is a local variable of type int *,
the value of *x (and hence, the value of the object x) can be changed by the
function call g(x)&per.
:p.
:p.
The mutability of a concrete type is determined by its type definition&per. For
abstract types, mutability does not depend on the type representation but on
what operations the type provides&per. If an abstract type has operations that may
change the value of instances of the type, the type is mutable&per. If not, it is
immutable&per. The value of an instance of an immutable type never changes&per. Since
object sharing is noticeable only for mutable types, they are checked
differently from immutable types&per.
:p.
The :font facename='System VIO' size=14x8./*@mutable@*/:font facename=default size=0x0. and :font facename='System VIO' size=14x8./*@immutable@*/:font facename=default size=0x0. annotations are used to declare an
abstract type as mutable or immutable&per. (If neither is used, the abstract type
:hp3.Two types have :hp1.compatible type:ehp1. if their types are the same&per.:ehp3.
.br
- ANSI C, 3&per.1&per.2&per.6&per.
.br
:p.
:hp3.Two types need not be identical to be compatible&per.:ehp3.
.br
- ANSI C, footnote to 3&per.1&per.2&per.6&per.
LCLint supports stricter checking of primitive C types&per. The char and enum
types can be checked as distinct types, and the different numeric types can be
type-checked strictly&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
3&per.4&per.1 Characters
:font facename=default size=0x0.
.br
.br
The primitive char type can be type-checked as a distinct type&per. If char is
used as a distinct type, common errors involving assigning ints to chars are
detected&per.
:p.
:p.
The :link reftype=hd res=18.:font facename='System VIO' size=14x8.+charint:font facename=default size=0x0.:elink. flag can be used for checking legacy programs where char and int
are used interchangeably&per. If charint is on, char types indistinguishable from
ints&per. To keep char and int as distinct types, but allow chars to be used to
index arrays, use :link reftype=hd res=18.:font facename='System VIO' size=14x8.+charindex:font facename=default size=0x0.:elink.&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
3&per.4&per.2 Enumerators
:font facename=default size=0x0.
.br
.br
Standard C treats user-declared enum types just like integers&per. An arbitrary
integral value may be assigned to an enum type, whether or not it was listed as
an enumerator member&per. LCLint checks each user-defined enum type as distinct
type&per. An error is reported if a value that is not an enumerator member is
assigned to the enum type, or if an enum type is used as an operand to an
arithmetic operator&per.
:p.
:p.
If the enumint flag is on, enum and int types may be used interchangeably&per.
Like charindex, if the enumindex flag is on, enum types may be used to index
arrays&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
3&per.4&per.3 Numeric Types
:font facename=default size=0x0.
.br
.br
LCLint reports where numeric types are used in dangerous or inconsistent ways&per.
With the strictest checking, LCLint will report an error anytime numeric types
do not match exactly&per. If the relaxquals flag is on, only those
inconsistencies which may corrupt values are reported&per. For example, if an int
is assigned to a variable of type long (or passed as a long formal parameter),
LCLint will not report an error if relaxquals is on since a long must have
at least enough bits to store an int without data loss&per. On the other hand, an
error would be reported if the long were assigned to an int, since the int type
may not have enough bits to store the long value&per.
:p.
:p.
Similarly, if a signed value is assigned to an unsigned, LCLint will report an
error since an unsigned type cannot represent all signed values correctly&per. If
the ignoresigns flag is on, checking is relaxed to ignore all sign qualifiers
in type comparisons (this is not recommended, since it will suppress reporting
of real bugs, but may be necessary for quickly checking certain legacy code)&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
3&per.4&per.4 Arbitrary Integral Types
:font facename=default size=0x0.
.br
.br
LCLint supports three different kinds of arbitrary integral types&colon.
Determining whether a function modifies a particular parameter or global is in
general an undecidable:link reftype=hd res=5.[9]:elink. problem&per. To enable useful
checking, certain simplifying assumptions are necessary&per. LCLint assumes an
object is modified when it appears on the left hand side of an assignment or it
is passed to a function as a parameter which may be modified by that function
(according to the called function's modifies clause)&per. Hence, LCLint will report
spurious modification errors for assignments that do not change the value
of an object or modifications that are always reversed before a procedure
returns&per. The :font facename='System VIO' size=14x8./*@-mods@*/:font facename=default size=0x0. and :font facename='System VIO' size=14x8./*@=mods@*/:font facename=default size=0x0. control comments can be used around
these modifications to suppress the message&per.
.br
:font facename='Helv' size=20x12.
.br
4&per.2 Global Variables
:font facename=default size=0x0.
.br
.br
Another aspect of a function's interface, is the global variables it uses&per. A
globals list in a function declaration lists external variables that may be
used in the function body&per. LCLint checks that global variables used in a
procedure match those listed in its globals list&per. A global is used in a
function if it appears in the body directly, or it is in the globals list of a
function called in the body&per. LCLint reports if a global that is used in a
procedure is not listed in its globals list, and if a listed global is not used
in the function implementation&per.
:p.
:link reftype=hd res=47.Figure 5:elink. shows an example function definition with a globals list and associated checking done by LCLint&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
4&per.2&per.1 Controlling Globals Checking
:font facename=default size=0x0.
.br
.br
Whether on not an error is reported for a use of a global variable in a given
function depends on the scope of the variable (file static or external), the
checking annotation used in the variable declaration or the implicit annotation
if no checking annotation is used, whether or not the function is declared with
a globals list, and flag settings&per.
:p.
:p.
A global or file static variable declaration may be preceded by an annotation
to indicate how the variable should be checked&per. In order of decreasing checks,
Undocumented use of the variable is reported in a function with a globals list,
but not in a function declared with no globals (unless :link reftype=hd res=18.:font facename='System VIO' size=14x8.globnoglobs:font facename=default size=0x0.:elink. is on)&per.
Undocumented uses of the variable are not reported, but undocumented
modifications are reported&per. (If :link reftype=hd res=18.:font facename='System VIO' size=14x8.modglobsnomods:font facename=default size=0x0.:elink. is on, errors are reported even
in functions declared with no modifies clause or globals list&per.)
:font facename=default size=0x0.&per. The :font facename='System VIO' size=14x8.codeimponly:font facename=default size=0x0. flag sets all of the implicit only flags&per.)
LCLint reports an error if a function returns a reference to storage reachable
from one of its parameters (if retalias is on) since this may introduce
unexpected aliases in the body of the calling function when the result is
assigned&per.
:p.
:p.
The returned annotation denotes a parameter that may be aliased by the return
value&per. LCLint checks the call assuming the result may be an alias to the
returned parameter&per. :link reftype=hd res=53.Figure 11:elink. shows an example use of a returned annotation&per.
.br
:font facename='Helv' size=20x12.
.br
6&per.2 Exposure
:font facename=default size=0x0.
.br
.br
LCLint detects places where the representation of an abstract type is exposed&per.
This occurs if a client has a pointer to storage that is part of the
representation of an instance of the abstract type&per. The client can then modify
or examine the storage this points to, and manipulate the value of the abstract
type instance without using its operations&per.
:p.
:hp2.:ehp2.There are three ways a representation may be exposed&colon.
:ol compact.
:li.Returning (or assigning to a global variable) an object that includes a
pointer to a mutable component of an abstract type representation&per. (Controlled
by :link reftype=hd res=18.:font facename='System VIO' size=14x8.retexpose:font facename=default size=0x0.:elink.)&per.
:li.Assigning a mutable component of an abstract object to storage reachable
from an actual parameter or a global variable that may be used after the call&per.
This means the client may manipulate the abstract object using the actual
parameter after the call&per. Note that if the corresponding formal parameter is
declared only, the caller may not use the actual parameter after the call so
the representation is not exposed&per. (Controlled by :link reftype=hd res=18.:font facename='System VIO' size=14x8.assignexpose:font facename=default size=0x0.:elink.)&per.
:li.Casting mutable storage to or from an abstract type&per. (Controlled by
:h2 res=10.LCLint User's Guide - 7&per. Value Constraints
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=32x20.
.br
7&per. Value Constraints
:font facename=default size=0x0.
.br
.br
LCLint can be used to constrain values of parameters, function results, global
variables, and derived storage such as structure fields&per. These constraints are
checked at :hp1.interface points:ehp1. -- where a function is called or returns&per.
:link reftype=hd res=10.Section 7&per.1:elink. describes how to constrain parameters, return values and structures
to detect use before definition errors&per. A similar approach is used for
restricting the use of possibly null pointers in Section 7&per.2&per. To do both well, and avoid spurious errors, information about when and if a function returns if
useful&per. Annotations for documenting execution control are described in
Like many static checkers, LCLint detects instances where the value of a
location is used before it is defined&per. This analysis is done at the procedural
level&per. If there is a path through the procedure that
:p.
uses a local variable before it is defined, a use before definition error is
reported&per. Use before definition checking is controlled by the :link reftype=hd res=18.:font facename='System VIO' size=14x8.usedef:font facename=default size=0x0.:elink. flag&per.
:p.
:p.
LCLint can do more checking than standard checkers though, because the
annotations can be used to describe what storage must be defined and what
storage may be undefined at interface points&per. Unannotated references are
expected to be completely defined at interface points&per. This means all storage
reachable from a global variable, parameter to a function, or function return
value is defined before and after a function call&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
7&per.1&per.1 Undefined Parameters
:font facename=default size=0x0.
.br
.br
Sometimes, function parameters or return values are expected to reference
undefined or partially defined storage&per. For example, a pointer parameter may
be intended only as an address to store a result, or a memory allocator may
return allocated but undefined storage&per. The :font facename='System VIO' size=14x8.out:font facename=default size=0x0. annotation denotes a pointer
to storage that may be undefined&per.
:p.
:p.
LCLint does not report an error when a pointer to allocated but undefined
storage is passed as an :font facename='System VIO' size=14x8.out:font facename=default size=0x0. parameter&per. Within the body of a function, LCLint
will assume an :font facename='System VIO' size=14x8.out:font facename=default size=0x0. parameter is allocated but not necessarily bound to a value,
so an error is reported if its value is used before it is defined&per.
:p.
:p.
LCLint reports an error if storage reachable by the caller after the call is
not defined when the function returns&per. This can be suppressed by :link reftype=hd res=18.:font facename='System VIO' size=14x8.-mustdefine:font facename=default size=0x0.:elink.&per.
When checking a call, an actual parameter corresponding to an :font facename='System VIO' size=14x8.out:font facename=default size=0x0. parameter is
assumed to be completely defined after the call returns&per.
:p.
:p.
When checking unannotated programs, many spurious use before definition errors
may be reported If :link reftype=hd res=18.:font facename='System VIO' size=14x8.impouts:font facename=default size=0x0.:elink. is on, no error is reported when an
incompletely-defined parameter is passed to a formal parameter with no
definition annotation, and the actual parameter is assumed to be defined after
the call&per. The :font facename='System VIO' size=14x8./*@in@*/:font facename=default size=0x0. annotation can be used to denote a parameter that must
be completely defined, even if impouts is on&per. If impouts is off, there is an
implicit in annotation on every parameter with no definition annotation&per.
:p.
:link reftype=hd res=55.Figure 13&per. Use before definition&per.:elink.
.br
:font facename='Tms Rmn' size=18x10.
.br
7&per.1&per.2 Relaxing Checking
:font facename=default size=0x0.
.br
.br
The reldef annotation relaxes definition checking for a particular declaration&per.
Storage declared with a reldef annotation is assumed to be defined when it is
used, but no error is reported if it is not defined before it is returned or
passed as a parameter&per.
:p.
:p.
It is up to the programmer to check reldef fields are used correctly&per. They
should be avoided in most cases, but may be useful for fields of structures
that may or may not be defined depending on other constraints&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
7&per.1&per.3 Partially Defined Structures
:font facename=default size=0x0.
.br
.br
The partial annotated can be used to relax checking of structure fields&per. A
structure with undefined fields may be passed as a partial parameter or
returned as a partial result&per. Inside a function body, no error is reported
when the field of a partial structure is used&per. After a call, all fields of a
structure that is passed as a partial parameter are assumed to be completely
defined&per.
:p.
.br
:font facename='Tms Rmn' size=18x10.
.br
7&per.1&per.4 Global Variables
:font facename=default size=0x0.
.br
.br
Special annotations can be used in the globals list of a function declaration
(:link reftype=hd res=7.Section 4&per.2:elink.) to describe the states of global variables before and after the
call&per.
:p.
:p.
If a global is preceded by undef, it is assumed to be undefined before the
call&per. Thus, no error is reported if the global is not defined when the function
is called, but an error is reported if the global is used in the function body
before it is defined&per.
:p.
:p.
The killed annotation denotes a global variable that may be undefined when the
call returns&per. For globals that contain dynamically allocated storage, a killed
global variable is similar to an only parameter (:link reftype=hd res=8.Section 5&per.2:elink.)&per. An error is
reported if it contains the only reference to storage that is not released
A common cause of program failures is when a null pointer is dereferenced&per.
LCLint detects these errors by distinguishing possibly NULL pointers at
interface boundaries&per.
:p.
:p.
The null annotation is used to indicate that a pointer value may be NULL&per. A
pointer declared with no null annotation, may not be NULL&per. If null checking is
turned on (controlled by null), LCLint will report an error when a possibly
null pointer is passed as a parameter, returned as a result, or assigned to an
external reference with no null qualifier&per.
:p.
:p.
If a pointer is declared with the null annotation, the code must check that it
is not NULL on all paths leading to the a dereference of the pointer (or the
pointer being returned or passed as a value with no null annotation)&per.
Dereferences of possibly null pointers may be protected by conditional
statements or assertions (to see how assert is declared see :link reftype=hd res=10.Section 7&per.3:elink.) that
check the pointer is not NULL&per.
:p.
:p.
Consider two implementations of firstChar in :link reftype=hd res=57.Figure 15:elink.&per. For firstChar1, LCLint
reports an error since the pointer that is dereferenced is declared with a null
annotation&per. For firstChar2, no error is reported since the true branch of the
s == NULL if statement returns, so the dereference of s is only reached if s is
not NULL&per.
:p.
.br
:font facename='Tms Rmn' size=18x10.
.br
7&per.2&per.1 Predicate Functions
:font facename=default size=0x0.
.br
.br
Another way to protect null dereference, is to declare a function using
falsenull or truenull and call the function in a conditional statement before
the null-annotated pointer is dereferenced&per. The falsenull and truenull
annotations may only be used on return values for functions that return a
boolean:link reftype=hd res=5.[19]:elink. result and whose first argument is
a possibly null pointer&per.
:p.
:p.
A function is annotated with :font facename='System VIO' size=14x8.truenull:font facename=default size=0x0. is assumed to return TRUE if its first
parameter is NULL and FALSE otherwise&per. For example, if isNull is declared as,
:cgraphic.
/*@truenull@*/ bool isNull (/*@null@*/ char *x);
:ecgraphic.
we could write firstChar2&colon.
:cgraphic.
char firstChar2 (/*@null@*/ char *s)
{
if (isNull (s)) return '\0';
return *s;
}
:ecgraphic.
No error is reported since the dereference of s is only reached if isNull(s) is
false, and since isNull is declared with the truenull annotation this means s
must not be null&per.
:p.
:p.
The :font facename='System VIO' size=14x8.falsenull:font facename=default size=0x0. annotation is not quite the opposite of truenull&per. If a function
declared with falsenull returns TRUE, it means its parameter is not NULL&per. If
it returns FALSE, the parameter may or may not be NULL&per.
:p.
:p.
For example, we could define isNonEmpty to return TRUE if its parameter is not
NULL and has least one character before the NUL terminator&colon.
References have the value :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. before (:font facename='System VIO' size=14x8.pre:font facename=default size=0x0.) or after
(:font facename='System VIO' size=14x8.post:font facename=default size=0x0.) the call&per. Note, this is not the same name or meaning as
the null annotation (which means the value may be :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0.&per.)
References do not have the value :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. before (:font facename='System VIO' size=14x8.pre:font facename=default size=0x0.) or
after (:font facename='System VIO' size=14x8.post:font facename=default size=0x0.) the call&per.
Some examples of special clauses are shown in Figure 17&per. The defines clause for
:font facename='System VIO' size=14x8.record_new:font facename=default size=0x0. indicates that the :font facename='System VIO' size=14x8.id:font facename=default size=0x0. field of the
structure pointed to by the result is defined, but the :font facename='System VIO' size=14x8.name:font facename=default size=0x0.
field is not&per. So, :font facename='System VIO' size=14x8.record_create:font facename=default size=0x0. needs to call
:font facename='System VIO' size=14x8.record_setName:font facename=default size=0x0. to define the :font facename='System VIO' size=14x8.name:font facename=default size=0x0. field&per. Similarly,
the releases clause for :font facename='System VIO' size=14x8.record_clearName:font facename=default size=0x0. indicates that no
storage is associated with the :font facename='System VIO' size=14x8.name:font facename=default size=0x0. field of its parameter
after the return, so no failure to deallocate storage message is
produced for the call to :font facename='System VIO' size=14x8.free:font facename=default size=0x0. in :font facename='System VIO' size=14x8.record_free:font facename=default size=0x0.&per.
Macros are commonly used in C programs to implement constants or to mimic
functions without the overhead of a function call&per. Macros that are used to
implement functions are a persistent source of bugs in C programs, since they
may not behave like the intended function when they are invoked with certain
parameters or used in certain syntactic contexts&per.
:p.
:p.
LCLint eliminates most of the potential problems by detecting macros with
dangerous implementations and dangerous macro invocations&per. Whether or not a
macro definition is checked or expanded normally depends on flag settings and
control comments (see :link reftype=hd res=11.Section 8&per.3:elink.)&per. Stylized macros can also be used to define
control structures for iterating through many values (see :link reftype=hd res=11.Section 8&per.4:elink.)&per.
.br
:font facename='Helv' size=20x12.
.br
8&per.1 Constant Macros
:font facename=default size=0x0.
.br
.br
Macros may be used to implement constants&per. To get type-checking for constant
macros, use the constant syntactic comment&colon.
:cgraphic.
/*@constant null char *mstring_undefined@*/
:ecgraphic.
Declared constants are not expanded and are checked according to the
declaration&per. A constant with a null annotation may be used as only storage&per.
.br
:font facename='Helv' size=20x12.
.br
8&per.2 Function-like Macros
:font facename=default size=0x0.
.br
.br
Using macros to imitate functions is notoriously dangerous&per. Consider this
broken macro for squaring a number&colon.
:p.
:cgraphic.
# define square(x) x * x
:ecgraphic.
This works fine for a simple invocation like square(i)&per. It behaves
unexpectedly, though, if it is invoked with a parameter that has a side
effect&per.
:p.
:p.
For example, :font facename='System VIO' size=14x8.square(i++):font facename=default size=0x0. expands to :font facename='System VIO' size=14x8.i++ * i++:font facename=default size=0x0.&per. Not
only does this give the incorrect result, it has undefined behavior
since the order in which the operands are evaluated is not defined&per. (See :link reftype=hd res=13.Section 10&per.1:elink. for more information
on how expressions exhibiting undefined evaluation order behavior are detected
by LCLint&per.) To correct the problem we either need to rewrite the macro so that
its parameter is evaluated exactly once, or prevent clients from invoking the
macro with a parameter that has a side-effect&per.
:p.
:p.
Another possible problem with macros is that they may produce unexpected
results because of operator precedence rules&per. The invocation, :font facename='System VIO' size=14x8.square(i+1):font facename=default size=0x0.
expands to :font facename='System VIO' size=14x8.i+1*i+1:font facename=default size=0x0., which evaluates to :font facename='System VIO' size=14x8.i+i+1:font facename=default size=0x0. instead
of the square of :font facename='System VIO' size=14x8.i+1:font facename=default size=0x0.&per. To
ensure the expected behavior, the macro parameter should be enclosed in
parentheses where it is used in the macro body&per.
:p.
:p.
Macros may also behave unexpectedly if they are not syntactically equivalent to
an expression&per. Consider the macro definition,
:cgraphic.
# define incCounts() ntotal++; ncurrent++;
:ecgraphic.
This works fine, unless it is used as a statement&per. For example,
:cgraphic.
if (x < 3) incCounts();
:ecgraphic.
increments ntotal if :font facename='System VIO' size=14x8.x < 3:font facename=default size=0x0. but always increments ncurrent&per.
:p.
:p.
One solution is to use the comma operator to define the macro&colon.
:cgraphic.
# define incCounts() (ntotal++, ncurrent++)
:ecgraphic.
More complicated macros can be written using a do à while construction&colon.
:p.
:cgraphic.
# define incCounts() \
do { ntotal++; ncurrent++; } while (FALSE)
:ecgraphic.
LCLint detects these pitfalls in macro definitions, and checks that a macro
behaves as much like a function as possible&per. A client should only be able to
tell that a function was implemented by a macro if it attempts to use the macro
as a pointer to a function&per.
:p.
:p.
These checks are done by LCLint on a macro definition corresponding to a
function&colon.
:p.
:ul compact.
:li.Each parameter to a macro (except those declared to be side-effect free,
see :link reftype=hd res=11.Section 8&per.2&per.1:elink.) must be used exactly once in all possible executions of the
macro, so side-effecting arguments behave as expected&per.[21] (Controlled by :link reftype=hd res=18.:font facename='System VIO' size=14x8.macroparams:font facename=default size=0x0.:elink.&per.)
:li.A parameter to a macro may not be used as the left hand side of an
assignment expression or as the operand of an increment or decrement operator
in the macro text, since this produces non-functional behavior&per. (Controlled by
:li.A macro definition must be syntactically equivalent to a statement when
it is invoked followed by a semicolon&per. (Controlled by :link reftype=hd res=18.:font facename='System VIO' size=14x8.macrostmt:font facename=default size=0x0.:elink.&per.)
:li.The type of the macro body must match the return type of the
corresponding function&per. If the macro is declared with type void, its body may
have any type but the macro value may not be used&per.
:li.All variables declared in the body of a macro definition must be in the
macro variable namespace, so they do not conflict with variables in the scope
where the macro is invoked (which may be used in the macro parameters)&per. By
default, the macro namespace is all names prefixed by m_&per. (See :link reftype=hd res=12.Section 9&per.2:elink. for
information on controlling namespaces&per.)
:eul.
At the call site, a macro is checked like any other function call&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
8&per.2&per.1 Side-Effect Free Parameters
:font facename=default size=0x0.
.br
.br
Suppose we really do want to implement square as a macro, but want do so in a
safe way&per. One way to do this is to require that it is never invoked with a
parameter that has a side-effect&per. LCLint will check that this constraint
holds, if the parameter is annotated to be :hp1.side-effect free:ehp1.&per. That is,
the expression corresponding to this parameter must not modify any state, so it
does not matter how many times it is evaluated&per. The sef annotation is used to
denote a parameter that may not have any side-effects&colon.
:cgraphic.
extern int square (/*@sef@*/ int x);
# define square(x) ((x) *(x))
:ecgraphic.
Now, LCLint will not report an error checking the definition of square even
though x is used more than once&per.
:p.
:p.
A message will be reported, however, if square is invoked with a parameter that
has a side-effect&per.
:p.
For the code fragment,
:cgraphic.
square (i++)
:ecgraphic.
LCLint produces the message&colon.
:cgraphic.
Parameter 1 to square is declared sef, but the argument may modify i&colon. i++
:ecgraphic.
It is also an error to pass a non-sef macro parameter as a sef macro parameter
in the body of a macro definition&per. For example,
:cgraphic.
extern int sumsquares (int x, int y);
# define sumsquares(x,y) (square(x) + square(y))
:ecgraphic.
Although x only appears once in the definition of sumsquares it will be
evaluated twice since square is expanded&per. LCLint reports an error when a
non-sef macro parameter is passed as a sef parameter&per.
:p.
:p.
A parameter may be passed as a sef parameter without an error being reported,
if LCLint can determine that evaluating the parameter has no side-effects&per. For
function calls, the modifies clause is used to determine if a side-effect is
possible&per.:link reftype=hd res=5.[22]:elink. To prevent many spurious
errors, if the called function has no modifies clause, LCLint will report an
error only if sefuncon is on&per. Justifiably paranoid programmers will insist on
setting sefuncon on, and will add modifies clauses to unconstrained functions
that are used in sef macro arguments&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
8&per.2&per.2 Polymorphism
:font facename=default size=0x0.
.br
.br
One problem with our new definition of square is that while the original macro
would work for parameters of any numeric type, LCLint will now report an error
is the new version is used with a non-integer parameter&per.
:p.
:p.
We can use the :font facename='System VIO' size=14x8./*@alt :font facename=default size=0x0.:hp3.type:ehp3.:font facename='System VIO' size=14x8.;,:font facename=default size=0x0.+:font facename='System VIO' size=14x8.@>:font facename=default size=0x0.
syntax to indicate that an alternate type may be used&per. For example,
:cgraphic.
extern int /*@alt float@*/ square (/*@sef@*/ int /*@alt float@*/ x);
# define square(x) ((x) *(x))
:ecgraphic.
declares square for both ints and floats&per.
:p.
Alternate types are also useful for declaring functions for which the return
value may be safely ignored (see :link reftype=hd res=13.Section 10&per.3&per.2:elink.)&per.
.br
:font facename='Helv' size=20x12.
.br
8&per.3 Controlling Macro Checking
:font facename=default size=0x0.
.br
.br
By default, LCLint expands macros normally and checks the resulting code after
macros have been expanded&per. Flags and control comments may be used to control
which macros are expanded and which are checked as functions or constants&per.
:p.
:p.
If the fcnmacros flag is on, LCLint assumes all macros defined with parameter
lists implement functions and checks them accordingly&per. Parameterized macros
are not expanded and are checked as functions with unknown result and parameter
types (or using the types in the prototype, if one is given)&per. The analogous
flag for macros that define constants is constmacros&per. If it is on, macros with
no parameter lists are assumed to be constants, and checked accordingly&per. The
allmacros flag sets both fcnmacros and constmacros&per. If the macrofcndecl flag
is set, a message reports parameterized macros with no corresponding function
prototype&per. If the macroconstdecl flag is set, a similar message reports macros
with no parameters with no corresponding constant declaration&per.
:p.
:p.
The macro checks described in the previous sections make sense only for macros
that are intended to replace functions or constants&per. When fcnmacros or
constmacros is on, more general macros need to be marked so they will not be
checked as functions or constants, and will be expanded normally&per. Macros which
are not meant to behave like functions should be preceded by the
:font facename='System VIO' size=14x8./*@notfunction@*/:font facename=default size=0x0. comment&per. For example,
:cgraphic.
/*@notfunction@*/
# define forever for(;;)
:ecgraphic.
Macros preceded by notfunction are expanded normally before regular checking is
done&per. If a macro that is not syntactically equivalent to a statement without a
semi-colon (e&per.g&per., a macro which enters a new scope) is not preceded by
notfunction, parse errors may result when fcnmacros or constmacros is on&per.
.br
:font facename='Helv' size=20x12.
.br
8&per.4 Iterators
:font facename=default size=0x0.
.br
.br
It is often useful to be able to execute the same code for many different
values&per. For example, we may want to sum all elements in an intSet that
represents a set of integers&per. If intSet is an abstract type, there is no easy
way of doing this in a client module without depending on the concrete
representation of the type&per. Instead, we could provide such a mechanism as part
of the type's implementation&per. We call a mechanism for looping through many
values an :hp1.iterator:ehp1.&per.
:p.
:p.
The C language provides no mechanism for creating user-defined iterators&per.
LCLint supports a stylized form of iterators declared using syntactic comments
and defined using macros&per.
:p.
:p.
Iterator declarations are similar to function declarations except instead of
returning a value, they assign values to their yield parameters in each
iteration&per. For example, we could add this iterator declaration to
The :link reftype=hd res=18.:font facename='System VIO' size=14x8.partial:font facename=default size=0x0.:elink. flag sets
flags for checking a partial system&per. Top-level unused declarations,
undefined declarations, and unnecessary external names are not reported
if :font facename='System VIO' size=14x8.partial:font facename=default size=0x0. is set&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
10&per.5&per.1 Unnecessary External Names
:font facename=default size=0x0.
.br
.br
LCLint can report variables and functions that are declared with global scope
(i&per.e&per., without using static), that are not used outside the file in which they
are defined&per. In a stand-alone system, these identifiers should usually be
declared using static to limit their scope&per. If the exportstatic flag is on,
LCLint will report declarations that could have file scope&per. It should only be
used when all relevant source files are listed on the LCLint command line;
otherwise, variables and functions may be incorrectly identified as only used
in the file scope since LCLint did not process the other file in which they are
used&per.
.br
:font facename='Tms Rmn' size=18x10.
.br
10&per.5&per.2 Declarations Missing from Headers
:font facename=default size=0x0.
.br
.br
A common practice in C programming styles, is that every function or variable
exported by :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.c:font facename=default size=0x0. is declared in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0.&per. If
the :link reftype=hd res=18.:font facename='System VIO' size=14x8.exportheader:font facename=default size=0x0.:elink. flag is on, LCLint will report exported declarations in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.c
:font facename=default size=0x0. that are not declared in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0.&per.
:p.
.br
:font facename='Helv' size=20x12.
.br
10&per.6 Compiler Limits
:font facename=default size=0x0.
.br
.br
The ANSI Standard includes limits on minimum numbers that a conforming compiler
must support&per. Whether of not a particular compiler exceeds these limits, it is
worth checking that a program does not exceed them so that it may be safely
compiled by other compilers&per. In addition, exceeding a limit may indicate a
problem in the code (e&per.g&per., it is too complex if the control nest depth limit is
exceeded) that should be fixed regardless of the compiler&per. The following
limits are checked by LCLint&per. For each limit, the maximum value may be set
from the command line (or locally using a stylized comment)&per. If the
:h2 res=16.LCLint User's Guide - Appendix A Availability
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=20x12.
.br
Appendix A Availability
:p.
:font facename=default size=0x0.
.br
.br
:hp2.:ehp2.The web home page for LCLint is :font facename='System VIO' size=14x8.http&colon.//larch-www&per.lcs&per.mit&per.edu&colon.8001/larch/lclint/index&per.html:font facename=default size=0x0.&per.
It includes this guide in postscript format, samples demonstrating LCLint, and links to related web sites&per.
:p.
:p.
LCLint can be downloaded from :font facename='System VIO' size=14x8.http&colon.//larch-www&per.lcs&per.mit&per.edu&colon.8001/larch/lclint/download&per.html:font facename=default size=0x0.
or obtained via anonymous ftp from :font facename='System VIO' size=14x8.ftp&colon.//larch&per.lcs&per.mit&per.edu/pub/Larch/lclint/:font facename=default size=0x0.
:p.
Several UNIX platforms are supported and source code is provided for other platforms&per.
:p.
LCLint can also be run remotely using a form at :link reftype=hd res=39.:font facename='System VIO' size=14x8.http&colon.//larch-www&per.lcs&per.mit&per.edu&colon.8001/larch/lclint/run&per.html:font facename=default size=0x0.:elink.
:h2 res=17.LCLint User's Guide - Appendix B Communication
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=20x12.
.br
Appendix B Communication
:font facename=default size=0x0.
.br
.br
:p.
:hp2.:ehp2.LCLint development is largely driven by suggestions and comments from
users&per. We are also very interested in hearing about your experiences using
LCLint in developing or maintaining programs, enforcing coding standards, or
teaching courses&per. For general information, suggestions, and questions on
LCLint send mail to :link reftype=hd res=40.:font facename='System VIO' size=14x8.lclint@larch&per.lcs&per.mit&per.edu:font facename=default size=0x0.:elink.&per.
:p.
:p.
To report a bug in LCLint send a message to :link reftype=hd res=41.:font facename='System VIO' size=14x8.lclint-bug@larch&per.lcs&per.mit&per.edu:font facename=default size=0x0.:elink.&per.
:p.
:p.
There are two mailing lists associated with LCLint&colon.
Informal discussions on the use and development of LCLint&per. To subscribe, send
a (human-readable) message to :font facename='System VIO' size=14x8.lclint-request@larch&per.lcs&per.mit&per.edu:font facename=default size=0x0.,
or use a form&per.
:p.
:p.
LCLint discussions relating to checks enabled by specifications or annotations
are welcome in the :link reftype=hd res=43.:font facename='System VIO' size=14x8.comp&per.specification&per.larch:font facename=default size=0x0.:elink.
usenet group&per. Messages more focused on C-specific checking would be more
appropriate for the lclint-interest list of one of the C language groups&per.
:hp2.:ehp2.Global flags can be set at the command line or in an options file, but
cannot be set locally using stylized comments&per. These flags control on-line
help, initialization files, pre-processor flags, libraries and output&per.
:p.
:hp2.:hp1.Help:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.On-line help provides documentation on LCLint operation and
flags&per. When a help flag is used, no checking is done by LCLint&per. Help flags
may be preceded by :font facename='System VIO' size=14x8.-:font facename=default size=0x0. or :font facename='System VIO' size=14x8.+:font facename=default size=0x0.&per.
Load options file :hp1.<file>:ehp1.&per. If this flag is used from the command
line, the default :font facename='System VIO' size=14x8.~/&per.lclintrc:font facename=default size=0x0. file is not loaded&per. This flag may be used in an
Load state from :hp1.<file>:ehp1. (created by :font facename='System VIO' size=14x8.-dump:font facename=default size=0x0.)&per. The default extension
:font facename='System VIO' size=14x8.&per.lcd:font facename=default size=0x0. is added if :hp1.<file>:ehp1. has no extension&per. Only one library file
may be loaded&per.
:p.
By default, the standard library is loaded if the -load flag is not used to
load a user library&per. If no user library is loaded, one of the following flags
may be used to select a different standard library&per. Precede the flag by + to
load the described library (or prevent a library from being loaded using
nolib)&per. See :link reftype=hd res=21.Apppendix F:elink. for information on the
Show all possible alternate types (see Section 8&per.2&per.2)&per. Default&colon. :font facename='System VIO' size=14x8.-:font facename=default size=0x0.
An abstract type defined in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0. (or specified in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0.) is
accessible in :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.c:font facename=default size=0x0.&per.
Allow :font facename='System VIO' size=14x8.void *:font facename=default size=0x0. to match pointers to abstract types&per. (Casting a pointer to an
abstract type to a pointer to :font facename='System VIO' size=14x8.void:font facename=default size=0x0. is okay if :link reftype=hd res=18.:font facename='System VIO' size=14x8.+voidabstract:font facename=default size=0x0.:elink. is set&per.)
Allow :font facename='System VIO' size=14x8.long:font facename=default size=0x0. type to match an arbitrary integral type (e&per.g&per., :font facename='System VIO' size=14x8.size_t:font facename=default size=0x0.)&per.
:hp2.:hp1.:ehp1.:ehp2.These flags control expansion and checking of macro definitions
and invocations&per.
:p.
:hp2.Macro Expansion:ehp2.
:p.
:hp2.:ehp2.These flags control which macros are checked as functions or constants,
and which are expanded in the pre-processing phase&per. Macros preceded by
:font facename='System VIO' size=14x8./*@notfunction@*/:font facename=default size=0x0. are never expanded regardless of these flag settings&per. These
flags may be used in source-file control comments&per.
Macro definition is not syntactically equivalent to function&per. This means if
the macro is used as a statement (e&per.g&per., :font facename='System VIO' size=14x8.if (test) macro();:font facename=default size=0x0.) unexpected behavior
may result&per. One fix is to surround the macro body with :font facename='System VIO' size=14x8.do { &per.&per.&per.; } while
An actual parameter involving a call to an unconstrained function (declared
without modifies clause) that may modify anything is passed as a :font facename='System VIO' size=14x8.sef:font facename=default size=0x0. parameter&per.
Set whether case is significant an internal names (-internalnamecaseinsensitive
means case is significant)&per. If :link reftype=hd res=18.:font facename='System VIO' size=14x8.+distinctinternalnames:font facename=default size=0x0.:elink. is not set, sets
:link reftype=hd res=18.:font facename='System VIO' size=14x8.+distinct-internal-names:font facename=default size=0x0.:elink. with unlimited internal name length&per.
There is a break inside a while, for or iterator loop that is inside a while,
for or iterator loop&per. Mark with :font facename='System VIO' size=14x8./*@innerbreak@*/:font facename=default size=0x0. to suppress the message&per.
Actual number of errors does not match number in :font facename='System VIO' size=14x8./*@i:font facename=default size=0x0.:hp1.<n>:ehp1.:font facename='System VIO' size=14x8.@*/:font facename=default size=0x0.
:h2 res=19.LCLint User's Guide - Appendix D Annotations
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=20x12.
.br
Appendix D Annotations:font facename=default size=0x0.
.br
.br
:p.
The
grammar below is the C syntax from [:link reftype=hd res=25.K&.R:elink.,A13] modified to show
the syntax of syntactic comments&per. Only productions effected by LCLint
annotations are shown&per. In the annotations, the :font facename='System VIO' size=14x8.@:font facename=default size=0x0. represents the comment marker
char, set by :font facename='System VIO' size=14x8.-commentchar:font facename=default size=0x0. (default is :font facename='System VIO' size=14x8.@:font facename=default size=0x0.)&per.
No errors will be reported from an /*@i:hp1.<n>:ehp1.@*/ (e&per.g&per.,
:font facename='System VIO' size=14x8./*@i3@*/:font facename=default size=0x0.) comment to the end of the line&per. If there are not
exactly :hp1.n :ehp1.errors suppressed from the comment point to the end of
the line, LCLint will report an error&per. This is more robust than i or
ignore since a message is generated if the expected number errors is not
present&per. Since errors are not necessarily detected until after this
file is processed (for example, and unused variable error), suppress
count errors are reported after all files have been processed&per. The :font facename='System VIO' size=14x8.-supcounts:font facename=default size=0x0. flag may be
used to suppress these errors&per. This is useful when a system if being
Like :font facename='System VIO' size=14x8.i:font facename=default size=0x0. and :font facename='System VIO' size=14x8.i:font facename=default size=0x0.:hp1.<n>:ehp1., except controlled by
:font facename='System VIO' size=14x8.+tmpcomments:font facename=default size=0x0. flag&per. These can be used to temporarily suppress
certain errors&per. Then, :font facename='System VIO' size=14x8.-tmpcomments:font facename=default size=0x0. can be set to find them
again&per.
:p.
:hp2.:hp1.Type Access:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.Control comments may also be used to override type access
settings&per. The syntax :font facename='System VIO' size=14x8./*@access :font facename=default size=0x0.:hp1.<type>:ehp1.,+:font facename='System VIO' size=14x8.@*/:font facename=default size=0x0. allows the following code to
access the representation of :hp1.<type>:ehp1.&per. Similarly,
to the representation of :hp1.<type>:ehp1.&per. The type in a noaccess
comment must have been declared as an abstract type&per. Type access
applies from the point of the comment to the end of the file or the next
access control comment for this type&per.
:p.
:hp2.:hp1.Macro Expansion:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.The :font facename='System VIO' size=14x8./*@notfunction@*/:font facename=default size=0x0.indicates that the next macro definition is
not intended to be a function, and should be expanded in line instead of
checked as a macro function definition&per.
:p.
:hp2.:hp1.Traditional Lint Comments:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.Some of the control comments supported by most standard UNIX
lints are supported by LCLint so legacy systems can be checked more easily&per.
These comments are not lexically consistent with LCLint comments, and their
meanings are less precise (and may vary between different lint programs), so we
recommend that LCLint comments are used instead except for checking legacy
systems already containing standard lint comments&per.
:p.
:p.
These standard lint comments supported by LCLint&colon.
Prevents errors for fall-through cases&per. Same meaning as :font facename='System VIO' size=14x8./*@fallthrough@*/:font facename=default size=0x0.&per.
:h2 res=21.LCLint User's Guide - Appendix F Libraries
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=20x12.
.br
Appendix F Libraries:font facename=default size=0x0.
.br
.br
:p.
:hp2.:ehp2.Libraries can be used to record interface information&per. A library
containing information about the Standard C Library is used to enable checking
of library calls&per. Program libraries can be created to enable fast checking of
single modules in a large program&per.
:p.
:hp2.:hp1.Standard Libraries:ehp1.:ehp2.
:p.
In order to check calls to library functions, LCLint uses an
annotated standard library&per. This contains more information about function
interfaces then is available in the system header files since it uses
annotations&per. Further, it contains only those functions documented in the ANSI
Standard&per. Many systems include extra functions in their system libraries;
programs that use these functions cannot be compiled on other systems that do
not provide them&per. Certain types defined by the library are treated as abstract
types (e&per.g&per., a program should not rely on how the FILE type is implemented)&per.
When checking source code, LCLint does include system headers according to
include directive in the source code, but instead uses the library description
of the standard library&per.
:p.
:p.
The LCLint distribution includes several different standard libraries&colon.
the ANSI standard library, the POSIX standard library , and an ad hoc
UNIX library&per. Each library comes in two versions&colon. the standard version
and the strict version&per.
:p.
:hp2.ANSI Library:ehp2.
:p.
The default behavior of LCLint is to use the ANSI standard library
(loaded from :font facename='System VIO' size=14x8.ansi&per.lcd:font facename=default size=0x0.)&per. This library is based on the standard library
described in the ANSI C Standard&per. It includes functions and types added
by Amendment 1 to the ANSI C Standard&per.
:p.
:hp2.POSIX Library:ehp2.
:p.
The POSIX library is selected by the :font facename='System VIO' size=14x8.+posixlib:font facename=default size=0x0. flag&per. The POSIX library
is based on the IEEE Std 1003&per.1-1990&per.
:p.
:hp2.UNIX Library:ehp2.
:p.
The UNIX library is selected by the :font facename='System VIO' size=14x8.+unixlib:font facename=default size=0x0. flag&per. This
library is an ad hoc attempt to capture additional functionality
provided by many UNIX platforms&per. Unfortunately, UNIX systems vary widely
and very few are consistent with the ANSI Standard&per.
:p.
The differences between the UNIX library and the POSIX library are&colon.
:ul compact.
:li.In the UNIX library, :font facename='System VIO' size=14x8.free:font facename=default size=0x0. is declared with a non-null
parameter&per. ANSI C specifies that :font facename='System VIO' size=14x8.free:font facename=default size=0x0. should handle the
argument :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0., but several UNIX platforms crash if :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. is
passed to :font facename='System VIO' size=14x8.free:font facename=default size=0x0.&per.
:li.Extra variables, constants and functions are included in the UNIX
library&per. Some declarations are not part of the POSIX library, but are
believed to be available on many UNIX systems&per. See :font facename='System VIO' size=14x8.lib/unix&per.h:font facename=default size=0x0.
for a list of the UNIX-only declarations&per.
:eul.
:p.
Code checked using the UNIX library can probably be ported to some UNIX
systems without difficulty&per. To enhance the likelihood that a program is
portable, the POSIX library should be used instead&per.
:p.
:hp2.Strict Libraries:ehp2.
:p.
Stricter versions of the libraries are used if the
:font facename='System VIO' size=14x8.unix-strct-lib:font facename=default size=0x0. flag is used&per. These libraries use a stricter
interpretation of the library&per. They will detect more errors in some programs, but may to produce many spurious errors for typical code&per.
:p.
The differences between the standard libraries and the strict libraries
are&colon.
:ul compact.
:li.The standard libraries declare the printing functions
(:font facename='System VIO' size=14x8.fprintf:font facename=default size=0x0., :font facename='System VIO' size=14x8.printf:font facename=default size=0x0., and :font facename='System VIO' size=14x8.sprintf:font facename=default size=0x0.) that may
return error codes to return :font facename='System VIO' size=14x8.int:font facename=default size=0x0. or :font facename='System VIO' size=14x8.void:font facename=default size=0x0.&per. This prevents typical
programs from leading to deluge of ignored return value errors, but may
mean some relevant errors are not detected&per. In the strict libraries, they
are declared to return :font facename='System VIO' size=14x8.int:font facename=default size=0x0., so ignored return value errors will
be reported (depending on other flag settings)&per. Programs should check
that this return value is non-negative&per.
:li.
The standard libraries declare some parameters and return values to be
alternate types (:font facename='System VIO' size=14x8.int:font facename=default size=0x0. or :font facename='System VIO' size=14x8.bool:font facename=default size=0x0., or :font facename='System VIO' size=14x8.int:font facename=default size=0x0. or
:font facename='System VIO' size=14x8.char:font facename=default size=0x0.)&per. The ANSI standard specifies these types as int to be
compatible with older versions of the library, but logically they make
more sense as :font facename='System VIO' size=14x8.bool:font facename=default size=0x0. or :font facename='System VIO' size=14x8.char:font facename=default size=0x0.&per. In the strict libraries,
the stronger type is used&per. The parameter to :font facename='System VIO' size=14x8.assert:font facename=default size=0x0. is
:font facename='System VIO' size=14x8.int:font facename=default size=0x0. or :font facename='System VIO' size=14x8.bool:font facename=default size=0x0. in the standard library, and :font facename='System VIO' size=14x8.bool:font facename=default size=0x0.
in the strict library&per. The parameter to the character functions
isspace, isupper, isxdigit, tolower and toupper is char or int in the
standard library and char in the strict library&per. The type of the return
value of the character classification functions (all of the previous
character functions except tolower and toupper) is bool or int in the
standard library and bool in the strict library&per. The type of the first
parameter to ungetc is char or int in the standard library and char in
the strict library (EOF should not be passed to ungetc)&per. The second
parameter to strchr and strrchr is char or int in the standard library
and char in the strict library&per.
:li.The global variables stdin, stdout and stderr are declared as
unchecked variables (see :link reftype=hd res=7.Section
4&per.2&per.1:elink.) in the standard libraries&per. In the strict libraries, they are checked&per. The global variable errno is declared unchecked in the standard
libraries, but declared checkedstrict in the strict libraries&per.
:eul.
:p.
:hp2.Generating the Standard Libraries:ehp2.
:p.
The standard libraries are generated from header files included in the
LCLint distribution&per. Some libraries are generated from more than one
header file&per. Since the POSIX library includes the ANSI library, the
headers for the ANSI and POSIX libraries are combined to produce the
POSIX library&per. Similarly, the UNIX library is composed of the ANSI,
POSIX and UNIX headers&per. The header files include some sections that are
conditionally selected by defining :font facename='System VIO' size=14x8.STRICT:font facename=default size=0x0.&per.
:p.
The commands to generate the standard libraries are&colon.
:hp2.:hp1.:ehp1.:ehp2.To enable running LCLint on large systems, mechanisms are
provided for creating libraries containing necessary information&per. This means
source files can be checked independently, after a library has been created&per.
The command line option -dump :hp1.library:ehp1. stores information in the file
:hp1.library:ehp1. (the default extension, :font facename='System VIO' size=14x8.&per.lcd:font facename=default size=0x0.:link reftype=hd res=5.[27]:elink., is
added)&per. Then, :font facename='System VIO' size=14x8.-load :font facename=default size=0x0.:hp1.library:ehp1. loads the library&per. The library
contains interface information from the files checked when the library was
created&per.
:p.
:hp2.:hp1.
Header File Inclusion
:ehp1.:ehp2.
:p.
The standard behavior of LCLint on encountering
:cgraphic.
#include <X&per.h>
:ecgraphic.
is to search for a file named :font facename='System VIO' size=14x8.X&per.h:font facename=default size=0x0. on the include search path
(set using :font facename='System VIO' size=14x8.-I:font facename=default size=0x0.) and then the system base include path (usually
:font facename='System VIO' size=14x8./usr/include:font facename=default size=0x0., default is set when LCLint is compiled)&per. If :font facename='System VIO' size=14x8.X&per.h:font facename=default size=0x0. is the name of a header file in a loaded
standard library (either
ANSI or POSIX) and :font facename='System VIO' size=14x8.X&per.h:font facename=default size=0x0. is found in a directory that is a system
directory (as set by the :font facename='System VIO' size=14x8.-sysdirs:font facename=default size=0x0. flag; the default is :font facename='System VIO' size=14x8./usr/include:font facename=default size=0x0.),
:font facename='System VIO' size=14x8.X&per.h:font facename=default size=0x0. will not be included if :font facename='System VIO' size=14x8.skip-ansi-headers:font facename=default size=0x0. or
:font facename='System VIO' size=14x8.skip-posix-headers:font facename=default size=0x0. (depending on whether :font facename='System VIO' size=14x8.X&per.h:font facename=default size=0x0. is an
ANSI or POSIX header file) is on (both are on by default)&per. To force all
headers to be included normally, use :font facename='System VIO' size=14x8.-skip-ansi-headers:font facename=default size=0x0. and
Sometimes headers in system directories contain non-standard syntax
which LCLint is unable to parse&per. The :font facename='System VIO' size=14x8.+skip-sys-headers:font facename=default size=0x0. flag
may be used to prevent any include file in a system directory from being
included&per.
:p.
LCLint is fast enough that it can be run on medium-size (10,000
line) programs without performance concerns&per. It takes about one second to
process a thousand source lines on a DEC Alpha&per. Libraries can be used to
enable efficient checking of small modules in large programs&per. To further
improve performance, header file inclusion can be optimized&per.
:p.
:p.
When processing a complete system in which many files include the same headers,
a large fraction of processing time is wasted re-reading header files
unnecessarily&per. If you are checking a 100-file program, and every file includes
:font facename='System VIO' size=14x8.utils&per.h:font facename=default size=0x0., LCLint will have to process utils&per.h 100 times (as would most C
compilers)&per. If the :link reftype=hd res=18.:font facename='System VIO' size=14x8.+singleinclude:font facename=default size=0x0.:elink. flag is used, each header file is processed
only once&per. Single header file processing produces a significant efficiency
improvement when checking large programs split into many files, but is only
safe if the same header file included in different contexts always has the same
meaning (i&per.e&per., it does not depend on preprocessor variable defined differently
at different inclusion sites)&per.
:p.
:p.
When processing a single file in a large system, a large fraction of the time
is spent processing included header files&per. This can be avoided if the
information in the header files is stored in a library instead&per. If
:link reftype=hd res=18.:font facename='System VIO' size=14x8.+neverinclude:font facename=default size=0x0.:elink. is set, inclusion of files ending in &per.h is prevented&per. Files with
different suffixes are included normally&per. To do this the header files must not
include any expanded macros&per. That is, the header file must be processed with
:link reftype=hd res=18.:font facename='System VIO' size=14x8.+allmacros:font facename=default size=0x0.:elink., and there must be no :font facename='System VIO' size=14x8./*@notfunction@*/:font facename=default size=0x0. control comments in the
header&per. Then, the :link reftype=hd res=18.:font facename='System VIO' size=14x8.+neverinclude:font facename=default size=0x0.:elink. flag may be used to prevent inclusion of header
files&per. Alternately, non-function macros can be moved to a different file with
a name that does not end in :font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0.&per. Remember, that this file must be included
directly from the :font facename='System VIO' size=14x8.&per.c:font facename=default size=0x0. file, since if it is included from a :font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0. file indirectly,
that :font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0. file is ignored so the other file is never included&per.
:p.
:p.
These options can be used for significant performance improvements on large
systems&per. The performance depends on how the code is structured, but checking a
single module in a large program is several times faster if libraries and
:link reftype=hd res=18.:font facename='System VIO' size=14x8.+neverinclude:font facename=default size=0x0.:elink. are used&per.
:h2 res=22.LCLint User's Guide - Appendix G Specifications
:font facename=default size=0x0.
:p.
.br
:font facename='Helv' size=20x12.
.br
Appendix G Specifications:font facename=default size=0x0.
.br
.br
:p.
:hp2.:ehp2.Another way of providing more information about programs is to use
formal specifications&per. Although this document has largely ignored
specifications, LCLint was originally designed to use the information in LCL
specifications instead of source-code annotations&per. This document focuses on
annotations since it takes less effort to add annotations to source code than
to maintain an additional specification file&per. Annotations can express
everything that can be expressed in LCL specifications that is relevant to
LCLint checking&per. However, LCL specifications can provide more precise
documentation on program interfaces than is possible with LCLint annotations&per.
This
appendix (extracted from [:link reftype=hd res=25.Evans94:elink.]) is a very brief introduction to LCL
Specifications&per.
For more information, consult [:link reftype=hd res=25.GH93:elink.]&per.
:p.
:p.
The Larch family of languages is a two-tiered approach to formal specification&per.
A specification is built using two languages -- the :hp1.Larch Shared
Language:ehp1. (LSL), which is independent of the implementation language, and a
:hp1.Larch Interface Language:ehp1. designed for the specific implementation
language&per. An LSL specification defines :hp1.sorts:ehp1., analogous to abstract
types in a programming language, and :hp1.operators:ehp1., analogous to procedures&per.
It expresses the underlying semantics of an abstraction&per.
:p.
:p.
The interface language specifies an interface to an abstraction in a particular
programming language&per. It captures the details of the interface needed by a
client using the abstraction and places constraints on both correct
implementations and uses of the module&per. The semantics of the interface are
described using primitives and sorts and operators defined in LSL
specifications&per. Interface languages have been designed for several
programming languages&per.
:p.
:p.
LCL
[GH93,
Tan94] is a Larch interface language for Standard C&per. LCL uses a
C-like syntax&per. Traditionally, a C module :hp1.M:ehp1. consists of a source file,
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.c:font facename=default size=0x0., and a header file, :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0.&per. The header
file contains prototype declarations for functions, variables and constants exported
by :hp1.M:ehp1., as well as those macro definitions that implement exported
functions or constants, and definitions of exported types&per. When using LCL, a
module includes two additional files - :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0., a formal specification of
:hp1.M:ehp1., and :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lh:font facename=default size=0x0., which is derived by LCLint (if the
:link reftype=hd res=22.:font facename='System VIO' size=14x8.lh:font facename=default size=0x0.:elink. flag is on) from
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0.&per. Clients use :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0. for documentation, and should
not need to look at any implementation file&per. The derived file,
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lh:font facename=default size=0x0., contains include directives (if :hp1.M:ehp1. depends on other specified modules), prototypes of functions and declarations of variables as specified in
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0.&per. The file :hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0. should include
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.lh:font facename=default size=0x0. and retain the implementation aspects of the old
:hp1.M:ehp1.:font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0., but is no longer used for client documentation&per.
:p.
:p.
The LCLint release package includes a grammar for LCL and examples of LCL
specifications&per.
:p.
:hp2.:hp1.Specification Flags:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.These flags are relevant only when LCLint is used with LCL
Generate :font facename='System VIO' size=14x8.&per.lcs:font facename=default size=0x0. files containing symbolic state of :font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0. files (used for imports)&per.
By default :font facename='System VIO' size=14x8.&per.lcs:font facename=default size=0x0. files are generated for each :font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0. file
processed&per. Use :font facename='System VIO' size=14x8.-lcs:font facename=default size=0x0. to
prevent generation of :font facename='System VIO' size=14x8.&per.lcs:font facename=default size=0x0. files&per.
Generate :font facename='System VIO' size=14x8.&per.lh:font facename=default size=0x0. files&per. By default, :font facename='System VIO' size=14x8.-lh:font facename=default size=0x0. is set and no
:font facename='System VIO' size=14x8.&per.lh:font facename=default size=0x0. files are generated&per. Use :link reftype=hd res=22.:font facename='System VIO' size=14x8.+lh:font facename=default size=0x0.:elink. to enable &per.lh file generation&per.
Set LCL initialization file to :hp1.<file>:ehp1.&per. The LCL initialization
file is read if any :font facename='System VIO' size=14x8.&per.lcl:font facename=default size=0x0. files are listed on the command line&per. The default
file is :font facename='System VIO' size=14x8.lclinit&per.lci:font facename=default size=0x0., found on the :font facename='System VIO' size=14x8.LARCH_PATH:font facename=default size=0x0.&per.
:hp2.:ehp2.LCLint can be used most productively with the emacs text editor&per. The
release package includes emacs files for running LCLint and editing code with
annotations&per.
:p.
:hp2.:hp1.Running LCLint:ehp1.:ehp2.
:p.
:hp2.:hp1.:ehp1.:ehp2.LCLint release includes :font facename='System VIO' size=14x8.emacs/lclint&per.elc:font facename=default size=0x0. that defines an emacs
command, :font facename='System VIO' size=14x8.M-x lclint:font facename=default size=0x0., for running LCLint&per. To load this file, add this line to
your :font facename='System VIO' size=14x8.&per.emacs:font facename=default size=0x0. file&colon.
The :font facename='System VIO' size=14x8.M-x lclint:font facename=default size=0x0. command is similar to :font facename='System VIO' size=14x8.M-x compile:font facename=default size=0x0.,
except it jumps to the exact column location of the error message,
instead of the beginning of the line&per. After typing :font facename='System VIO' size=14x8.M-x lclint:font facename=default size=0x0.,
you will be prompted for a compile command&per. Enter the command
identically to the command that would be used to run LCLint from the
command line&per. If errors are found, :font facename='System VIO' size=14x8.M-x next-lclint-error:font facename=default size=0x0. jumps
to the point where the next error was found&per. (Note, this only works if
:link reftype=hd res=18.:font facename='System VIO' size=14x8.+showcolumn:font facename=default size=0x0.:elink. is set to
make LCLint include column numbers in error messages&per.)
:p.
:p.
The command can be bound to a key to enable rapid jumping through the error
messages&per. For example, to set the key do :font facename='System VIO' size=14x8.CTRL:font facename=default size=0x0.-backslash add
this line to your :font facename='System VIO' size=14x8.&per.emacs:font facename=default size=0x0. file&colon.
for LCLint syntactic comments and annotations&per. If it is loaded, the comment
surrounding an LCLint annotation will be added automatically&per. For example,
typing ":font facename='System VIO' size=14x8.only:font facename=default size=0x0." and a space, will produce ":font facename='System VIO' size=14x8./*@only@*/:font facename=default size=0x0. "&per.
Abbreviations are provided for each LCLint syntactic comment&per. The
abbreviation of :font facename='System VIO' size=14x8./*@null@*/:font facename=default size=0x0. is :font facename='System VIO' size=14x8.nll:font facename=default size=0x0. (not null), since
it is often necessary to type NULL&per.
:p.
Abbreviations are loaded and used when a :font facename='System VIO' size=14x8.&per.c:font facename=default size=0x0. or :font facename='System VIO' size=14x8.&per.h:font facename=default size=0x0. file is edited by adding
3 Unlike regular C comments, control comments should not be used within a
single token&per. They may introduce new separators in the code during parsing&per.
:p.
4 For abstract types whose instances can change value, a client does need to
know if assignment has copy or sharing semantics (see Section 3&per.2)&per.
:p.
5 :hp3.Does not apply to HTML version&per.:ehp3.
:hp1.italics:ehp1.&per.
:p.
6 The meta-notation, item,+ is used to denote a comma separated list of items&per.
For example, :font facename='System VIO' size=14x8./*@access mstring, intSet@*/:font facename=default size=0x0. provides access to
the representations of both :font facename='System VIO' size=14x8.mstring:font facename=default size=0x0. and :font facename='System VIO' size=14x8.intSet:font facename=default size=0x0.&per.)
:p.
7 Through the parameter&per. Modifications using some other variable that has a
pointer to the location of this parameter are not considered&per.
:p.
8 The flag :link reftype=hd res=18.:font facename='System VIO' size=14x8.-booltype:font facename=default size=0x0.:elink.
can be used to select a different name for the boolean type&per. To change
the names of :font facename='System VIO' size=14x8.TRUE:font facename=default size=0x0. and :font facename='System VIO' size=14x8.FALSE:font facename=default size=0x0., use :font facename='System VIO' size=14x8.-booltrue:font facename=default size=0x0.
and :link reftype=hd res=18.:font facename='System VIO' size=14x8.-boolfalse:font facename=default size=0x0.:elink.&per. The
LCLint distribution includes an implementation of :font facename='System VIO' size=14x8.bool:font facename=default size=0x0., in :font facename='System VIO' size=14x8.lib/bool&per.h:font facename=default size=0x0.&per.
However, it isn't necessary to use this implementation to get the
benefits of boolean checking&per.
:p.
9 This means that theoreticians can prove that no algorithm exists that solves
the problem correctly for all possible programs&per.
:p.
10 This section is largely based on [Evans96]&per. It semi-formally defines
some of the terms needed to describe memory management checking; if you are satisfied with an intuitive understanding of these terms, this section may be
skipped&per.
:p.
11 This is similar to the LISP storage model, except that objects are typed&per.
:p.
12 Except :font facename='System VIO' size=14x8.sizeof:font facename=default size=0x0., which does not need the value of its argument&per.
:p.
13 If the storage is not assigned to a reference, an internal reference
is created to track the storage&per.
:p.
14 The full declaration of :font facename='System VIO' size=14x8.malloc:font facename=default size=0x0. also includes a :font facename='System VIO' size=14x8.null:font facename=default size=0x0.
annotation (:link reftype=hd res=10.Section 7&per.2:elink.) to
indicate that the result may be :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. (as it is when the requested storage
cannot be allocated) and an :font facename='System VIO' size=14x8.out:font facename=default size=0x0. annotation (Section 7&per.1) to indicate that the result
points to undefined storage&per.
:p.
15 The full declaration of :font facename='System VIO' size=14x8.free:font facename=default size=0x0. also has :font facename='System VIO' size=14x8.out:font facename=default size=0x0. and
:font facename='System VIO' size=14x8.null:font facename=default size=0x0. annotations on the parameter to indicate that the argument
may be :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. and need not point to defined storage&per. According
to [:link reftype=hd res=1.ANSI:elink., 4&per.10&per.3&per.2], :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. may
be passed to :font facename='System VIO' size=14x8.free:font facename=default size=0x0. without an error&per. On some UNIX platforms,
passing :font facename='System VIO' size=14x8.NULL:font facename=default size=0x0. to :font facename='System VIO' size=14x8.free:font facename=default size=0x0. causes a program crash so the
UNIX version of the standard library (Appendix F) specifies :font facename='System VIO' size=14x8.free:font facename=default size=0x0. without the
:font facename='System VIO' size=14x8.null:font facename=default size=0x0. annotation on its parameter&per. To check that allocated
objects are completely destroyed (e&per.g&per., all unshared objects inside a
structure are deallocated before the structure is deallocated), LCLint
checks that any parameter passed as an :font facename='System VIO' size=14x8.out only void *:font facename=default size=0x0. does not
contain references to live, unshared objects&per. This makes sense, since
such a parameter could not be used sensibly in any way other than
deallocating its storage&per.
:p.
16 If an exposure qualifier is used (see Section 6&per.2), the implied dependent
annotation is used instead of the more generally implied only
annotation&per.
:p.
17 Strictly, we should also check that the returned :font facename='System VIO' size=14x8.observer:font facename=default size=0x0. storage is not
used again after any other calls to the abstract type module using the same
parameter&per. LCLint does not attempt to check this, and in practice it is not
usually a problem&per.
:p.
18 Note that if the parameter is annotated with :font facename='System VIO' size=14x8.only:font facename=default size=0x0., it is not an error to
assign it to part of an abstract representation, since the caller may not use
the storage after the call returns&per.
:p.
19 That is, the return type is :font facename='System VIO' size=14x8.bool:font facename=default size=0x0., or :font facename='System VIO' size=14x8.int:font facename=default size=0x0. if +boolint is used&per.
:p.
20 The sef annotation denotes a parameter as side-effect free (see Section 8&per.2&per.1)&per.
By declaring the argument to assert to be side-effect free, LCLint will report
errors if the parameter to assert produces a side-effect&per. This is especially
pertinent if assertions are turned off when the production version is compiled&per.
The :font facename='System VIO' size=14x8.bool /*@alt int@*/:font facename=default size=0x0. type specifier for the parameter means
the parameter type must match either :font facename='System VIO' size=14x8.bool:font facename=default size=0x0. or :font facename='System VIO' size=14x8.int:font facename=default size=0x0.&per.
Alternate types are described in :link reftype=hd res=11.Section
8&per.2&per.2:elink.&per.
:p.
21 To be completely correct, all the macro parameters should be evaluated
before the macro has any side-effects&per. Since checking this would require
extensive analysis for occasional modest gain, it was not considered worth
implementing&per.
:p.
22 Note that functions which do not produce to the same result each time they
are called with the same arguments should be declared to modify internalState
so they will lead to errors if they are passed as sef parameters&per.
:p.
23 The most renown C naming convention is the Hungarian naming convention,
introduced by Charles Simonyi [Simonyi, Charles, and Martin Heller&per. "The
Hungarian Revolution&per." :hp1.BYTE:ehp1., August 1991, p&per. 131-38]&per. The names for
LCLint naming conventions follow the tradition of using Central European
nationalities as mnemonics for naming conventions&per. The LCLint conventions are
similar to the Hungarian naming convention in that they encode type information
in names, except that the LCLint conventions encode the names of accessible
abstract types instead of the type of the declaration of return value&per.
Prefixes used in the Hungarian naming convention are not supported by LCLint&per.
:p.
24 Namespace prefixes should probably be described by regular expressions&per.
LCLint uses a simpler, more limited means for describing names, which is
believed to be adequate for describing most useful naming conventions&per. If
there is sufficient interest, regular expressions may be supported in a future
version of LCLint&per.
:p.
25 Peter van der Linden estimates that default fall through is the wrong
behavior 97% of the time&per. [:link reftype=hd res=1.vdL95:elink., p&per. 37]
:p.
26 "Software Glitch Cripples AT&.T Network", Telephony, 22 January 1990&per.
:p.
27 In earlier versions of LCLint, the default extension :font facename='System VIO' size=14x8.&per.lldmp:font facename=default size=0x0. was used&per. This
has been shortened to :font facename='System VIO' size=14x8.&per.lcd:font facename=default size=0x0.&per.