lock_lint(1)lock_lint(1)NAMElock_lint - verify use of locks in multi-threaded programs
SYNOPSISlock_lint subcommand
DESCRIPTION
LockLint is a tool that statically analyzes ANSI C source code to aid
in the detection of data races and deadlocks caused by inconsistent
usages of mutex and readers-writer locks. LockLint supports the ANSI C
programmer using Solaris's libthread API.
There are two interfaces for LockLint:
subcommands
These are entered from a command line (or from a script) and
take the form:
lock_lint subcommand
source code annotations
These are entered directly into your source code. Although
there are fewer source code annotations than subcommands, they
are often preferable to subcommands.
To start a LockLint session, type:
lock_lint start
This starts a user-specifiable subshell with an appropriate LockLint
context established. (See the start subcommand, below, for more infor‐
mation.)
For LockLint to analyze your source code, the code must first be com‐
piled using the -Zll option of the C compiler. The C compiler then pro‐
duces the LockLint database files (.ll files), one for each .c file
compiled. The .ll files will later be loaded into LockLint via the
load subcommand.
SUBCOMMANDS
For quick information on any LockLint subcommand while you're in a
LockLint session, use the LockLint help subcommand (see below).
For efficiency and ease, you can alias subcommands (if your shell
allows it); you can also put subcommands into a script file and run
that script.
analyze [-hv]
Analyze the loaded files for lock inconsistencies which may lead
to data races and deadlocks. This subcommand may produce a
great deal of output, so you may want to redirect the output to
a file. This directive can only be run once for each saved
state (see save).
Once the analysis is done, you can find still more potential
problems in the output of the "vars" and "order" subcommands.
For example, the command
lock_lint vars -h | fgrep *
will show variables which are not properly protected by any
lock.
assert side effect mutex acquired in func ...
assert side effect rwlock [read] acquired in func ...
assert side effect mutex|rwlock released in func ...
assert side effect rwlock upgraded|downgraded in func ...
assert mutex|rwlock protects var ...
assert mutex protects func ...
assert rwlock protects [reads in] func ...
assert order lock lock ...
assert read only var ...
assert rwlock covers lock ...
Provide LockLint with assertions about how locks are being used.
During analysis LockLint reports on any violations of these
assertions.
declare mutex mutex ...
declare rwlocks rwlock ...
declare func_ptr targets func ...
declare nonreturning func ...
declare one tag ...
declare readable var ...
declare root func ...
Declare various attributes about locks, functions and variables
in the program.
disallows
List the calling sequences which are disallowed, as specified
using the disallow subcommand.
exit To exit LockLint, use the exit command of the shell you are
using. When the subshell started by the lock_lint start command
exits, LockLint exits.
files List the source code files as represented by the .ll files
loaded via the load subcommand.
funcptrs [-botu] func_ptr ...
funcptrs [-blotuz]
funcptrs [-botu] func_ptr ...
funcptrs [-blotuz]
List information about the function pointers used in the loaded
files.
funcs [-adehou] func ...
funcs [-adehilou]
funcs [-adehlou] [directly] called by func ...
funcs [-adehlou] [directly] calling func ...
funcs [-adehlou] [directly] reading var ...
funcs [-adehlou] [directly] writing var ...
funcs [-adehlou] [directly] accessing var ...
funcs [-adehlou] [directly] affecting lock ...
funcs [-adehlou] [directly] inverting lock ...
List information about the functions defined and/or called in
the loaded files.
help [subcommand]
The help subcommand with no topic specified gives a list of sub‐
commands with their options and some general help information.
Detailed help on a subcommand can be specified via the syntax:
lock_lint help first word of subcommand
Help is also available on the following keywords:
condvars inversions names
example limitations overview
exit locking shell
ifdef makefile
shell
ignore func|var ... [in func ... ]
Tell LockLint to exclude certain functions and variables from
the analysis. This exclusion may be limited to specific func‐
tions using the "in func ..." clause; otherwise the exclusion
applies to all functions.
load file ...
Load the specified .ll files. The extension may be omitted, but
if an extension is specified, it must be .ll. Absolute and rel‐
ative paths are allowed. The following are legal (depending
upon your shell's capabilities):
lock_lint load *.ll
lock_lint load ../foo/abcdef{1,2}
lock_lint load `find . -name ll -print`
locks [-co] lock ...
locks [-clo]
locks [-clo] [directly] affected by func ...
locks [-clo] [directly] inverted by func ...
List information about the locks of the loaded files. Note that
only those variables which are actually used in lock manipula‐
tion routines are shown; locks which are simply declared but
never manipulated will not be shown.
members struct_tag
List the members of the struct with the specified tag, one per
line. For structures which were not assigned a tag, the nota‐
tion "file@line is used (e.g. "x.c@29"), where the file and line
number are the source location of the struct's declaration.
order [lock [lock]].
List information about the order in which locks are acquired by
the code being analyzed. It may only be run after analysis is
complete.
pointer calls
List calls made through function pointers in the loaded files.
reallow func ...
Allow exceptions to disallow subcommands.
reallows
List the calling sequences which are reallowed, as specified
using the reallow subcommand.
refresh
Pop the saved state stack restoring LockLint to the state of the
top of the saved state stack. The description associated with
that state is printed. Then save the state again with the same
description (so that it may be restored/refreshed again).
restore
Pop the saved state stack restoring LockLint to the state of the
top of the saved state stack. The description associated with
that state is printed.
save description
Save the current state of the tool on a stack. The specified
description is attached to the state. Saved states form a LIFO
(Last-In-First-Out) stack, so that the last state saved is the
first one restored.
saves List the descriptions of the states saved on the saved stack via
the save subcommand. The descriptions are shown from top to
bottom with the first description being the most recently saved
state that has not been restored. And the last description
being the oldest state saved that has not been restored.
start cmd
Start a LockLint session. A LockLint session must be started
prior to using any other LockLint subcommand. By default the
start subcommand establishes LockLint context and starts a sub‐
shell for the user — as specified via $SHELL — within that con‐
text. The only piece of the LockLint context exported to the
subshell is the LL_CONTEXT environment variable. LL_CONTEXT
contains the path to the temporary directory of files used to
maintain a LockLint session.
sym name ...
List the various things the specified names could refer to
within the loaded files. For example, "foo" might refer both to
variable "x.c:func1/foo" and to function y.c:foo, depending on
context.
unassert vars var ...
Undo any assertion about locks protecting the specified vari‐
ables. Note that there is no way to remove an assertion about a
lock protecting a function.
vars [-aho] var ...
vars [-ahilo]
vars [-ahlo] protected by lock
vars [-ahlo] [directly] read by func ...
vars [-ahlo] [directly] written by func ...
vars [-ahlo] [directly] accessed by func ...
List information about the variables of the loaded files. Note
that only those variables which are actually *used* are shown;
variables which are simply declared in the program but never
accessed will not be shown.
SOURCE CODE ANNOTATIONSASSERT(NO_LOCKS_HELD);
assert(NO_LOCKS_HELD);
Tell LockLint that when this point in the code is reached, no
locks should be held by the thread executing this test. Viola‐
tions will be reported during analysis.
ASSERT(NO_COMPETING_THREADS);
assert(NO_COMPETING_THREADS);
Tell LockLint that when this point in the code is reached, no
other threads should be competing with the one running this
code. Violations (based on info provided by certain NOTE-style
assertions) are reported during analysis.
ASSERT(MUTEX_HELD(lock_expr) && ...);
assert(MUTEX_HELD(lock_expr) && ...);
Cause an error to be reported if the executing thread does not
hold the lock as described.
NOTE(MUTEX_PROTECTS_DATA(Mutex, DataNameList));
NOTE(RWLOCK_PROTECTS_DATA(Rwlock, DataNameList));
NOTE(SCHEME_PROTECTS_DATA(“description”, DataNameList));
The first two annotations tell LockLint that the lock should be
held whenever the specified data are accessed.
The third annotation, SCHEME_PROTECTS_DATA, describes how data
which are not protected by a mutex or readers/writer lock are
protected. The description supplied for the scheme is simply
text.
NOTE(READ_ONLY_DATA(DataNameList));
Tell LockLint that the data should only be read, and not writ‐
ten.
NOTE(DATA_READABLE_WITHOUT_LOCK(DataNameList));
Tell LockLint that the specified data may be read without pro‐
tecting locks being held on them.
NOTE(RWLOCK_COVERS_LOCKS(RwlockName, LockNameList));
Tell LockLint that a hierarchical relationship exists between a
readers/writer lock and a set of other locks.
NOTE(MUTEX_ACQUIRED_AS_SIDE_EFFECT(MutexExpr));
NOTE(READ_LOCK_ACQUIRED_AS_SIDE_EFFECT(RwlockExpr));
NOTE(WRITE_LOCK_ACQUIRED_AS_SIDE_EFFECT(RwlockExpr));
NOTE(LOCK_RELEASED_AS_SIDE_EFFECT(LockExpr));
NOTE(LOCK_UPGRADED_AS_SIDE_EFFECT(RwlockExpr));
NOTE(LOCK_DOWNGRADED_AS_SIDE_EFFECT(RwlockExpr));
NOTE(NO_COMPETING_THREADS_AS_SIDE_EFFECT);
NOTE(COMPETING_THREADS_AS_SIDE_EFFECT);
Tell LockLint that the function has the specified side effect on
the specified lock - that is, that the function deliberately
leaves the lock in a different state on exit than it was in when
the function was entered. In the case of the last two of these
annotations, the side effect is not about a lock but rather
about the state of concurrency.
NOTE(COMPETING_THREADS_NOW);
NOTE(NO_COMPETING_THREADS_NOW);
The first annotation tells LockLint that after this point in the
code, other threads exist which might try to access the same
data that this thread will access. The second function speci‐
fies that this is no longer the case, that either no other
threads are running, or whatever threads are running will not be
accessing data that this thread will access.
NOTE(NOT_REACHED);
Tell LockLint that a particular point in the code cannot be
reached, and therefore LockLint should ignore the condition of
locks held at that point. Lock Order
NOTE(LOCK_ORDER(LockNameList));
Specify the order in which locks should be acquired.
NOTE(NOW_INVISIBLE_TO_OTHER_THREADS(DataExpr, ...));
NOTE(NOW_VISIBLE_TO_OTHER_THREADS(DataExpr, ...));
Tell LockLint whether or not the variables represented by the
specified expressions are visible to other threads - that is,
whether or not other threads could access the variables.
NOTE(ASSUMING_PROTECTED(DataExpr, ...));
Tell LockLint that this function assumes that the variables rep‐
resented by the specified expressions are protected - that is,
either the appropriate lock is held for each variable; or the
variables are invisible to other threads; or there are no com‐
peting threads when the call is made.
ENVIRONMENT
LL_CONTEXT contains path to context directory
SHELL used as default shell
TMPDIR used as default tmp directory path
SEE ALSO
For complete Sun Studio documentation, go to http://develop‐
ers.sun.com/sunstudio/documentation/
CAVEATS
Currently, LockLint does not check to see if a .ll is out of date with
respect to its source file.
FILES
file.ll LockLint database file from cc
lock_lint lock_lint command
lock_lint_server LockLint engine
help directory of help files
cmd.ll_help help topic on cmd
ERRORS
Exit status from a lock_lint command is as follows:
0 Normal
1 System error
2 User caused error, like incorrect options or undefined name
3 Multiple types of errors
5 Lock_lint detected error: violation of an assertion,
potential data race or deadlock may have been found,
unprotected data references, etc.
10 Licensing error
August 1996 lock_lint(1)
