1<html lang="en"> 2<head> 3<title>Pragmas - The C Preprocessor</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="The C Preprocessor"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="prev" href="Line-Control.html#Line-Control" title="Line Control"> 9<link rel="next" href="Other-Directives.html#Other-Directives" title="Other Directives"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1987-2013 Free Software Foundation, Inc. 13 14Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.3 or 16any later version published by the Free Software Foundation. A copy of 17the license is included in the 18section entitled ``GNU Free Documentation License''. 19 20This manual contains no Invariant Sections. The Front-Cover Texts are 21(a) (see below), and the Back-Cover Texts are (b) (see below). 22 23(a) The FSF's Front-Cover Text is: 24 25 A GNU Manual 26 27(b) The FSF's Back-Cover Text is: 28 29 You have freedom to copy and modify this GNU Manual, like GNU 30 software. Copies published by the Free Software Foundation raise 31 funds for GNU development. 32--> 33<meta http-equiv="Content-Style-Type" content="text/css"> 34<style type="text/css"><!-- 35 pre.display { font-family:inherit } 36 pre.format { font-family:inherit } 37 pre.smalldisplay { font-family:inherit; font-size:smaller } 38 pre.smallformat { font-family:inherit; font-size:smaller } 39 pre.smallexample { font-size:smaller } 40 pre.smalllisp { font-size:smaller } 41 span.sc { font-variant:small-caps } 42 span.roman { font-family:serif; font-weight:normal; } 43 span.sansserif { font-family:sans-serif; font-weight:normal; } 44--></style> 45<link rel="stylesheet" type="text/css" href="../cs.css"> 46</head> 47<body> 48<div class="node"> 49<a name="Pragmas"></a> 50<p> 51Next: <a rel="next" accesskey="n" href="Other-Directives.html#Other-Directives">Other Directives</a>, 52Previous: <a rel="previous" accesskey="p" href="Line-Control.html#Line-Control">Line Control</a>, 53Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> 54<hr> 55</div> 56 57<h2 class="chapter">7 Pragmas</h2> 58 59<p>The ‘<samp><span class="samp">#pragma</span></samp>’ directive is the method specified by the C standard 60for providing additional information to the compiler, beyond what is 61conveyed in the language itself. Three forms of this directive 62(commonly known as <dfn>pragmas</dfn>) are specified by the 1999 C standard. 63A C compiler is free to attach any meaning it likes to other pragmas. 64 65 <p>GCC has historically preferred to use extensions to the syntax of the 66language, such as <code>__attribute__</code>, for this purpose. However, GCC 67does define a few pragmas of its own. These mostly have effects on the 68entire translation unit or source file. 69 70 <p>In GCC version 3, all GNU-defined, supported pragmas have been given a 71<code>GCC</code> prefix. This is in line with the <code>STDC</code> prefix on all 72pragmas defined by C99. For backward compatibility, pragmas which were 73recognized by previous versions are still recognized without the 74<code>GCC</code> prefix, but that usage is deprecated. Some older pragmas are 75deprecated in their entirety. They are not recognized with the 76<code>GCC</code> prefix. See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. 77 78 <p><a name="index-g_t_0040code_007b_005fPragma_007d-100"></a>C99 introduces the <code>_Pragma<!-- /@w --></code> operator. This feature addresses a 79major problem with ‘<samp><span class="samp">#pragma</span></samp>’: being a directive, it cannot be 80produced as the result of macro expansion. <code>_Pragma<!-- /@w --></code> is an 81operator, much like <code>sizeof</code> or <code>defined</code>, and can be embedded 82in a macro. 83 84 <p>Its syntax is <code>_Pragma (</code><var>string-literal</var><code>)<!-- /@w --></code>, where 85<var>string-literal</var> can be either a normal or wide-character string 86literal. It is destringized, by replacing all ‘<samp><span class="samp">\\</span></samp>’ with a single 87‘<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 88processed as if it had appeared as the right hand side of a 89‘<samp><span class="samp">#pragma</span></samp>’ directive. For example, 90 91<pre class="smallexample"> _Pragma ("GCC dependency \"parse.y\"") 92</pre> 93 <p class="noindent">has the same effect as <code>#pragma GCC dependency "parse.y"</code>. The 94same effect could be achieved using macros, for example 95 96<pre class="smallexample"> #define DO_PRAGMA(x) _Pragma (#x) 97 DO_PRAGMA (GCC dependency "parse.y") 98</pre> 99 <p>The standard is unclear on where a <code>_Pragma</code> operator can appear. 100The preprocessor does not accept it within a preprocessing conditional 101directive like ‘<samp><span class="samp">#if</span></samp>’. To be safe, you are probably best keeping it 102out of directives other than ‘<samp><span class="samp">#define</span></samp>’, and putting it on a line of 103its own. 104 105 <p>This manual documents the pragmas which are meaningful to the 106preprocessor itself. Other pragmas are meaningful to the C or C++ 107compilers. They are documented in the GCC manual. 108 109 <p>GCC plugins may provide their own pragmas. 110 111 <dl> 112<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 113the current file and another file. If the other file is more recent than 114the current file, a warning is issued. This is useful if the current 115file is derived from the other file, and should be regenerated. The 116other file is searched for using the normal include search path. 117Optional trailing text can be used to give more information in the 118warning message. 119 120 <pre class="smallexample"> #pragma GCC dependency "parse.y" 121 #pragma GCC dependency "/usr/include/time.h" rerun fixincludes 122</pre> 123 <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 124from your program, and make sure that it never creeps back in. To 125enforce this, you can <dfn>poison</dfn> the identifier with this pragma. 126<code>#pragma GCC poison</code> is followed by a list of identifiers to 127poison. If any of those identifiers appears anywhere in the source 128after the directive, it is a hard error. For example, 129 130 <pre class="smallexample"> #pragma GCC poison printf sprintf fprintf 131 sprintf(some_string, "hello"); 132</pre> 133 <p class="noindent">will produce an error. 134 135 <p>If a poisoned identifier appears as part of the expansion of a macro 136which was defined before the identifier was poisoned, it will <em>not</em> 137cause an error. This lets you poison an identifier without worrying 138about system headers defining macros that use it. 139 140 <p>For example, 141 142 <pre class="smallexample"> #define strrchr rindex 143 #pragma GCC poison rindex 144 strrchr(some_string, 'h'); 145</pre> 146 <p class="noindent">will not produce an error. 147 148 <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 149current file to be treated as if it came from a system header. 150See <a href="System-Headers.html#System-Headers">System Headers</a>. 151 152 <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 153a warning diagnostic with the text ‘<samp><span class="samp">message</span></samp>’. The message 154contained in the pragma must be a single string literal. Similarly, 155<code>#pragma GCC error "message"</code> issues an error message. Unlike 156the ‘<samp><span class="samp">#warning</span></samp>’ and ‘<samp><span class="samp">#error</span></samp>’ directives, these pragmas can be 157embedded in preprocessor macros using ‘<samp><span class="samp">_Pragma</span></samp>’. 158 159 </dl> 160 161 </body></html> 162 163