| 2 |
7u83 |
1 |
<!-- Crown Copyright (c) 1998 -->
|
|
|
2 |
<HTML>
|
|
|
3 |
<HEAD>
|
|
|
4 |
<TITLE>C Checker Reference Manual: Preprocessing checks</TITLE>
|
|
|
5 |
</HEAD>
|
|
|
6 |
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
|
|
|
7 |
<A NAME=S70>
|
|
|
8 |
<H1>C Checker Reference Manual</H1>
|
|
|
9 |
<H3>January 1998</H3>
|
|
|
10 |
<A HREF="tdfc10.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
|
|
|
11 |
<A HREF="tdfc8.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="#S71"><B>6.1 </B> - Introduction</A><DD>
|
|
|
19 |
<DT><A HREF="#S72"><B>6.2 </B> - Preprocessor directives
|
|
|
20 |
</A><DD>
|
|
|
21 |
<DT><A HREF="#S73"><B>6.3 </B> - Indented Preprocessing Directives</A><DD>
|
|
|
22 |
<DT><A HREF="#S74"><B>6.4 </B> - Multiple macro definitions</A>
|
|
|
23 |
<DD>
|
|
|
24 |
<DT><A HREF="#S75"><B>6.5 </B> - Macro arguments</A><DD>
|
|
|
25 |
<DT><A HREF="#S76"><B>6.6 </B> - Unmatched quotes</A><DD>
|
|
|
26 |
<DT><A HREF="#S77"><B>6.7 </B> - Include depth</A><DD>
|
|
|
27 |
<DT><A HREF="#S78"><B>6.8 </B> - Text after #endif</A><DD>
|
|
|
28 |
<DT><A HREF="#S79"><B>6.9 </B> - Text after #</A><DD>
|
|
|
29 |
<DT><A HREF="#S80"><B>6.10 </B> - New line at end of file</A><DD>
|
|
|
30 |
</DL>
|
|
|
31 |
|
|
|
32 |
<HR>
|
|
|
33 |
<H1>6 Preprocessing checks</H1>
|
|
|
34 |
<A NAME=S71>
|
|
|
35 |
<HR><H2>6.1 Introduction</H2>
|
|
|
36 |
This chapter describes tchk's capabilities for checking the preprocessing
|
|
|
37 |
constructs that arise in C.<P>
|
|
|
38 |
<A NAME=S72>
|
|
|
39 |
<HR><H2>6.2 <A NAME=1>Preprocessor directives </H2>
|
|
|
40 |
By default, the TenDRA C checker understands those preprocessor directives
|
|
|
41 |
specified by the ISO C standard, section 6.8, i.e. #if, #ifdef, #ifndef,
|
|
|
42 |
#elif, #else, #endif, #error, #line and #pragma. As has been mentioned,
|
|
|
43 |
#pragma statements play a significant role in the checker. While any
|
|
|
44 |
recognised #pragma statements are processed, all unknown pragma statements
|
|
|
45 |
are ignored by default. The check to detect unknown pragma statements
|
|
|
46 |
is controlled by:<P>
|
|
|
47 |
<PRE>
|
|
|
48 |
#pragma TenDRA unknown pragma <EM>permit</EM>
|
|
|
49 |
</PRE>
|
|
|
50 |
The option for <EM>permit</EM> are <CODE>disallow</CODE> (raise an
|
|
|
51 |
error if an unknown pragma is encountered), <CODE>warning</CODE> (allow
|
|
|
52 |
unknown pragmas with a warning), or <CODE>allow</CODE> (allow unknown
|
|
|
53 |
pragmas without comment).<P>
|
|
|
54 |
In addition, the common non-ISO preprocessor directives, #file, #ident,
|
|
|
55 |
#assert, #unassert and #weak may be permitted using:<P>
|
|
|
56 |
<PRE>
|
|
|
57 |
#pragma TenDRA directive <EM>dir</EM> allow
|
|
|
58 |
</PRE>
|
|
|
59 |
where <EM>dir</EM> is the appropriate one of <CODE>file</CODE>, <CODE>ident
|
|
|
60 |
</CODE>, <CODE>assert</CODE>, <CODE>unassert</CODE> or <CODE>weak</CODE>.
|
|
|
61 |
If <CODE>allow</CODE> is replaced by <CODE>warning</CODE> then the
|
|
|
62 |
directive is allowed, but a warning is issued. In either case, the
|
|
|
63 |
modifier <CODE>(ignore) </CODE>may be added to indicate that, although
|
|
|
64 |
the directive is allowed, its effect is ignored. Thus for example:<P>
|
|
|
65 |
<PRE>
|
|
|
66 |
#pragma TenDRA directive ident (ignore) allow
|
|
|
67 |
</PRE>
|
|
|
68 |
causes the checker to ignore any #ident directives without raising
|
|
|
69 |
any errors.<P>
|
|
|
70 |
Finally, the directive dir can be disallowed using:<P>
|
|
|
71 |
<PRE>
|
|
|
72 |
#pragma TenDRA directive <EM>dir</EM> disallow
|
|
|
73 |
</PRE>
|
|
|
74 |
Any other unknown preprocessing directives cause the checker to raise
|
|
|
75 |
an error in the default mode. The pragma may be used to force the
|
|
|
76 |
checker to ignore such directives without raising any errors.<P>
|
|
|
77 |
<PRE>
|
|
|
78 |
#pragma TenDRA unknown directive allow
|
|
|
79 |
</PRE>
|
|
|
80 |
<CODE>Disallow</CODE> and <CODE>warning</CODE> variants are also available.<P>
|
|
|
81 |
<A NAME=S73>
|
|
|
82 |
<HR><H2>6.3 <A NAME=7>Indented Preprocessing Directives</H2>
|
|
|
83 |
The ISO C standard allows white space to occur before the # in a preprocessing
|
|
|
84 |
directive, and between the # and the directive name. Many older preprocessors
|
|
|
85 |
have problems with such directives. The checker's treatment of such
|
|
|
86 |
directives can be set using:<P>
|
|
|
87 |
<PRE>
|
|
|
88 |
#pragma TenDRA indented # directive <EM>permit</EM>
|
|
|
89 |
</PRE>
|
|
|
90 |
which detects white space before the # and:<P>
|
|
|
91 |
<PRE>
|
|
|
92 |
#pragma TenDRA indented directive after # <EM>permit</EM>
|
|
|
93 |
</PRE>
|
|
|
94 |
which detects white space between the # and the directive name. The
|
|
|
95 |
options for <EM>permit</EM> are <CODE>allow</CODE>, <CODE>warning</CODE>
|
|
|
96 |
or <CODE>disallow</CODE> as usual. The default checking profile allows
|
|
|
97 |
both forms of indented directives.<P>
|
|
|
98 |
<A NAME=S74>
|
|
|
99 |
<HR><H2>6.4 <A NAME=9>Multiple macro definitions</H2>
|
|
|
100 |
The ISO C standard states that, for two definitions of a function-like
|
|
|
101 |
macro to be equal, both the spelling of the parameters and the macro
|
|
|
102 |
definition must be equal. Thus, for example, in:<P>
|
|
|
103 |
<PRE>
|
|
|
104 |
#define f( x ) ( x )
|
|
|
105 |
#define f( y ) ( y )
|
|
|
106 |
</PRE>
|
|
|
107 |
the two definitions of f are not equal, despite the fact that they
|
|
|
108 |
are clearly equivalent. Tchk has an alternative definition of macro
|
|
|
109 |
equality which allows for consistent substitution of parameter names.
|
|
|
110 |
The type of macro equality used is controlled by:<P>
|
|
|
111 |
<PRE>
|
|
|
112 |
#pragma TenDRA weak macro equality allow
|
|
|
113 |
</PRE>
|
|
|
114 |
where permit is <CODE>allow</CODE> (use alternative definition of
|
|
|
115 |
macro equality),<CODE>warning</CODE> (as for allow but raise a warning),
|
|
|
116 |
or <CODE>disallow</CODE> (use the ISO C definition of macro equality
|
|
|
117 |
- this is the default setting).<P>
|
|
|
118 |
More generally, the pragma: <P>
|
|
|
119 |
<PRE>
|
|
|
120 |
#pragma TenDRA extra macro definition allow
|
|
|
121 |
</PRE>
|
|
|
122 |
allows macros to be redefined, both consistently and inconsistently.
|
|
|
123 |
If the definitions are incompatible, the first definition is overwritten.
|
|
|
124 |
This pragma has a <CODE>disallow</CODE> variant, which resets the
|
|
|
125 |
check to its default mode. <P>
|
|
|
126 |
<A NAME=S75>
|
|
|
127 |
<HR><H2>6.5 <A NAME=11>Macro arguments</H2>
|
|
|
128 |
According to the ISO C standard, section 6.8.3, if a macro argument
|
|
|
129 |
contains a sequence of preprocessing tokens that would otherwise act
|
|
|
130 |
as a preprocessing directive, the behaviour is undefined. Tchk allows
|
|
|
131 |
preprocessing directives in macro arguments by default. The check
|
|
|
132 |
to detect such macro arguments is controlled by:<P>
|
|
|
133 |
<PRE>
|
|
|
134 |
#pragma TenDRA directive as macro argument <EM>permit</EM>
|
|
|
135 |
</PRE>
|
|
|
136 |
where <EM>permit</EM> is <CODE>allow</CODE>, <CODE>warning</CODE>
|
|
|
137 |
or <CODE>disallow</CODE>.<P>
|
|
|
138 |
The ISO C standard, section 6.8.3.2, also states that each # preprocessing
|
|
|
139 |
token in the replacement list for a function-like macro shall be followed
|
|
|
140 |
by a parameter as the next preprocessing token in the replacement
|
|
|
141 |
list. By default, if tchk encounters a # in a function-like macro
|
|
|
142 |
replacement list which is not followed by a parameter of the macro
|
|
|
143 |
an error is raised. The checker's behaviour in this situation is controlled
|
|
|
144 |
by: <P>
|
|
|
145 |
<PRE>
|
|
|
146 |
#pragma TenDRA no ident after # <EM>permit</EM>
|
|
|
147 |
</PRE>
|
|
|
148 |
where the options for <EM>permit</EM> are <CODE>allow</CODE> (do not
|
|
|
149 |
raise errors), <CODE>disallow</CODE> (default mode) and <CODE>warning</CODE>
|
|
|
150 |
(raise warnings instead of errors). <P>
|
|
|
151 |
<A NAME=S76>
|
|
|
152 |
<HR><H2>6.6 <A NAME=15>Unmatched quotes</H2>
|
|
|
153 |
The ISO C standard, section 6.1, states that if a ` or " character
|
|
|
154 |
matches the category of preprocessing tokens described as "single
|
|
|
155 |
non-whitespace-characters that do not lexically match the other preprocessing
|
|
|
156 |
token categories", then the behaviour is undefined. For example:<P>
|
|
|
157 |
<PRE>
|
|
|
158 |
#define a `b
|
|
|
159 |
</PRE>
|
|
|
160 |
would result in undefined behaviour. By default the ` character is
|
|
|
161 |
ignored by tchk. A check to detect such statements may be controlled
|
|
|
162 |
by:<P>
|
|
|
163 |
<PRE>
|
|
|
164 |
#pragma TenDRA unmatched quote <EM>permit</EM>
|
|
|
165 |
</PRE>
|
|
|
166 |
<EM>The usual</EM><CODE> allow</CODE>, <CODE>warning</CODE> and <CODE>disallow
|
|
|
167 |
</CODE> options are available.<P>
|
|
|
168 |
<A NAME=S77>
|
|
|
169 |
<HR><H2>6.7 <A NAME=17>Include depth</H2>
|
|
|
170 |
Most preprocessors set a maximum depth for #include directives (which
|
|
|
171 |
may be limited by the maximum number of files which can be open on
|
|
|
172 |
the host system). By default, the checker supports a depth equal to
|
|
|
173 |
this maximum number. However, a smaller maximum depth can be set using:<P>
|
|
|
174 |
<PRE>
|
|
|
175 |
#pragma TenDRA includes depth n
|
|
|
176 |
</PRE>
|
|
|
177 |
where <CODE>n</CODE> can be any positive integral constant.<P>
|
|
|
178 |
<A NAME=S78>
|
|
|
179 |
<HR><H2>6.8 <A NAME=19>Text after #endif</H2>
|
|
|
180 |
The ISO C standard, section 6.8, specifies that #endif and #else preprocessor
|
|
|
181 |
directives do not take any arguments, but should be followed by a
|
|
|
182 |
newline. In the default checking mode, tchk raises an error when #endif
|
|
|
183 |
or #else statements are not directly followed by a new line. This
|
|
|
184 |
behaviour may be modified using:<P>
|
|
|
185 |
<PRE>
|
|
|
186 |
#pragma TenDRA text after directive <EM>permit</EM>
|
|
|
187 |
</PRE>
|
|
|
188 |
where <EM>permit</EM> is <CODE>allow</CODE> (no errors are raised
|
|
|
189 |
and any text on the same line as the #endif or #else statement is
|
|
|
190 |
ignored), <CODE>warning</CODE> or <CODE>disallow</CODE>.<P>
|
|
|
191 |
<A NAME=S79>
|
|
|
192 |
<HR><H2>6.9 <A NAME=21>Text after #</H2>
|
|
|
193 |
The ISO C standard specifies that a # occuring outside of a macro
|
|
|
194 |
replacement list must be followed by a new line or by a preprocessing
|
|
|
195 |
directive and this is enforced by the checker in default mode . The
|
|
|
196 |
check is controlled by:<P>
|
|
|
197 |
<PRE>
|
|
|
198 |
#pragma TenDRA no directive/nline after ident <EM>permit</EM>
|
|
|
199 |
</PRE>
|
|
|
200 |
where <EM>permit</EM> may be <CODE>allow, disallow</CODE> or
|
|
|
201 |
<CODE>warning</CODE>.<P>
|
|
|
202 |
<A NAME=S80>
|
|
|
203 |
<HR><H2>6.10 <A NAME=23>New line at end of file</H2>
|
|
|
204 |
The ISO C standard, section 5.1.1.2, states that source files must
|
|
|
205 |
end with new lines. Files which do not end in new lines are flagged
|
|
|
206 |
as errors by the checker in default mode. The behaviour can be modified
|
|
|
207 |
using:<P>
|
|
|
208 |
<PRE>
|
|
|
209 |
#pragma TenDRA no nline after file end <EM>permit</EM>
|
|
|
210 |
</PRE>
|
|
|
211 |
where <EM>permit</EM> has the usual <CODE>allow</CODE><EM>,</EM><CODE>
|
|
|
212 |
disallow</CODE> and <CODE>warning</CODE> options.<P>
|
|
|
213 |
<!-- FM pgf ignored -->
|
|
|
214 |
<HR>
|
|
|
215 |
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
|
|
|
216 |
Copyright © 1998.</I></P>
|
|
|
217 |
</BODY>
|
|
|
218 |
</HTML>
|