@copying
@c man begin COPYRIGHT
Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
+2008, 2009, 2010
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation. A copy of
the license is included in the
@c man end
@ifinfo
@dircategory Software development
@direntry
-* Cpp: (cpp). The GNU C preprocessor.
+* Cpp: (cpp). The GNU C preprocessor.
@end direntry
@end ifinfo
* Include Operation::
* Search Path::
* Once-Only Headers::
+* Alternatives to Wrapper #ifndef::
* Computed Includes::
* Wrapper Headers::
* System Headers::
Obsolete Features
-* Assertions::
-* Obsolete once-only headers::
+* Obsolete Features::
@end detailmenu
@end menu
few things required by the standard. These are features which are
rarely, if ever, used, and may cause surprising changes to the meaning
of a program which does not expect them. To get strict ISO Standard C,
-you should use the @option{-std=c89} or @option{-std=c99} options, depending
+you should use the @option{-std=c90}, @option{-std=c99} or
+@option{-std=c1x} options, depending
on which version of the standard you want. To get all the mandatory
diagnostics, you must also use @option{-pedantic}. @xref{Invocation}.
* Include Operation::
* Search Path::
* Once-Only Headers::
+* Alternatives to Wrapper #ifndef::
* Computed Includes::
* Wrapper Headers::
* System Headers::
file, the macro name should contain the name of the file and some
additional text, to avoid conflicts with other header files.
+@node Alternatives to Wrapper #ifndef
+@section Alternatives to Wrapper #ifndef
+
+CPP supports two more ways of indicating that a header file should be
+read only once. Neither one is as portable as a wrapper @samp{#ifndef}
+and we recommend you do not use them in new programs, with the caveat
+that @samp{#import} is standard practice in Objective-C.
+
+@findex #import
+CPP supports a variant of @samp{#include} called @samp{#import} which
+includes a file, but does so at most once. If you use @samp{#import}
+instead of @samp{#include}, then you don't need the conditionals
+inside the header file to prevent multiple inclusion of the contents.
+@samp{#import} is standard in Objective-C, but is considered a
+deprecated extension in C and C++.
+
+@samp{#import} is not a well designed feature. It requires the users of
+a header file to know that it should only be included once. It is much
+better for the header file's implementor to write the file so that users
+don't need to know this. Using a wrapper @samp{#ifndef} accomplishes
+this goal.
+
+In the present implementation, a single use of @samp{#import} will
+prevent the file from ever being read again, by either @samp{#import} or
+@samp{#include}. You should not rely on this; do not use both
+@samp{#import} and @samp{#include} to refer to the same header file.
+
+Another way to prevent a header file from being included more than once
+is with the @samp{#pragma once} directive. If @samp{#pragma once} is
+seen when scanning a header file, that file will never be read again, no
+matter what.
+
+@samp{#pragma once} does not have the problems that @samp{#import} does,
+but it is not recognized by all preprocessors, so you cannot rely on it
+in a portable program.
+
@node Computed Includes
@section Computed Includes
@cindex computed includes
@item __OBJC__
This macro is defined, with value 1, when the Objective-C compiler is in
use. You can use @code{__OBJC__} to test whether a header is compiled
-by a C compiler or a Objective-C compiler.
+by a C compiler or an Objective-C compiler.
@item __ASSEMBLER__
This macro is defined with value 1 when preprocessing assembly
The common predefined macros are GNU C extensions. They are available
with the same meanings regardless of the machine or operating system on
-which you are using GNU C@. Their names all start with double
-underscores.
+which you are using GNU C or GNU Fortran. Their names all start with
+double underscores.
@table @code
@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers
which use it. Otherwise, the precompiled headers will not be used.
+@item __GFORTRAN__
+The GNU Fortran compiler defines this.
+
@item __GNUC__
@itemx __GNUC_MINOR__
@itemx __GNUC_PATCHLEVEL__
These macros are defined by all GNU compilers that use the C
-preprocessor: C, C++, and Objective-C@. Their values are the major
+preprocessor: C, C++, Objective-C and Fortran. Their values are the major
version, minor version, and patch level of the compiler, as integer
constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3,
@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These
This macro expands to a decimal integer constant that represents the
depth of nesting in include files. The value of this macro is
incremented on every @samp{#include} directive and decremented at the
-end of every included file. It starts out at 0, it's value within the
+end of every included file. It starts out at 0, its value within the
base file specified on the command line.
@item __ELF__
@item __GNUC_GNU_INLINE__
GCC defines this macro if functions declared @code{inline} will be
-handled in GCC's traditional gnu89 mode. Object files will contain
+handled in GCC's traditional gnu90 mode. Object files will contain
externally visible definitions of all functions declared @code{inline}
without @code{extern} or @code{static}. They will not contain any
definitions of any functions declared @code{extern inline}.
@code{inline} without @code{extern}.
If this macro is defined, GCC supports the @code{gnu_inline} function
-attribute as a way to always get the gnu89 behavior. Support for
+attribute as a way to always get the gnu90 behavior. Support for
this and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If
neither macro is defined, an older version of GCC is being used:
-@code{inline} functions will be compiled in gnu89 mode, and the
+@code{inline} functions will be compiled in gnu90 mode, and the
@code{gnu_inline} function attribute will not be recognized.
@item __CHAR_UNSIGNED__
@itemx __WINT_TYPE__
@itemx __INTMAX_TYPE__
@itemx __UINTMAX_TYPE__
+@itemx __SIG_ATOMIC_TYPE__
+@itemx __INT8_TYPE__
+@itemx __INT16_TYPE__
+@itemx __INT32_TYPE__
+@itemx __INT64_TYPE__
+@itemx __UINT8_TYPE__
+@itemx __UINT16_TYPE__
+@itemx __UINT32_TYPE__
+@itemx __UINT64_TYPE__
+@itemx __INT_LEAST8_TYPE__
+@itemx __INT_LEAST16_TYPE__
+@itemx __INT_LEAST32_TYPE__
+@itemx __INT_LEAST64_TYPE__
+@itemx __UINT_LEAST8_TYPE__
+@itemx __UINT_LEAST16_TYPE__
+@itemx __UINT_LEAST32_TYPE__
+@itemx __UINT_LEAST64_TYPE__
+@itemx __INT_FAST8_TYPE__
+@itemx __INT_FAST16_TYPE__
+@itemx __INT_FAST32_TYPE__
+@itemx __INT_FAST64_TYPE__
+@itemx __UINT_FAST8_TYPE__
+@itemx __UINT_FAST16_TYPE__
+@itemx __UINT_FAST32_TYPE__
+@itemx __UINT_FAST64_TYPE__
+@itemx __INTPTR_TYPE__
+@itemx __UINTPTR_TYPE__
These macros are defined to the correct underlying types for the
@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t},
-@code{intmax_t}, and @code{uintmax_t}
-typedefs, respectively. They exist to make the standard header files
-@file{stddef.h} and @file{wchar.h} work correctly. You should not use
-these macros directly; instead, include the appropriate headers and use
-the typedefs.
+@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
+@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
+@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
+@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
+@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
+@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
+@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
+@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
+@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs,
+respectively. They exist to make the standard header files
+@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} work correctly.
+You should not use these macros directly; instead, include the
+appropriate headers and use the typedefs. Some of these macros may
+not be defined on particular systems if GCC does not provide a
+@file{stdint.h} header on those systems.
@item __CHAR_BIT__
Defined to the number of bits used in the representation of the
@itemx __INT_MAX__
@itemx __LONG_MAX__
@itemx __LONG_LONG_MAX__
+@itemx __WINT_MAX__
+@itemx __SIZE_MAX__
+@itemx __PTRDIFF_MAX__
@itemx __INTMAX_MAX__
+@itemx __UINTMAX_MAX__
+@itemx __SIG_ATOMIC_MAX__
+@itemx __INT8_MAX__
+@itemx __INT16_MAX__
+@itemx __INT32_MAX__
+@itemx __INT64_MAX__
+@itemx __UINT8_MAX__
+@itemx __UINT16_MAX__
+@itemx __UINT32_MAX__
+@itemx __UINT64_MAX__
+@itemx __INT_LEAST8_MAX__
+@itemx __INT_LEAST16_MAX__
+@itemx __INT_LEAST32_MAX__
+@itemx __INT_LEAST64_MAX__
+@itemx __UINT_LEAST8_MAX__
+@itemx __UINT_LEAST16_MAX__
+@itemx __UINT_LEAST32_MAX__
+@itemx __UINT_LEAST64_MAX__
+@itemx __INT_FAST8_MAX__
+@itemx __INT_FAST16_MAX__
+@itemx __INT_FAST32_MAX__
+@itemx __INT_FAST64_MAX__
+@itemx __UINT_FAST8_MAX__
+@itemx __UINT_FAST16_MAX__
+@itemx __UINT_FAST32_MAX__
+@itemx __UINT_FAST64_MAX__
+@itemx __INTPTR_MAX__
+@itemx __UINTPTR_MAX__
+@itemx __WCHAR_MIN__
+@itemx __WINT_MIN__
+@itemx __SIG_ATOMIC_MIN__
Defined to the maximum value of the @code{signed char}, @code{wchar_t},
@code{signed short},
-@code{signed int}, @code{signed long}, @code{signed long long}, and
-@code{intmax_t} types
-respectively. They exist to make the standard header given numerical limits
-work correctly. You should not use these macros directly; instead, include
-the appropriate headers.
+@code{signed int}, @code{signed long}, @code{signed long long},
+@code{wint_t}, @code{size_t}, @code{ptrdiff_t},
+@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
+@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
+@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
+@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
+@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
+@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
+@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
+@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
+@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and
+to the minimum value of the @code{wchar_t}, @code{wint_t}, and
+@code{sig_atomic_t} types respectively. They exist to make the
+standard header given numerical limits work correctly. You should not
+use these macros directly; instead, include the appropriate headers.
+Some of these macros may not be defined on particular systems if GCC
+does not provide a @file{stdint.h} header on those systems.
+
+@item __INT8_C
+@itemx __INT16_C
+@itemx __INT32_C
+@itemx __INT64_C
+@itemx __UINT8_C
+@itemx __UINT16_C
+@itemx __UINT32_C
+@itemx __UINT64_C
+@itemx __INTMAX_C
+@itemx __UINTMAX_C
+Defined to implementations of the standard @file{stdint.h} macros with
+the same names without the leading @code{__}. They exist the make the
+implementation of that header work correctly. You should not use
+these macros directly; instead, include the appropriate headers. Some
+of these macros may not be defined on particular systems if GCC does
+not provide a @file{stdint.h} header on those systems.
@item __SIZEOF_INT__
@itemx __SIZEOF_LONG__
@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t}
and @code{ptrdiff_t}.
+@item __BYTE_ORDER__
+@itemx __ORDER_LITTLE_ENDIAN__
+@itemx __ORDER_BIG_ENDIAN__
+@itemx __ORDER_PDP_ENDIAN__
+@code{__BYTE_ORDER__} is defined to one of the values
+@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or
+@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and
+multi-word quantities in memory. If @code{__BYTE_ORDER__} is equal to
+@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, then
+multi-byte and multi-word quantities are laid out identically: the
+byte (word) at the lowest address is the least significant or most
+significant byte (word) of the quantity, respectively. If
+@code{__BYTE_ORDER__} is equal to @code{__ORDER_PDP_ENDIAN__}, then
+bytes in 16-bit words are laid out in a little-endian fashion, whereas
+the 16-bit subwords of a 32-bit quantity are laid out in big-endian
+fashion.
+
+You should use these macros for testing like this:
+
+@smallexample
+/* @r{Test for a little-endian machine} */
+#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+@end smallexample
+
@item __DEPRECATED
This macro is defined, with value 1, when compiling a C++ source file
with warnings about deprecated constructs enabled. These warnings are
@item __EXCEPTIONS
This macro is defined, with value 1, when compiling a C++ source file
-with exceptions enabled. If @option{-fno-exceptions} was used when
-compiling the file, then this macro will not be defined.
+with exceptions enabled. If @option{-fno-exceptions} is used when
+compiling the file, then this macro is not defined.
+
+@item __GXX_RTTI
+This macro is defined, with value 1, when compiling a C++ source file
+with runtime type identification enabled. If @option{-fno-rtti} is
+used when compiling the file, then this macro is not defined.
@item __USING_SJLJ_EXCEPTIONS__
This macro is defined, with value 1, if the compiler uses the old
These macros are defined when the target processor supports atomic compare
and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively.
+@item __GCC_HAVE_DWARF2_CFI_ASM
+This macro is defined when the compiler is emitting Dwarf2 CFI directives
+to the assembler. When this is defined, it is possible to emit those same
+directives in inline assembly.
+
+@item __FP_FAST_FMA
+@itemx __FP_FAST_FMAF
+@itemx __FP_FAST_FMAL
+These macros are defined with value 1 if the backend supports the
+@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that
+the include file @file{math.h} can define the macros
+@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL}
+for compatibility with the 1999 C standard.
@end table
@node System-specific Predefined Macros
preprocessor itself. Other pragmas are meaningful to the C or C++
compilers. They are documented in the GCC manual.
+GCC plugins may provide their own pragmas.
+
@ftable @code
@item #pragma GCC dependency
@code{#pragma GCC dependency} allows you to check the relative dates of
@item The mapping of physical source file multi-byte characters to the
execution character set.
-Currently, CPP requires its input to be ASCII or UTF-8. The execution
-character set may be controlled by the user, with the
-@option{-fexec-charset} and @option{-fwide-exec-charset} options.
+The input character set can be specified using the
+@option{-finput-charset} option, while the execution character set may
+be controlled using the @option{-fexec-charset} and
+@option{-fwide-exec-charset} options.
@item Identifier characters.
@anchor{Identifier characters}
identifier characters by default.
Currently the targets that by default do not permit @samp{$} are AVR,
-IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX and
-BeOS operating systems.
+IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
+operating system.
You can override the default with @option{-fdollars-in-identifiers} or
@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}.
same way; i.e.@: escape sequences such as @samp{\a} are given the
values they would have on the target machine.
-The compiler values a multi-character character constant a character
+The compiler evaluates a multi-character character constant a character
at a time, shifting the previous value left by the number of bits per
target character, and then or-ing in the bit-pattern of the new
character truncated to the width of a target character. The final
@node Obsolete Features
@section Obsolete Features
-CPP has a number of features which are present mainly for
-compatibility with older programs. We discourage their use in new code.
-In some cases, we plan to remove the feature in a future version of GCC@.
-
-@menu
-* Assertions::
-* Obsolete once-only headers::
-@end menu
+CPP has some features which are present mainly for compatibility with
+older programs. We discourage their use in new code. In some cases,
+we plan to remove the feature in a future version of GCC@.
-@node Assertions
@subsection Assertions
@cindex assertions
You can also make or cancel assertions using command line options.
@xref{Invocation}.
-@node Obsolete once-only headers
-@subsection Obsolete once-only headers
-
-CPP supports two more ways of indicating that a header file should be
-read only once. Neither one is as portable as a wrapper @samp{#ifndef},
-and we recommend you do not use them in new programs.
-
-@findex #import
-In the Objective-C language, there is a variant of @samp{#include}
-called @samp{#import} which includes a file, but does so at most once.
-If you use @samp{#import} instead of @samp{#include}, then you don't
-need the conditionals inside the header file to prevent multiple
-inclusion of the contents. GCC permits the use of @samp{#import} in C
-and C++ as well as Objective-C@. However, it is not in standard C or C++
-and should therefore not be used by portable programs.
-
-@samp{#import} is not a well designed feature. It requires the users of
-a header file to know that it should only be included once. It is much
-better for the header file's implementor to write the file so that users
-don't need to know this. Using a wrapper @samp{#ifndef} accomplishes
-this goal.
-
-In the present implementation, a single use of @samp{#import} will
-prevent the file from ever being read again, by either @samp{#import} or
-@samp{#include}. You should not rely on this; do not use both
-@samp{#import} and @samp{#include} to refer to the same header file.
-
-Another way to prevent a header file from being included more than once
-is with the @samp{#pragma once} directive. If @samp{#pragma once} is
-seen when scanning a header file, that file will never be read again, no
-matter what.
-
-@samp{#pragma once} does not have the problems that @samp{#import} does,
-but it is not recognized by all preprocessors, so you cannot rely on it
-in a portable program.
-
@node Differences from previous versions
@section Differences from previous versions
@cindex differences from previous versions