| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A header file is a file containing C declarations and macro definitions (see section 3. Macros) to be shared between several source files. You request the use of a header file in your program by including it, with the C preprocessing directive `#include'.
Header files serve two purposes.
Including a header file produces the same results as copying the header file into each source file that needs it. Such copying would be time-consuming and error-prone. With a header file, the related declarations appear in only one place. If they need to be changed, they can be changed in one place, and programs that include the header file will automatically use the new version when next recompiled. The header file eliminates the labor of finding and changing all the copies as well as the risk that a failure to find one copy will result in inconsistencies within a program.
In C, the usual convention is to give header files names that end with `.h'. It is most portable to use only letters, digits, dashes, and underscores in header file names, and at most one dot.
2.1 Include Syntax 2.2 Include Operation 2.3 Search Path 2.4 Once-Only Headers 2.5 Computed Includes 2.6 Wrapper Headers 2.7 System Headers
Both user and system header files are included using the preprocessing directive `#include'. It has two variants:
#include <file>
#include "file"
<file>.
The argument of `#include', whether delimited with quote marks or
angle brackets, behaves like a string constant in that comments are not
recognized, and macro names are not expanded. Thus, #include
<x/*y> specifies inclusion of a system header file named `x/*y'.
However, if backslashes occur within file, they are 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 filename containing three
backslashes. (Some systems interpret `\' as a pathname separator.
All of these also interpret `/' the same way. It is most portable
to use only `/'.)
It is an error if there is anything (other than comments) on the line after the file name.
The `#include' directive works by directing the C preprocessor to scan the specified file as input before continuing with the rest of the current file. The output from the preprocessor contains 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' directive. For example, if you have a header file `header.h' as follows,
char *test (void); |
and a main program called `program.c' that uses the header file, like this,
int x;
#include "header.h"
int
main (void)
{
puts (test ());
}
|
the compiler will see the same token stream as it would if `program.c' read
int x;
char *test (void);
int
main (void)
{
puts (test ());
}
|
Included files are not limited to declarations and macro definitions; those are merely 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, an included file must consist of complete tokens. Comments and string literals which have not been closed by the end of an included file are invalid. For error recovery, they are considered to end at the end of the file.
To avoid confusion, it is best if header files contain only complete syntactic units--function declarations or definitions, type declarations, etc.
The line following the `#include' directive is always treated as a separate line by the C preprocessor, even if the included file lacks a final newline.
GCC looks in several different places for headers. On a normal Unix
system, if you do not instruct it otherwise, it will look for headers
requested with #include <file> in:
/usr/local/include /usr/lib/gcc-lib/target/version/include /usr/target/include /usr/include |
For C++ programs, it will also look in `/usr/include/g++-v3', first. In the above, target is the canonical name of the system GCC was configured to compile code for; often but not always the same as the canonical name of the system it runs on. version is the version of GCC in use.
You can add to this list with the `-Idir' command line option. All the directories named by `-I' are searched, in left-to-right order, before the default directories. The only exception is when `dir' is already searched by default. In this case, the option is ignored and the search order for system directories remains unchanged.
Duplicate directories are removed from the quote and bracket search chains before the two chains are merged to make the final search chain. Thus, it is possible for a directory to occur twice in the final search chain if it was specified in both the quote and bracket chains.
You can prevent GCC from searching any of the default directories with the `-nostdinc' option. This is useful when you are compiling an operating system kernel or some other program that does not use the standard C library facilities, or the standard C library itself. `-I' options are not ignored as described above when `-nostdinc' is in effect.
GCC looks for headers requested with #include "file"
first in the directory containing the current file, then in the same
places it would have looked for a header requested with angle brackets.
For example, if `/usr/include/sys/stat.h' contains
#include "types.h", GCC looks for `types.h' first in
`/usr/include/sys', then in its usual search path.
`#line' (see section 6. Line Control) does not change GCC's idea of the directory containing the current file.
You may put `-I-' at any point in your list of `-I' options. This has two effects. First, directories appearing before the `-I-' in the list are searched only for headers requested with quote marks. Directories after `-I-' are searched for all headers. Second, the directory containing the current file is not searched for anything, unless it happens to be one of the directories named by an `-I' switch.
`-I. -I-' is not the same as no `-I' options at all, and does not cause the same behavior for `<>' includes that `""' includes get with no special options. `-I.' searches the compiler's current working directory for header files. That may or may not be the same as the directory containing the current file.
If you need to look for headers in a directory named `-', write `-I./-'.
There are several more ways to adjust the header search path. They are generally less useful. See section 12. Invocation.
If a header file happens to be included twice, the compiler will process its contents twice. This is very likely to cause an error, e.g. when the compiler sees the same structure definition twice. Even if it does not, it will certainly waste time.
The standard way to prevent this is to enclose the entire real contents of the file in a conditional, like this:
/* File foo. */ #ifndef FILE_FOO_SEEN #define FILE_FOO_SEEN the entire file #endif /* !FILE_FOO_SEEN */ |
This construct is commonly known as a wrapper #ifndef.
When the header is included again, the conditional will be false,
because FILE_FOO_SEEN is defined. The preprocessor will skip
over the entire contents of the file, and the compiler will not see it
twice.
CPP optimizes even further. It remembers when a header file has a wrapper `#ifndef'. If a subsequent `#include' specifies that header, and the macro in the `#ifndef' is still defined, it does not bother to rescan the file at all.
You can put comments outside the wrapper. They will not interfere with this optimization.
The macro FILE_FOO_SEEN is called the controlling macro or
guard macro. In a user header file, the macro name should not
begin with `_'. In a system header file, it should begin with
`__' to avoid conflicts with user programs. In any kind of header
file, the macro name should contain the name of the file and some
additional text, to avoid conflicts with other header files.
Sometimes it is necessary to select one of several different header files to be included into your program. They might specify configuration parameters to be used on different sorts of operating systems, for instance. You could do this with a series of conditionals,
#if SYSTEM_1 # include "system_1.h" #elif SYSTEM_2 # include "system_2.h" #elif SYSTEM_3 ... #endif |
That rapidly becomes tedious. Instead, the preprocessor offers the ability to use a macro for the header name. This is called a computed include. Instead of writing a header name as the direct argument of `#include', you simply put a macro name there instead:
#define SYSTEM_H "system_1.h" ... #include SYSTEM_H |
SYSTEM_H will be expanded, and the preprocessor will look for
`system_1.h' as if the `#include' had been written that way
originally. SYSTEM_H could be defined by your Makefile with a
`-D' option.
You must be careful when you define the macro. `#define' saves tokens, not text. The preprocessor has no way of knowing that the macro will be used as the argument of `#include', so it generates ordinary tokens, not a header name. This is unlikely to cause problems if you use double-quote includes, which are close enough to string constants. If you use angle brackets, however, you may have trouble.
The syntax of a computed include is actually a bit more general than the above. If the first non-whitespace character after `#include' is not `"' or `<', then the entire line is macro-expanded like running text would be.
If the line expands to a single string constant, the contents of that string constant are the file to be included. CPP does not re-examine the string for embedded quotes, but neither does it process backslash escapes in the string. Therefore
#define HEADER "a\"b" #include HEADER |
looks for a file named `a\"b'. CPP searches for the file according to the rules for double-quoted includes.
If the line expands to a token stream beginning with a `<' token and including a `>' token, then the tokens between the `<' and the first `>' are combined to form the filename to be included. Any whitespace between tokens is reduced to a single space; then any space after the initial `<' is retained, but a trailing space before the closing `>' is ignored. CPP searches for the file according to the rules for angle-bracket includes.
In either case, if there are any tokens on the line after the file name, an error occurs and the directive is not processed. It is also an error if the result of expansion does not match either of the two expected forms.
These rules are implementation-defined behavior according to the C standard. To minimize the risk of different compilers interpreting your computed includes differently, we recommend you use only a single object-like macro which expands to a string constant. This will also minimize confusion for people reading your program.
Sometimes it is necessary to adjust the contents of a system-provided
header file without editing it directly. GCC's fixincludes
operation does this, for example. One way to do that would be to create
a new header file with the same name and insert it in the search path
before the original header. That works fine as long as you're willing
to replace the old header entirely. But what if you want to refer to
the old header from the new one?
You cannot simply include the old header with `#include'. That will start from the beginning, and find your new header again. If your header 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" |
There is no way to solve this problem within the C standard, but you can use the GNU extension `#include_next'. It means, "Include the next file with this name." This directive works like `#include' except in searching for the specified file: it starts searching the list of header file directories after the directory in which the current file was found.
Suppose you specify `-I /usr/local/include', and the list of
directories to search also includes `/usr/include'; and suppose
both directories contain `signal.h'. Ordinary #include
<signal.h> finds the file under `/usr/local/include'. If that
file contains #include_next <signal.h>, it starts searching
after 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 you
specify has the same name as the current file. It simply looks for the
file named, starting with the directory in the search path after the one
where the current file was found.
The use of `#include_next' can lead to great confusion. We
recommend it be used only when there is no other alternative. In
particular, it should not be used in the headers belonging to a specific
program; it should be used only to make global corrections along the
lines of fixincludes.
The header files declaring interfaces to the operating system and runtime libraries often cannot be written in strictly conforming C. Therefore, GCC gives code found in system headers special treatment. All warnings, other than those generated by `#warning' (see section 5. Diagnostics), are suppressed while GCC is processing a system header. Macros defined in a system header are immune to a few warnings wherever they are expanded. This immunity is granted on an ad-hoc basis, when we find that a warning generates lots of false positives because of code in macros defined in system headers.
Normally, only the headers found in specific directories are considered system headers. These directories are determined when GCC is compiled. There are, however, two ways to make normal headers into system headers.
The `-isystem' command line option adds its argument to the list of directories to search for headers, just like `-I'. Any headers found in that directory will be considered system headers.
All directories named by `-isystem' are searched after all directories named by `-I', no matter what their order was on the command line. If the same directory is named by both `-I' and `-isystem', the `-I' option is ignored. GCC provides an informative message when this occurs if `-v' is used.
There is also a directive, #pragma GCC system_header, which
tells GCC to consider the rest of the current include file a system
header, no matter where it was found. Code that comes before the
`#pragma' in the file will not be affected. #pragma GCC
system_header has no effect in the primary source file.
On very old systems, some of the pre-defined system header directories
get even more special treatment. GNU C++ considers code in headers
found in those directories to be surrounded by an extern "C"
block. There is no way to request this behavior with a `#pragma',
or from the command line.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |