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