1<html lang="en"> 2<head> 3<title>Once-Only Headers - 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="up" href="Header-Files.html#Header-Files" title="Header Files"> 9<link rel="prev" href="Search-Path.html#Search-Path" title="Search Path"> 10<link rel="next" href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" title="Alternatives to Wrapper #ifndef"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 141997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 152008, 2009, 2010, 2011 16Free Software Foundation, Inc. 17 18Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.3 or 20any later version published by the Free Software Foundation. A copy of 21the license is included in the 22section entitled ``GNU Free Documentation License''. 23 24This manual contains no Invariant Sections. The Front-Cover Texts are 25(a) (see below), and the Back-Cover Texts are (b) (see below). 26 27(a) The FSF's Front-Cover Text is: 28 29 A GNU Manual 30 31(b) The FSF's Back-Cover Text is: 32 33 You have freedom to copy and modify this GNU Manual, like GNU 34 software. Copies published by the Free Software Foundation raise 35 funds for GNU development. 36--> 37<meta http-equiv="Content-Style-Type" content="text/css"> 38<style type="text/css"><!-- 39 pre.display { font-family:inherit } 40 pre.format { font-family:inherit } 41 pre.smalldisplay { font-family:inherit; font-size:smaller } 42 pre.smallformat { font-family:inherit; font-size:smaller } 43 pre.smallexample { font-size:smaller } 44 pre.smalllisp { font-size:smaller } 45 span.sc { font-variant:small-caps } 46 span.roman { font-family:serif; font-weight:normal; } 47 span.sansserif { font-family:sans-serif; font-weight:normal; } 48--></style> 49<link rel="stylesheet" type="text/css" href="../cs.css"> 50</head> 51<body> 52<div class="node"> 53<a name="Once-Only-Headers"></a> 54<a name="Once_002dOnly-Headers"></a> 55<p> 56Next: <a rel="next" accesskey="n" href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef">Alternatives to Wrapper #ifndef</a>, 57Previous: <a rel="previous" accesskey="p" href="Search-Path.html#Search-Path">Search Path</a>, 58Up: <a rel="up" accesskey="u" href="Header-Files.html#Header-Files">Header Files</a> 59<hr> 60</div> 61 62<h3 class="section">2.4 Once-Only Headers</h3> 63 64<p><a name="index-repeated-inclusion-28"></a><a name="index-including-just-once-29"></a><a name="index-wrapper-_0040code_007b_0023ifndef_007d-30"></a> 65If a header file happens to be included twice, the compiler will process 66its contents twice. This is very likely to cause an error, e.g. when the 67compiler sees the same structure definition twice. Even if it does not, 68it will certainly waste time. 69 70 <p>The standard way to prevent this is to enclose the entire real contents 71of the file in a conditional, like this: 72 73<pre class="smallexample"> /* File foo. */ 74 #ifndef FILE_FOO_SEEN 75 #define FILE_FOO_SEEN 76 77 <var>the entire file</var> 78 79 #endif /* !FILE_FOO_SEEN */ 80</pre> 81 <p>This construct is commonly known as a <dfn>wrapper #ifndef</dfn>. 82When the header is included again, the conditional will be false, 83because <code>FILE_FOO_SEEN</code> is defined. The preprocessor will skip 84over the entire contents of the file, and the compiler will not see it 85twice. 86 87 <p>CPP optimizes even further. It remembers when a header file has a 88wrapper ‘<samp><span class="samp">#ifndef</span></samp>’. If a subsequent ‘<samp><span class="samp">#include</span></samp>’ specifies that 89header, and the macro in the ‘<samp><span class="samp">#ifndef</span></samp>’ is still defined, it does 90not bother to rescan the file at all. 91 92 <p>You can put comments outside the wrapper. They will not interfere with 93this optimization. 94 95 <p><a name="index-controlling-macro-31"></a><a name="index-guard-macro-32"></a>The macro <code>FILE_FOO_SEEN</code> is called the <dfn>controlling macro</dfn> or 96<dfn>guard macro</dfn>. In a user header file, the macro name should not 97begin with ‘<samp><span class="samp">_</span></samp>’. In a system header file, it should begin with 98‘<samp><span class="samp">__</span></samp>’ to avoid conflicts with user programs. In any kind of header 99file, the macro name should contain the name of the file and some 100additional text, to avoid conflicts with other header files. 101 102 </body></html> 103 104