cpp: Wrapper Headers

1 
1 2.7 Wrapper Headers
1 ===================
1 
1 Sometimes it is necessary to adjust the contents of a system-provided
1 header file without editing it directly.  GCC's 'fixincludes' operation
1 does this, for example.  One way to do that would be to create a new
1 header file with the same name and insert it in the search path before
1 the original header.  That works fine as long as you're willing to
1 replace the old header entirely.  But what if you want to refer to the
1 old header from the new one?
1 
1    You cannot simply include the old header with '#include'.  That will
1 start from the beginning, and find your new header again.  If your
11 header is not protected from multiple inclusion (⇒Once-Only
 Headers), it will recurse infinitely and cause a fatal error.
1 
1    You could include the old header with an absolute pathname:
1      #include "/usr/include/old-header.h"
1 This works, but is not clean; should the system headers ever move, you
1 would have to edit the new headers to match.
1 
1    There is no way to solve this problem within the C standard, but you
1 can use the GNU extension '#include_next'.  It means, "Include the
1 _next_ file with this name".  This directive works like '#include'
1 except in searching for the specified file: it starts searching the list
1 of header file directories _after_ the directory in which the current
1 file was found.
1 
1    Suppose you specify '-I /usr/local/include', and the list of
1 directories to search also includes '/usr/include'; and suppose both
1 directories contain 'signal.h'.  Ordinary '#include <signal.h>' finds
1 the file under '/usr/local/include'.  If that file contains
1 '#include_next <signal.h>', it starts searching after that directory,
1 and finds the file in '/usr/include'.
1 
1    '#include_next' does not distinguish between '<FILE>' and '"FILE"'
1 inclusion, nor does it check that the file you specify has the same name
1 as the current file.  It simply looks for the file named, starting with
1 the directory in the search path after the one where the current file
1 was found.
1 
1    The use of '#include_next' can lead to great confusion.  We recommend
1 it be used only when there is no other alternative.  In particular, it
1 should not be used in the headers belonging to a specific program; it
1 should be used only to make global corrections along the lines of
1 'fixincludes'.
1