| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1987-2015 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.2, 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="prev" 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="prev">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> |
| |
| <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. Three forms of this directive |
| (commonly known as <em>pragmas</em>) are specified by the 1999 C standard. |
| A C compiler is free to attach any meaning it likes to other pragmas. |
| </p> |
| <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> |
| <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-_005fPragma"></a> |
| <p>C99 introduces 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> |
| </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="prev">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> |
