PATH
Both user and system header files are included using the preprocessor command #include . The #include command directs the C preprocessor to scan the specified file as input before continuing with the rest of the current file. The output from the preprocessor will contain the output already generated, followed by the output resulting from the included file, followed by the output that comes from the text after the #include command. Included files can themselves contain #include commands to include other files.
Included files are not limited to declarations and macro definitions, although those are the typical uses. Any fragment of a C program can be included from another file. The include file could even contain the beginning of a statement that is concluded in the containing file, or the end of a statement that was started in the including file. However, a comment or a string or character constant may not start in the included file and finish in the including file. An unterminated comment, string constant or character constant in an included file is considered to end (with an error message) at the end of the file.
The line following the #include command is always treated as a separate line by the C preprocessor, even if the included file lacks a final newline.
The Objective-C language equivalent of #include is #import ; the only difference is that #import doesn't include a file more than once, no matter how many #import commands try to include it. You should feel free to use #import in your code, but be aware that it isn't defined as part of ANSI-standard C.
The #include command has three variants:
#include <
file
>
This variant is used for system or framework header files. It searches for a file named file in a list of directories specified by you, and then, if it isn't found, in a standard list of system directories. You specify directories to search for header files with the command option -I (see the section " See Invoking the C Preprocessor "). The option -nostdinc inhibits searching the standard system directories; in this case only the directories you specify are searched.
For frameworks the semantics of the text between the angle brackets is different. The word preceding the slash indicates a framework. Thus the line:
<AppKit/AppKit.h>
causes the search for the header file AppKit.h to occur in the Application Kit framework ( /System/Library/Frameworks/AppKit.framework ). The PrivateHeaders subdirectory is searched first, and then the Headers directory, thus allowing a private header file to override a public one. The flags -F , -I , and -L affect search path for frameworks (see "Invoking the Preprocessor," below); The linker's -framework flag, however, has no effect.
The parsing of this form of #include is slightly special because comments are not recognized within the < file > argument. (The < and > are similar to string delimiters instead of operators.) Thus, in #include <x/*y> the /* doesn't start a comment and the command specifies inclusion of a system header file named x/*y . (Of course, a header file with such a name is unlikely to exist on Mac OS X or a UNIX system, where shell wildcard features would make it hard to manipulate.)
The file argument may not contain a > character, although it may contain a < character. Whitespace characters in the file argument may or may not be ignored, so do not use them.
#include "
file
"
This variant is used for header files of your own program. It searches for a file named file first in the current directory, then in the same directories used for system header files. The current directory is tried first because it's presumed to be the location of the files of the program being compiled. (If the -I- option is used, the special treatment of the current directory is inhibited.)
The file argument may not contain " characters. If backslashes occur within file , they might be considered ordinary text characters, not escape characters. None of the character escape sequences appropriate to string constants in C are processed. Thus, #include "x\n\\y" specifies a file name containing three backslashes. It isn't clear why this behavior is ever useful, but the ANSI standard specifies it.
#include
anything else
This variant is called a computed #include . Any #include command whose argument doesn't fit the above two forms is a computed #include . The text anything else is checked for macro calls, which are expanded. When this is done, the result must fit one of the above two variants.
This feature allows you to define a macro that controls the file name to be used at a later point in the program. One application of this is to allow a site-configuration file for your program to specify the names of the system header files to be used. This can help in porting the program to various operating systems in which the necessary system header files are found in different places.