include_next directive

The preprocessor directive #include_next behaveslike the #include directive, except that it specifically excludesthe directory of the including file from the paths to be searched for thenamed file. All search paths up to and including the directory of the includingfile are omitted from the list of paths to be searched for the included file.This allows you to include multiple versions of a file with the same namein different parts of an application; or to include one header file in anotherheader file with the same name (without the header including itself recursively).Provided that the different file versions are stored in different directories,the directive ensures you can access each version of the file, without requiringthat you use absolute paths to specify the file name.

Read syntax diagramSkip visual syntax diagram#include_next directive syntax
 
>>-#--include_next--+-"--+-----------+--file_name--"-+---------><
                    |    '-file_path-'               |
                    '-<--+-----------+--file_name-->-'
                         '-file_path-'

The directive must only be used in header files, and the file specifiedby the file_name must be a header file. There is nodistinction between the use of double quotation marks and angle brackets toenclose the file name.

As an example of how search paths are resolved with the #include_next directive, assume that there are two versions of the file t.h: the first one, which is included in the source file t.c,is located in the subdirectory path1; the second one, which isincluded in the first one, is located in the subdirectory path2.Both directories are specified as include file search paths when t.c is compiled.

/* t.c  */

#include "t.h"

int main()
{
printf("%d", ret_val);
}

/* t.h in path1 */

#include_next "t.h"

int ret_val = RET;

/* t.h in path2 */

#define RET 55;

The #include_next directive instructs the preprocessorto skip the path1 directory and start the search for the includedfile from the path2 directory. This directive allows you to usetwo different versions of t.h and it prevents t.h frombeing included recursively.

http://publib.boulder.ibm.com/infocenter/compbgpl/v9v111/index.jsp?topic=/com.ibm.xlcpp9.bg.doc/language_ref/include_next.htm

GNU Extension

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

You cannot simply include the old header with `#include'. Thatwill start from the beginning, and find your new header again. If yourheader is not protected from multiple inclusion (see section 2.4 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, youwould have to edit the new headers to match.

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

Suppose you specify `-I /usr/local/include', and the list ofdirectories to search also includes `/usr/include'; and supposeboth directories contain `signal.h'. Ordinary #include<signal.h> finds the file under `/usr/local/include'. If thatfile contains #include_next <signal.h>, it starts searchingafter 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 youspecify has the same name as the current file. It simply looks for thefile named, starting with the directory in the search path after the onewhere the current file was found.

The use of `#include_next' can lead to great confusion. Werecommend it be used only when there is no other alternative. Inparticular, it should not be used in the headers belonging to a specificprogram; it should be used only to make global corrections along thelines of fixincludes.

http://www.delorie.com/gnu/docs/gcc/cpp_11.html