| <html lang="en"> | |
| <head> | |
| <title>Pragmas - The C Preprocessor</title> | |
| <meta http-equiv="Content-Type" content="text/html"> | |
| <meta name="description" content="The C Preprocessor"> | |
| <meta name="generator" content="makeinfo 4.13"> | |
| <link title="Top" rel="start" href="index.html#Top"> | |
| <link rel="prev" href="Line-Control.html#Line-Control" title="Line Control"> | |
| <link rel="next" href="Other-Directives.html#Other-Directives" title="Other Directives"> | |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> | |
| <!-- | |
| Copyright (C) 1987-2013 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. | |
| --> | |
| <meta http-equiv="Content-Style-Type" content="text/css"> | |
| <style type="text/css"><!-- | |
| pre.display { font-family:inherit } | |
| pre.format { font-family:inherit } | |
| pre.smalldisplay { font-family:inherit; font-size:smaller } | |
| pre.smallformat { font-family:inherit; font-size:smaller } | |
| pre.smallexample { font-size:smaller } | |
| pre.smalllisp { font-size:smaller } | |
| span.sc { font-variant:small-caps } | |
| span.roman { font-family:serif; font-weight:normal; } | |
| span.sansserif { font-family:sans-serif; font-weight:normal; } | |
| --></style> | |
| </head> | |
| <body> | |
| <div class="node"> | |
| <a name="Pragmas"></a> | |
| <p> | |
| Next: <a rel="next" accesskey="n" href="Other-Directives.html#Other-Directives">Other Directives</a>, | |
| Previous: <a rel="previous" accesskey="p" href="Line-Control.html#Line-Control">Line Control</a>, | |
| Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> | |
| <hr> | |
| </div> | |
| <h2 class="chapter">7 Pragmas</h2> | |
| <p>The ‘<samp><span class="samp">#pragma</span></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. Three forms of this directive | |
| (commonly known as <dfn>pragmas</dfn>) are specified by the 1999 C standard. | |
| A C compiler is free to attach any meaning it likes to other pragmas. | |
| <p>GCC has historically preferred to use extensions to the syntax of the | |
| language, such as <code>__attribute__</code>, for this purpose. However, GCC | |
| does define a few pragmas of its own. These mostly have effects on the | |
| entire translation unit or source file. | |
| <p>In GCC version 3, all GNU-defined, supported pragmas have been given a | |
| <code>GCC</code> prefix. This is in line with the <code>STDC</code> prefix on all | |
| pragmas defined by C99. For backward compatibility, pragmas which were | |
| recognized by previous versions are still recognized without the | |
| <code>GCC</code> prefix, but that usage is deprecated. Some older pragmas are | |
| deprecated in their entirety. They are not recognized with the | |
| <code>GCC</code> prefix. See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. | |
| <p><a name="index-g_t_0040code_007b_005fPragma_007d-100"></a>C99 introduces the <code>_Pragma<!-- /@w --></code> operator. This feature addresses a | |
| major problem with ‘<samp><span class="samp">#pragma</span></samp>’: being a directive, it cannot be | |
| produced as the result of macro expansion. <code>_Pragma<!-- /@w --></code> is an | |
| operator, much like <code>sizeof</code> or <code>defined</code>, and can be embedded | |
| in a macro. | |
| <p>Its syntax is <code>_Pragma (</code><var>string-literal</var><code>)<!-- /@w --></code>, where | |
| <var>string-literal</var> can be either a normal or wide-character string | |
| literal. It is destringized, by replacing all ‘<samp><span class="samp">\\</span></samp>’ with a single | |
| ‘<samp><span class="samp">\</span></samp>’ and all ‘<samp><span class="samp">\"</span></samp>’ with a ‘<samp><span class="samp">"</span></samp>’. The result is then | |
| processed as if it had appeared as the right hand side of a | |
| ‘<samp><span class="samp">#pragma</span></samp>’ directive. For example, | |
| <pre class="smallexample"> _Pragma ("GCC dependency \"parse.y\"") | |
| </pre> | |
| <p class="noindent">has the same effect as <code>#pragma GCC dependency "parse.y"</code>. The | |
| same effect could be achieved using macros, for example | |
| <pre class="smallexample"> #define DO_PRAGMA(x) _Pragma (#x) | |
| DO_PRAGMA (GCC dependency "parse.y") | |
| </pre> | |
| <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><span class="samp">#if</span></samp>’. To be safe, you are probably best keeping it | |
| out of directives other than ‘<samp><span class="samp">#define</span></samp>’, and putting it on a line of | |
| its own. | |
| <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>GCC plugins may provide their own pragmas. | |
| <dl> | |
| <dt><code>#pragma GCC dependency</code><a name="index-g_t_0023pragma-GCC-dependency-101"></a><dd><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. | |
| <pre class="smallexample"> #pragma GCC dependency "parse.y" | |
| #pragma GCC dependency "/usr/include/time.h" rerun fixincludes | |
| </pre> | |
| <br><dt><code>#pragma GCC poison</code><a name="index-g_t_0023pragma-GCC-poison-102"></a><dd>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 <dfn>poison</dfn> 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, | |
| <pre class="smallexample"> #pragma GCC poison printf sprintf fprintf | |
| sprintf(some_string, "hello"); | |
| </pre> | |
| <p class="noindent">will produce an error. | |
| <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>For example, | |
| <pre class="smallexample"> #define strrchr rindex | |
| #pragma GCC poison rindex | |
| strrchr(some_string, 'h'); | |
| </pre> | |
| <p class="noindent">will not produce an error. | |
| <br><dt><code>#pragma GCC system_header</code><a name="index-g_t_0023pragma-GCC-system_005fheader-103"></a><dd>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>. | |
| <br><dt><code>#pragma GCC warning</code><a name="index-g_t_0023pragma-GCC-warning-104"></a><dt><code>#pragma GCC error</code><a name="index-g_t_0023pragma-GCC-error-105"></a><dd><code>#pragma GCC warning "message"</code> causes the preprocessor to issue | |
| a warning diagnostic with the text ‘<samp><span class="samp">message</span></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><span class="samp">#warning</span></samp>’ and ‘<samp><span class="samp">#error</span></samp>’ directives, these pragmas can be | |
| embedded in preprocessor macros using ‘<samp><span class="samp">_Pragma</span></samp>’. | |
| </dl> | |
| </body></html> | |