3. Abstract Types
4. Function Interfaces
5. Memory Management
7. Value Constraints
9. Naming Conventions
10. Other Checks
|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 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.
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 +.
helpDisplay 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 informationDescribe 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.
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 +.
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.
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.
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-processor
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.
nolibDo 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.
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.
usestderrSend 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.
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.
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.
showcolumnShow 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: 80
Mode 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 -.
weakWeak 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 Flags
These 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.
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.
Implicit abstract annotation for type declarations that do not use concrete.
Representation of mutable type has sharing semantics.
Access (Section 3.1)
An abstract type defined in M.h (or specified in M.lcl) is accessible in M.c.
An abstract type named type is accessible in files named type.<extenstion>.
An abstract type named type may be accessible in a function named type_name. (see Section 9.1.1)
An abstract type named type may be accessible in a function named typeName. (see Section.9.1.2)
An abstract type named type may be accessible in a function named type_name or typeName. (see Section 9.1.3)
Sets 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.
Boolean type is an abstract type.
Set name of boolean type to <name>.
Set name of boolean false to <name>.
Set name of boolean true to <name>.
Type of condition test is a pointer.
Type of condition test is an integral type.
Type of condition test is not a boolean, pointer or integral type.
Sets predboolint, predboolptr and preboolothers.
The condition test is an assignment expression. If an assignment is intended, add an extra parentheses nesting (e.g., if ((a = b)) ...).
Arithmetic involving pointer and integer.
Allow the operand of the ! operator to be a pointer.
An operand to a bitwise operator is not an unsigned values. This may have unexpected results depending on the signed representations.
An operand to a shift operator is not unsigned values. This may have unexpected results depending on the signed representations.
Primitive operation does not type check strictly.
Operand of sizeof operator is a type. (Safer to use expression, int *x = sizeof (*x); instead of sizeof (int).)
Invalid format code in format string for printflike or scanflike function.
Type-mismatch in parameter corresponding to format code in a printflike or scanflike function.
Type of main does not match expected type (function returning an int, taking no parameters or two parameters of type int and char **.)
Comparison between boolean values. This is dangerous since there may be multiple TRUE values if any non-zero value is interpreted at TRUE.
Comparison involving float or double values. This is dangerous since it may produce unexpected results because floating point representations are inexact.
Comparison between pointer and number.
Allow 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.)
A pointer to a function is cast to (or used as) a pointer to void (or vice versa).
Forward declarations of pointers to abstract representation match abstract type.
A variable declaration has no explicit type. The type is implicitly int.
A formal parameter is declared with an incomplete type (e.g., int).
Allow char to index arrays.
Allow members of enum type to index arrays.
Make bool and int types equivalent. (No type errors are reported when a boolean is used where an integral type is expected and vice versa.)
Make char and int types equivalent.
Make enum and int types equivalent.
Make float and double types equivalent.
Ignore type qualifiers (long, short, unsigned).
Report 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.)
Ignore signs in type comparisons (unsigned matches signed).
Allow long type to match an arbitrary integral type (e.g., size_t).
Allow long unsigned type to match an arbitrary integral type (e.g., dev_t).
Allow any integral type to match an arbitrary integral type (e.g., dev_t).
Allow unsigned long type to match an arbitrary unsigned integral type (e.g., size_t).
Allow long type to match an arbitrary signed integral type (e.g., ssize_t).m: ++++
Integer literals can be used as floats.
A character constant may be used as an int.
Literal 0 may be used as a pointer.
Allow all numeric types to match.
Initializer does not set every field in the structure.
Modification (Section 4.1)
Undocumented modification of caller-visible state. Without +moduncon, modification errors are only reported in the definitions of functions declared with a modifies clause (or specified).
Documented modification is not detected. An object listed in the modifies clause for a function, is not modified by the implementation.
Report modification errors in functions declared without a modifies clause.(Sets modnomods, mod-globs-nomods and mod-strict-globs-nomods.)
Report modification errors (not involving global variables) in functions declared without a modifies clause.
An 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.
A function that modifies internalState is called from a function that does not list internalState in its modifies clause.
A 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.
Undocumented use of a checked global variable in a function with a globals list.
A global listed in the globals list is not used in the implementation.
Use of a checked global in a function with no globals list.
Undocumented use of internal state (should have globals internalState).
Use of internal state in function with no globals list.
A function returns with global in inconsistent state (null or undefined)
Report use and modification errors for globals not annotated with unchecked.
Report use and modification errors for checkedstrict globals.
Modification of Global Variables
Undocumented modification of a checked global variable.
Undocumented modification of an unchecked global variable.
Undocumented modification of a checked global variable in a function with no modifies clause.
Undocumented modification of a checkedstrict global variable in a function declared with no modifies clause.
Globals Lists and Modifies Clauses
Global variable used in modifies clause is not listed in globals list. (The global is added to the globals list.)
Global variable used in modifies clause of a function with no globals list.
A function declared with a globals list but no modifies clause is assumed to modify nothing.
A function declared with a modifies clause but no globals list is assumed to use no globals.
Implicit Checking Qualifiers
Implicit checked qualifier on global variables with no checking annotation.
Implicit checked qualifier file static scope variables with no checking annotation.
Implicit checkmod qualifier on global variables with no checking annotation.
Implicit checkmod qualifier file static scope variables with no checking annotation.
Implicit checked qualifier on global variables with no checking annotation.
Implicit checked qualifier file static scope variables with no checking annotation.
Implicit checkmod qualifier on function scope static variables with no checking annotation.
Function returns with global aliasing external state (sets checkstrictglobalias, checkedglobalias, checkmodglobalias and uncheckedglobalias).
Function returns with a checkstrict global aliasing external state.
Function returns with a checked global aliasing external state.
Function returns with a checkmod global aliasing external state.
Function returns with an unchecked global aliasing external state.
Declaration Consistency (Section 4.3)
Identifier redeclared or redefined with inconsistent type.
Identifier defined in a library is redefined with inconsistent type
Standard library function overloaded.
A struct or enum type is redefined with inconsistent fields or members.
Reporting of memory management errors is controlled by flags setting checking and implicit annotations and code annotations.
Deallocation Errors (Section 5.2)
Storage used after it may have been released.
An array element used after it may have been released.
Storage 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.)
Storage 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.
Treat 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.
Allocated storage was not released before return or scope exit Errors are reported for only, fresh or owned storage.
All 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.)
Report 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.)
A transfer error is reported when storage is transferred (by an assignment, passing a parameter, or returning) in a way that is inconsistent.
Sets all memory transfer errors flags.
Only storage transferred to non-only reference (memory leak).
Owned storage transferred to non-owned reference (memory leak).
Newly-allocated storage transferred to non-only reference (memory leak).
Shared storage transferred to non-shared reference.
Inconsistent dependent transfer. Dependent storage is transferred to a non-dependent reference.
Temporary storage (associated with a temp formal parameter) is transferred to a non-temporary reference. The storage may be released or new aliases created.
Kept storage transferred to non-temporary reference.
Keep storage is transferred in a way that may add a new alias to it, or release it.
Reference counted storage is transferred in an inconsistent way.
A new reference transferred to a reference counted reference (reference count is not set correctly).
An immediate address (result of &) is transferred inconsistently.
Static storage is transferred in an inconsistent way.
Inconsistent exposure transfer. Exposed storage is transferred to a non-exposed, non-observer reference.
Inconsistent observer transfer. Observer storage is transferred to a non-observer reference.
Unqualified storage is transferred in an inconsistent way.
Only storage transferred to an unqualified global or static reference. This may lead to a memory leak, since the new reference is not necessarily released.
Static storage is used as an initial value in an inconsistent way.
Unqualified storage is used as an initial value in an inconsistent way.
Storage derivable from a parameter does not match the alias kind expected for the formal parameter.
A 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)
Assume unannotated global storage is only.
Assume unannotated parameter is temp.
Assume unannotated returned storage is only.
Assume unannotated structure or union field is only.
Sets globimponly, retimponly and structimponly.
Report memory errors for unqualified storage.
Passing 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.