Rev 2 | Blame | Compare with Previous | Last modification | View Log | RSS feed
<!-- Crown Copyright (c) 1998 -->
<HTML>
<HEAD>
<TITLE>C Checker Reference Manual: Configuring the Checker</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
<A NAME=S7>
<H1>C Checker Reference Manual</H1>
<H3>January 1998</H3>
<A HREF="tdfc6.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
<A HREF="tdfc1.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
<A HREF="tdfc1.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
</A>
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
<HR>
<DL>
<DT><A HREF="#S8"><B>2.1 </B> - Introduction</A><DD>
<DL>
<DT><A HREF="#S9"><B>2.1.1 </B> - Built-in checking profiles</A><DD>
<DT><A HREF="#S10"><B>2.1.2 </B> - Minimum integer ranges</A><DD>
<DT><A HREF="#S11"><B>2.1.3 </B> - API selection</A><DD>
<DT><A HREF="#S12"><B>2.1.4 </B> - Individual command line checking
options</A><DD>
<DT><A HREF="#S13"><B>2.1.5 </B> - Construct a customised checking
environment</A><DD>
</DL>
<DT><A HREF="#S14"><B>2.2 </B> - Scoping checking profiles</A><DD>
</DL>
<HR>
<H1>2 Configuring the Checker</H1>
<A NAME=S8>
<HR><H2>2.1 Introduction</H2>
There are several methods available for configuring the checker most
of which are selected by using the relevant command line option. More
detailed customisation may require special #pragma statements to be
incorporated into the source code to be analysed (this commonly takes
the form of a startup file). The configuration options generally act
independently of one another and unless explicitly forbidden in the
descriptions below, they may be combined in any way.<P>
<A NAME=S9>
<H3>2.1.1 Built-in checking profiles</H3>
Six standard checking profiles are provided with the tool and are
held as a set of startup files which are automatically included in
each C source file. A brief description of each profile is given below,
for a complete descriptions see Annex A.<P>
<UL>
<LI>Xs ( strict checks ) denotes strict ISO standard C with most extra
checks enabled as warnings;<P>
<LI>Xp ( partial checks ) denotes strict ISO standard C with some
extra checks enabled;<P>
<LI>Xc ( conformance ) denotes strict ISO standard C with no extra
checks enabled;<P>
<LI>Xw ( warning mode ) represents a `warning' oriented compilation
mode. Many non-ISO standard C features are permitted with a warning.
Extra checks are performed to produce warnings.<P>
<LI>Xa ( `standard-ish' C ) denotes ISO standard C with syntatic relaxation
and no extra checks;<P>
<LI>Xt ( traditional C ) denotes traditional ( Kernighan and Ritchie
) C with no extra checks.<P>
</UL>
( The modes Xc, Xa, and Xt are meant to roughly correspond to the
modes found on some System V compilers. )<P>
The default checking environment is Xc, other environments are specified
by passing the name of the environment to the checker as a command
line flag, e.g. the -Xs flag specifies that the Xs environment is
to be used. These environments are the base checking modes and may
not be combined: if more than one base mode is specified, only the
final base mode is actually used - the earlier ones are ignored.<P>
There are also two "add-on" checking profiles, called <CODE>nepc
</CODE> (<CODE>n</CODE>o <CODE>e</CODE>xtra <CODE>p</CODE>ortability
<CODE>c</CODE>hecks) and <CODE>not_ansi</CODE>, which may be used
to complement any base mode. The "add-on" modes may alter
the status of checks set in the base mode. The <CODE>nepc</CODE> mode
switches off many of the checks relating to portability issues and
may be specified by passing the<CODE> -nepc</CODE> command line option
to tchk. The <CODE>not_ansi</CODE> mode supports a raft of non-ISO
features and is specified using the <CODE>-not_ansi</CODE> command
line flag.<P>
<P>
<A NAME=S10>
<H3>2.1.2 Minimum integer ranges</H3>
By default the checker assumes that all integer ranges conform to
the minimum ranges prescribed by the ISO C standard, i.e. char contain
at least 8 bits, short and int contain at least 16 bits and long contains
at least 32 bits. If the -Y32bit flag is passed to the checker it
assumes that integers conform to the minimum ranges commonly found
on most 32 bit machines, i.e. int contains at least 32 bits and int
is strictly larger than short so that the integral promotion of unsigned
short is int under the ISO C standard integer promotion rules.<P>
<A NAME=S11>
<H3>2.1.3 API selection</H3>
By default, programs are checked against the standard ISO C API as
specified in the ISO C standard Chapter 7. Other APIs are specified
by passing the -Yapi-name flag to the tchk, where api-name
<EM>is one of the API designators listed below</EM>. APIs fall into
two categories: base APIs and extension APIs. If more than one base
API is specified to tchk, only the last one is used for checking;
the others are ignored. Additional extension APIs, however, may be
used in addition to any suitable base API.<P>
The base APIs available are:<P>
<UL>
<LI>ansi ANSI X3.159;<P>
<LI>iso ISO MSE 9899:1990(Amendment 1:1993(E));<P>
<LI>posix POSIX 1003.1;<P>
<LI>posix2 POSIX 1003.2;<P>
<LI>xpg3 X/Open Portability Guide 3;<P>
<LI>xpg4 X/Open Portability Guide 4;<P>
<LI>cose COSE 1170;<P>
<LI>svid3 System V Interface Definition 3rd Edition;<P>
<LI>aes AES Revision A;<P>
<LI>system System headers as main API.<P>
</UL>
and the extension APIs are:<P>
<UL>
<LI>bsd_extn BSD-like extension for use with POSIX etc.;<P>
<LI>x5_lib X11 (Release 5) Library;<P>
<LI>x5_t X11 (Release 5) Intrinsics Toolkit;<P>
<LI>x5_mu X11 (Release 5) Miscellaneous Utilities;<P>
<LI>x5_aw X11 (Release 5) Athena Widgets;<P>
<LI>x5_mit X11 (Release 5) MIT Implementation;<P>
<LI>x5_proto X11 (Release 5) Protocol Extension;<P>
<LI>x5_ext X11 (Release 5) Extensions;<P>
<LI>x5_private X11 (Release 5) private headers (otherwise protected
);<P>
<LI>motif Motif 1.1;<P>
<LI>system+ System headers as last resort API. Search the system headers
only for those objects for which no declaration or definition can
be found within the base API.<P>
</UL>
<A NAME=S12>
<H3>2.1.4 Individual command line checking options</H3>
Some of the checks available can be controlled using a command line
option of the form -Xopt,opt,..., where the various opt options give
a comma-separated list of commands. These commands have the form test=status,
where test is the name of the check, and status is either check (apply
check and give an error if it fails), warn (apply check and give a
warning if it fails) or dont (do not apply check). The names of checks
can be found with their descriptions in Chapters 3 - 8; for example
the check for implicit function declarations described in
<A HREF="tdfc6.html#30">3.4.1</A> may be switched on using <CODE>-X:implicit_func=check
</CODE>.<P>
<A NAME=S13>
<H3>2.1.5 Construct a customised checking environment</H3>
The individual checks performed by the C static checker are generally
controlled by #pragma directives. The reason for this is that the
ISO standard places no restrictions on the syntax following a #pragma
preprocessing directive, and most compilers/checkers can be configured
to ignore any unknown #pragma directives they encounter.<P>
Most of these directives begin:<P>
<PRE>
#pragma TenDRA ...
</PRE>
and are always checked for syntactical correctness. The individual
directives, together with the checks they control are described in
Chapters 3 - 8. Section 2.2 describes the method of constructing a
new checking profile from these individual checks.<P>
<A NAME=S14>
<HR><H2>2.2 <A NAME=13>Scoping checking profiles</H2>
Almost all the available checks are scoped (exceptions will be mentioned
in the description of the check). A new checking scope may be started
by inserting the pragma:<P>
<PRE>
#pragma TenDRA begin
</PRE>
at the outermost level. The scope runs until the matching:<P>
<PRE>
#pragma TenDRA end
</PRE>
directive, or to the end of the translation unit (the ISO C standard
definition of a translation unit as being a source file, together
with any headers or source files included using the #include preprocessing
directive, less any source lines skipped by any of the conditional
inclusion preprocessing directives, is used throughout this document).
<P>
Checking scopes may be nested in the obvious way.<P>
Each new checking scope inherits its initial set of checks from the
checking scope which immediately contains it (this includes the implicit
main checking scope consisting of the entire source file). Any checks
switched on or off within the scope apply only to that scope and any
scope it contains. The set of checks applied reverts to its previous
state at the end of a scope. Thus, for example:<P>
<PRE>
#pragma TenDRA variable analysis on
/* Variable analysis is on here */
#pragma TenDRA begin
#pragma TenDRA variable analysis off
/* Variable analysis is off here */
#pragma TenDRA end
/* Variable analysis is on again here */
</PRE>
Once a check has been set any attempt to change its status within
the same scope is flagged as an error. If checks need to be switched
on and off in the same source file, they must be properly scoped.
The built-in compilation modes have the entire source file as their
scope.<P>
The method of applying different checking profiles to different parts
of a program clearly needs to take into account those properties of
C which can circumvent such scoping. Consider for example:<P>
<PRE>
#pragma TenDRA begin
#pragma TenDRA unknown escape allow
#define STRING "hello\!"
#pragma TenDRA end
char * f () {
return ( STRING ) ;
}
</PRE>
The macro STRING is defined in an area where unknown escape sequences,
such as \!, are allowed, but it is expanded in an area where they
are not allowed (this is the default setting). The conventional approach
to macro expansion would lead to the unknown escape sequence being
flagged as an error, even though the user probably intended to avoid
this. The checker therefore expands all macros using the checking
profile in which they were defined, rather than the current checking
scope.<P>
The directives describing the user's desired checking profile could
be included directly in the program itself, ideally in some configuration
file which is #include'd in all source files. It is however perhaps
more appropriate to store the directives as a startup file, <EM>file</EM>
say, which is passed to the checker using the<CODE> -f</CODE><EM>file</EM><CODE>
</CODE>command line option. It should be noted that user-defined compilation
modes are defined on top of a built-in mode base (normally Xc, the
default mode). It is therefore important to scope the new checking
profile as described above.<P>
Names may be associated with checking scopes by using an alternative
form of the begin directive:<P>
<PRE>
#pragma TenDRA begin name environment identifier
</PRE>
where identifier is any valid C identifier. Thereafter a statement
of the form:<P>
<PRE>
#pragma TenDRA use environment identifier
</PRE>
changes the current checking environment to the environment associated
with identifier. <P>
Sometimes it may be desirable to use different checking profiles for
different parts of a translation unit, e.g. applying less strict checks
to any system headers which may be included. The checker can be configured
to apply a named checking scope, <EM>env_name</EM>, to any files included
from a directory which has been named <EM>dir_name</EM>, using:<P>
<PRE>
#pragma TenDRA directory <EM>dir_name</EM> use environment <EM>env_name</EM>
</PRE>
The directory name must be passed to the checker using the <CODE>-N</CODE><EM>dir_name
</EM><CODE>:</CODE><EM>dir</EM><CODE> </CODE>command line option.
This is equivalent to the usual <CODE>-I</CODE><CODE>dir</CODE> option
for specifying include paths, except that it also attaches the name
dir_name to the directory.<P>
<P>
<!-- FM pgf ignored -->
<HR>
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
Copyright © 1998.</I></P>
</BODY>
</HTML>