The best way to learn to use LCLint, of course, is to actually use it (if you don't already have LCLint installed on your system, download it). Before you read much further in this document, I recommend finding a small C program. Then, try running:
lclint *.c
For the most C programs, this will produce a large number of messages. To turn off reporting for some of the messages, try:
lclint -weak *.c
The -weak flag is a mode flag that sets many checking parameters to select weaker checking than is done in the default mode. Other LCLint flags will be introduced in the following sections; a complete list is given in Appendix C.
The first line gives the name of the function in which the error is found. This is printed before the first message reported for a function. (The function context is not printed if -showfunc is used.)sample.c: (in function faucet) sample.c:11:12: Fresh storage x not released before return A memory leak has been detected. Newly-allocated or only-qualified storage is not released before the last reference to is it lost. Use -mustfree to suppress message. sample.c:5:47: Fresh storage x allocated
The second line is the text of the message. This message reports a memory leak - storage allocated in a function is not deallocated before the function returns. The text is preceded by the file name, line and column number where the error is located. The column numbers are used by the emacs mode (see Appendix H) to jump to the appropriate line and column location. (Column numbers are not printed if -showcolumn is used.)
The next line is a hint giving more information about the suspected error. Most hints also include information on how the message may be suppressed. For this message, setting the -mustfree flag would prevent the message from being reported. Hints may be turned off by using -hints. Normally, a hint is given only the first time a class of error is reported. To have LCLint print a hint for every message regardless, use +forcehints.
The final line of the message gives additional location information. For this message, it tells where the leaking storage is allocated.
The generic message format is (parts enclosed in square brackets are optional):
[<file>:<line> (in <context>)]
<file>:<line>[,<column>]: message
[hint]
<file>:<line>,<column>: extra location information, if appopriate
The text of messages and hints may be longer than one line. They are split
into lines of length less than the value set using -linelen
<number>. The default line length is 80 characters. LCLint
attempts to split lines in a sensible place as near to the line length limit as
possible.
The +parenfileformat flag
can be used to generate file locations in the format recognized by
Microsoft Developer Studio. If +parenfileformat is set, the
line number follows the file name in parentheses (e.g.,
sample.c(11).).
2.2 Flags
So that many programming styles can be supported, LCLint provides over 300
flags for controlling checking and message reporting. Some of the flags are
introduced in the body of this document. Apppendix C describes every flag.
Modes and shortcut flags are provided for setting many flags at once.
Individual flags can override the mode settings.
Flags are preceded by + or -. When a flag is preceded by + we say it is on; when it is preceded by - it is off. The precise meaning of on and off depends on the type of flag.
The +/- flag settings are used for consistency and clarity, but contradict standard UNIX usage and is easy to accidentally use the wrong one. To reduce the likelihood of using the wrong flag, LCLint issues warnings when a flag is set in an unusual way. 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. The -warnflags flag suppresses these warnings.
Default flag settings will be read from ~/.lclintrc if it is
readable (in Windows, the $HOME/lclint.rc file is used). If
there is a .lclintrc file in the working directory, settings
in this file will be read next and its settings will override those in
~/.lclintrc. Command-line flags override settings in either
file. The syntax of the .lclintrc file is the same as that
of command-line flags, except that flags may be on separate lines and
the # character may be used to indicate that the remainder of
the line is a comment. The -nof flag prevents the
~/.lclintrc file from being loaded. The -f <filename> flag
loads options from filename.
2.3 Stylized Comments
Stylized comments are used to provide extra information about a type,
variable or function interface to improve checking, or to control flag
settings locally.
All stylized comments begin with /*@ and are closed by the end of the comment. The role of the @ may be played by any printable character. Use -commentchar <char> to select a different stylized comment marker.
Syntactic comments for function interfaces are described in Section 4; comments for declaring constants in Section 8.1. and comments for declaring iterators in Section 8.4. Sections 3-8 include descriptions of annotations for expressing assumptions about variables, parameters, return values, structure fields and type definitions. A summary of annotations is found in Apppendix D.
Most flags (all except those characterized as "global" in Apppendix C) can be set locally using control comments. A control comment can set flags locally to override the command line settings. The original flag settings are restored before processing the next file. 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. For instance,
/*@+boolint -modifies =showfunc@*/sets boolint on (this makes bool and int indistinguishable types), sets modifies off (this prevents reporting of modification errors), and sets showfunc to its original setting (this controls whether or not the name of a function is displayed before a message).
Next: Abstract Types
Contents