| cpp.texi (169690) | cpp.texi (220755) |
|---|---|
| 1\input texinfo 2@setfilename cpp.info 3@settitle The C Preprocessor 4@setchapternewpage off 5@c @smallbook 6@c @cropmarks 7@c @finalout 8 --- 58 unchanged lines hidden (view full) --- 67@insertcopying 68@end titlepage 69@contents 70@page 71 72@ifnottex 73@node Top 74@top | 1\input texinfo 2@setfilename cpp.info 3@settitle The C Preprocessor 4@setchapternewpage off 5@c @smallbook 6@c @cropmarks 7@c @finalout 8 --- 58 unchanged lines hidden (view full) --- 67@insertcopying 68@end titlepage 69@contents 70@page 71 72@ifnottex 73@node Top 74@top |
| 75The C preprocessor implements the macro language used to transform C, 76C++, and Objective-C programs before they are compiled. It can also be 77useful on its own. | 75The C preprocessor implements the macro language used to transform C 76and C++ programs before they are compiled. It can also be useful on 77its own. |
| 78 79@menu 80* Overview:: 81* Header Files:: 82* Macros:: 83* Conditionals:: 84* Diagnostics:: 85* Line Control:: --- 95 unchanged lines hidden (view full) --- 181@chapter Overview 182@c man begin DESCRIPTION 183The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} 184that is used automatically by the C compiler to transform your program 185before compilation. It is called a macro processor because it allows 186you to define @dfn{macros}, which are brief abbreviations for longer 187constructs. 188 | 78 79@menu 80* Overview:: 81* Header Files:: 82* Macros:: 83* Conditionals:: 84* Diagnostics:: 85* Line Control:: --- 95 unchanged lines hidden (view full) --- 181@chapter Overview 182@c man begin DESCRIPTION 183The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} 184that is used automatically by the C compiler to transform your program 185before compilation. It is called a macro processor because it allows 186you to define @dfn{macros}, which are brief abbreviations for longer 187constructs. 188 |
| 189The C preprocessor is intended to be used only with C, C++, and 190Objective-C source code. In the past, it has been abused as a general 191text processor. It will choke on input which does not obey C's lexical 192rules. For example, apostrophes will be interpreted as the beginning of 193character constants, and cause errors. Also, you cannot rely on it 194preserving characteristics of the input which are not significant to 195C-family languages. If a Makefile is preprocessed, all the hard tabs 196will be removed, and the Makefile will not work. | 189The C preprocessor is intended to be used only with C and C++ source 190code. In the past, it has been abused as a general text processor. It 191will choke on input which does not obey C's lexical rules. For 192example, apostrophes will be interpreted as the beginning of character 193constants, and cause errors. Also, you cannot rely on it preserving 194characteristics of the input which are not significant to C-family 195languages. If a Makefile is preprocessed, all the hard tabs will be 196removed, and the Makefile will not work. |
| 197 198Having said that, you can often get away with using cpp on things which 199are not C@. Other Algol-ish programming languages are often safe 200(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} 201mode preserves more white space, and is otherwise more permissive. Many 202of the problems can be avoided by writing C or C++ style comments 203instead of native language comments, and keeping macros simple. 204 --- 1668 unchanged lines hidden (view full) --- 1873implementation, unless GNU CPP is being used with GCC@. 1874 1875The value @code{199409L} signifies the 1989 C standard as amended in 18761994, which is the current default; the value @code{199901L} signifies 1877the 1999 revision of the C standard. Support for the 1999 revision is 1878not yet complete. 1879 1880This macro is not defined if the @option{-traditional-cpp} option is | 197 198Having said that, you can often get away with using cpp on things which 199are not C@. Other Algol-ish programming languages are often safe 200(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} 201mode preserves more white space, and is otherwise more permissive. Many 202of the problems can be avoided by writing C or C++ style comments 203instead of native language comments, and keeping macros simple. 204 --- 1668 unchanged lines hidden (view full) --- 1873implementation, unless GNU CPP is being used with GCC@. 1874 1875The value @code{199409L} signifies the 1989 C standard as amended in 18761994, which is the current default; the value @code{199901L} signifies 1877the 1999 revision of the C standard. Support for the 1999 revision is 1878not yet complete. 1879 1880This macro is not defined if the @option{-traditional-cpp} option is |
| 1881used, nor when compiling C++ or Objective-C@. | 1881used, nor when compiling C++. |
| 1882 1883@item __STDC_HOSTED__ 1884This macro is defined, with value 1, if the compiler's target is a 1885@dfn{hosted environment}. A hosted environment has the complete 1886facilities of the standard C library available. 1887 1888@item __cplusplus 1889This macro is defined when the C++ compiler is in use. You can use 1890@code{__cplusplus} to test whether a header is compiled by a C compiler 1891or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in 1892that it expands to a version number. A fully conforming implementation 1893of the 1998 C++ standard will define this macro to @code{199711L}. The 1894GNU C++ compiler is not yet fully conforming, so it uses @code{1} 1895instead. It is hoped to complete the implementation of standard C++ 1896in the near future. 1897 | 1882 1883@item __STDC_HOSTED__ 1884This macro is defined, with value 1, if the compiler's target is a 1885@dfn{hosted environment}. A hosted environment has the complete 1886facilities of the standard C library available. 1887 1888@item __cplusplus 1889This macro is defined when the C++ compiler is in use. You can use 1890@code{__cplusplus} to test whether a header is compiled by a C compiler 1891or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in 1892that it expands to a version number. A fully conforming implementation 1893of the 1998 C++ standard will define this macro to @code{199711L}. The 1894GNU C++ compiler is not yet fully conforming, so it uses @code{1} 1895instead. It is hoped to complete the implementation of standard C++ 1896in the near future. 1897 |
| 1898@item __OBJC__ 1899This macro is defined, with value 1, when the Objective-C compiler is in 1900use. You can use @code{__OBJC__} to test whether a header is compiled 1901by a C compiler or a Objective-C compiler. 1902 | |
| 1903@item __ASSEMBLER__ 1904This macro is defined with value 1 when preprocessing assembly 1905language. 1906 1907@end table 1908 1909@node Common Predefined Macros 1910@subsection Common Predefined Macros --- 5 unchanged lines hidden (view full) --- 1916underscores. 1917 1918@table @code 1919 1920@item __GNUC__ 1921@itemx __GNUC_MINOR__ 1922@itemx __GNUC_PATCHLEVEL__ 1923These macros are defined by all GNU compilers that use the C | 1898@item __ASSEMBLER__ 1899This macro is defined with value 1 when preprocessing assembly 1900language. 1901 1902@end table 1903 1904@node Common Predefined Macros 1905@subsection Common Predefined Macros --- 5 unchanged lines hidden (view full) --- 1911underscores. 1912 1913@table @code 1914 1915@item __GNUC__ 1916@itemx __GNUC_MINOR__ 1917@itemx __GNUC_PATCHLEVEL__ 1918These macros are defined by all GNU compilers that use the C |
| 1924preprocessor: C, C++, and Objective-C@. Their values are the major 1925version, minor version, and patch level of the compiler, as integer 1926constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, | 1919preprocessor: C and C++. Their values are the major version, minor 1920version, and patch level of the compiler, as integer constants. For 1921example, GCC 3.2.1 will define @code{__GNUC__} to 3, |
| 1927@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These 1928macros are also defined if you invoke the preprocessor directly. 1929 1930@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the 1931widely-used development snapshots leading up to 3.0 (which identify 1932themselves as GCC 2.96 or 2.97, depending on which snapshot you have). 1933 1934If all you need to know is whether or not your program is being compiled --- 185 unchanged lines hidden (view full) --- 2120value 1 if the compiler will use weak symbols, COMDAT sections, or 2121other similar techniques to collapse symbols with ``vague linkage'' 2122that are defined in multiple translation units. If the compiler will 2123not collapse such symbols, this macro is defined with value 0. In 2124general, user code should not need to make use of this macro; the 2125purpose of this macro is to ease implementation of the C++ runtime 2126library provided with G++. 2127 | 1922@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These 1923macros are also defined if you invoke the preprocessor directly. 1924 1925@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the 1926widely-used development snapshots leading up to 3.0 (which identify 1927themselves as GCC 2.96 or 2.97, depending on which snapshot you have). 1928 1929If all you need to know is whether or not your program is being compiled --- 185 unchanged lines hidden (view full) --- 2115value 1 if the compiler will use weak symbols, COMDAT sections, or 2116other similar techniques to collapse symbols with ``vague linkage'' 2117that are defined in multiple translation units. If the compiler will 2118not collapse such symbols, this macro is defined with value 0. In 2119general, user code should not need to make use of this macro; the 2120purpose of this macro is to ease implementation of the C++ runtime 2121library provided with G++. 2122 |
| 2128@item __NEXT_RUNTIME__ 2129This macro is defined, with value 1, if (and only if) the NeXT runtime 2130(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU 2131runtime is used, this macro is not defined, so that you can use this 2132macro to determine which runtime (NeXT or GNU) is being used. 2133 | |
| 2134@item __LP64__ 2135@itemx _LP64 2136These macros are defined, with value 1, if (and only if) the compilation 2137is for a target where @code{long int} and pointer both use 64-bits and 2138@code{int} uses 32-bit. 2139 2140@item __SSP__ 2141This macro is defined, with value 1, when @option{-fstack-protector} is in --- 1286 unchanged lines hidden (view full) --- 3428preprocessor output. The primary significance of the existence of the 3429null directive is that an input line consisting of just a @samp{#} will 3430produce no output, rather than a line of output containing just a 3431@samp{#}. Supposedly some old C programs contain such lines. 3432 3433@node Preprocessor Output 3434@chapter Preprocessor Output 3435 | 2123@item __LP64__ 2124@itemx _LP64 2125These macros are defined, with value 1, if (and only if) the compilation 2126is for a target where @code{long int} and pointer both use 64-bits and 2127@code{int} uses 32-bit. 2128 2129@item __SSP__ 2130This macro is defined, with value 1, when @option{-fstack-protector} is in --- 1286 unchanged lines hidden (view full) --- 3417preprocessor output. The primary significance of the existence of the 3418null directive is that an input line consisting of just a @samp{#} will 3419produce no output, rather than a line of output containing just a 3420@samp{#}. Supposedly some old C programs contain such lines. 3421 3422@node Preprocessor Output 3423@chapter Preprocessor Output 3424 |
| 3436When the C preprocessor is used with the C, C++, or Objective-C 3437compilers, it is integrated into the compiler and communicates a stream 3438of binary tokens directly to the compiler's parser. However, it can 3439also be used in the more conventional standalone mode, where it produces 3440textual output. | 3425When the C preprocessor is used with the C or C++ compilers, it is 3426integrated into the compiler and communicates a stream of binary tokens 3427directly to the compiler's parser. However, it can also be used in the 3428more conventional standalone mode, where it produces textual output. |
| 3441@c FIXME: Document the library interface. 3442 3443@cindex output format 3444The output from the C preprocessor looks much like the input, except 3445that all preprocessing directive lines have been replaced with blank 3446lines and all comments with spaces. Long runs of blank lines are 3447discarded. 3448 --- 599 unchanged lines hidden (view full) --- 4048no effect. 4049 4050You can also make or cancel assertions using command line options. 4051@xref{Invocation}. 4052 4053@node Obsolete once-only headers 4054@subsection Obsolete once-only headers 4055 | 3429@c FIXME: Document the library interface. 3430 3431@cindex output format 3432The output from the C preprocessor looks much like the input, except 3433that all preprocessing directive lines have been replaced with blank 3434lines and all comments with spaces. Long runs of blank lines are 3435discarded. 3436 --- 599 unchanged lines hidden (view full) --- 4036no effect. 4037 4038You can also make or cancel assertions using command line options. 4039@xref{Invocation}. 4040 4041@node Obsolete once-only headers 4042@subsection Obsolete once-only headers 4043 |
| 4056CPP supports two more ways of indicating that a header file should be 4057read only once. Neither one is as portable as a wrapper @samp{#ifndef}, 4058and we recommend you do not use them in new programs. | 4044CPP supports one more way of indicating that a header file should be 4045read only once. This is not as portable as a wrapper @samp{#ifndef}, 4046and we recommend you do not use it in new programs. |
| 4059 | 4047 |
| 4060@findex #import 4061In the Objective-C language, there is a variant of @samp{#include} 4062called @samp{#import} which includes a file, but does so at most once. 4063If you use @samp{#import} instead of @samp{#include}, then you don't 4064need the conditionals inside the header file to prevent multiple 4065inclusion of the contents. GCC permits the use of @samp{#import} in C 4066and C++ as well as Objective-C@. However, it is not in standard C or C++ 4067and should therefore not be used by portable programs. 4068 4069@samp{#import} is not a well designed feature. It requires the users of 4070a header file to know that it should only be included once. It is much 4071better for the header file's implementor to write the file so that users 4072don't need to know this. Using a wrapper @samp{#ifndef} accomplishes 4073this goal. 4074 4075In the present implementation, a single use of @samp{#import} will 4076prevent the file from ever being read again, by either @samp{#import} or 4077@samp{#include}. You should not rely on this; do not use both 4078@samp{#import} and @samp{#include} to refer to the same header file. 4079 4080Another way to prevent a header file from being included more than once 4081is with the @samp{#pragma once} directive. If @samp{#pragma once} is 4082seen when scanning a header file, that file will never be read again, no | 4048A way to prevent a header file from being included more than once is 4049with the @samp{#pragma once} directive. If @samp{#pragma once} is seen 4050when scanning a header file, that file will never be read again, no |
| 4083matter what. 4084 4085@samp{#pragma once} does not have the problems that @samp{#import} does, 4086but it is not recognized by all preprocessors, so you cannot rely on it 4087in a portable program. 4088 4089@node Differences from previous versions 4090@section Differences from previous versions --- 193 unchanged lines hidden --- | 4051matter what. 4052 4053@samp{#pragma once} does not have the problems that @samp{#import} does, 4054but it is not recognized by all preprocessors, so you cannot rely on it 4055in a portable program. 4056 4057@node Differences from previous versions 4058@section Differences from previous versions --- 193 unchanged lines hidden --- |