]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. _include-operation: | |
7 | ||
8 | Include Operation | |
9 | ***************** | |
10 | ||
11 | The :samp:`#include` directive works by directing the C preprocessor to | |
12 | scan the specified file as input before continuing with the rest of the | |
13 | current file. The output from the preprocessor contains the output | |
14 | already generated, followed by the output resulting from the included | |
15 | file, followed by the output that comes from the text after the | |
16 | :samp:`#include` directive. For example, if you have a header file | |
17 | :samp:`header.h` as follows, | |
18 | ||
19 | .. code-block:: c++ | |
20 | ||
21 | char *test (void); | |
22 | ||
23 | and a main program called :samp:`program.c` that uses the header file, | |
24 | like this, | |
25 | ||
26 | .. code-block:: c++ | |
27 | ||
28 | int x; | |
29 | #include "header.h" | |
30 | ||
31 | int | |
32 | main (void) | |
33 | { | |
34 | puts (test ()); | |
35 | } | |
36 | ||
37 | the compiler will see the same token stream as it would if | |
38 | :samp:`program.c` read | |
39 | ||
40 | .. code-block:: c++ | |
41 | ||
42 | int x; | |
43 | char *test (void); | |
44 | ||
45 | int | |
46 | main (void) | |
47 | { | |
48 | puts (test ()); | |
49 | } | |
50 | ||
51 | Included files are not limited to declarations and macro definitions; | |
52 | those are merely the typical uses. Any fragment of a C program can be | |
53 | included from another file. The include file could even contain the | |
54 | beginning of a statement that is concluded in the containing file, or | |
55 | the end of a statement that was started in the including file. However, | |
56 | an included file must consist of complete tokens. Comments and string | |
57 | literals which have not been closed by the end of an included file are | |
58 | invalid. For error recovery, they are considered to end at the end of | |
59 | the file. | |
60 | ||
61 | To avoid confusion, it is best if header files contain only complete | |
62 | syntactic units---function declarations or definitions, type | |
63 | declarations, etc. | |
64 | ||
65 | The line following the :samp:`#include` directive is always treated as a | |
66 | separate line by the C preprocessor, even if the included file lacks a | |
3ed1b4ce | 67 | final newline. |