1. Overview
2. Operation
3. Abstract Types
5. Memory Management
6. Sharing
7. Value Constraints
9. Naming Conventions
10. Other Checks
Contact: lclint@cs.virginia.edu
|
|
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. | |||
Appendix C Flags
Flags can be grouped into four major categories:
Global flags can be used in initialization files and at the command line; all other flags may also be used in control comments.
- Global flags for controlling initializations and global behavior
- Message format flags for controlling how messages are displayed
- Mode selectors for coarse control of LCLint checking
- Checking flags that control checking and what classes of messages are reported
Global Flags
Global flags can be set at the command line or in an options file, but cannot be set locally using stylized comments. These flags control on-line help, initialization files, pre-processor flags, libraries and output.
Help
On-line help provides documentation on LCLint operation and flags. When a help flag is used, no checking is done by LCLint. Help flags may be preceded by - or +.
help
Display general help overview, including list of additional help topics.help <topic>Display help on <topic>. Available topics:help <flag>
annotations describe annotations comments describe control comments flags summarize flag categories flags <category> all flags pertaining to <category> (one of the categories listed by lclint -help flags) flags alpha all flags in alphabetical order flags full print a full description of all flags print information on mailing lists modes flags settings in modes prefixcodes character codes for setting namespace prefixes references print references to relevant papers and web sites vars describe environment variables version print maintainer and version information Describe flag <flag>. (May list several flags.)warnflagsDisplay a warning when a flag is set in a surprising way. An error is reported if an obsolete (LCLint Version 1.4 or earlier) flag is set, a flag is set to its current value (i.e., the + or - may be wrong), or a mode selector flag is set after mode checking flags that will be reset by the mode were set. By default, warnflags is on. To suppress flag warnings, use -warnflags.Initialization
These flags control directories and files used by LCLint. They may be used from the command line or in an options file, but may not be used as control comments in the source code. Except where noted. they have the same meaning preceded by - or +.
tmpdir <directory>
Set directory for writing temp files. Default is /tmp/.I<directory>Add directory to path searched for C include files. Note there is no space after the I, to be consistent with C preprocessor flags.S<directory>Add directory to path search for .lcl specification files.
f <file>
Load options file <file>. If this flag is used from the command line, the default ~/.lclintrc file is not loaded. This flag may be used in an options file to load in another options file.nofPrevents the default options files (./.lclintrc and ~/.lclintrc) from being loaded. (Setting -nof overrides +nof, causing the options files to be loaded normally.)systemdirsSet directories for system files (default is "/usr/include"). Separate directories with colons (e.g., "/usr/include:/usr/local/lib"). Flag settings propagate to files in a system directory. If -systemdirerrors is set, no errors are reported for files in system directories.Pre-processor
These flags are used to define or undefine pre-processor constants. The -I<directory> flag is also passed to the C pre-processor.
D<initializer>
Passed to the C pre-processor.U<initializer>Passed to the C pre-processorLibraries
These flags control the creation and use of libraries.
dump <file>
Save state in <file> for loading. The default extension .lcd is added if <file> has no extension.load <file>Load state from <file> (created by -dump). The default extension .lcd is added if <file> has no extension. Only one library file may be loaded.By default, the standard library is loaded if the -load flag is not used to load a user library. If no user library is loaded, one of the following flags may be used to select a different standard library. Precede the flag by + to load the described library (or prevent a library from being loaded using nolib). See Apppendix F for information on the provided libraries.
nolib
Do not load any library. This prevents the standard library from being loaded.ansi-libUse the ANSI standard library (selected by default).strict-libUse strict version of the ANSI standard library.posix-libUse the POSIX standard library.posix-strict-libUse the strict version of the POSIX standard library.unix-libUse UNIX version of standard library.unix-strict-libUse the strict version of the UNIX standard library.Output
These flags control what additional information is printed by LCLint. Setting +<flag> causes the described information to be printed; setting -<flag> prevents it. By default, all these flags are off.
usestderr
Send error messages to standard error (instead of standard out).showsummaryShow a summary of all errors reported and suppressed. Counts of suppressed errors are not necessarily correct since turning a flag off may prevent some checking from being done to save computation, and errors that are not reported may propagate differently from when they are reported.showscanShow file names are they are processed.showallusesShow list of uses of all external identifiers sorted by number of uses.statsDisplay number of lines processed and checking time.timedistDisplay distribution of where checking time is spent.quietSuppress herald and error count. (If quiet is not set, LCLint prints out a herald with version information before checking begins, and a line summarizing the total number of errors reported.)whichlibPrint out the standard library filename and creation information.limit <number>At most <number> similar errors are reported consecutively. Further errors are suppressed, and a message showing the number of suppressed messages is printed.Expected Errors
Normally, LCLint will expect to report no errors. The exit status will be success (0) if no errors are reported, and failure if any errors are reported. Flags can be used to set the expected number of reported errors. Because of the provided error suppression mechanisms, these options should probably not be used for final checking real programs but may be useful in developing programs using make.
expect <number>
Exactly <number> code errors are expected. LCLint will exit with failure exit status unless <number> code errors are detected.Message Format
These flags control how messages are printed. They may be set at the command line, in options files, or locally in syntactic comments. The linelen and limit flags may be preceded by + or - with the same meaning; for the other flags, + turns on the describe printing and - turns it off. The box to the left of each flag gives its default value.
showcolumn
Show column number where error is found. Default: +showfuncShow name of function (or macro) definition containing error. The function name is printed once before the first message detected in that function. Default: +showallconjs
Show all possible alternate types (see Section 8.2.2). Default: -paren-file-formatUse file(line) format in messages.hintsProvide hints describing an error and how a message may be suppressed for the first error reported in each error class. Default: +forcehintsProvide hints for all errors reported, even if the hint has already been displayed for the same error class. Default: -linelen <number>Set length of maximum message line to <number> characters. LCLint will split messages longer than <number> characters long into multiple lines. Default: 80Mode Selector Flags
Mode selects flags set the mode checking flags to predefined values. They provide a quick coarse-grain way of controlling what classes of errors are reported. Specific checking flags may be set after a mode flag to override the mode settings. Mode flags may be used locally, however the mode settings will override specific command line flag settings. A warning is produced if a mode flag is used after a mode checking flag has been set.
These are brief descriptions to give a general idea of what each mode does. To see the complete flag settings in each mode, use lclint -help modes. A mode flag has the same effect when used with either + or -.
weak
Weak checking, intended for typical unannotated C code. No modifies checking, macro checking, rep exposure, or clean interface checking is done. Return values of type int may be ignored. The types bool, int, char and user-defined enum types are all equivalent. Old style declarations are unreported.standardThe default mode. All checking done by weak, plus modifies checking, global alias checking, use all parameters, using released storage, ignored return values or any type, macro checking, unreachable code, infinite loops, and fall-through cases. The types bool, int and char are distinct. Old style declarations are reported.checksModerately strict checking. All checking done by standard, plus must modification checking, rep exposure, return alias, memory management and complete interfaces.strictAbsurdly strict checking. All checking done by checks, plus modifications and global variables used in unspecified functions, strict standard library, and strict typing of C operators. A special reward will be presented to the first person to produce a real program that produces no errors with strict checking.Checking FlagsThese flags control checking done by LCLint. They may be set locally using syntactic comments, from the command line, or in an options file. Some flags directly control whether a certain class of message is reported. Preceding the flag by + turns reporting on, and preceding the flag by - turns reporting off. Other flags control checking less directly by determining default values (what annotations are implicit), making types equivalent (to prevent certain type errors), controlling representation access, etc. For these flags, the effect of + is described, and the effect of - is the opposite (or explicitly explained if there is no clear opposite). The organization of this section mirrors Sections 3-10.
Key
Under each flag name is a flag descriptor encoding the what kind of flag it is and its default value. The descriptions are:
plain: -
A plain flag. The value after the colon gives the default setting (e.g., this flag is off.)m: --++A mode checking flag. The value of the flag is set by the mode selector. The four signs give the setting in the weak, standard, checks and strict modes. (e.g., this flag is off in the weak and standard modes, and on in the checks and strict modes.)shortcutA shortcut flag. This flag sets other flags, so it has no default value.Types
Abstract Types
plain: -
impabstractImplicit abstract annotation for type declarations that do not use concrete.
m: -+++
mutrepRepresentation of mutable type has sharing semantics.
Access (Section 3.1)
plain: +
accessmoduleAn abstract type defined in M.h (or specified in M.lcl) is accessible in M.c.
plain: +
accessfileAn abstract type named type is accessible in files named type.<extenstion>.
plain: +
accessczechAn abstract type named type may be accessible in a function named type_name. (see Section 9.1.1)
plain: -
accessslovakAn abstract type named type may be accessible in a function named typeName. (see Section.9.1.2)
plain: -
accessczechoslovakAn abstract type named type may be accessible in a function named type_name or typeName. (see Section 9.1.3)
shortcut
accessallSets accessmodule, accessfile and accessczech.
Boolean Types (Section 3.3)
These flags control the type name used to represent booleans, and whether the boolean type is abstract.
plain: -
boolBoolean type is an abstract type.
plain: unset
booltype <name>Set name of boolean type to <name>.
plain: FALSE
boolfalse <name>Set name of boolean false to <name>.
plain: TRUE
booltrue <name>Set name of boolean true to <name>.
Predicates
m: --++
predboolptrType of condition test is a pointer.
m: -+++
predboolintType of condition test is an integral type.
m: ++++
predboolothersType of condition test is not a boolean, pointer or integral type.
shortcut
predboolSets predboolint, predboolptr and preboolothers.
plain: +
predassignThe condition test is an assignment expression. If an assignment is intended, add an extra parentheses nesting (e.g., if ((a = b)) ...).
Primitive Operations
m: ---+
ptrarithArithmetic involving pointer and integer.
m: ++--
ptrnegateAllow the operand of the ! operator to be a pointer.
m: ---+
bitwisesignedAn operand to a bitwise operator is not an unsigned values. This may have unexpected results depending on the signed representations.
m: -+++
shiftsignedAn operand to a shift operator is not unsigned values. This may have unexpected results depending on the signed representations.
m: ---+
strictopsPrimitive operation does not type check strictly.
m: ---+
sizeoftypeOperand of sizeof operator is a type. (Safer to use expression, int *x = sizeof (*x); instead of sizeof (int).)
Format Codes
plain: +
formatcodeInvalid format code in format string for printflike or scanflike function.
plain: +
formattypeType-mismatch in parameter corresponding to format code in a printflike or scanflike function.
Main
plain: +
maintypeType of main does not match expected type (function returning an int, taking no parameters or two parameters of type int and char **.)
Comparisons
m: -+++
boolcompareComparison between boolean values. This is dangerous since there may be multiple TRUE values if any non-zero value is interpreted at TRUE.
m: -+++
realcompareComparison involving float or double values. This is dangerous since it may produce unexpected results because floating point representations are inexact.
m: -+++
ptrcompareComparison between pointer and number.
Type Equivalence
m: +---
voidabstractAllow void * to match pointers to abstract types. (Casting a pointer to an abstract type to a pointer to void is okay if +voidabstract is set.)
plain: +
castfcnptrA pointer to a function is cast to (or used as) a pointer to void (or vice versa).
m: +---
forwarddeclForward declarations of pointers to abstract representation match abstract type.
m: -+++
imptypeA variable declaration has no explicit type. The type is implicitly int.
plain: +
incompletetypeA formal parameter is declared with an incomplete type (e.g., int[][]).
m: +---
charindexAllow char to index arrays.
m: ----
enumindexAllow members of enum type to index arrays.
m: +---
boolintMake bool and int types equivalent. (No type errors are reported when a boolean is used where an integral type is expected and vice versa.)
m: +---
charintMake char and int types equivalent.
m: ++--
enumintMake enum and int types equivalent.
m: +---
floatdoubleMake float and double types equivalent.
m: ----
ignorequalsIgnore type qualifiers (long, short, unsigned).
m: ++--
relaxqualsReport qualifier mismatches only if dangerous (information may be lost since a larger type is assigned to (or passed as) a smaller one or a comparison uses signed and unsigned values.)
m: ----
ignoresignsIgnore signs in type comparisons (unsigned matches signed).
plain: -
longintegralAllow long type to match an arbitrary integral type (e.g., size_t).
m: +---
longunsignedintegralAllow long unsigned type to match an arbitrary integral type (e.g., dev_t).
plain: -
matchanyintegralAllow any integral type to match an arbitrary integral type (e.g., dev_t).
m: +---
long-unsigned-unsigned-integralAllow unsigned long type to match an arbitrary unsigned integral type (e.g., size_t).
m: +---
long-signed-integralAllow long type to match an arbitrary signed integral type (e.g., ssize_t).
m: ++++
num-literalInteger literals can be used as floats.
plain: +
char-int-literalA character constant may be used as an int.
m: ++++
zeroptrLiteral 0 may be used as a pointer.
m: ----
relaxtypesAllow all numeric types to match.
plain: +
fullinitblockInitializer does not set every field in the structure.
Function Interfaces
Modification (Section 4.1)
m: ++++
modifiesUndocumented modification of caller-visible state. Without +moduncon, modification errors are only reported in the definitions of functions declared with a modifies clause (or specified).
m: --++
mustmodDocumented modification is not detected. An object listed in the modifies clause for a function, is not modified by the implementation.
shortcut
mod-unconReport modification errors in functions declared without a modifies clause.(Sets modnomods, mod-globs-nomods and mod-strict-globs-nomods.)
m: ---+
mod-nomodsReport modification errors (not involving global variables) in functions declared without a modifies clause.
m: ---+
mod-uncon-nomodsAn unconstrained function is called in a function body where modifications are checked. Since the unconstrained function may modify anything, there may be undetected modifications in the checked function.
m: ---+
mod-internal-strictA function that modifies internalState is called from a function that does not list internalState in its modifies clause.
m: ---+
mod-file-sysA function modifies the file system but does not list fileSystem in its modifies clause.
Global Variables (Section 4.2)
Errors involving the use and modification of global and file static variables are reported depending on flag settings, annotations where the global variable is declared, and whether or not the function where the global is used was declared with a globals clause.
m: ++++
globsUndocumented use of a checked global variable in a function with a globals list.
m: ++++
globuseA global listed in the globals list is not used in the implementation.
m: ---+
globnoglobsUse of a checked global in a function with no globals list.
m: ---+
internalglobsUndocumented use of internal state (should have globals internalState).
m: ---+
internalglobsnoglobsUse of internal state in function with no globals list.
m: -+++
globstateA function returns with global in inconsistent state (null or undefined)
m: --++
allglobsReport use and modification errors for globals not annotated with unchecked.
m: ++++
checkstrictglobsReport use and modification errors for checkedstrict globals.
Modification of Global Variables
m: -+++
modglobsUndocumented modification of a checked global variable.
m: ---+
modglobsuncheckedUndocumented modification of an unchecked global variable.
m: ---+
modglobsnomodsUndocumented modification of a checked global variable in a function with no modifies clause.
m: ---+
modstrictglobsnomodsUndocumented modification of a checkedstrict global variable in a function declared with no modifies clause.
Globals Lists and Modifies Clauses
m: ---+
warnmissingglobsGlobal variable used in modifies clause is not listed in globals list. (The global is added to the globals list.)
m: ---+
warnmissingglobsnoglobsGlobal variable used in modifies clause of a function with no globals list.
m: --++
globsimpmodsnothingA function declared with a globals list but no modifies clause is assumed to modify nothing.
m: ----
modsimpnoglobsA function declared with a modifies clause but no globals list is assumed to use no globals.
Implicit Checking Qualifiers
m: ----
impcheckedglobsImplicit checked qualifier on global variables with no checking annotation.
m: ----
impcheckedstaticsImplicit checked qualifier file static scope variables with no checking annotation.
m: ----
impcheckmodglobsImplicit checkmod qualifier on global variables with no checking annotation.
m: ----
impcheckmodstaticsImplicit checkmod qualifier file static scope variables with no checking annotation.
m: ---+
impcheckedstrictglobsImplicit checked qualifier on global variables with no checking annotation.
m: ---+
impcheckedstrictstaticsImplicit checked qualifier file static scope variables with no checking annotation.
m: --++
impcheckmodinternalsImplicit checkmod qualifier on function scope static variables with no checking annotation.
m: -+++
impglobsweakGlobal Aliasing
shortcut
globaliasFunction returns with global aliasing external state (sets checkstrictglobalias, checkedglobalias, checkmodglobalias and uncheckedglobalias).
m: -+++
checkstrictglobaliasFunction returns with a checkstrict global aliasing external state.
m: -+++
checkedglobaliasFunction returns with a checked global aliasing external state.
m: -+++
checkmodglobaliasFunction returns with a checkmod global aliasing external state.
m: --++
uncheckedglobaliasFunction returns with an unchecked global aliasing external state.
Declaration Consistency (Section 4.3)
m: -+++
incondefsIdentifier redeclared or redefined with inconsistent type.
m: -+++
incondefslibIdentifier defined in a library is redefined with inconsistent type
m: ----
overloadStandard library function overloaded.
m: -+++
matchfieldsA struct or enum type is redefined with inconsistent fields or members.
Memory Management
Reporting of memory management errors is controlled by flags setting checking and implicit annotations and code annotations.
Deallocation Errors (Section 5.2)
m: -+++
usereleasedStorage used after it may have been released.
m: ---+
strictusereleasedAn array element used after it may have been released.
Inconsistent Branches
m: -+++
branchstateStorage has inconsistent states of alternate paths through a branch (e.g., it is released in the true branch of an if-statement, but there is no else branch.)
m: ---+
strictbranchstateStorage through array fetch has inconsistent states of alternate paths through a branch. Since array elements are not checked accurately, this may lead to spurious errors.
m: --++
deparraysTreat array elements as dependent storage. Checking of array elements cannot be done accurately by LCLint. If deparrays is not set, array elements are assumed to be independent, so code that releases the same element more than once will produce no error. If deparrays is set, array elements are assumed to be dependent, so code that releases the same element more that once will produce an error, but so will code that releases different elements correctly will produce a spurious error.
Memory Leaks
m: -+++
mustfreeAllocated storage was not released before return or scope exit Errors are reported for only, fresh or owned storage.
m: -+++
compdestroyAll only references derivable from out only parameter of type void * must be released. (This is the type of the parameter to free, but may also be used for user-defined deallocation functions.)
m: ---+
strictdestroyReport complete destruction errors for array elements that may have been released. (If strictdestroy is not set, LCLint will assume that if any array element was released, the entire array was correctly released.)
Transfer Errors
A transfer error is reported when storage is transferred (by an assignment, passing a parameter, or returning) in a way that is inconsistent.
shortcut
memtransSets all memory transfer errors flags.
m: -+++
onlytransOnly storage transferred to non-only reference (memory leak).
m: -+++
ownedtransOwned storage transferred to non-owned reference (memory leak).
m: -+++
freshtransNewly-allocated storage transferred to non-only reference (memory leak).
m: -+++
sharedtransShared storage transferred to non-shared reference.
m: -+++
dependenttransInconsistent dependent transfer. Dependent storage is transferred to a non-dependent reference.
m: -+++
temptransTemporary storage (associated with a temp formal parameter) is transferred to a non-temporary reference. The storage may be released or new aliases created.
m: -+++
kepttransKept storage transferred to non-temporary reference.
m: -+++
keeptransKeep storage is transferred in a way that may add a new alias to it, or release it.
m: -+++
refcounttransReference counted storage is transferred in an inconsistent way.
m: -+++
newreftransA new reference transferred to a reference counted reference (reference count is not set correctly).
m: -+++
immediatetransAn immediate address (result of &) is transferred inconsistently.
m: -+++
statictransStatic storage is transferred in an inconsistent way.
m: -+++
exposetransInconsistent exposure transfer. Exposed storage is transferred to a non-exposed, non-observer reference.
m: -+++
observertransInconsistent observer transfer. Observer storage is transferred to a non-observer reference.
m: -+++
unqualifiedtransUnqualified storage is transferred in an inconsistent way.
Initializers
m: --++
onlyunqglobaltransOnly storage transferred to an unqualified global or static reference. This may lead to a memory leak, since the new reference is not necessarily released.
m: --++
staticinittransStatic storage is used as an initial value in an inconsistent way.
m: --++
unqualifiedinittransUnqualified storage is used as an initial value in an inconsistent way.
Derived Storage
m: -+++
compmempassStorage derivable from a parameter does not match the alias kind expected for the formal parameter.
Stack References
m: ++++
stackrefA stack reference is pointed to by an external reference when the function returns. Since the call frame will be destroyed when the function returns the return value will point to dead storage. (Section 5.2.6)
Implicit Memory Annotations (Section 5.3)
plain: +
globimponlyAssume unannotated global storage is only.
plain: +
paramimptempAssume unannotated parameter is temp.
plain: +
retimponlyAssume unannotated returned storage is only.
plain: +
structimponlyAssume unannotated structure or union field is only.
shortcut
codeimponlySets globimponly, retimponly and structimponly.
m: -+++
memimpReport memory errors for unqualified storage.
m: ----
passunknownPassing a value as an unannotated parameter clears its annotation. This will prevent many spurious errors from being report for unannotated programs, but eliminates the possibility of detecting many errors.