The include directive searches for the named file and inserts its contents into the text just as if it had been inserted there by a text editor. A file that is included this way is generally referred to as a header file and carries a .h suffix, but it can be any text file with any name.
The include directive has two forms. The one most used for system header files surrounds the name with a pair of angle brackets, with the form for user header files being surrounded by quotes, as follows:
#include <syshead.h> #include "userhead.h"
The following is a list of characteristics and rules that apply to the #include directive:
■ The angle brackets surrounding the file name cause the search to begin in any directories that were specified by using a -I option and then continue by looking through the standard set of system directories.
■ A pair of quotes surrounding the file name causes the search to begin in the current working directory (the one containing the source file being processed) and then continue with the directories that would normally be searched by a directive with the angle brackets.
■ On a UNIX system, the standard set of system directories is as follows:
■ Two separate lists of directories are searched to locate header files. The standard system header files are in the second list. The -I command-line option adds directories to the list that is searched first. The options -prefix, -withprefix, and -idirafter all manipulate the directory names in the second list searched.
■ If GCC is compiling a C++ program, the directory /usr/include/g++v3 is searched by the preprocessor before any of the other standard system directories.
■ A relative path name can be used as the name of the file. For example, if you specify #include <sys/time.h>, the file time.h will be sought in a subdirectory named sys of all the standard directories.
■ The slash character is always interpreted as a path separator, even on systems that use a different character (such as a backslash) as the path separator. This way, it is always portable to use a slash for the path names.
■ The file name is taken literally. No macros are expanded and no characters have special meanings. If the name specified contains an asterisk or backslash character, the name of the file must contain a literal asterisk or backslash character.
■ A #define directive can be used to specify the name of a header file, as in the following example:
#define BOGHEADER "bog_3.h" #include BOGHEADER
■ It is an error to have anything other than a comment on the same line as the #include directive.
■ For the purposes of searching for files, the #line directive does not change the current working directory.
■ The -I- option can be used to modify how the -I options specify which directories are to be searched. See Appendix D for more information.
Was this article helpful?