aarch64-linux-gnu-4.9/share/doc/cpp/Once_002dOnly-Headers.html - toolchains/linux-x86/gcc - Git at Google

 <!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: Once-Only Headers</title>

 <meta name="description" content="The C Preprocessor: Once-Only Headers">
 <meta name="keywords" content="The C Preprocessor: Once-Only Headers">
 <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="Header-Files.html#Header-Files" rel="up" title="Header Files">
 <link href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" rel="next" title="Alternatives to Wrapper #ifndef">
 <link href="Search-Path.html#Search-Path" rel="prev" title="Search Path">
 <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="Once_002dOnly-Headers"></a>
 <div class="header">
 <p>
 Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="prev">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> &nbsp; [<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="Once_002dOnly-Headers-1"></a>
 <h3 class="section">2.4 Once-Only Headers</h3>
 <a name="index-repeated-inclusion"></a>
 <a name="index-including-just-once"></a>
 <a name="index-wrapper-_0023ifndef"></a>

 <p>If a header file happens to be included twice, the compiler will process
 its contents twice.  This is very likely to cause an error, e.g. when the
 compiler sees the same structure definition twice.  Even if it does not,
 it will certainly waste time.
 </p>
 <p>The standard way to prevent this is to enclose the entire real contents
 of the file in a conditional, like this:
 </p>
 <div class="smallexample">
 <pre class="smallexample">/* File foo.  */
 #ifndef FILE_FOO_SEEN
 #define FILE_FOO_SEEN

 <var>the entire file</var>

 #endif /* !FILE_FOO_SEEN */
 </pre></div>

 <p>This construct is commonly known as a <em>wrapper #ifndef</em>.
 When the header is included again, the conditional will be false,
 because <code>FILE_FOO_SEEN</code> is defined.  The preprocessor will skip
 over the entire contents of the file, and the compiler will not see it
 twice.
 </p>
 <p>CPP optimizes even further.  It remembers when a header file has a
 wrapper &lsquo;<samp>#ifndef</samp>&rsquo;.  If a subsequent &lsquo;<samp>#include</samp>&rsquo; specifies that
 header, and the macro in the &lsquo;<samp>#ifndef</samp>&rsquo; is still defined, it does
 not bother to rescan the file at all.
 </p>
 <p>You can put comments outside the wrapper.  They will not interfere with
 this optimization.
 </p>
 <a name="index-controlling-macro"></a>
 <a name="index-guard-macro"></a>
 <p>The macro <code>FILE_FOO_SEEN</code> is called the <em>controlling macro</em> or
 <em>guard macro</em>.  In a user header file, the macro name should not
 begin with &lsquo;<samp>_</samp>&rsquo;.  In a system header file, it should begin with
 &lsquo;<samp>__</samp>&rsquo; to avoid conflicts with user programs.  In any kind of header
 file, the macro name should contain the name of the file and some
 additional text, to avoid conflicts with other header files.
 </p>
 <hr>
 <div class="header">
 <p>
 Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="prev">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> &nbsp; [<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>
	<!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: Once-Only Headers</title>

	<meta name="description" content="The C Preprocessor: Once-Only Headers">
	<meta name="keywords" content="The C Preprocessor: Once-Only Headers">
	<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="Header-Files.html#Header-Files" rel="up" title="Header Files">
	<link href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" rel="next" title="Alternatives to Wrapper #ifndef">
	<link href="Search-Path.html#Search-Path" rel="prev" title="Search Path">
	<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="Once_002dOnly-Headers"></a>
	<div class="header">
	<p>
	Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="prev">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</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="Once_002dOnly-Headers-1"></a>
	<h3 class="section">2.4 Once-Only Headers</h3>
	<a name="index-repeated-inclusion"></a>
	<a name="index-including-just-once"></a>
	<a name="index-wrapper-_0023ifndef"></a>

	<p>If a header file happens to be included twice, the compiler will process
	its contents twice. This is very likely to cause an error, e.g. when the
	compiler sees the same structure definition twice. Even if it does not,
	it will certainly waste time.
	</p>
	<p>The standard way to prevent this is to enclose the entire real contents
	of the file in a conditional, like this:
	</p>
	<div class="smallexample">
	<pre class="smallexample">/* File foo. */
	#ifndef FILE_FOO_SEEN
	#define FILE_FOO_SEEN

	<var>the entire file</var>

	#endif /* !FILE_FOO_SEEN */
	</pre></div>

	<p>This construct is commonly known as a <em>wrapper #ifndef</em>.
	When the header is included again, the conditional will be false,
	because <code>FILE_FOO_SEEN</code> is defined. The preprocessor will skip
	over the entire contents of the file, and the compiler will not see it
	twice.
	</p>
	<p>CPP optimizes even further. It remembers when a header file has a
	wrapper ‘<samp>#ifndef</samp>’. If a subsequent ‘<samp>#include</samp>’ specifies that
	header, and the macro in the ‘<samp>#ifndef</samp>’ is still defined, it does
	not bother to rescan the file at all.
	</p>
	<p>You can put comments outside the wrapper. They will not interfere with
	this optimization.
	</p>
	<a name="index-controlling-macro"></a>
	<a name="index-guard-macro"></a>
	<p>The macro <code>FILE_FOO_SEEN</code> is called the <em>controlling macro</em> or
	<em>guard macro</em>. In a user header file, the macro name should not
	begin with ‘<samp>_</samp>’. In a system header file, it should begin with
	‘<samp>__</samp>’ to avoid conflicts with user programs. In any kind of header
	file, the macro name should contain the name of the file and some
	additional text, to avoid conflicts with other header files.
	</p>
	<hr>
	<div class="header">
	<p>
	Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="prev">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</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>