			   LCLint Version 2.2
		       MIT/LCS Distribution Site
			     26 August 1996

			      David Evans
			 evs@larch.lcs.mit.edu

LCLint is a tool for statically checking C programs.  With minimal
effort, LCLint can be used as a better lint.  If additional effort is
invested adding annotations to programs, LCLint can perform stronger
checks than can be done by any standard lint.

LCLint does many of the traditional lint checks including unused
declarations, type inconsistencies, use-before-definition, unreachable
code, ignored return values, execution paths with no return, likely
infinite loops, and fall-through cases.  Our main focus, however, is on
more powerful checks that are made possible by additional information
given in source code annotations.  Annotations are stylized comments
that document certain assumptions about functions, variables,
parameters, and types.  They may be used to indicate where the
representation of a user-defined type is hidden, to limit where a global
variable may be used or modified, to constrain what a function
implementation may do to its parameters, and to express checked
assumptions about variables, types, structure fields, function
parameters, and function results.  In addition to the checks
specifically enabled by annotations, many of the traditional lint checks
are improved by exploiting this additional information.

Some problems detected by LCLint include:

o Violations of information hiding.  A user-defined type can be declared
  as abstract, and a message is reported where code inappropriately
  depends on the representation of the type.

o Inconsistent modification of caller-visible state.  Functions can be
  annotated with information on what caller-visible state may be modified
  by the function, and an error is reported if the modifications produces
  by the function contradict its declaration.  

o Inconsistent use of global variables.  Information on what global and
  file scope variables a function may use can be added to function
  declarations, and a message is reported if the implementation of the
  function uses other global variables or does not uses every global
  variable listed in its declaration.  

o Memory management errors.  Instances where storage that has been
  deallocated is used, or where storage is not deallocated (memory leaks).

o Dangerous data sharing or unexpected aliasing.  Parameters to a
  function share storage in a way that may lead to undefined or undesired
  behavior, or a reference to storage within the representation of an
  abstract type is created.  

o Using possibly undefined storage or returning storage that is not
  completely defined (except as documented).  

o Dereferencing a possibly null pointer.  

o Dangerous macro implementations or invocations. 

o Violations of customizable naming conventions. 

o Program behavior that is undefined because it depends on order of
  evaluation, likely infinite loops, fall-through cases, incomplete logic,
  statements with no effect, ignored return values, unused declarations,
  and exceeding certain standard limits.  

LCLint checking can be customized to select what classes of errors are
reported using command line flags and stylized comments in the code.

For more information, please visit the LCLint home page at

    http://larch-www.lcs.mit.edu:8001/larch/lclint/

We are very interested in hearing about your experiences using LCLint.
Send any questions or comments to lclint@larch.lcs.mit.edu.

There are two mailing lists associated with LCLint:

   lclint-announce@larch.lcs.mit.edu

      Reserved for announcements of new releases and bug fixes.

   lclint-interest@larch.lcs.mit.edu

      Informal discussions on the use and development of lclint.

Send a (human-readable) message to lclint-request@larch.lcs.mit.edu to
subscribe to a list.  Everyone who uses lclint should subscribe to
lclint-announce, to be informed of new releases.


Installation Instructions
=========================

Download one of the common packages:

        o the standard version (lclint.common.tar.gz) - includes 
          libraries, emacs files, documentation, and test suite.
        o the minimal version (lclint.common-mini.tar.gz - does 
          not include documentation or test suite.

     Unless your disk space is very limited, the standard version is
     recommened.

Download the binary package for your platform:

        o DEC Alpha AXP running DEC Unix (lclint.alpha.tar.gz)
        o DECstation running Ultrix (lclint.decmips.tar.gz)
        o SUN SPARCstation running Solaris 2 (lclint.solaris.tar.gz)
        o SUN workstation running SunOS 4 (lclint.sunos4.tar.gz)
        o linux (ELF binary, compiled using Linux 1.3.68) (lclint.linux-elf.tar.gz)

Move both packages to the directory where you want to install LCLint.
Extracting the tar files will create an lclint subdirectory in this
directory.

Uncompress the packages. Run

     gzip -d lclint.*.tar.gz

Extract files from both tar archives. Run

     tar xf lclint.<package>.tar

  This will create an lclint directory, containing several
  subdirectories:

	bin/lclint

           LCLint binary

        emacs/

	   lclint.elc 
              emacs mode for running LCLint
	   lclint-abbrevs
              emacs abbreviations for LCLint annotations

	lib/

          Library files including:
	     ansi.lcd, ansistrict.lcd, posix.lcd, posixstrict.lcd,
             unix.lcd, unixstrict.lcd
	        standard libraries
             bool.h
                standard boolean header
	     CTrait.syms, lclinit.lci
                LCL Initialization Files

Set environment variables:

   * LARCH_PATH - path to search for lclint libraries and initializations
     files. If you are using the standard directories, this should be
     ".:base-directory/lib".
   * LCLINT_CPPCMD - command to run C preprocessor. Default is /lib/cpp. If
     you want to use a different preprocessor, set LCLINT_CPPCMD to the
     preprocessor command.
   * LCLIMPORTDIR - directory containing lcl imports files. If you are using
     the standard directories, this is base-directory/imports.

  Put the commands to set these variables in one of your initialization
  dotfiles (usually ~/.environment). Set up your command path to include the
  directory containing lclint/bin/lclint, or move the binary to a directory on
  your command path.

Run the test suite. (Unless you downloaded the common-mini package.) This
requires the GNU make utility (sometimes called gmake, make or gnumake). If
you don't have gmake installed on your system, download it from
prep.ai.mit.edu.

     cd lclint/test
     gmake test


