1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation. A copy of
the license is included in the
section entitled "GNU Free Documentation License".
This manual contains no Invariant Sections. The Front-Cover Texts are
(a) (see below), and the Back-Cover Texts are (b) (see below).
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development. -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The C Preprocessor: Pragmas</title>
<meta name="description" content="The C Preprocessor: Pragmas">
<meta name="keywords" content="The C Preprocessor: Pragmas">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Other-Directives.html#Other-Directives" rel="next" title="Other Directives">
<link href="Line-Control.html#Line-Control" rel="previous" title="Line Control">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Pragmas"></a>
<div class="header">
<p>
Next: <a href="Other-Directives.html#Other-Directives" accesskey="n" rel="next">Other Directives</a>, Previous: <a href="Line-Control.html#Line-Control" accesskey="p" rel="previous">Line Control</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Pragmas-1"></a>
<h2 class="chapter">7 Pragmas</h2>
<a name="index-pragma-directive"></a>
<p>The ‘<samp>#pragma</samp>’ directive is the method specified by the C standard
for providing additional information to the compiler, beyond what is
conveyed in the language itself. The forms of this directive
(commonly known as <em>pragmas</em>) specified by C standard are prefixed with
<code>STDC</code>. A C compiler is free to attach any meaning it likes to other
pragmas. Most GNU-defined, supported pragmas have been given a
<code>GCC</code> prefix.
</p>
<a name="index-_005fPragma"></a>
<p>C99 introduced the <code><span class="nolinebreak">_Pragma</span><!-- /@w --></code> operator. This feature addresses a
major problem with ‘<samp>#pragma</samp>’: being a directive, it cannot be
produced as the result of macro expansion. <code><span class="nolinebreak">_Pragma</span><!-- /@w --></code> is an
operator, much like <code>sizeof</code> or <code>defined</code>, and can be embedded
in a macro.
</p>
<p>Its syntax is <code><span class="nolinebreak">_Pragma</span> (<var><span class="nolinebreak">string-literal</span></var>)<!-- /@w --></code>, where
<var>string-literal</var> can be either a normal or wide-character string
literal. It is destringized, by replacing all ‘<samp>\\</samp>’ with a single
‘<samp>\</samp>’ and all ‘<samp>\"</samp>’ with a ‘<samp>"</samp>’. The result is then
processed as if it had appeared as the right hand side of a
‘<samp>#pragma</samp>’ directive. For example,
</p>
<div class="smallexample">
<pre class="smallexample">_Pragma ("GCC dependency \"parse.y\"")
</pre></div>
<p>has the same effect as <code>#pragma GCC dependency "parse.y"</code>. The
same effect could be achieved using macros, for example
</p>
<div class="smallexample">
<pre class="smallexample">#define DO_PRAGMA(x) _Pragma (#x)
DO_PRAGMA (GCC dependency "parse.y")
</pre></div>
<p>The standard is unclear on where a <code>_Pragma</code> operator can appear.
The preprocessor does not accept it within a preprocessing conditional
directive like ‘<samp>#if</samp>’. To be safe, you are probably best keeping it
out of directives other than ‘<samp>#define</samp>’, and putting it on a line of
its own.
</p>
<p>This manual documents the pragmas which are meaningful to the
preprocessor itself. Other pragmas are meaningful to the C or C++
compilers. They are documented in the GCC manual.
</p>
<p>GCC plugins may provide their own pragmas.
</p>
<dl compact="compact">
<dt><code>#pragma GCC dependency</code>
<a name="index-_0023pragma-GCC-dependency"></a>
</dt>
<dd><p><code>#pragma GCC dependency</code> allows you to check the relative dates of
the current file and another file. If the other file is more recent than
the current file, a warning is issued. This is useful if the current
file is derived from the other file, and should be regenerated. The
other file is searched for using the normal include search path.
Optional trailing text can be used to give more information in the
warning message.
</p>
<div class="smallexample">
<pre class="smallexample">#pragma GCC dependency "parse.y"
#pragma GCC dependency "/usr/include/time.h" rerun fixincludes
</pre></div>
</dd>
<dt><code>#pragma GCC poison</code>
<a name="index-_0023pragma-GCC-poison"></a>
</dt>
<dd><p>Sometimes, there is an identifier that you want to remove completely
from your program, and make sure that it never creeps back in. To
enforce this, you can <em>poison</em> the identifier with this pragma.
<code>#pragma GCC poison</code> is followed by a list of identifiers to
poison. If any of those identifiers appears anywhere in the source
after the directive, it is a hard error. For example,
</p>
<div class="smallexample">
<pre class="smallexample">#pragma GCC poison printf sprintf fprintf
sprintf(some_string, "hello");
</pre></div>
<p>will produce an error.
</p>
<p>If a poisoned identifier appears as part of the expansion of a macro
which was defined before the identifier was poisoned, it will <em>not</em>
cause an error. This lets you poison an identifier without worrying
about system headers defining macros that use it.
</p>
<p>For example,
</p>
<div class="smallexample">
<pre class="smallexample">#define strrchr rindex
#pragma GCC poison rindex
strrchr(some_string, 'h');
</pre></div>
<p>will not produce an error.
</p>
</dd>
<dt><code>#pragma GCC system_header</code>
<a name="index-_0023pragma-GCC-system_005fheader-1"></a>
</dt>
<dd><p>This pragma takes no arguments. It causes the rest of the code in the
current file to be treated as if it came from a system header.
See <a href="System-Headers.html#System-Headers">System Headers</a>.
</p>
</dd>
<dt><code>#pragma GCC warning</code>
<a name="index-_0023pragma-GCC-warning"></a>
</dt>
<dt><code>#pragma GCC error</code>
<a name="index-_0023pragma-GCC-error"></a>
</dt>
<dd><p><code>#pragma GCC warning "message"</code> causes the preprocessor to issue
a warning diagnostic with the text ‘<samp>message</samp>’. The message
contained in the pragma must be a single string literal. Similarly,
<code>#pragma GCC error "message"</code> issues an error message. Unlike
the ‘<samp>#warning</samp>’ and ‘<samp>#error</samp>’ directives, these pragmas can be
embedded in preprocessor macros using ‘<samp>_Pragma</samp>’.
</p>
</dd>
<dt><code>#pragma once</code>
<a name="index-_0023pragma-once"></a>
</dt>
<dd><p>If <code>#pragma once</code> is seen when scanning a header file, that
file will never be read again, no matter what. It is a less-portable
alternative to using ‘<samp>#ifndef</samp>’ to guard the contents of header files
against multiple inclusions.
</p>
</dd>
<dt><code>#pragma region {tokens}...</code>
<a name="index-_0023pragma-region-_007btokens_007d_002e_002e_002e"></a>
</dt>
<dt><code>#pragma endregion {tokens}...</code>
<a name="index-_0023pragma-endregion-_007btokens_007d_002e_002e_002e"></a>
</dt>
<dd><p>These pragmas are accepted, but have no effect.
</p>
</dd>
</dl>
<hr>
<div class="header">
<p>
Next: <a href="Other-Directives.html#Other-Directives" accesskey="n" rel="next">Other Directives</a>, Previous: <a href="Line-Control.html#Line-Control" accesskey="p" rel="previous">Line Control</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
