1<html lang="en"> 2<head> 3<title>Wrapper 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="Computed-Includes.html#Computed-Includes" title="Computed Includes"> 10<link rel="next" href="System-Headers.html#System-Headers" title="System Headers"> 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="Wrapper-Headers"></a> 54<p> 55Next: <a rel="next" accesskey="n" href="System-Headers.html#System-Headers">System Headers</a>, 56Previous: <a rel="previous" accesskey="p" href="Computed-Includes.html#Computed-Includes">Computed Includes</a>, 57Up: <a rel="up" accesskey="u" href="Header-Files.html#Header-Files">Header Files</a> 58<hr> 59</div> 60 61<h3 class="section">2.7 Wrapper Headers</h3> 62 63<p><a name="index-wrapper-headers-36"></a><a name="index-overriding-a-header-file-37"></a><a name="index-g_t_0023include_005fnext-38"></a> 64Sometimes it is necessary to adjust the contents of a system-provided 65header file without editing it directly. GCC's <samp><span class="command">fixincludes</span></samp> 66operation does this, for example. One way to do that would be to create 67a new header file with the same name and insert it in the search path 68before the original header. That works fine as long as you're willing 69to replace the old header entirely. But what if you want to refer to 70the old header from the new one? 71 72 <p>You cannot simply include the old header with ‘<samp><span class="samp">#include</span></samp>’. That 73will start from the beginning, and find your new header again. If your 74header is not protected from multiple inclusion (see <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a>), it will recurse infinitely and cause a fatal error. 75 76 <p>You could include the old header with an absolute pathname: 77<pre class="smallexample"> #include "/usr/include/old-header.h" 78</pre> 79 <p class="noindent">This works, but is not clean; should the system headers ever move, you 80would have to edit the new headers to match. 81 82 <p>There is no way to solve this problem within the C standard, but you can 83use the GNU extension ‘<samp><span class="samp">#include_next</span></samp>’. It means, “Include the 84<em>next</em> file with this name”. This directive works like 85‘<samp><span class="samp">#include</span></samp>’ except in searching for the specified file: it starts 86searching the list of header file directories <em>after</em> the directory 87in which the current file was found. 88 89 <p>Suppose you specify <samp><span class="option">-I /usr/local/include</span></samp>, and the list of 90directories to search also includes <samp><span class="file">/usr/include</span></samp>; and suppose 91both directories contain <samp><span class="file">signal.h</span></samp>. Ordinary <code>#include <signal.h><!-- /@w --></code> finds the file under <samp><span class="file">/usr/local/include</span></samp>. If that 92file contains <code>#include_next <signal.h><!-- /@w --></code>, it starts searching 93after that directory, and finds the file in <samp><span class="file">/usr/include</span></samp>. 94 95 <p>‘<samp><span class="samp">#include_next</span></samp>’ does not distinguish between <code><</code><var>file</var><code>></code> 96and <code>"</code><var>file</var><code>"</code> inclusion, nor does it check that the file you 97specify has the same name as the current file. It simply looks for the 98file named, starting with the directory in the search path after the one 99where the current file was found. 100 101 <p>The use of ‘<samp><span class="samp">#include_next</span></samp>’ can lead to great confusion. We 102recommend it be used only when there is no other alternative. In 103particular, it should not be used in the headers belonging to a specific 104program; it should be used only to make global corrections along the 105lines of <samp><span class="command">fixincludes</span></samp>. 106 107 </body></html> 108 109