The #include_next directive

The preprocessor directive #include_next behaves like the #include directive, except that it specifically excludes the directory of the including file from the paths to be searched for the named file. All search paths up to and including the directory of the including file 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 name in different parts of an application; or to include one header file in another header 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 requiring that you use absolute paths to specify the file name.

#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 specified by the file_name must be a header file. There is no distinction between the use of double quotation marks and angle brackets to enclose 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 is included 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 preprocessor to skip the path1 directory and start the search for the included file from the path2 directory. This directive allows you to use two different versions of t.h and it prevents t.h from being included recursively.