GNU Info

(cpp-300.info)Wrapper Headers

---

Next: System Headers Prev: Computed Includes Up: Header Files

---

Enter node , (file) or (file)node

Wrapper Headers
===============

   Sometimes it is necessary to adjust the contents of a system-provided
header file without editing it directly.  GCC's `fixincludes' operation
does this, for example.  One way to do that would be to create a new
header file with the same name and insert it in the search path before
the original header.  That works fine as long as you're willing to
replace the old header entirely.  But what if you want to refer to the
old header from the new one?

   You cannot simply include the old header with `#include'.  That will
start from the beginning, and find your new header again.  If your
header is not protected from multiple inclusion (Note: Once-Only
Headers), it will recurse infinitely and cause a fatal error.

   You could include the old header with an absolute pathname:
     #include "/usr/include/old-header.h"

This works, but is not clean; should the system headers ever move, you
would have to edit the new headers to match.

   There is no way to solve this problem within the C standard, but you
can use the GNU extension `#include_next'.  It means, "Include the
_next_ file with this name."  This directive works like `#include'
except in searching for the specified file: it starts searching the
list of header file directories _after_ the directory in which the
current file was found.

   Suppose you specify `-I /usr/local/include', and the list of
directories to search also includes `/usr/include'; and suppose both
directories contain `signal.h'.  Ordinary `#include <signal.h>' finds
the file under `/usr/local/include'.  If that file contains
`#include_next <signal.h>', it starts searching after that directory,
and finds the file in `/usr/include'.

   `#include_next' does not distinguish between `<FILE>' and `"FILE"'
inclusion, nor does it check that the file you specify has the same
name as the current file.  It simply looks for the file named, starting
with the directory in the search path after the one where the current
file was found.

   The use of `#include_next' can lead to great confusion.  We
recommend it be used only when there is no other alternative.  In
particular, it should not be used in the headers belonging to a specific
program; it should be used only to make global corrections along the
lines of `fixincludes'.