Guide Contents 1. Overview 2. Operation 3. Abstract Types	4. Function Interfaces 5. Memory Management 6. Sharing 7. Value Constraints	8. Macros 9. Naming Conventions 10. Other Checks Contact: lclint@cs.virginia.edu
This guide is preserved to maintain old links, but has been replaced by the Splint Manual.

2. Operation

LCLint is invoked by listing files to be checked. Initialization files, command line flags, and stylized comments may be used to customize checking globally and locally.

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.

2.1 Messages

The format and content of messages printed by LCLint can be customized by the user. A typical message is:

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 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.)

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.

2.3.1 Annotations

Annotations are stylized comments that follow a definite syntax. Although they are comments, they may only be used in fixed grammatical contexts (e.g., like a type qualifier).

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.

2.3.2 Control Comments

Unlike annotations, control comments may appear between any two tokens in a C program.[3] Syntactically, they are no different from standard comments. Control comments are used to provide source-level control of LCLint checking. They may be used to suppress spurious messages, set flags, and control checking locally in other ways. A complete description of control comments is found in Apppendix E.

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

This guide is preserved to maintain old links, but has been replaced by the Splint Manual.
	Guide Contents 1. Overview 2. Operation 3. Abstract Types	4. Function Interfaces 5. Memory Management 6. Sharing 7. Value Constraints	8. Macros 9. Naming Conventions 10. Other Checks Contact: lclint@cs.virginia.edu