| 2 |
7u83 |
1 |
<!-- Crown Copyright (c) 1998 -->
|
|
|
2 |
<HTML>
|
|
|
3 |
<HEAD>
|
|
|
4 |
<TITLE>C Checker Reference Manual: Configuring the Checker</TITLE>
|
|
|
5 |
</HEAD>
|
|
|
6 |
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
|
|
|
7 |
<A NAME=S7>
|
|
|
8 |
<H1>C Checker Reference Manual</H1>
|
|
|
9 |
<H3>January 1998</H3>
|
|
|
10 |
<A HREF="tdfc6.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
|
|
|
11 |
<A HREF="tdfc1.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
|
|
|
12 |
<A HREF="tdfc1.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
|
|
|
13 |
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
|
|
|
14 |
</A>
|
|
|
15 |
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
|
|
|
16 |
<HR>
|
|
|
17 |
<DL>
|
|
|
18 |
<DT><A HREF="#S8"><B>2.1 </B> - Introduction</A><DD>
|
|
|
19 |
<DL>
|
|
|
20 |
<DT><A HREF="#S9"><B>2.1.1 </B> - Built-in checking profiles</A><DD>
|
|
|
21 |
<DT><A HREF="#S10"><B>2.1.2 </B> - Minimum integer ranges</A><DD>
|
|
|
22 |
<DT><A HREF="#S11"><B>2.1.3 </B> - API selection</A><DD>
|
|
|
23 |
<DT><A HREF="#S12"><B>2.1.4 </B> - Individual command line checking
|
|
|
24 |
options</A><DD>
|
|
|
25 |
<DT><A HREF="#S13"><B>2.1.5 </B> - Construct a customised checking
|
|
|
26 |
environment</A><DD>
|
|
|
27 |
</DL>
|
|
|
28 |
<DT><A HREF="#S14"><B>2.2 </B> - Scoping checking profiles</A><DD>
|
|
|
29 |
</DL>
|
|
|
30 |
|
|
|
31 |
<HR>
|
|
|
32 |
<H1>2 Configuring the Checker</H1>
|
|
|
33 |
<A NAME=S8>
|
|
|
34 |
<HR><H2>2.1 Introduction</H2>
|
|
|
35 |
There are several methods available for configuring the checker most
|
|
|
36 |
of which are selected by using the relevant command line option. More
|
|
|
37 |
detailed customisation may require special #pragma statements to be
|
|
|
38 |
incorporated into the source code to be analysed (this commonly takes
|
|
|
39 |
the form of a startup file). The configuration options generally act
|
|
|
40 |
independently of one another and unless explicitly forbidden in the
|
|
|
41 |
descriptions below, they may be combined in any way.<P>
|
|
|
42 |
<A NAME=S9>
|
|
|
43 |
<H3>2.1.1 Built-in checking profiles</H3>
|
|
|
44 |
Six standard checking profiles are provided with the tool and are
|
|
|
45 |
held as a set of startup files which are automatically included in
|
|
|
46 |
each C source file. A brief description of each profile is given below,
|
|
|
47 |
for a complete descriptions see Annex A.<P>
|
|
|
48 |
<UL>
|
|
|
49 |
<LI>Xs ( strict checks ) denotes strict ISO standard C with most extra
|
|
|
50 |
checks enabled as warnings;<P>
|
|
|
51 |
<LI>Xp ( partial checks ) denotes strict ISO standard C with some
|
|
|
52 |
extra checks enabled;<P>
|
|
|
53 |
<LI>Xc ( conformance ) denotes strict ISO standard C with no extra
|
|
|
54 |
checks enabled;<P>
|
|
|
55 |
<LI>Xw ( warning mode ) represents a `warning' oriented compilation
|
|
|
56 |
mode. Many non-ISO standard C features are permitted with a warning.
|
|
|
57 |
Extra checks are performed to produce warnings.<P>
|
|
|
58 |
<LI>Xa ( `standard-ish' C ) denotes ISO standard C with syntatic relaxation
|
|
|
59 |
and no extra checks;<P>
|
|
|
60 |
<LI>Xt ( traditional C ) denotes traditional ( Kernighan and Ritchie
|
|
|
61 |
) C with no extra checks.<P>
|
|
|
62 |
</UL>
|
|
|
63 |
( The modes Xc, Xa, and Xt are meant to roughly correspond to the
|
|
|
64 |
modes found on some System V compilers. )<P>
|
|
|
65 |
The default checking environment is Xc, other environments are specified
|
|
|
66 |
by passing the name of the environment to the checker as a command
|
|
|
67 |
line flag, e.g. the -Xs flag specifies that the Xs environment is
|
|
|
68 |
to be used. These environments are the base checking modes and may
|
|
|
69 |
not be combined: if more than one base mode is specified, only the
|
|
|
70 |
final base mode is actually used - the earlier ones are ignored.<P>
|
|
|
71 |
There are also two "add-on" checking profiles, called <CODE>nepc
|
|
|
72 |
</CODE> (<CODE>n</CODE>o <CODE>e</CODE>xtra <CODE>p</CODE>ortability
|
|
|
73 |
<CODE>c</CODE>hecks) and <CODE>not_ansi</CODE>, which may be used
|
|
|
74 |
to complement any base mode. The "add-on" modes may alter
|
|
|
75 |
the status of checks set in the base mode. The <CODE>nepc</CODE> mode
|
|
|
76 |
switches off many of the checks relating to portability issues and
|
|
|
77 |
may be specified by passing the<CODE> -nepc</CODE> command line option
|
|
|
78 |
to tchk. The <CODE>not_ansi</CODE> mode supports a raft of non-ISO
|
|
|
79 |
features and is specified using the <CODE>-not_ansi</CODE> command
|
|
|
80 |
line flag.<P>
|
|
|
81 |
<P>
|
|
|
82 |
<A NAME=S10>
|
|
|
83 |
<H3>2.1.2 Minimum integer ranges</H3>
|
|
|
84 |
By default the checker assumes that all integer ranges conform to
|
|
|
85 |
the minimum ranges prescribed by the ISO C standard, i.e. char contain
|
|
|
86 |
at least 8 bits, short and int contain at least 16 bits and long contains
|
|
|
87 |
at least 32 bits. If the -Y32bit flag is passed to the checker it
|
|
|
88 |
assumes that integers conform to the minimum ranges commonly found
|
|
|
89 |
on most 32 bit machines, i.e. int contains at least 32 bits and int
|
|
|
90 |
is strictly larger than short so that the integral promotion of unsigned
|
|
|
91 |
short is int under the ISO C standard integer promotion rules.<P>
|
|
|
92 |
<A NAME=S11>
|
|
|
93 |
<H3>2.1.3 API selection</H3>
|
|
|
94 |
By default, programs are checked against the standard ISO C API as
|
|
|
95 |
specified in the ISO C standard Chapter 7. Other APIs are specified
|
|
|
96 |
by passing the -Yapi-name flag to the tchk, where api-name
|
|
|
97 |
<EM>is one of the API designators listed below</EM>. APIs fall into
|
|
|
98 |
two categories: base APIs and extension APIs. If more than one base
|
|
|
99 |
API is specified to tchk, only the last one is used for checking;
|
|
|
100 |
the others are ignored. Additional extension APIs, however, may be
|
|
|
101 |
used in addition to any suitable base API.<P>
|
|
|
102 |
The base APIs available are:<P>
|
|
|
103 |
<UL>
|
|
|
104 |
<LI>ansi ANSI X3.159;<P>
|
|
|
105 |
<LI>iso ISO MSE 9899:1990(Amendment 1:1993(E));<P>
|
|
|
106 |
<LI>posix POSIX 1003.1;<P>
|
|
|
107 |
<LI>posix2 POSIX 1003.2;<P>
|
|
|
108 |
<LI>xpg3 X/Open Portability Guide 3;<P>
|
|
|
109 |
<LI>xpg4 X/Open Portability Guide 4;<P>
|
|
|
110 |
<LI>cose COSE 1170;<P>
|
|
|
111 |
<LI>svid3 System V Interface Definition 3rd Edition;<P>
|
|
|
112 |
<LI>aes AES Revision A;<P>
|
|
|
113 |
<LI>system System headers as main API.<P>
|
|
|
114 |
</UL>
|
|
|
115 |
and the extension APIs are:<P>
|
|
|
116 |
<UL>
|
|
|
117 |
<LI>bsd_extn BSD-like extension for use with POSIX etc.;<P>
|
|
|
118 |
<LI>x5_lib X11 (Release 5) Library;<P>
|
|
|
119 |
<LI>x5_t X11 (Release 5) Intrinsics Toolkit;<P>
|
|
|
120 |
<LI>x5_mu X11 (Release 5) Miscellaneous Utilities;<P>
|
|
|
121 |
<LI>x5_aw X11 (Release 5) Athena Widgets;<P>
|
|
|
122 |
<LI>x5_mit X11 (Release 5) MIT Implementation;<P>
|
|
|
123 |
<LI>x5_proto X11 (Release 5) Protocol Extension;<P>
|
|
|
124 |
<LI>x5_ext X11 (Release 5) Extensions;<P>
|
|
|
125 |
<LI>x5_private X11 (Release 5) private headers (otherwise protected
|
|
|
126 |
);<P>
|
|
|
127 |
<LI>motif Motif 1.1;<P>
|
|
|
128 |
<LI>system+ System headers as last resort API. Search the system headers
|
|
|
129 |
only for those objects for which no declaration or definition can
|
|
|
130 |
be found within the base API.<P>
|
|
|
131 |
</UL>
|
|
|
132 |
<A NAME=S12>
|
|
|
133 |
<H3>2.1.4 Individual command line checking options</H3>
|
|
|
134 |
Some of the checks available can be controlled using a command line
|
|
|
135 |
option of the form -Xopt,opt,..., where the various opt options give
|
|
|
136 |
a comma-separated list of commands. These commands have the form test=status,
|
|
|
137 |
where test is the name of the check, and status is either check (apply
|
|
|
138 |
check and give an error if it fails), warn (apply check and give a
|
|
|
139 |
warning if it fails) or dont (do not apply check). The names of checks
|
|
|
140 |
can be found with their descriptions in Chapters 3 - 8; for example
|
|
|
141 |
the check for implicit function declarations described in
|
|
|
142 |
<A HREF="tdfc6.html#30">3.4.1</A> may be switched on using <CODE>-X:implicit_func=check
|
|
|
143 |
</CODE>.<P>
|
|
|
144 |
<A NAME=S13>
|
|
|
145 |
<H3>2.1.5 Construct a customised checking environment</H3>
|
|
|
146 |
The individual checks performed by the C static checker are generally
|
|
|
147 |
controlled by #pragma directives. The reason for this is that the
|
|
|
148 |
ISO standard places no restrictions on the syntax following a #pragma
|
|
|
149 |
preprocessing directive, and most compilers/checkers can be configured
|
|
|
150 |
to ignore any unknown #pragma directives they encounter.<P>
|
|
|
151 |
Most of these directives begin:<P>
|
|
|
152 |
<PRE>
|
|
|
153 |
#pragma TenDRA ...
|
|
|
154 |
</PRE>
|
|
|
155 |
and are always checked for syntactical correctness. The individual
|
|
|
156 |
directives, together with the checks they control are described in
|
|
|
157 |
Chapters 3 - 8. Section 2.2 describes the method of constructing a
|
|
|
158 |
new checking profile from these individual checks.<P>
|
|
|
159 |
<A NAME=S14>
|
|
|
160 |
<HR><H2>2.2 <A NAME=13>Scoping checking profiles</H2>
|
|
|
161 |
Almost all the available checks are scoped (exceptions will be mentioned
|
|
|
162 |
in the description of the check). A new checking scope may be started
|
|
|
163 |
by inserting the pragma:<P>
|
|
|
164 |
<PRE>
|
|
|
165 |
#pragma TenDRA begin
|
|
|
166 |
</PRE>
|
|
|
167 |
at the outermost level. The scope runs until the matching:<P>
|
|
|
168 |
<PRE>
|
|
|
169 |
#pragma TenDRA end
|
|
|
170 |
</PRE>
|
|
|
171 |
directive, or to the end of the translation unit (the ISO C standard
|
|
|
172 |
definition of a translation unit as being a source file, together
|
|
|
173 |
with any headers or source files included using the #include preprocessing
|
|
|
174 |
directive, less any source lines skipped by any of the conditional
|
|
|
175 |
inclusion preprocessing directives, is used throughout this document).
|
|
|
176 |
<P>
|
|
|
177 |
Checking scopes may be nested in the obvious way.<P>
|
|
|
178 |
Each new checking scope inherits its initial set of checks from the
|
|
|
179 |
checking scope which immediately contains it (this includes the implicit
|
|
|
180 |
main checking scope consisting of the entire source file). Any checks
|
|
|
181 |
switched on or off within the scope apply only to that scope and any
|
|
|
182 |
scope it contains. The set of checks applied reverts to its previous
|
|
|
183 |
state at the end of a scope. Thus, for example:<P>
|
|
|
184 |
<PRE>
|
|
|
185 |
#pragma TenDRA variable analysis on
|
|
|
186 |
/* Variable analysis is on here */
|
|
|
187 |
#pragma TenDRA begin
|
|
|
188 |
#pragma TenDRA variable analysis off
|
|
|
189 |
/* Variable analysis is off here */
|
|
|
190 |
#pragma TenDRA end
|
|
|
191 |
/* Variable analysis is on again here */
|
|
|
192 |
</PRE>
|
|
|
193 |
Once a check has been set any attempt to change its status within
|
|
|
194 |
the same scope is flagged as an error. If checks need to be switched
|
|
|
195 |
on and off in the same source file, they must be properly scoped.
|
|
|
196 |
The built-in compilation modes have the entire source file as their
|
|
|
197 |
scope.<P>
|
|
|
198 |
The method of applying different checking profiles to different parts
|
|
|
199 |
of a program clearly needs to take into account those properties of
|
|
|
200 |
C which can circumvent such scoping. Consider for example:<P>
|
|
|
201 |
<PRE>
|
|
|
202 |
#pragma TenDRA begin
|
|
|
203 |
#pragma TenDRA unknown escape allow
|
|
|
204 |
#define STRING "hello\!"
|
|
|
205 |
#pragma TenDRA end
|
|
|
206 |
char * f () {
|
|
|
207 |
return ( STRING ) ;
|
|
|
208 |
}
|
|
|
209 |
</PRE>
|
|
|
210 |
The macro STRING is defined in an area where unknown escape sequences,
|
|
|
211 |
such as \!, are allowed, but it is expanded in an area where they
|
|
|
212 |
are not allowed (this is the default setting). The conventional approach
|
|
|
213 |
to macro expansion would lead to the unknown escape sequence being
|
|
|
214 |
flagged as an error, even though the user probably intended to avoid
|
|
|
215 |
this. The checker therefore expands all macros using the checking
|
|
|
216 |
profile in which they were defined, rather than the current checking
|
|
|
217 |
scope.<P>
|
|
|
218 |
The directives describing the user's desired checking profile could
|
|
|
219 |
be included directly in the program itself, ideally in some configuration
|
|
|
220 |
file which is #include'd in all source files. It is however perhaps
|
|
|
221 |
more appropriate to store the directives as a startup file, <EM>file</EM>
|
|
|
222 |
say, which is passed to the checker using the<CODE> -f</CODE><EM>file</EM><CODE>
|
|
|
223 |
</CODE>command line option. It should be noted that user-defined compilation
|
|
|
224 |
modes are defined on top of a built-in mode base (normally Xc, the
|
|
|
225 |
default mode). It is therefore important to scope the new checking
|
|
|
226 |
profile as described above.<P>
|
|
|
227 |
Names may be associated with checking scopes by using an alternative
|
|
|
228 |
form of the begin directive:<P>
|
|
|
229 |
<PRE>
|
|
|
230 |
#pragma TenDRA begin name environment identifier
|
|
|
231 |
</PRE>
|
|
|
232 |
where identifier is any valid C identifier. Thereafter a statement
|
|
|
233 |
of the form:<P>
|
|
|
234 |
<PRE>
|
|
|
235 |
#pragma TenDRA use environment identifier
|
|
|
236 |
</PRE>
|
|
|
237 |
changes the current checking environment to the environment associated
|
|
|
238 |
with identifier. <P>
|
|
|
239 |
Sometimes it may be desirable to use different checking profiles for
|
|
|
240 |
different parts of a translation unit, e.g. applying less strict checks
|
|
|
241 |
to any system headers which may be included. The checker can be configured
|
|
|
242 |
to apply a named checking scope, <EM>env_name</EM>, to any files included
|
|
|
243 |
from a directory which has been named <EM>dir_name</EM>, using:<P>
|
|
|
244 |
<PRE>
|
|
|
245 |
#pragma TenDRA directory <EM>dir_name</EM> use environment <EM>env_name</EM>
|
|
|
246 |
</PRE>
|
|
|
247 |
The directory name must be passed to the checker using the <CODE>-N</CODE><EM>dir_name
|
|
|
248 |
</EM><CODE>:</CODE><EM>dir</EM><CODE> </CODE>command line option.
|
|
|
249 |
This is equivalent to the usual <CODE>-I</CODE><CODE>dir</CODE> option
|
|
|
250 |
for specifying include paths, except that it also attaches the name
|
|
|
251 |
dir_name to the directory.<P>
|
|
|
252 |
<P>
|
|
|
253 |
<!-- FM pgf ignored -->
|
|
|
254 |
<HR>
|
|
|
255 |
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
|
|
|
256 |
Copyright © 1998.</I></P>
|
|
|
257 |
</BODY>
|
|
|
258 |
</HTML>
|