| <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, 1989, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, |
| 2008, 2009, 2010 |
| 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.2 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> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </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>. |
| |
| </dl> |
| |
| </body></html> |
| |
