3 @settitle The C Preprocessor
10 @c man begin COPYRIGHT
11 Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
12 1997, 1998, 1999, 2000, 2001
13 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.1 or
17 any later version published by the Free Software Foundation. A copy of
18 the license is included in the
20 section entitled ``GNU Free Documentation License''.
22 @c man begin COPYRIGHT
29 @c man begin COPYRIGHT
30 This manual contains no Invariant Sections. The Front-Cover Texts are
31 (a) (see below), and the Back-Cover Texts are (b) (see below).
33 (a) The FSF's Front-Cover Text is:
37 (b) The FSF's Back-Cover Text is:
39 You have freedom to copy and modify this GNU Manual, like GNU
40 software. Copies published by the Free Software Foundation raise
41 funds for GNU development.
45 @macro gcctabopt{body}
50 @dircategory Programming
52 * Cpp: (cpp). The GNU C preprocessor.
57 @title The C Preprocessor
58 @subtitle Last revised April 2001
59 @subtitle for GCC version 3
60 @author Richard M. Stallman
61 @author Zachary Weinberg
63 @c There is a fill at the bottom of the page, so we need a filll to
65 @vskip 0pt plus 1filll
74 The C preprocessor implements the macro language used to transform C,
75 C++, and Objective-C programs before they are compiled. It can also be
87 * Preprocessor Output::
89 * Implementation Details::
91 * GNU Free Documentation License::
92 * Index of Directives::
96 --- The Detailed Node Listing ---
100 * Initial processing::
102 * The preprocessing language::
107 * Include Operation::
109 * Once-Only Headers::
110 * Computed Includes::
116 * Object-like Macros::
117 * Function-like Macros::
122 * Predefined Macros::
123 * Undefining and Redefining Macros::
128 * Standard Predefined Macros::
129 * Common Predefined Macros::
130 * System-specific Predefined Macros::
131 * C++ Named Operators::
136 * Operator Precedence Problems::
137 * Swallowing the Semicolon::
138 * Duplication of Side Effects::
139 * Self-Referential Macros::
141 * Newlines in Arguments::
146 * Conditional Syntax::
157 Implementation Details
159 * Implementation-defined behavior::
160 * Implementation limits::
161 * Obsolete Features::
162 * Differences from previous versions::
167 * Obsolete once-only headers::
168 * Miscellaneous obsolete features::
180 @c man begin DESCRIPTION
181 The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}
182 that is used automatically by the C compiler to transform your program
183 before compilation. It is called a macro processor because it allows
184 you to define @dfn{macros}, which are brief abbreviations for longer
187 The C preprocessor is intended to be used only with C, C++, and
188 Objective-C source code. In the past, it has been abused as a general
189 text processor. It will choke on input which does not obey C's lexical
190 rules. For example, apostrophes will be interpreted as the beginning of
191 character constants, and cause errors. Also, you cannot rely on it
192 preserving characteristics of the input which are not significant to
193 C-family languages. If a Makefile is preprocessed, all the hard tabs
194 will be removed, and the Makefile will not work.
196 Having said that, you can often get away with using cpp on things which
197 are not C@. Other Algol-ish programming languages are often safe
198 (Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional}
199 mode preserves more white space, and is otherwise more permissive. Many
200 of the problems can be avoided by writing C or C++ style comments
201 instead of native language comments, and keeping macros simple.
203 Wherever possible, you should use a preprocessor geared to the language
204 you are writing in. Modern versions of the GNU assembler have macro
205 facilities. Most high level programming languages have their own
206 conditional compilation and inclusion mechanism. If all else fails,
207 try a true general text processor, such as GNU M4.
209 C preprocessors vary in some details. This manual discusses the GNU C
210 preprocessor, which provides a small superset of the features of ISO
211 Standard C@. In its default mode, the GNU C preprocessor does not do a
212 few things required by the standard. These are features which are
213 rarely, if ever, used, and may cause surprising changes to the meaning
214 of a program which does not expect them. To get strict ISO Standard C,
215 you should use the @option{-std=c89} or @option{-std=c99} options, depending
216 on which version of the standard you want. To get all the mandatory
217 diagnostics, you must also use @option{-pedantic}. @xref{Invocation}.
221 * Initial processing::
223 * The preprocessing language::
226 @node Initial processing
227 @section Initial processing
229 The preprocessor performs a series of textual transformations on its
230 input. These happen before all other processing. Conceptually, they
231 happen in a rigid order, and the entire file is run through each
232 transformation before the next one begins. GNU CPP actually does them
233 all at once, for performance reasons. These transformations correspond
234 roughly to the first three ``phases of translation'' described in the C
239 @cindex character sets
241 The input file is read into memory and broken into lines.
243 GNU CPP expects its input to be a text file, that is, an unstructured
244 stream of ASCII characters, with some characters indicating the end of a
245 line of text. Extended ASCII character sets, such as ISO Latin-1 or
246 Unicode encoded in UTF-8, are also acceptable. Character sets that are
247 not strict supersets of seven-bit ASCII will not work. We plan to add
248 complete support for international character sets in a future release.
250 Different systems use different conventions to indicate the end of a
251 line. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR
252 LF}}, @kbd{CR}, and @kbd{@w{LF CR}} as end-of-line markers. The first
253 three are the canonical sequences used by Unix, DOS and VMS, and the
254 classic Mac OS (before OSX) respectively. You may therefore safely copy
255 source code written on any of those systems to a different one and use
256 it without conversion. (GCC may lose track of the current line number
257 if a file doesn't consistently use one convention, as sometimes happens
258 when it is edited on computers with different conventions that share a
259 network file system.) @kbd{@w{LF CR}} is included because it has been
260 reported as an end-of-line marker under exotic conditions.
262 If the last line of any input file lacks an end-of-line marker, the end
263 of the file is considered to implicitly supply one. The C standard says
264 that this condition provokes undefined behavior, so GCC will emit a
269 If trigraphs are enabled, they are replaced by their corresponding
272 These are nine three-character sequences, all starting with @samp{??},
273 that are defined by ISO C to stand for single characters. They permit
274 obsolete systems that lack some of C's punctuation to use C@. For
275 example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character
276 constant for a newline. By default, GCC ignores trigraphs, but if you
277 request a strictly conforming mode with the @option{-std} option, then
280 Trigraphs are not popular and many compilers implement them incorrectly.
281 Portable code should not rely on trigraphs being either converted or
282 ignored. If you use the @option{-Wall} or @option{-Wtrigraphs} options,
283 GCC will warn you when a trigraph would change the meaning of your
284 program if it were converted.
286 In a string constant, you can prevent a sequence of question marks from
287 being confused with a trigraph by inserting a backslash between the
288 question marks. @t{"(??\?)"} is the string @samp{(???)}, not
289 @samp{(?]}. Traditional C compilers do not recognize this idiom.
291 The nine trigraphs and their replacements are
294 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
295 Replacement: [ ] @{ @} # \ ^ | ~
299 @cindex continued lines
300 @cindex backslash-newline
301 Continued lines are merged into one long line.
303 A continued line is a line which ends with a backslash, @samp{\}. The
304 backslash is removed and the following line is joined with the current
305 one. No space is inserted, so you may split a line anywhere, even in
306 the middle of a word. (It is generally more readable to split lines
307 only at white space.)
309 The trailing backslash on a continued line is commonly referred to as a
310 @dfn{backslash-newline}.
312 If there is white space between a backslash and the end of a line, that
313 is still a continued line. However, as this is usually the result of an
314 editing mistake, and many compilers will not accept it as a continued
315 line, GCC will warn you about it.
319 @cindex line comments
320 @cindex block comments
321 All comments are replaced with single spaces.
323 There are two kinds of comments. @dfn{Block comments} begin with
324 @samp{/*} and continue until the next @samp{*/}. Block comments do not
328 /* @r{this is} /* @r{one comment} */ @r{text outside comment}
331 @dfn{Line comments} begin with @samp{//} and continue to the end of the
332 current line. Line comments do not nest either, but it does not matter,
333 because they would end in the same place anyway.
336 // @r{this is} // @r{one comment}
337 @r{text outside comment}
341 It is safe to put line comments inside block comments, or vice versa.
346 // @r{contains line comment}
348 */ @r{outside comment}
350 // @r{line comment} /* @r{contains block comment} */
354 But beware of commenting out one end of a block comment with a line
359 // @r{l.c.} /* @r{block comment begins}
360 @r{oops! this isn't a comment anymore} */
364 Comments are not recognized within string literals. @t{@w{"/* blah
365 */"}} is the string constant @samp{@w{/* blah */}}, not an empty string.
367 Line comments are not in the 1989 edition of the C standard, but they
368 are recognized by GCC as an extension. In C++ and in the 1999 edition
369 of the C standard, they are an official part of the language.
371 Since these transformations happen before all other processing, you can
372 split a line mechanically with backslash-newline anywhere. You can
373 comment out the end of a line. You can continue a line comment onto the
374 next line with backslash-newline. You can even split @samp{/*},
375 @samp{*/}, and @samp{//} onto multiple lines with backslash-newline.
391 is equivalent to @code{@w{#define FOO 1020}}. All these tricks are
392 extremely confusing and should not be used in code intended to be
395 There is no way to prevent a backslash at the end of a line from being
396 interpreted as a backslash-newline.
404 is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid
405 having to worry about this, do not use the deprecated GNU extension
406 which permits multi-line strings. Instead, use string literal
415 Your program will be more portable this way, too.
418 @section Tokenization
421 @cindex preprocessing tokens
422 After the textual transformations are finished, the input file is
423 converted into a sequence of @dfn{preprocessing tokens}. These mostly
424 correspond to the syntactic tokens used by the C compiler, but there are
425 a few differences. White space separates tokens; it is not itself a
426 token of any kind. Tokens do not have to be separated by white space,
427 but it is often necessary to avoid ambiguities.
429 When faced with a sequence of characters that has more than one possible
430 tokenization, the preprocessor is greedy. It always makes each token,
431 starting from the left, as big as possible before moving on to the next
432 token. For instance, @code{a+++++b} is interpreted as
433 @code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the
434 latter tokenization could be part of a valid C program and the former
437 Once the input file is broken into tokens, the token boundaries never
438 change, except when the @samp{##} preprocessing operator is used to paste
439 tokens together. @xref{Concatenation}. For example,
451 The compiler does not re-tokenize the preprocessor's output. Each
452 preprocessing token becomes one compiler token.
455 Preprocessing tokens fall into five broad classes: identifiers,
456 preprocessing numbers, string literals, punctuators, and other. An
457 @dfn{identifier} is the same as an identifier in C: any sequence of
458 letters, digits, or underscores, which begins with a letter or
459 underscore. Keywords of C have no significance to the preprocessor;
460 they are ordinary identifiers. You can define a macro whose name is a
461 keyword, for instance. The only identifier which can be considered a
462 preprocessing keyword is @code{defined}. @xref{Defined}.
464 This is mostly true of other languages which use the C preprocessor.
465 However, a few of the keywords of C++ are significant even in the
466 preprocessor. @xref{C++ Named Operators}.
468 In the 1999 C standard, identifiers may contain letters which are not
469 part of the ``basic source character set,'' at the implementation's
470 discretion (such as accented Latin letters, Greek letters, or Chinese
471 ideograms). This may be done with an extended character set, or the
472 @samp{\u} and @samp{\U} escape sequences. GCC does not presently
473 implement either feature in the preprocessor or the compiler.
475 As an extension, GCC treats @samp{$} as a letter. This is for
476 compatibility with some systems, such as VMS, where @samp{$} is commonly
477 used in system-defined function and object names. @samp{$} is not a
478 letter in strictly conforming mode, or if you specify the @option{-$}
479 option. @xref{Invocation}.
482 @cindex preprocessing numbers
483 A @dfn{preprocessing number} has a rather bizarre definition. The
484 category includes all the normal integer and floating point constants
485 one expects of C, but also a number of other things one might not
486 initially recognize as a number. Formally, preprocessing numbers begin
487 with an optional period, a required decimal digit, and then continue
488 with any sequence of letters, digits, underscores, periods, and
489 exponents. Exponents are the two-character sequences @samp{e+},
490 @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and
491 @samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new
492 to C99. They are used for hexadecimal floating-point constants.)
494 The purpose of this unusual definition is to isolate the preprocessor
495 from the full complexity of numeric constants. It does not have to
496 distinguish between lexically valid and invalid floating-point numbers,
497 which is complicated. The definition also permits you to split an
498 identifier at any position and get exactly two tokens, which can then be
499 pasted back together with the @samp{##} operator.
501 It's possible for preprocessing numbers to cause programs to be
502 misinterpreted. For example, @code{0xE+12} is a preprocessing number
503 which does not translate to any valid numeric constant, therefore a
504 syntax error. It does not mean @code{@w{0xE + 12}}, which is what you
507 @cindex string literals
508 @cindex string constants
509 @cindex character constants
510 @cindex header file names
511 @c the @: prevents makeinfo from turning '' into ".
512 @dfn{String literals} are string constants, character constants, and
513 header file names (the argument of @samp{#include}).@footnote{The C
514 standard uses the term @dfn{string literal} to refer only to what we are
515 calling @dfn{string constants}.} String constants and character
516 constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In
517 either case embedded quotes should be escaped with a backslash:
518 @t{'\'@:'} is the character constant for @samp{'}. There is no limit on
519 the length of a character constant, but the value of a character
520 constant that contains more than one character is
521 implementation-defined. @xref{Implementation Details}.
523 Header file names either look like string constants, @t{"@dots{}"}, or are
524 written with angle brackets instead, @t{<@dots{}>}. In either case,
525 backslash is an ordinary character. There is no way to escape the
526 closing quote or angle bracket. The preprocessor looks for the header
527 file in different places depending on which form you use. @xref{Include
530 In standard C, no string literal may extend past the end of a line. GNU
531 CPP accepts multi-line string constants, but not multi-line character
532 constants or header file names. This extension is deprecated and will
533 be removed in GCC 3.1. You may use continued lines instead, or string
534 constant concatenation. @xref{Differences from previous versions}.
538 @cindex alternative tokens
539 @dfn{Punctuators} are all the usual bits of punctuation which are
540 meaningful to C and C++. All but three of the punctuation characters in
541 ASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and
542 @samp{`}. In addition, all the two- and three-character operators are
543 punctuators. There are also six @dfn{digraphs}, which the C++ standard
544 calls @dfn{alternative tokens}, which are merely alternate ways to spell
545 other punctuators. This is a second attempt to work around missing
546 punctuation in obsolete systems. It has no negative side effects,
547 unlike trigraphs, but does not cover as much ground. The digraphs and
548 their corresponding normal punctuators are:
551 Digraph: <% %> <: :> %: %:%:
552 Punctuator: @{ @} [ ] # ##
556 Any other single character is considered ``other.'' It is passed on to
557 the preprocessor's output unmolested. The C compiler will almost
558 certainly reject source code containing ``other'' tokens. In ASCII, the
559 only other characters are @samp{@@}, @samp{$}, @samp{`}, and control
560 characters other than NUL (all bits zero). (Note that @samp{$} is
561 normally considered a letter.) All characters with the high bit set
562 (numeric range 0x7F--0xFF) are also ``other'' in the present
563 implementation. This will change when proper support for international
564 character sets is added to GCC@.
566 NUL is a special case because of the high probability that its
567 appearance is accidental, and because it may be invisible to the user
568 (many terminals do not display NUL at all). Within comments, NULs are
569 silently ignored, just as any other character would be. In running
570 text, NUL is considered white space. For example, these two directives
571 have the same meaning.
579 (where @samp{^@@} is ASCII NUL)@. Within string or character constants,
580 NULs are preserved. In the latter two cases the preprocessor emits a
583 @node The preprocessing language
584 @section The preprocessing language
586 @cindex preprocessing directives
587 @cindex directive line
588 @cindex directive name
590 After tokenization, the stream of tokens may simply be passed straight
591 to the compiler's parser. However, if it contains any operations in the
592 @dfn{preprocessing language}, it will be transformed first. This stage
593 corresponds roughly to the standard's ``translation phase 4'' and is
594 what most people think of as the preprocessor's job.
596 The preprocessing language consists of @dfn{directives} to be executed
597 and @dfn{macros} to be expanded. Its primary capabilities are:
601 Inclusion of header files. These are files of declarations that can be
602 substituted into your program.
605 Macro expansion. You can define @dfn{macros}, which are abbreviations
606 for arbitrary fragments of C code. The preprocessor will replace the
607 macros with their definitions throughout the program. Some macros are
608 automatically defined for you.
611 Conditional compilation. You can include or exclude parts of the
612 program according to various conditions.
615 Line control. If you use a program to combine or rearrange source files
616 into an intermediate file which is then compiled, you can use line
617 control to inform the compiler where each source line originally came
621 Diagnostics. You can detect problems at compile time and issue errors
625 There are a few more, less useful, features.
627 Except for expansion of predefined macros, all these operations are
628 triggered with @dfn{preprocessing directives}. Preprocessing directives
629 are lines in your program that start with @samp{#}. Whitespace is
630 allowed before and after the @samp{#}. The @samp{#} is followed by an
631 identifier, the @dfn{directive name}. It specifies the operation to
632 perform. Directives are commonly referred to as @samp{#@var{name}}
633 where @var{name} is the directive name. For example, @samp{#define} is
634 the directive that defines a macro.
636 The @samp{#} which begins a directive cannot come from a macro
637 expansion. Also, the directive name is not macro expanded. Thus, if
638 @code{foo} is defined as a macro expanding to @code{define}, that does
639 not make @samp{#foo} a valid preprocessing directive.
641 The set of valid directive names is fixed. Programs cannot define new
642 preprocessing directives.
644 Some directives require arguments; these make up the rest of the
645 directive line and must be separated from the directive name by
646 whitespace. For example, @samp{#define} must be followed by a macro
647 name and the intended expansion of the macro.
649 A preprocessing directive cannot cover more than one line. The line
650 may, however, be continued with backslash-newline, or by a block comment
651 which extends past the end of the line. In either case, when the
652 directive is processed, the continuations have already been merged with
653 the first line to make one long line.
656 @chapter Header Files
659 A header file is a file containing C declarations and macro definitions
660 (@pxref{Macros}) to be shared between several source files. You request
661 the use of a header file in your program by @dfn{including} it, with the
662 C preprocessing directive @samp{#include}.
664 Header files serve two purposes.
668 @cindex system header files
669 System header files declare the interfaces to parts of the operating
670 system. You include them in your program to supply the definitions and
671 declarations you need to invoke system calls and libraries.
674 Your own header files contain declarations for interfaces between the
675 source files of your program. Each time you have a group of related
676 declarations and macro definitions all or most of which are needed in
677 several different source files, it is a good idea to create a header
681 Including a header file produces the same results as copying the header
682 file into each source file that needs it. Such copying would be
683 time-consuming and error-prone. With a header file, the related
684 declarations appear in only one place. If they need to be changed, they
685 can be changed in one place, and programs that include the header file
686 will automatically use the new version when next recompiled. The header
687 file eliminates the labor of finding and changing all the copies as well
688 as the risk that a failure to find one copy will result in
689 inconsistencies within a program.
691 In C, the usual convention is to give header files names that end with
692 @file{.h}. It is most portable to use only letters, digits, dashes, and
693 underscores in header file names, and at most one dot.
697 * Include Operation::
699 * Once-Only Headers::
700 * Computed Includes::
706 @section Include Syntax
709 Both user and system header files are included using the preprocessing
710 directive @samp{#include}. It has two variants:
713 @item #include <@var{file}>
714 This variant is used for system header files. It searches for a file
715 named @var{file} in a standard list of system directories. You can prepend
716 directories to this list with the @option{-I} option (@pxref{Invocation}).
718 @item #include "@var{file}"
719 This variant is used for header files of your own program. It searches
720 for a file named @var{file} first in the directory containing the
721 current file, then in the same directories used for @code{<@var{file}>}.
724 The argument of @samp{#include}, whether delimited with quote marks or
725 angle brackets, behaves like a string constant in that comments are not
726 recognized, and macro names are not expanded. Thus, @code{@w{#include
727 <x/*y>}} specifies inclusion of a system header file named @file{x/*y}.
729 However, if backslashes occur within @var{file}, they are considered
730 ordinary text characters, not escape characters. None of the character
731 escape sequences appropriate to string constants in C are processed.
732 Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three
733 backslashes. (Some systems interpret @samp{\} as a pathname separator.
734 All of these also interpret @samp{/} the same way. It is most portable
735 to use only @samp{/}.)
737 It is an error if there is anything (other than comments) on the line
740 @node Include Operation
741 @section Include Operation
743 The @samp{#include} directive works by directing the C preprocessor to
744 scan the specified file as input before continuing with the rest of the
745 current file. The output from the preprocessor contains the output
746 already generated, followed by the output resulting from the included
747 file, followed by the output that comes from the text after the
748 @samp{#include} directive. For example, if you have a header file
749 @file{header.h} as follows,
756 and a main program called @file{program.c} that uses the header file,
771 the compiler will see the same token stream as it would if
772 @file{program.c} read
785 Included files are not limited to declarations and macro definitions;
786 those are merely the typical uses. Any fragment of a C program can be
787 included from another file. The include file could even contain the
788 beginning of a statement that is concluded in the containing file, or
789 the end of a statement that was started in the including file. However,
790 a comment or a string or character constant may not start in the
791 included file and finish in the including file. An unterminated
792 comment, string constant or character constant in an included file is
793 considered to end (with an error message) at the end of the file.
795 To avoid confusion, it is best if header files contain only complete
796 syntactic units---function declarations or definitions, type
799 The line following the @samp{#include} directive is always treated as a
800 separate line by the C preprocessor, even if the included file lacks a
806 GCC looks in several different places for headers. On a normal Unix
807 system, if you do not instruct it otherwise, it will look for headers
808 requested with @code{@w{#include <@var{file}>}} in:
812 /usr/lib/gcc-lib/@var{target}/@var{version}/include
813 /usr/@var{target}/include
817 For C++ programs, it will also look in @file{/usr/include/g++-v3},
818 first. In the above, @var{target} is the canonical name of the system
819 GCC was configured to compile code for; often but not always the same as
820 the canonical name of the system it runs on. @var{version} is the
821 version of GCC in use.
823 You can add to this list with the @option{-I@var{dir}} command line
824 option. All the directories named by @option{-I} are searched, in
825 left-to-right order, @emph{before} the default directories. You can
826 also prevent GCC from searching any of the default directories with the
827 @option{-nostdinc} option. This is useful when you are compiling an
828 operating system kernel or some other program that does not use the
829 standard C library facilities, or the standard C library itself.
831 GCC looks for headers requested with @code{@w{#include "@var{file}"}}
832 first in the directory containing the current file, then in the same
833 places it would have looked for a header requested with angle brackets.
834 For example, if @file{/usr/include/sys/stat.h} contains
835 @code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in
836 @file{/usr/include/sys}, then in its usual search path.
838 If you name a search directory with @option{-I@var{dir}} that is also a
839 system include directory, the @option{-I} wins; the directory will be
840 searched according to the @option{-I} ordering, and it will not be
841 treated as a system include directory. GCC will warn you when a system
842 include directory is hidden in this way.
844 @samp{#line} (@pxref{Line Control}) does not change GCC's idea of the
845 directory containing the current file.
847 You may put @option{-I-} at any point in your list of @option{-I} options.
848 This has two effects. First, directories appearing before the
849 @option{-I-} in the list are searched only for headers requested with
850 quote marks. Directories after @option{-I-} are searched for all
851 headers. Second, the directory containing the current file is not
852 searched for anything, unless it happens to be one of the directories
853 named by an @option{-I} switch.
855 @option{-I. -I-} is not the same as no @option{-I} options at all, and does
856 not cause the same behavior for @samp{<>} includes that @samp{""}
857 includes get with no special options. @option{-I.} searches the
858 compiler's current working directory for header files. That may or may
859 not be the same as the directory containing the current file.
861 If you need to look for headers in a directory named @file{-}, write
864 There are several more ways to adjust the header search path. They are
865 generally less useful. @xref{Invocation}.
867 @node Once-Only Headers
868 @section Once-Only Headers
869 @cindex repeated inclusion
870 @cindex including just once
871 @cindex wrapper @code{#ifndef}
873 If a header file happens to be included twice, the compiler will process
874 its contents twice. This is very likely to cause an error, e.g.@: when the
875 compiler sees the same structure definition twice. Even if it does not,
876 it will certainly waste time.
878 The standard way to prevent this is to enclose the entire real contents
879 of the file in a conditional, like this:
884 #ifndef FILE_FOO_SEEN
885 #define FILE_FOO_SEEN
887 @var{the entire file}
889 #endif /* !FILE_FOO_SEEN */
893 This construct is commonly known as a @dfn{wrapper #ifndef}.
894 When the header is included again, the conditional will be false,
895 because @code{FILE_FOO_SEEN} is defined. The preprocessor will skip
896 over the entire contents of the file, and the compiler will not see it
899 GNU CPP optimizes even further. It remembers when a header file has a
900 wrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that
901 header, and the macro in the @samp{#ifndef} is still defined, it does
902 not bother to rescan the file at all.
904 You can put comments outside the wrapper. They will not interfere with
907 @cindex controlling macro
909 The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or
910 @dfn{guard macro}. In a user header file, the macro name should not
911 begin with @samp{_}. In a system header file, it should begin with
912 @samp{__} to avoid conflicts with user programs. In any kind of header
913 file, the macro name should contain the name of the file and some
914 additional text, to avoid conflicts with other header files.
916 @node Computed Includes
917 @section Computed Includes
918 @cindex computed includes
919 @cindex macros in include
921 Sometimes it is necessary to select one of several different header
922 files to be included into your program. They might specify
923 configuration parameters to be used on different sorts of operating
924 systems, for instance. You could do this with a series of conditionals,
928 # include "system_1.h"
930 # include "system_2.h"
936 That rapidly becomes tedious. Instead, the preprocessor offers the
937 ability to use a macro for the header name. This is called a
938 @dfn{computed include}. Instead of writing a header name as the direct
939 argument of @samp{#include}, you simply put a macro name there instead:
942 #define SYSTEM_H "system_1.h"
948 @code{SYSTEM_H} will be expanded, and the preprocessor will look for
949 @file{system_1.h} as if the @samp{#include} had been written that way
950 originally. @code{SYSTEM_H} could be defined by your Makefile with a
953 You must be careful when you define the macro. @samp{#define} saves
954 tokens, not text. The preprocessor has no way of knowing that the macro
955 will be used as the argument of @samp{#include}, so it generates
956 ordinary tokens, not a header name. This is unlikely to cause problems
957 if you use double-quote includes, which are close enough to string
958 constants. If you use angle brackets, however, you may have trouble.
960 The syntax of a computed include is actually a bit more general than the
961 above. If the first non-whitespace character after @samp{#include} is
962 not @samp{"} or @samp{<}, then the entire line is macro-expanded
963 like running text would be.
965 If the line expands to a single string constant, the contents of that
966 string constant are the file to be included. CPP does not re-examine the
967 string for embedded quotes, but neither does it process backslash
968 escapes in the string. Therefore
971 #define HEADER "a\"b"
976 looks for a file named @file{a\"b}. CPP searches for the file according
977 to the rules for double-quoted includes.
979 If the line expands to a token stream beginning with a @samp{<} token
980 and including a @samp{>} token, then the tokens between the @samp{<} and
981 the first @samp{>} are combined to form the filename to be included.
982 Any whitespace between tokens is reduced to a single space; then any
983 space after the initial @samp{<} is retained, but a trailing space
984 before the closing @samp{>} is ignored. CPP searches for the file
985 according to the rules for angle-bracket includes.
987 In either case, if there are any tokens on the line after the file name,
988 an error occurs and the directive is not processed. It is also an error
989 if the result of expansion does not match either of the two expected
992 These rules are implementation-defined behavior according to the C
993 standard. To minimize the risk of different compilers interpreting your
994 computed includes differently, we recommend you use only a single
995 object-like macro which expands to a string constant. This will also
996 minimize confusion for people reading your program.
998 @node Wrapper Headers
999 @section Wrapper Headers
1000 @cindex wrapper headers
1001 @cindex overriding a header file
1002 @findex #include_next
1004 Sometimes it is necessary to adjust the contents of a system-provided
1005 header file without editing it directly. GCC's @command{fixincludes}
1006 operation does this, for example. One way to do that would be to create
1007 a new header file with the same name and insert it in the search path
1008 before the original header. That works fine as long as you're willing
1009 to replace the old header entirely. But what if you want to refer to
1010 the old header from the new one?
1012 You cannot simply include the old header with @samp{#include}. That
1013 will start from the beginning, and find your new header again. If your
1014 header is not protected from multiple inclusion (@pxref{Once-Only
1015 Headers}), it will recurse infinitely and cause a fatal error.
1017 You could include the old header with an absolute pathname:
1019 #include "/usr/include/old-header.h"
1022 This works, but is not clean; should the system headers ever move, you
1023 would have to edit the new headers to match.
1025 There is no way to solve this problem within the C standard, but you can
1026 use the GNU extension @samp{#include_next}. It means, ``Include the
1027 @emph{next} file with this name.'' This directive works like
1028 @samp{#include} except in searching for the specified file: it starts
1029 searching the list of header file directories @emph{after} the directory
1030 in which the current file was found.
1032 Suppose you specify @option{-I /usr/local/include}, and the list of
1033 directories to search also includes @file{/usr/include}; and suppose
1034 both directories contain @file{signal.h}. Ordinary @code{@w{#include
1035 <signal.h>}} finds the file under @file{/usr/local/include}. If that
1036 file contains @code{@w{#include_next <signal.h>}}, it starts searching
1037 after that directory, and finds the file in @file{/usr/include}.
1039 @samp{#include_next} does not distinguish between @code{<@var{file}>}
1040 and @code{"@var{file}"} inclusion, nor does it check that the file you
1041 specify has the same name as the current file. It simply looks for the
1042 file named, starting with the directory in the search path after the one
1043 where the current file was found.
1045 The use of @samp{#include_next} can lead to great confusion. We
1046 recommend it be used only when there is no other alternative. In
1047 particular, it should not be used in the headers belonging to a specific
1048 program; it should be used only to make global corrections along the
1049 lines of @command{fixincludes}.
1051 @node System Headers
1052 @section System Headers
1053 @cindex system header files
1055 The header files declaring interfaces to the operating system and
1056 runtime libraries often cannot be written in strictly conforming C@.
1057 Therefore, GCC gives code found in @dfn{system headers} special
1058 treatment. All warnings, other than those generated by @samp{#warning}
1059 (@pxref{Diagnostics}), are suppressed while GCC is processing a system
1060 header. Macros defined in a system header are immune to a few warnings
1061 wherever they are expanded. This immunity is granted on an ad-hoc
1062 basis, when we find that a warning generates lots of false positives
1063 because of code in macros defined in system headers.
1065 Normally, only the headers found in specific directories are considered
1066 system headers. These directories are determined when GCC is compiled.
1067 There are, however, two ways to make normal headers into system headers.
1069 The @option{-isystem} command line option adds its argument to the list of
1070 directories to search for headers, just like @option{-I}. Any headers
1071 found in that directory will be considered system headers.
1073 All directories named by @option{-isystem} are searched @emph{after} all
1074 directories named by @option{-I}, no matter what their order was on the
1075 command line. If the same directory is named by both @option{-I} and
1076 @option{-isystem}, @option{-I} wins; it is as if the @option{-isystem} option
1077 had never been specified at all. GCC warns you when this happens.
1079 @findex #pragma GCC system_header
1080 There is also a directive, @code{@w{#pragma GCC system_header}}, which
1081 tells GCC to consider the rest of the current include file a system
1082 header, no matter where it was found. Code that comes before the
1083 @samp{#pragma} in the file will not be affected. @code{@w{#pragma GCC
1084 system_header}} has no effect in the primary source file.
1086 On very old systems, some of the pre-defined system header directories
1087 get even more special treatment. GNU C++ considers code in headers
1088 found in those directories to be surrounded by an @code{@w{extern "C"}}
1089 block. There is no way to request this behavior with a @samp{#pragma},
1090 or from the command line.
1095 A @dfn{macro} is a fragment of code which has been given a name.
1096 Whenever the name is used, it is replaced by the contents of the macro.
1097 There are two kinds of macros. They differ mostly in what they look
1098 like when they are used. @dfn{Object-like} macros resemble data objects
1099 when used, @dfn{function-like} macros resemble function calls.
1101 You may define any valid identifier as a macro, even if it is a C
1102 keyword. The preprocessor does not know anything about keywords. This
1103 can be useful if you wish to hide a keyword such as @code{const} from an
1104 older compiler that does not understand it. However, the preprocessor
1105 operator @code{defined} (@pxref{Defined}) can never be defined as a
1106 macro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be
1107 macros when you are compiling C++.
1110 * Object-like Macros::
1111 * Function-like Macros::
1116 * Predefined Macros::
1117 * Undefining and Redefining Macros::
1121 @node Object-like Macros
1122 @section Object-like Macros
1123 @cindex object-like macro
1124 @cindex symbolic constants
1125 @cindex manifest constants
1127 An @dfn{object-like macro} is a simple identifier which will be replaced
1128 by a code fragment. It is called object-like because it looks like a
1129 data object in code that uses it. They are most commonly used to give
1130 symbolic names to numeric constants.
1133 You create macros with the @samp{#define} directive. @samp{#define} is
1134 followed by the name of the macro and then the token sequence it should
1135 be an abbreviation for, which is variously referred to as the macro's
1136 @dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example,
1139 #define BUFFER_SIZE 1024
1143 defines a macro named @code{BUFFER_SIZE} as an abbreviation for the
1144 token @code{1024}. If somewhere after this @samp{#define} directive
1145 there comes a C statement of the form
1148 foo = (char *) malloc (BUFFER_SIZE);
1152 then the C preprocessor will recognize and @dfn{expand} the macro
1153 @code{BUFFER_SIZE}. The C compiler will see the same tokens as it would
1157 foo = (char *) malloc (1024);
1160 By convention, macro names are written in upper case. Programs are
1161 easier to read when it is possible to tell at a glance which names are
1164 The macro's body ends at the end of the @samp{#define} line. You may
1165 continue the definition onto multiple lines, if necessary, using
1166 backslash-newline. When the macro is expanded, however, it will all
1167 come out on one line. For example,
1170 #define NUMBERS 1, \
1173 int x[] = @{ NUMBERS @};
1174 @expansion{} int x[] = @{ 1, 2, 3 @};
1178 The most common visible consequence of this is surprising line numbers
1181 There is no restriction on what can go in a macro body provided it
1182 decomposes into valid preprocessing tokens. Parentheses need not
1183 balance, and the body need not resemble valid C code. (If it does not,
1184 you may get error messages from the C compiler when you use the macro.)
1186 The C preprocessor scans your program sequentially. Macro definitions
1187 take effect at the place you write them. Therefore, the following input
1188 to the C preprocessor
1204 When the preprocessor expands a macro name, the macro's expansion
1205 replaces the macro invocation, then the expansion is examined for more
1206 macros to expand. For example,
1210 #define TABLESIZE BUFSIZE
1211 #define BUFSIZE 1024
1213 @expansion{} BUFSIZE
1219 @code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that
1220 macro is expanded to produce the final result, @code{1024}.
1222 Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was
1223 defined. The @samp{#define} for @code{TABLESIZE} uses exactly the
1224 expansion you specify---in this case, @code{BUFSIZE}---and does not
1225 check to see whether it too contains macro names. Only when you
1226 @emph{use} @code{TABLESIZE} is the result of its expansion scanned for
1229 This makes a difference if you change the definition of @code{BUFSIZE}
1230 at some point in the source file. @code{TABLESIZE}, defined as shown,
1231 will always expand using the definition of @code{BUFSIZE} that is
1232 currently in effect:
1235 #define BUFSIZE 1020
1236 #define TABLESIZE BUFSIZE
1242 Now @code{TABLESIZE} expands (in two stages) to @code{37}.
1244 If the expansion of a macro contains its own name, either directly or
1245 via intermediate macros, it is not expanded again when the expansion is
1246 examined for more macros. This prevents infinite recursion.
1247 @xref{Self-Referential Macros}, for the precise details.
1249 @node Function-like Macros
1250 @section Function-like Macros
1251 @cindex function-like macros
1253 You can also define macros whose use looks like a function call. These
1254 are called @dfn{function-like macros}. To define a function-like macro,
1255 you use the same @samp{#define} directive, but you put a pair of
1256 parentheses immediately after the macro name. For example,
1259 #define lang_init() c_init()
1261 @expansion{} c_init()
1264 A function-like macro is only expanded if its name appears with a pair
1265 of parentheses after it. If you write just the name, it is left alone.
1266 This can be useful when you have a function and a macro of the same
1267 name, and you wish to use the function sometimes.
1270 extern void foo(void);
1271 #define foo() /* optimized inline version */
1277 Here the call to @code{foo()} will use the macro, but the function
1278 pointer will get the address of the real function. If the macro were to
1279 be expanded, it would cause a syntax error.
1281 If you put spaces between the macro name and the parentheses in the
1282 macro definition, that does not define a function-like macro, it defines
1283 an object-like macro whose expansion happens to begin with a pair of
1287 #define lang_init () c_init()
1289 @expansion{} () c_init()()
1292 The first two pairs of parentheses in this expansion come from the
1293 macro. The third is the pair that was originally after the macro
1294 invocation. Since @code{lang_init} is an object-like macro, it does not
1295 consume those parentheses.
1297 @node Macro Arguments
1298 @section Macro Arguments
1300 @cindex macros with arguments
1301 @cindex arguments in macro definitions
1303 Function-like macros can take @dfn{arguments}, just like true functions.
1304 To define a macro that uses arguments, you insert @dfn{parameters}
1305 between the pair of parentheses in the macro definition that make the
1306 macro function-like. The parameters must be valid C identifiers,
1307 separated by commas and optionally whitespace.
1309 To invoke a macro that takes arguments, you write the name of the macro
1310 followed by a list of @dfn{actual arguments} in parentheses, separated
1311 by commas. The invocation of the macro need not be restricted to a
1312 single logical line---it can cross as many lines in the source file as
1313 you wish. The number of arguments you give must match the number of
1314 parameters in the macro definition. When the macro is expanded, each
1315 use of a parameter in its body is replaced by the tokens of the
1316 corresponding argument. (You need not use all of the parameters in the
1319 As an example, here is a macro that computes the minimum of two numeric
1320 values, as it is defined in many C programs, and some uses.
1323 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1324 x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b));
1325 y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2));
1326 z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p));
1330 (In this small example you can already see several of the dangers of
1331 macro arguments. @xref{Macro Pitfalls}, for detailed explanations.)
1333 Leading and trailing whitespace in each argument is dropped, and all
1334 whitespace between the tokens of an argument is reduced to a single
1335 space. Parentheses within each argument must balance; a comma within
1336 such parentheses does not end the argument. However, there is no
1337 requirement for square brackets or braces to balance, and they do not
1338 prevent a comma from separating arguments. Thus,
1341 macro (array[x = y, x + 1])
1345 passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
1346 1]}. If you want to supply @code{array[x = y, x + 1]} as an argument,
1347 you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C
1350 All arguments to a macro are completely macro-expanded before they are
1351 substituted into the macro body. After substitution, the complete text
1352 is scanned again for macros to expand, including the arguments. This rule
1353 may seem strange, but it is carefully designed so you need not worry
1354 about whether any function call is actually a macro invocation. You can
1355 run into trouble if you try to be too clever, though. @xref{Argument
1356 Prescan}, for detailed discussion.
1358 For example, @code{min (min (a, b), c)} is first expanded to
1361 min (((a) < (b) ? (a) : (b)), (c))
1369 ((((a) < (b) ? (a) : (b))) < (c)
1370 ? (((a) < (b) ? (a) : (b)))
1376 (Line breaks shown here for clarity would not actually be generated.)
1378 @cindex empty macro arguments
1379 You can leave macro arguments empty; this is not an error to the
1380 preprocessor (but many macros will then expand to invalid code).
1381 You cannot leave out arguments entirely; if a macro takes two arguments,
1382 there must be exactly one comma at the top level of its argument list.
1383 Here are some silly examples using @code{min}:
1386 min(, b) @expansion{} (( ) < (b) ? ( ) : (b))
1387 min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( ))
1388 min(,) @expansion{} (( ) < ( ) ? ( ) : ( ))
1389 min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( ))
1391 min() @error{} macro "min" requires 2 arguments, but only 1 given
1392 min(,,) @error{} macro "min" passed 3 arguments, but takes just 2
1395 Whitespace is not a preprocessing token, so if a macro @code{foo} takes
1396 one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an
1397 empty argument. Previous GNU preprocessor implementations and
1398 documentation were incorrect on this point, insisting that a
1399 function-like macro that takes a single argument be passed a space if an
1400 empty argument was required.
1402 Macro parameters appearing inside string literals are not replaced by
1403 their corresponding actual arguments.
1406 #define foo(x) x, "x"
1407 foo(bar) @expansion{} bar, "x"
1410 @node Stringification
1411 @section Stringification
1412 @cindex stringification
1413 @cindex @samp{#} operator
1415 Sometimes you may want to convert a macro argument into a string
1416 constant. Parameters are not replaced inside string constants, but you
1417 can use the @samp{#} preprocessing operator instead. When a macro
1418 parameter is used with a leading @samp{#}, the preprocessor replaces it
1419 with the literal text of the actual argument, converted to a string
1420 constant. Unlike normal parameter replacement, the argument is not
1421 macro-expanded first. This is called @dfn{stringification}.
1423 There is no way to combine an argument with surrounding text and
1424 stringify it all together. Instead, you can write a series of adjacent
1425 string constants and stringified arguments. The preprocessor will
1426 replace the stringified arguments with string constants. The C
1427 compiler will then combine all the adjacent string constants into one
1430 Here is an example of a macro definition that uses stringification:
1434 #define WARN_IF(EXP) \
1436 fprintf (stderr, "Warning: " #EXP "\n"); @} \
1439 @expansion{} do @{ if (x == 0)
1440 fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0);
1445 The argument for @code{EXP} is substituted once, as-is, into the
1446 @code{if} statement, and once, stringified, into the argument to
1447 @code{fprintf}. If @code{x} were a macro, it would be expanded in the
1448 @code{if} statement, but not in the string.
1450 The @code{do} and @code{while (0)} are a kludge to make it possible to
1451 write @code{WARN_IF (@var{arg});}, which the resemblance of
1452 @code{WARN_IF} to a function would make C programmers want to do; see
1453 @ref{Swallowing the Semicolon}.
1455 Stringification in C involves more than putting double-quote characters
1456 around the fragment. The preprocessor backslash-escapes the quotes
1457 surrounding embedded string constants, and all backslashes within string and
1458 character constants, in order to get a valid C string constant with the
1459 proper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in
1460 @t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string
1461 or character constants are not duplicated: @samp{\n} by itself
1462 stringifies to @t{"\n"}.
1464 All leading and trailing whitespace in text being stringified is
1465 ignored. Any sequence of whitespace in the middle of the text is
1466 converted to a single space in the stringified result. Comments are
1467 replaced by whitespace long before stringification happens, so they
1468 never appear in stringified text.
1470 There is no way to convert a macro argument into a character constant.
1472 If you want to stringify the result of expansion of a macro argument,
1473 you have to use two levels of macros.
1476 #define xstr(s) str(s)
1482 @expansion{} xstr (4)
1483 @expansion{} str (4)
1487 @code{s} is stringified when it is used in @code{str}, so it is not
1488 macro-expanded first. But @code{s} is an ordinary argument to
1489 @code{xstr}, so it is completely macro-expanded before @code{xstr}
1490 itself is expanded (@pxref{Argument Prescan}). Therefore, by the time
1491 @code{str} gets to its argument, it has already been macro-expanded.
1494 @section Concatenation
1495 @cindex concatenation
1496 @cindex token pasting
1497 @cindex token concatenation
1498 @cindex @samp{##} operator
1500 It is often useful to merge two tokens into one while expanding macros.
1501 This is called @dfn{token pasting} or @dfn{token concatenation}. The
1502 @samp{##} preprocessing operator performs token pasting. When a macro
1503 is expanded, the two tokens on either side of each @samp{##} operator
1504 are combined into a single token, which then replaces the @samp{##} and
1505 the two original tokens in the macro expansion. Usually both will be
1506 identifiers, or one will be an identifier and the other a preprocessing
1507 number. When pasted, they make a longer identifier. This isn't the
1508 only valid case. It is also possible to concatenate two numbers (or a
1509 number and a name, such as @code{1.5} and @code{e3}) into a number.
1510 Also, multi-character operators such as @code{+=} can be formed by
1513 However, two tokens that don't together form a valid token cannot be
1514 pasted together. For example, you cannot concatenate @code{x} with
1515 @code{+} in either order. If you try, the preprocessor issues a warning
1516 and emits the two tokens. Whether it puts white space between the
1517 tokens is undefined. It is common to find unnecessary uses of @samp{##}
1518 in complex macros. If you get this warning, it is likely that you can
1519 simply remove the @samp{##}.
1521 Both the tokens combined by @samp{##} could come from the macro body,
1522 but you could just as well write them as one token in the first place.
1523 Token pasting is most useful when one or both of the tokens comes from a
1524 macro argument. If either of the tokens next to an @samp{##} is a
1525 parameter name, it is replaced by its actual argument before @samp{##}
1526 executes. As with stringification, the actual argument is not
1527 macro-expanded first. If the argument is empty, that @samp{##} has no
1530 Keep in mind that the C preprocessor converts comments to whitespace
1531 before macros are even considered. Therefore, you cannot create a
1532 comment by concatenating @samp{/} and @samp{*}. You can put as much
1533 whitespace between @samp{##} and its operands as you like, including
1534 comments, and you can put comments in arguments that will be
1535 concatenated. However, it is an error if @samp{##} appears at either
1536 end of a macro body.
1538 Consider a C program that interprets named commands. There probably
1539 needs to be a table of commands, perhaps an array of structures declared
1547 void (*function) (void);
1552 struct command commands[] =
1554 @{ "quit", quit_command @},
1555 @{ "help", help_command @},
1561 It would be cleaner not to have to give each command name twice, once in
1562 the string constant and once in the function name. A macro which takes the
1563 name of a command as an argument can make this unnecessary. The string
1564 constant can be created with stringification, and the function name by
1565 concatenating the argument with @samp{_command}. Here is how it is done:
1568 #define COMMAND(NAME) @{ #NAME, NAME ## _command @}
1570 struct command commands[] =
1578 @node Variadic Macros
1579 @section Variadic Macros
1580 @cindex variable number of arguments
1581 @cindex macros with variable arguments
1582 @cindex variadic macros
1584 A macro can be declared to accept a variable number of arguments much as
1585 a function can. The syntax for defining the macro is similar to that of
1586 a function. Here is an example:
1589 #define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__)
1592 This kind of macro is called @dfn{variadic}. When the macro is invoked,
1593 all the tokens in its argument list after the last named argument (this
1594 macro has none), including any commas, become the @dfn{variable
1595 argument}. This sequence of tokens replaces the identifier
1596 @code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we
1597 have this expansion:
1600 eprintf ("%s:%d: ", input_file, lineno)
1601 @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno)
1604 The variable argument is completely macro-expanded before it is inserted
1605 into the macro expansion, just like an ordinary argument. You may use
1606 the @samp{#} and @samp{##} operators to stringify the variable argument
1607 or to paste its leading or trailing token with another token. (But see
1608 below for an important special case for @samp{##}.)
1610 If your macro is complicated, you may want a more descriptive name for
1611 the variable argument than @code{@w{__VA_ARGS__}}. GNU CPP permits
1612 this, as an extension. You may write an argument name immediately
1613 before the @samp{@dots{}}; that name is used for the variable argument.
1614 The @code{eprintf} macro above could be written
1617 #define eprintf(args@dots{}) fprintf (stderr, args)
1621 using this extension. You cannot use @code{__VA_ARGS__} and this
1622 extension in the same macro.
1624 You can have named arguments as well as variable arguments in a variadic
1625 macro. We could define @code{eprintf} like this, instead:
1628 #define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__)
1632 This formulation looks more descriptive, but unfortunately it is less
1633 flexible: you must now supply at least one argument after the format
1634 string. In standard C, you cannot omit the comma separating the named
1635 argument from the variable arguments. Furthermore, if you leave the
1636 variable argument empty, you will get a syntax error, because
1637 there will be an extra comma after the format string.
1640 eprintf("success!\n", );
1641 @expansion{} fprintf(stderr, "success!\n", );
1644 GNU CPP has a pair of extensions which deal with this problem. First,
1645 you are allowed to leave the variable argument out entirely:
1648 eprintf ("success!\n")
1649 @expansion{} fprintf(stderr, "success!\n", );
1653 Second, the @samp{##} token paste operator has a special meaning when
1654 placed between a comma and a variable argument. If you write
1657 #define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__)
1661 and the variable argument is left out when the @code{eprintf} macro is
1662 used, then the comma before the @samp{##} will be deleted. This does
1663 @emph{not} happen if you pass an empty argument, nor does it happen if
1664 the token preceding @samp{##} is anything other than a comma.
1667 eprintf ("success!\n")
1668 @expansion{} fprintf(stderr, "success!\n");
1671 C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}}
1672 can appear is in the replacement list of a variadic macro. It may not
1673 be used as a macro name, macro argument name, or within a different type
1674 of macro. It may also be forbidden in open text; the standard is
1675 ambiguous. We recommend you avoid using it except for its defined
1678 Variadic macros are a new feature in C99. GNU CPP has supported them
1679 for a long time, but only with a named variable argument
1680 (@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are
1681 concerned with portability to previous versions of GCC, you should use
1682 only named variable arguments. On the other hand, if you are concerned
1683 with portability to other conforming implementations of C99, you should
1684 use only @code{@w{__VA_ARGS__}}.
1686 Previous versions of GNU CPP implemented the comma-deletion extension
1687 much more generally. We have restricted it in this release to minimize
1688 the differences from C99. To get the same effect with both this and
1689 previous versions of GCC, the token preceding the special @samp{##} must
1690 be a comma, and there must be white space between that comma and
1691 whatever comes immediately before it:
1694 #define eprintf(format, args@dots{}) fprintf (stderr, format , ##args)
1698 @xref{Differences from previous versions}, for the gory details.
1700 @node Predefined Macros
1701 @section Predefined Macros
1703 @cindex predefined macros
1704 Several object-like macros are predefined; you use them without
1705 supplying their definitions. They fall into three classes: standard,
1706 common, and system-specific.
1708 In C++, there is a fourth category, the named operators. They act like
1709 predefined macros, but you cannot undefine them.
1712 * Standard Predefined Macros::
1713 * Common Predefined Macros::
1714 * System-specific Predefined Macros::
1715 * C++ Named Operators::
1718 @node Standard Predefined Macros
1719 @subsection Standard Predefined Macros
1720 @cindex standard predefined macros.
1722 The standard predefined macros are specified by the C and/or C++
1723 language standards, so they are available with all compilers that
1724 implement those standards. Older compilers may not provide all of
1725 them. Their names all start with double underscores.
1729 This macro expands to the name of the current input file, in the form of
1730 a C string constant. This is the path by which the preprocessor opened
1731 the file, not the short name specified in @samp{#include} or as the
1732 input file name argument. For example,
1733 @code{"/usr/local/include/myheader.h"} is a possible expansion of this
1737 This macro expands to the current input line number, in the form of a
1738 decimal integer constant. While we call it a predefined macro, it's
1739 a pretty strange macro, since its ``definition'' changes with each
1740 new line of source code.
1743 @code{__FILE__} and @code{__LINE__} are useful in generating an error
1744 message to report an inconsistency detected by the program; the message
1745 can state the source line at which the inconsistency was detected. For
1749 fprintf (stderr, "Internal error: "
1750 "negative string length "
1751 "%d at %s, line %d.",
1752 length, __FILE__, __LINE__);
1755 An @samp{#include} directive changes the expansions of @code{__FILE__}
1756 and @code{__LINE__} to correspond to the included file. At the end of
1757 that file, when processing resumes on the input file that contained
1758 the @samp{#include} directive, the expansions of @code{__FILE__} and
1759 @code{__LINE__} revert to the values they had before the
1760 @samp{#include} (but @code{__LINE__} is then incremented by one as
1761 processing moves to the line after the @samp{#include}).
1763 A @samp{#line} directive changes @code{__LINE__}, and may change
1764 @code{__FILE__} as well. @xref{Line Control}.
1766 C99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__}
1767 for a long time. Both of these are strings containing the name of the
1768 current function (there are slight semantic differences; see the GCC
1769 manual). Neither of them is a macro; the preprocessor does not know the
1770 name of the current function. They tend to be useful in conjunction
1771 with @code{__FILE__} and @code{__LINE__}, though.
1776 This macro expands to a string constant that describes the date on which
1777 the preprocessor is being run. The string constant contains eleven
1778 characters and looks like @code{@w{"Feb 12 1996"}}. If the day of the
1779 month is less than 10, it is padded with a space on the left.
1782 This macro expands to a string constant that describes the time at
1783 which the preprocessor is being run. The string constant contains
1784 eight characters and looks like @code{"23:59:01"}.
1787 In normal operation, this macro expands to the constant 1, to signify
1788 that this compiler conforms to ISO Standard C@. If GNU CPP is used with
1789 a compiler other than GCC, this is not necessarily true; however, the
1790 preprocessor always conforms to the standard, unless the
1791 @option{-traditional} option is used.
1793 This macro is not defined if the @option{-traditional} option is used.
1795 On some hosts, the system compiler uses a different convention, where
1796 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1797 conformance to the C Standard. GNU CPP follows the host convention when
1798 processing system header files, but when processing user files
1799 @code{__STDC__} is always 1. This has been reported to cause problems;
1800 for instance, some versions of Solaris provide X Windows headers that
1801 expect @code{__STDC__} to be either undefined or 1. You may be able to
1802 work around this sort of problem by using an @option{-I} option to
1803 cancel treatment of those headers as system headers. @xref{Invocation}.
1805 @item __STDC_VERSION__
1806 This macro expands to the C Standard's version number, a long integer
1807 constant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and
1808 @var{mm} are the year and month of the Standard version. This signifies
1809 which version of the C Standard the compiler conforms to. Like
1810 @code{__STDC__}, this is not necessarily accurate for the entire
1811 implementation, unless GNU CPP is being used with GCC@.
1813 The value @code{199409L} signifies the 1989 C standard as amended in
1814 1994, which is the current default; the value @code{199901L} signifies
1815 the 1999 revision of the C standard. Support for the 1999 revision is
1818 This macro is not defined if the @option{-traditional} option is used, nor
1819 when compiling C++ or Objective-C@.
1821 @item __STDC_HOSTED__
1822 This macro is defined, with value 1, if the compiler's target is a
1823 @dfn{hosted environment}. A hosted environment has the complete
1824 facilities of the standard C library available.
1827 This macro is defined when the C++ compiler is in use. You can use
1828 @code{__cplusplus} to test whether a header is compiled by a C compiler
1829 or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in
1830 that it expands to a version number. A fully conforming implementation
1831 of the 1998 C++ standard will define this macro to @code{199711L}. The
1832 GNU C++ compiler is not yet fully conforming, so it uses @code{1}
1833 instead. We hope to complete our implementation in the near future.
1837 @node Common Predefined Macros
1838 @subsection Common Predefined Macros
1839 @cindex common predefined macros
1841 The common predefined macros are GNU C extensions. They are available
1842 with the same meanings regardless of the machine or operating system on
1843 which you are using GNU C@. Their names all start with double
1849 @itemx __GNUC_MINOR__
1850 @itemx __GNUC_PATCHLEVEL__
1851 These macros are defined by all GNU compilers that use the C
1852 preprocessor: C, C++, and Objective-C@. Their values are the major
1853 version, minor version, and patch level of the compiler, as integer
1854 constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3,
1855 @code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. They
1856 are defined only when the entire compiler is in use; if you invoke the
1857 preprocessor directly, they are not defined.
1859 @code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the
1860 widely-used development snapshots leading up to 3.0 (which identify
1861 themselves as GCC 2.96 or 2.97, depending on which snapshot you have).
1863 If all you need to know is whether or not your program is being compiled
1864 by GCC, you can simply test @code{__GNUC__}. If you need to write code
1865 which depends on a specific version, you must be more careful. Each
1866 time the minor version is increased, the patch level is reset to zero;
1867 each time the major version is increased (which happens rarely), the
1868 minor version and patch level are reset. If you wish to use the
1869 predefined macros directly in the conditional, you will need to write it
1873 /* @r{Test for GCC > 3.2.0} */
1874 #if __GNUC__ > 3 || \
1875 (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
1876 (__GNUC_MINOR__ == 2 && \
1877 __GNUC_PATCHLEVEL__ > 0))
1881 Another approach is to use the predefined macros to
1882 calculate a single number, then compare that against a threshold:
1885 #define GCC_VERSION (__GNUC__ * 10000 \
1886 + __GNUC_MINOR__ * 100 \
1887 + __GNUC_PATCHLEVEL__)
1889 /* @r{Test for GCC > 3.2.0} */
1890 #if GCC_VERSION > 30200
1894 Many people find this form easier to understand.
1897 The GNU C++ compiler defines this. Testing it is equivalent to
1898 testing @code{@w{(__GNUC__ && __cplusplus)}}.
1900 @item __STRICT_ANSI__
1901 GCC defines this macro if and only if the @option{-ansi} switch, or a
1902 @option{-std} switch specifying strict conformance to some version of ISO C,
1903 was specified when GCC was invoked. It is defined to @samp{1}.
1904 This macro exists primarily to direct GNU libc's header files to
1905 restrict their definitions to the minimal set found in the 1989 C
1909 This macro expands to the name of the main input file, in the form
1910 of a C string constant. This is the source file that was specified
1911 on the command line of the preprocessor or C compiler.
1913 @item __INCLUDE_LEVEL__
1914 This macro expands to a decimal integer constant that represents the
1915 depth of nesting in include files. The value of this macro is
1916 incremented on every @samp{#include} directive and decremented at the
1917 end of every included file. It starts out at 0, it's value within the
1918 base file specified on the command line.
1921 This macro expands to a string constant which describes the version of
1922 the compiler in use. You should not rely on its contents having any
1923 particular form, but it can be counted on to contain at least the
1927 @itemx __OPTIMIZE_SIZE__
1928 @itemx __NO_INLINE__
1929 These macros describe the compilation mode. @code{__OPTIMIZE__} is
1930 defined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is
1931 defined if the compiler is optimizing for size, not speed.
1932 @code{__NO_INLINE__} is defined if no functions will be inlined into
1933 their callers (when not optimizing, or when inlining has been
1934 specifically disabled by @option{-fno-inline}).
1936 These macros cause certain GNU header files to provide optimized
1937 definitions, using macros or inline functions, of system library
1938 functions. You should not use these macros in any way unless you make
1939 sure that programs will execute with the same effect whether or not they
1940 are defined. If they are defined, their value is 1.
1942 @item __CHAR_UNSIGNED__
1943 GCC defines this macro if and only if the data type @code{char} is
1944 unsigned on the target machine. It exists to cause the standard header
1945 file @file{limits.h} to work correctly. You should not use this macro
1946 yourself; instead, refer to the standard macros defined in @file{limits.h}.
1948 @item __REGISTER_PREFIX__
1949 This macro expands to a single token (not a string constant) which is
1950 the prefix applied to CPU register names in assembly language for this
1951 target. You can use it to write assembly that is usable in multiple
1952 environments. For example, in the @code{m68k-aout} environment it
1953 expands to nothing, but in the @code{m68k-coff} environment it expands
1954 to a single @samp{%}.
1956 @item __USER_LABEL_PREFIX__
1957 This macro expands to a single token which is the prefix applied to
1958 user labels (symbols visible to C code) in assembly. For example, in
1959 the @code{m68k-aout} environment it expands to an @samp{_}, but in the
1960 @code{m68k-coff} environment it expands to nothing.
1962 This macro will have the correct definition even if
1963 @option{-f(no-)underscores} is in use, but it will not be correct if
1964 target-specific options that adjust this prefix are used (e.g.@: the
1965 OSF/rose @option{-mno-underscores} option).
1968 @itemx __PTRDIFF_TYPE__
1969 @itemx __WCHAR_TYPE__
1970 @itemx __WINT_TYPE__
1971 These macros are defined to the correct underlying types for the
1972 @code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, and @code{wint_t}
1973 typedefs, respectively. They exist to make the standard header files
1974 @file{stddef.h} and @file{wchar.h} work correctly. You should not use
1975 these macros directly; instead, include the appropriate headers and use
1978 @item __USING_SJLJ_EXCEPTIONS__
1979 This macro is defined, with value 1, if the compiler uses the old
1980 mechanism based on @code{setjmp} and @code{longjmp} for exception
1984 @node System-specific Predefined Macros
1985 @subsection System-specific Predefined Macros
1987 @cindex system-specific predefined macros
1988 @cindex predefined macros, system-specific
1989 @cindex reserved namespace
1991 The C preprocessor normally predefines several macros that indicate what
1992 type of system and machine is in use. They are obviously different on
1993 each target supported by GCC@. This manual, being for all systems and
1994 machines, cannot tell you what their names are, but you can use
1995 @command{cpp -dM} to see them all. @xref{Invocation}. All system-specific
1996 predefined macros expand to the constant 1, so you can test them with
1997 either @samp{#ifdef} or @samp{#if}.
1999 The C standard requires that all system-specific macros be part of the
2000 @dfn{reserved namespace}. All names which begin with two underscores,
2001 or an underscore and a capital letter, are reserved for the compiler and
2002 library to use as they wish. However, historically system-specific
2003 macros have had names with no special prefix; for instance, it is common
2004 to find @code{unix} defined on Unix systems. For all such macros, GCC
2005 provides a parallel macro with two underscores added at the beginning
2006 and the end. If @code{unix} is defined, @code{__unix__} will be defined
2007 too. There will never be more than two underscores; the parallel of
2008 @code{_mips} is @code{__mips__}.
2010 When the @option{-ansi} option, or any @option{-std} option that
2011 requests strict conformance, is given to the compiler, all the
2012 system-specific predefined macros outside the reserved namespace are
2013 suppressed. The parallel macros, inside the reserved namespace, remain
2016 We are slowly phasing out all predefined macros which are outside the
2017 reserved namespace. You should never use them in new programs, and we
2018 encourage you to correct older code to use the parallel macros whenever
2019 you find it. We don't recommend you use the system-specific macros that
2020 are in the reserved namespace, either. It is better in the long run to
2021 check specifically for features you need, using a tool such as
2024 @node C++ Named Operators
2025 @subsection C++ Named Operators
2026 @cindex named operators
2027 @cindex C++ named operators
2030 In C++, there are eleven keywords which are simply alternate spellings
2031 of operators normally written with punctuation. These keywords are
2032 treated as such even in the preprocessor. They function as operators in
2033 @samp{#if}, and they cannot be defined as macros or poisoned. In C, you
2034 can request that those keywords take their C++ meaning by including
2035 @file{iso646.h}. That header defines each one as a normal object-like
2036 macro expanding to the appropriate punctuator.
2038 These are the named operators and their corresponding punctuators:
2040 @multitable {Named Operator} {Punctuator}
2041 @item Named Operator @tab Punctuator
2042 @item @code{and} @tab @code{&&}
2043 @item @code{and_eq} @tab @code{&=}
2044 @item @code{bitand} @tab @code{&}
2045 @item @code{bitor} @tab @code{|}
2046 @item @code{compl} @tab @code{~}
2047 @item @code{not} @tab @code{!}
2048 @item @code{not_eq} @tab @code{!=}
2049 @item @code{or} @tab @code{||}
2050 @item @code{or_eq} @tab @code{|=}
2051 @item @code{xor} @tab @code{^}
2052 @item @code{xor_eq} @tab @code{^=}
2055 @node Undefining and Redefining Macros
2056 @section Undefining and Redefining Macros
2057 @cindex undefining macros
2058 @cindex redefining macros
2061 If a macro ceases to be useful, it may be @dfn{undefined} with the
2062 @samp{#undef} directive. @samp{#undef} takes a single argument, the
2063 name of the macro to undefine. You use the bare macro name, even if the
2064 macro is function-like. It is an error if anything appears on the line
2065 after the macro name. @samp{#undef} has no effect if the name is not a
2070 x = FOO; @expansion{} x = 4;
2072 x = FOO; @expansion{} x = FOO;
2075 Once a macro has been undefined, that identifier may be @dfn{redefined}
2076 as a macro by a subsequent @samp{#define} directive. The new definition
2077 need not have any resemblance to the old definition.
2079 However, if an identifier which is currently a macro is redefined, then
2080 the new definition must be @dfn{effectively the same} as the old one.
2081 Two macro definitions are effectively the same if:
2083 @item Both are the same type of macro (object- or function-like).
2084 @item All the tokens of the replacement list are the same.
2085 @item If there are any parameters, they are the same.
2086 @item Whitespace appears in the same places in both. It need not be
2087 exactly the same amount of whitespace, though. Remember that comments
2088 count as whitespace.
2092 These definitions are effectively the same:
2094 #define FOUR (2 + 2)
2095 #define FOUR (2 + 2)
2096 #define FOUR (2 /* two */ + 2)
2101 #define FOUR (2 + 2)
2102 #define FOUR ( 2+2 )
2103 #define FOUR (2 * 2)
2104 #define FOUR(score,and,seven,years,ago) (2 + 2)
2107 If a macro is redefined with a definition that is not effectively the
2108 same as the old one, the preprocessor issues a warning and changes the
2109 macro to use the new definition. If the new definition is effectively
2110 the same, the redefinition is silently ignored. This allows, for
2111 instance, two different headers to define a common macro. The
2112 preprocessor will only complain if the definitions do not match.
2114 @node Macro Pitfalls
2115 @section Macro Pitfalls
2116 @cindex problems with macros
2117 @cindex pitfalls of macros
2119 In this section we describe some special rules that apply to macros and
2120 macro expansion, and point out certain cases in which the rules have
2121 counter-intuitive consequences that you must watch out for.
2125 * Operator Precedence Problems::
2126 * Swallowing the Semicolon::
2127 * Duplication of Side Effects::
2128 * Self-Referential Macros::
2129 * Argument Prescan::
2130 * Newlines in Arguments::
2134 @subsection Misnesting
2136 When a macro is called with arguments, the arguments are substituted
2137 into the macro body and the result is checked, together with the rest of
2138 the input file, for more macro calls. It is possible to piece together
2139 a macro call coming partially from the macro body and partially from the
2140 arguments. For example,
2143 #define twice(x) (2*(x))
2144 #define call_with_1(x) x(1)
2146 @expansion{} twice(1)
2147 @expansion{} (2*(1))
2150 Macro definitions do not have to have balanced parentheses. By writing
2151 an unbalanced open parenthesis in a macro body, it is possible to create
2152 a macro call that begins inside the macro body but ends outside of it.
2156 #define strange(file) fprintf (file, "%s %d",
2158 strange(stderr) p, 35)
2159 @expansion{} fprintf (stderr, "%s %d", p, 35)
2162 The ability to piece together a macro call can be useful, but the use of
2163 unbalanced open parentheses in a macro body is just confusing, and
2166 @node Operator Precedence Problems
2167 @subsection Operator Precedence Problems
2168 @cindex parentheses in macro bodies
2170 You may have noticed that in most of the macro definition examples shown
2171 above, each occurrence of a macro argument name had parentheses around
2172 it. In addition, another pair of parentheses usually surround the
2173 entire macro definition. Here is why it is best to write macros that
2176 Suppose you define a macro as follows,
2179 #define ceil_div(x, y) (x + y - 1) / y
2183 whose purpose is to divide, rounding up. (One use for this operation is
2184 to compute how many @code{int} objects are needed to hold a certain
2185 number of @code{char} objects.) Then suppose it is used as follows:
2188 a = ceil_div (b & c, sizeof (int));
2189 @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int);
2193 This does not do what is intended. The operator-precedence rules of
2194 C make it equivalent to this:
2197 a = (b & (c + sizeof (int) - 1)) / sizeof (int);
2201 What we want is this:
2204 a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
2208 Defining the macro as
2211 #define ceil_div(x, y) ((x) + (y) - 1) / (y)
2215 provides the desired result.
2217 Unintended grouping can result in another way. Consider @code{sizeof
2218 ceil_div(1, 2)}. That has the appearance of a C expression that would
2219 compute the size of the type of @code{ceil_div (1, 2)}, but in fact it
2220 means something very different. Here is what it expands to:
2223 sizeof ((1) + (2) - 1) / (2)
2227 This would take the size of an integer and divide it by two. The
2228 precedence rules have put the division outside the @code{sizeof} when it
2229 was intended to be inside.
2231 Parentheses around the entire macro definition prevent such problems.
2232 Here, then, is the recommended way to define @code{ceil_div}:
2235 #define ceil_div(x, y) (((x) + (y) - 1) / (y))
2238 @node Swallowing the Semicolon
2239 @subsection Swallowing the Semicolon
2240 @cindex semicolons (after macro calls)
2242 Often it is desirable to define a macro that expands into a compound
2243 statement. Consider, for example, the following macro, that advances a
2244 pointer (the argument @code{p} says where to find it) across whitespace
2248 #define SKIP_SPACES(p, limit) \
2249 @{ char *lim = (limit); \
2250 while (p < lim) @{ \
2251 if (*p++ != ' ') @{ \
2256 Here backslash-newline is used to split the macro definition, which must
2257 be a single logical line, so that it resembles the way such code would
2258 be laid out if not part of a macro definition.
2260 A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly
2261 speaking, the call expands to a compound statement, which is a complete
2262 statement with no need for a semicolon to end it. However, since it
2263 looks like a function call, it minimizes confusion if you can use it
2264 like a function call, writing a semicolon afterward, as in
2265 @code{SKIP_SPACES (p, lim);}
2267 This can cause trouble before @code{else} statements, because the
2268 semicolon is actually a null statement. Suppose you write
2272 SKIP_SPACES (p, lim);
2277 The presence of two statements---the compound statement and a null
2278 statement---in between the @code{if} condition and the @code{else}
2279 makes invalid C code.
2281 The definition of the macro @code{SKIP_SPACES} can be altered to solve
2282 this problem, using a @code{do @dots{} while} statement. Here is how:
2285 #define SKIP_SPACES(p, limit) \
2286 do @{ char *lim = (limit); \
2287 while (p < lim) @{ \
2288 if (*p++ != ' ') @{ \
2289 p--; break; @}@}@} \
2293 Now @code{SKIP_SPACES (p, lim);} expands into
2296 do @{@dots{}@} while (0);
2300 which is one statement. The loop executes exactly once; most compilers
2301 generate no extra code for it.
2303 @node Duplication of Side Effects
2304 @subsection Duplication of Side Effects
2306 @cindex side effects (in macro arguments)
2307 @cindex unsafe macros
2308 Many C programs define a macro @code{min}, for ``minimum'', like this:
2311 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
2314 When you use this macro with an argument containing a side effect,
2318 next = min (x + y, foo (z));
2322 it expands as follows:
2325 next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
2329 where @code{x + y} has been substituted for @code{X} and @code{foo (z)}
2332 The function @code{foo} is used only once in the statement as it appears
2333 in the program, but the expression @code{foo (z)} has been substituted
2334 twice into the macro expansion. As a result, @code{foo} might be called
2335 two times when the statement is executed. If it has side effects or if
2336 it takes a long time to compute, the results might not be what you
2337 intended. We say that @code{min} is an @dfn{unsafe} macro.
2339 The best solution to this problem is to define @code{min} in a way that
2340 computes the value of @code{foo (z)} only once. The C language offers
2341 no standard way to do this, but it can be done with GNU extensions as
2346 (@{ typeof (X) x_ = (X); \
2347 typeof (Y) y_ = (Y); \
2348 (x_ < y_) ? x_ : y_; @})
2351 The @samp{(@{ @dots{} @})} notation produces a compound statement that
2352 acts as an expression. Its value is the value of its last statement.
2353 This permits us to define local variables and assign each argument to
2354 one. The local variables have underscores after their names to reduce
2355 the risk of conflict with an identifier of wider scope (it is impossible
2356 to avoid this entirely). Now each argument is evaluated exactly once.
2358 If you do not wish to use GNU C extensions, the only solution is to be
2359 careful when @emph{using} the macro @code{min}. For example, you can
2360 calculate the value of @code{foo (z)}, save it in a variable, and use
2361 that variable in @code{min}:
2365 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
2369 next = min (x + y, tem);
2375 (where we assume that @code{foo} returns type @code{int}).
2377 @node Self-Referential Macros
2378 @subsection Self-Referential Macros
2379 @cindex self-reference
2381 A @dfn{self-referential} macro is one whose name appears in its
2382 definition. Recall that all macro definitions are rescanned for more
2383 macros to replace. If the self-reference were considered a use of the
2384 macro, it would produce an infinitely large expansion. To prevent this,
2385 the self-reference is not considered a macro call. It is passed into
2386 the preprocessor output unchanged. Let's consider an example:
2389 #define foo (4 + foo)
2393 where @code{foo} is also a variable in your program.
2395 Following the ordinary rules, each reference to @code{foo} will expand
2396 into @code{(4 + foo)}; then this will be rescanned and will expand into
2397 @code{(4 + (4 + foo))}; and so on until the computer runs out of memory.
2399 The self-reference rule cuts this process short after one step, at
2400 @code{(4 + foo)}. Therefore, this macro definition has the possibly
2401 useful effect of causing the program to add 4 to the value of @code{foo}
2402 wherever @code{foo} is referred to.
2404 In most cases, it is a bad idea to take advantage of this feature. A
2405 person reading the program who sees that @code{foo} is a variable will
2406 not expect that it is a macro as well. The reader will come across the
2407 identifier @code{foo} in the program and think its value should be that
2408 of the variable @code{foo}, whereas in fact the value is four greater.
2410 One common, useful use of self-reference is to create a macro which
2411 expands to itself. If you write
2418 then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is
2419 left alone by the preprocessor whenever it's used in running text. You
2420 can tell that it's a macro with @samp{#ifdef}. You might do this if you
2421 want to define numeric constants with an @code{enum}, but have
2422 @samp{#ifdef} be true for each constant.
2424 If a macro @code{x} expands to use a macro @code{y}, and the expansion of
2425 @code{y} refers to the macro @code{x}, that is an @dfn{indirect
2426 self-reference} of @code{x}. @code{x} is not expanded in this case
2427 either. Thus, if we have
2435 then @code{x} and @code{y} expand as follows:
2439 x @expansion{} (4 + y)
2440 @expansion{} (4 + (2 * x))
2442 y @expansion{} (2 * x)
2443 @expansion{} (2 * (4 + y))
2448 Each macro is expanded when it appears in the definition of the other
2449 macro, but not when it indirectly appears in its own definition.
2451 @node Argument Prescan
2452 @subsection Argument Prescan
2453 @cindex expansion of arguments
2454 @cindex macro argument expansion
2455 @cindex prescan of macro arguments
2457 Macro arguments are completely macro-expanded before they are
2458 substituted into a macro body, unless they are stringified or pasted
2459 with other tokens. After substitution, the entire macro body, including
2460 the substituted arguments, is scanned again for macros to be expanded.
2461 The result is that the arguments are scanned @emph{twice} to expand
2462 macro calls in them.
2464 Most of the time, this has no effect. If the argument contained any
2465 macro calls, they are expanded during the first scan. The result
2466 therefore contains no macro calls, so the second scan does not change
2467 it. If the argument were substituted as given, with no prescan, the
2468 single remaining scan would find the same macro calls and produce the
2471 You might expect the double scan to change the results when a
2472 self-referential macro is used in an argument of another macro
2473 (@pxref{Self-Referential Macros}): the self-referential macro would be
2474 expanded once in the first scan, and a second time in the second scan.
2475 However, this is not what happens. The self-references that do not
2476 expand in the first scan are marked so that they will not expand in the
2479 You might wonder, ``Why mention the prescan, if it makes no difference?
2480 And why not skip it and make the preprocessor faster?'' The answer is
2481 that the prescan does make a difference in three special cases:
2485 Nested calls to a macro.
2487 We say that @dfn{nested} calls to a macro occur when a macro's argument
2488 contains a call to that very macro. For example, if @code{f} is a macro
2489 that expects one argument, @code{f (f (1))} is a nested pair of calls to
2490 @code{f}. The desired expansion is made by expanding @code{f (1)} and
2491 substituting that into the definition of @code{f}. The prescan causes
2492 the expected result to happen. Without the prescan, @code{f (1)} itself
2493 would be substituted as an argument, and the inner use of @code{f} would
2494 appear during the main scan as an indirect self-reference and would not
2498 Macros that call other macros that stringify or concatenate.
2500 If an argument is stringified or concatenated, the prescan does not
2501 occur. If you @emph{want} to expand a macro, then stringify or
2502 concatenate its expansion, you can do that by causing one macro to call
2503 another macro that does the stringification or concatenation. For
2504 instance, if you have
2507 #define AFTERX(x) X_ ## x
2508 #define XAFTERX(x) AFTERX(x)
2509 #define TABLESIZE 1024
2510 #define BUFSIZE TABLESIZE
2513 then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and
2514 @code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to
2515 @code{X_TABLESIZE}. Prescan always does a complete expansion.)
2518 Macros used in arguments, whose expansions contain unshielded commas.
2520 This can cause a macro expanded on the second scan to be called with the
2521 wrong number of arguments. Here is an example:
2525 #define bar(x) lose(x)
2526 #define lose(x) (1 + (x))
2529 We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which
2530 would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)}
2531 expands into @code{lose(a,b)}, and you get an error because @code{lose}
2532 requires a single argument. In this case, the problem is easily solved
2533 by the same parentheses that ought to be used to prevent misnesting of
2534 arithmetic operations:
2539 #define bar(x) lose((x))
2542 The extra pair of parentheses prevents the comma in @code{foo}'s
2543 definition from being interpreted as an argument separator.
2547 @node Newlines in Arguments
2548 @subsection Newlines in Arguments
2549 @cindex newlines in macro arguments
2551 The invocation of a function-like macro can extend over many logical
2552 lines. However, in the present implementation, the entire expansion
2553 comes out on one line. Thus line numbers emitted by the compiler or
2554 debugger refer to the line the invocation started on, which might be
2555 different to the line containing the argument causing the problem.
2557 Here is an example illustrating this:
2560 #define ignore_second_arg(a,b,c) a; c
2562 ignore_second_arg (foo (),
2568 The syntax error triggered by the tokens @code{syntax error} results in
2569 an error message citing line three---the line of ignore_second_arg---
2570 even though the problematic code comes from line five.
2572 We consider this a bug, and intend to fix it in the near future.
2575 @chapter Conditionals
2576 @cindex conditionals
2578 A @dfn{conditional} is a directive that instructs the preprocessor to
2579 select whether or not to include a chunk of code in the final token
2580 stream passed to the compiler. Preprocessor conditionals can test
2581 arithmetic expressions, or whether a name is defined as a macro, or both
2582 simultaneously using the special @code{defined} operator.
2584 A conditional in the C preprocessor resembles in some ways an @code{if}
2585 statement in C, but it is important to understand the difference between
2586 them. The condition in an @code{if} statement is tested during the
2587 execution of your program. Its purpose is to allow your program to
2588 behave differently from run to run, depending on the data it is
2589 operating on. The condition in a preprocessing conditional directive is
2590 tested when your program is compiled. Its purpose is to allow different
2591 code to be included in the program depending on the situation at the
2592 time of compilation.
2594 However, the distinction is becoming less clear. Modern compilers often
2595 do test @code{if} statements when a program is compiled, if their
2596 conditions are known not to vary at run time, and eliminate code which
2597 can never be executed. If you can count on your compiler to do this,
2598 you may find that your program is more readable if you use @code{if}
2599 statements with constant conditions (perhaps determined by macros). Of
2600 course, you can only use this to exclude code, not type definitions or
2601 other preprocessing directives, and you can only do it if the code
2602 remains syntactically valid when it is not to be used.
2604 GCC version 3 eliminates this kind of never-executed code even when
2605 not optimizing. Older versions did it only when optimizing.
2608 * Conditional Uses::
2609 * Conditional Syntax::
2613 @node Conditional Uses
2614 @section Conditional Uses
2616 There are three general reasons to use a conditional.
2620 A program may need to use different code depending on the machine or
2621 operating system it is to run on. In some cases the code for one
2622 operating system may be erroneous on another operating system; for
2623 example, it might refer to data types or constants that do not exist on
2624 the other system. When this happens, it is not enough to avoid
2625 executing the invalid code. Its mere presence will cause the compiler
2626 to reject the program. With a preprocessing conditional, the offending
2627 code can be effectively excised from the program when it is not valid.
2630 You may want to be able to compile the same source file into two
2631 different programs. One version might make frequent time-consuming
2632 consistency checks on its intermediate data, or print the values of
2633 those data for debugging, and the other not.
2636 A conditional whose condition is always false is one way to exclude code
2637 from the program but keep it as a sort of comment for future reference.
2640 Simple programs that do not need system-specific logic or complex
2641 debugging hooks generally will not need to use preprocessing
2644 @node Conditional Syntax
2645 @section Conditional Syntax
2648 A conditional in the C preprocessor begins with a @dfn{conditional
2649 directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
2664 The simplest sort of conditional is
2670 @var{controlled text}
2672 #endif /* @var{MACRO} */
2676 @cindex conditional group
2677 This block is called a @dfn{conditional group}. @var{controlled text}
2678 will be included in the output of the preprocessor if and only if
2679 @var{MACRO} is defined. We say that the conditional @dfn{succeeds} if
2680 @var{MACRO} is defined, @dfn{fails} if it is not.
2682 The @var{controlled text} inside of a conditional can include
2683 preprocessing directives. They are executed only if the conditional
2684 succeeds. You can nest conditional groups inside other conditional
2685 groups, but they must be completely nested. In other words,
2686 @samp{#endif} always matches the nearest @samp{#ifdef} (or
2687 @samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional
2688 group in one file and end it in another.
2690 Even if a conditional fails, the @var{controlled text} inside it is
2691 still run through initial transformations and tokenization. Therefore,
2692 it must all be lexically valid C@. Normally the only way this matters is
2693 that all comments and string literals inside a failing conditional group
2694 must still be properly ended.
2696 The comment following the @samp{#endif} is not required, but it is a
2697 good practice if there is a lot of @var{controlled text}, because it
2698 helps people match the @samp{#endif} to the corresponding @samp{#ifdef}.
2699 Older programs sometimes put @var{MACRO} directly after the
2700 @samp{#endif} without enclosing it in a comment. This is invalid code
2701 according to the C standard. GNU CPP accepts it with a warning. It
2702 never affects which @samp{#ifndef} the @samp{#endif} matches.
2705 Sometimes you wish to use some code if a macro is @emph{not} defined.
2706 You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}.
2707 One common use of @samp{#ifndef} is to include code only the first
2708 time a header file is included. @xref{Once-Only Headers}.
2710 Macro definitions can vary between compilations for several reasons.
2711 Here are some samples.
2715 Some macros are predefined on each kind of machine
2716 (@pxref{System-specific Predefined Macros}). This allows you to provide
2717 code specially tuned for a particular machine.
2720 System header files define more macros, associated with the features
2721 they implement. You can test these macros with conditionals to avoid
2722 using a system feature on a machine where it is not implemented.
2725 Macros can be defined or undefined with the @option{-D} and @option{-U}
2726 command line options when you compile the program. You can arrange to
2727 compile the same source file into two different programs by choosing a
2728 macro name to specify which program you want, writing conditionals to
2729 test whether or how this macro is defined, and then controlling the
2730 state of the macro with command line options, perhaps set in the
2731 Makefile. @xref{Invocation}.
2734 Your program might have a special header file (often called
2735 @file{config.h}) that is adjusted when the program is compiled. It can
2736 define or not define macros depending on the features of the system and
2737 the desired capabilities of the program. The adjustment can be
2738 automated by a tool such as @command{autoconf}, or done by hand.
2744 The @samp{#if} directive allows you to test the value of an arithmetic
2745 expression, rather than the mere existence of one macro. Its syntax is
2749 #if @var{expression}
2751 @var{controlled text}
2753 #endif /* @var{expression} */
2757 @var{expression} is a C expression of integer type, subject to stringent
2758 restrictions. It may contain
2765 Character constants, which are interpreted as they would be in normal
2769 Arithmetic operators for addition, subtraction, multiplication,
2770 division, bitwise operations, shifts, comparisons, and logical
2771 operations (@code{&&} and @code{||}). The latter two obey the usual
2772 short-circuiting rules of standard C@.
2775 Macros. All macros in the expression are expanded before actual
2776 computation of the expression's value begins.
2779 Uses of the @code{defined} operator, which lets you check whether macros
2780 are defined in the middle of an @samp{#if}.
2783 Identifiers that are not macros, which are all considered to be the
2784 number zero. This allows you to write @code{@w{#if MACRO}} instead of
2785 @code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will
2786 always have a nonzero value. Function-like macros used without their
2787 function call parentheses are also treated as zero.
2789 In some contexts this shortcut is undesirable. The @option{-Wundef}
2790 option causes GCC to warn whenever it encounters an identifier which is
2791 not a macro in an @samp{#if}.
2794 The preprocessor does not know anything about types in the language.
2795 Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and
2796 neither are @code{enum} constants. They will be taken as identifiers
2797 which are not macros, and replaced by zero. In the case of
2798 @code{sizeof}, this is likely to cause the expression to be invalid.
2800 The preprocessor calculates the value of @var{expression}. It carries
2801 out all calculations in the widest integer type known to the compiler;
2802 on most machines supported by GCC this is 64 bits. This is not the same
2803 rule as the compiler uses to calculate the value of a constant
2804 expression, and may give different results in some cases. If the value
2805 comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled
2806 text} is included; otherwise it is skipped.
2808 If @var{expression} is not correctly formed, GCC issues an error and
2809 treats the conditional as having failed.
2814 @cindex @code{defined}
2815 The special operator @code{defined} is used in @samp{#if} and
2816 @samp{#elif} expressions to test whether a certain name is defined as a
2817 macro. @code{defined @var{name}} and @code{defined (@var{name})} are
2818 both expressions whose value is 1 if @var{name} is defined as a macro at
2819 the current point in the program, and 0 otherwise. Thus, @code{@w{#if
2820 defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}.
2822 @code{defined} is useful when you wish to test more than one macro for
2823 existence at once. For example,
2826 #if defined (__vax__) || defined (__ns16000__)
2830 would succeed if either of the names @code{__vax__} or
2831 @code{__ns16000__} is defined as a macro.
2833 Conditionals written like this:
2836 #if defined BUFSIZE && BUFSIZE >= 1024
2840 can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}},
2841 since if @code{BUFSIZE} is not defined, it will be interpreted as having
2844 If the @code{defined} operator appears as a result of a macro expansion,
2845 the C standard says the behavior is undefined. GNU cpp treats it as a
2846 genuine @code{defined} operator and evaluates it normally. It will warn
2847 wherever your code uses this feature if you use the command-line option
2848 @option{-pedantic}, since other compilers may handle it differently.
2854 The @samp{#else} directive can be added to a conditional to provide
2855 alternative text to be used if the condition fails. This is what it
2860 #if @var{expression}
2862 #else /* Not @var{expression} */
2864 #endif /* Not @var{expression} */
2869 If @var{expression} is nonzero, the @var{text-if-true} is included and
2870 the @var{text-if-false} is skipped. If @var{expression} is zero, the
2873 You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too.
2879 One common case of nested conditionals is used to check for more than two
2880 possible alternatives. For example, you might have
2894 Another conditional directive, @samp{#elif}, allows this to be
2895 abbreviated as follows:
2902 #else /* X != 2 and X != 1*/
2904 #endif /* X != 2 and X != 1*/
2907 @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
2908 middle of a conditional group and subdivides it; it does not require a
2909 matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif}
2910 directive includes an expression to be tested. The text following the
2911 @samp{#elif} is processed only if the original @samp{#if}-condition
2912 failed and the @samp{#elif} condition succeeds.
2914 More than one @samp{#elif} can go in the same conditional group. Then
2915 the text after each @samp{#elif} is processed only if the @samp{#elif}
2916 condition succeeds after the original @samp{#if} and all previous
2917 @samp{#elif} directives within it have failed.
2919 @samp{#else} is allowed after any number of @samp{#elif} directives, but
2920 @samp{#elif} may not follow @samp{#else}.
2923 @section Deleted Code
2924 @cindex commenting out code
2926 If you replace or delete a part of the program but want to keep the old
2927 code around for future reference, you often cannot simply comment it
2928 out. Block comments do not nest, so the first comment inside the old
2929 code will end the commenting-out. The probable result is a flood of
2932 One way to avoid this problem is to use an always-false conditional
2933 instead. For instance, put @code{#if 0} before the deleted code and
2934 @code{#endif} after it. This works even if the code being turned
2935 off contains conditionals, but they must be entire conditionals
2936 (balanced @samp{#if} and @samp{#endif}).
2938 Some people use @code{#ifdef notdef} instead. This is risky, because
2939 @code{notdef} might be accidentally defined as a macro, and then the
2940 conditional would succeed. @code{#if 0} can be counted on to fail.
2942 Do not use @code{#if 0} for comments which are not C code. Use a real
2943 comment, instead. The interior of @code{#if 0} must consist of complete
2944 tokens; in particular, single-quote characters must balance. Comments
2945 often contain unbalanced single-quote characters (known in English as
2946 apostrophes). These confuse @code{#if 0}. They don't confuse
2950 @chapter Diagnostics
2952 @cindex reporting errors
2953 @cindex reporting warnings
2956 The directive @samp{#error} causes the preprocessor to report a fatal
2957 error. The tokens forming the rest of the line following @samp{#error}
2958 are used as the error message.
2960 You would use @samp{#error} inside of a conditional that detects a
2961 combination of parameters which you know the program does not properly
2962 support. For example, if you know that the program will not run
2963 properly on a VAX, you might write
2968 #error "Won't work on VAXen. See comments at get_last_object."
2973 If you have several configuration parameters that must be set up by
2974 the installation in a consistent way, you can use conditionals to detect
2975 an inconsistency and report it with @samp{#error}. For example,
2978 #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
2979 #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
2984 The directive @samp{#warning} is like @samp{#error}, but causes the
2985 preprocessor to issue a warning and continue preprocessing. The tokens
2986 following @samp{#warning} are used as the warning message.
2988 You might use @samp{#warning} in obsolete header files, with a message
2989 directing the user to the header file which should be used instead.
2991 Neither @samp{#error} nor @samp{#warning} macro-expands its argument.
2992 Internal whitespace sequences are each replaced with a single space.
2993 The line must consist of complete tokens. It is wisest to make the
2994 argument of these directives be a single string constant; this avoids
2995 problems with apostrophes and the like.
2998 @chapter Line Control
2999 @cindex line control
3001 The C preprocessor informs the C compiler of the location in your source
3002 code where each token came from. Presently, this is just the file name
3003 and line number. All the tokens resulting from macro expansion are
3004 reported as having appeared on the line of the source file where the
3005 outermost macro was used. We intend to be more accurate in the future.
3007 If you write a program which generates source code, such as the
3008 @command{bison} parser generator, you may want to adjust the preprocessor's
3009 notion of the current file name and line number by hand. Parts of the
3010 output from @command{bison} are generated from scratch, other parts come
3011 from a standard parser file. The rest are copied verbatim from
3012 @command{bison}'s input. You would like compiler error messages and
3013 symbolic debuggers to be able to refer to @code{bison}'s input file.
3016 @command{bison} or any such program can arrange this by writing
3017 @samp{#line} directives into the output file. @samp{#line} is a
3018 directive that specifies the original line number and source file name
3019 for subsequent input in the current preprocessor input file.
3020 @samp{#line} has three variants:
3023 @item #line @var{linenum}
3024 @var{linenum} is a non-negative decimal integer constant. It specifies
3025 the line number which should be reported for the following line of
3026 input. Subsequent lines are counted from @var{linenum}.
3028 @item #line @var{linenum} @var{filename}
3029 @var{linenum} is the same as for the first form, and has the same
3030 effect. In addition, @var{filename} is a string constant. The
3031 following line and all subsequent lines are reported to come from the
3032 file it specifies, until something else happens to change that.
3034 @item #line @var{anything else}
3035 @var{anything else} is checked for macro calls, which are expanded.
3036 The result should match one of the above two forms.
3039 @samp{#line} directives alter the results of the @code{__FILE__} and
3040 @code{__LINE__} predefined macros from that point on. @xref{Standard
3041 Predefined Macros}. They do not have any effect on @samp{#include}'s
3042 idea of the directory containing the current file.
3047 The @samp{#pragma} directive is the method specified by the C standard
3048 for providing additional information to the compiler, beyond what is
3049 conveyed in the language itself. Three forms of this directive
3050 (commonly known as @dfn{pragmas}) are specified by the 1999 C standard.
3051 A C compiler is free to attach any meaning it likes to other pragmas.
3053 GCC has historically preferred to use extensions to the syntax of the
3054 language, such as @code{__attribute__}, for this purpose. However, GCC
3055 does define a few pragmas of its own. These mostly have effects on the
3056 entire translation unit or source file.
3058 In GCC version 3, all GNU-defined, supported pragmas have been given a
3059 @code{GCC} prefix. This is in line with the @code{STDC} prefix on all
3060 pragmas defined by C99. For backward compatibility, pragmas which were
3061 recognized by previous versions are still recognized without the
3062 @code{GCC} prefix, but that usage is deprecated. Some older pragmas are
3063 deprecated in their entirety. They are not recognized with the
3064 @code{GCC} prefix. @xref{Obsolete Features}.
3066 @cindex @code{_Pragma}
3067 C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a
3068 major problem with @samp{#pragma}: being a directive, it cannot be
3069 produced as the result of macro expansion. @code{@w{_Pragma}} is an
3070 operator, much like @code{sizeof} or @code{defined}, and can be embedded
3073 Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where
3074 @var{string-literal} can be either a normal or wide-character string
3075 literal. It is destringized, by replacing all @samp{\\} with a single
3076 @samp{\} and all @samp{\"} with a @samp{"}. The result is then
3077 processed as if it had appeared as the right hand side of a
3078 @samp{#pragma} directive. For example,
3081 _Pragma ("GCC dependency \"parse.y\"")
3085 has the same effect as @code{#pragma GCC dependency "parse.y"}. The
3086 same effect could be achieved using macros, for example
3089 #define DO_PRAGMA(x) _Pragma (#x)
3090 DO_PRAGMA (GCC dependency "parse.y")
3093 The standard is unclear on where a @code{_Pragma} operator can appear.
3094 The preprocessor does not accept it within a preprocessing conditional
3095 directive like @samp{#if}. To be safe, you are probably best keeping it
3096 out of directives other than @samp{#define}, and putting it on a line of
3099 This manual documents the pragmas which are meaningful to the
3100 preprocessor itself. Other pragmas are meaningful to the C or C++
3101 compilers. They are documented in the GCC manual.
3104 @item #pragma GCC dependency
3105 @code{#pragma GCC dependency} allows you to check the relative dates of
3106 the current file and another file. If the other file is more recent than
3107 the current file, a warning is issued. This is useful if the current
3108 file is derived from the other file, and should be regenerated. The
3109 other file is searched for using the normal include search path.
3110 Optional trailing text can be used to give more information in the
3114 #pragma GCC dependency "parse.y"
3115 #pragma GCC dependency "/usr/include/time.h" rerun fixincludes
3118 @item #pragma GCC poison
3119 Sometimes, there is an identifier that you want to remove completely
3120 from your program, and make sure that it never creeps back in. To
3121 enforce this, you can @dfn{poison} the identifier with this pragma.
3122 @code{#pragma GCC poison} is followed by a list of identifiers to
3123 poison. If any of those identifiers appears anywhere in the source
3124 after the directive, it is a hard error. For example,
3127 #pragma GCC poison printf sprintf fprintf
3128 sprintf(some_string, "hello");
3132 will produce an error.
3134 If a poisoned identifier appears as part of the expansion of a macro
3135 which was defined before the identifier was poisoned, it will @emph{not}
3136 cause an error. This lets you poison an identifier without worrying
3137 about system headers defining macros that use it.
3142 #define strrchr rindex
3143 #pragma GCC poison rindex
3144 strrchr(some_string, 'h');
3148 will not produce an error.
3150 @item #pragma GCC system_header
3151 This pragma takes no arguments. It causes the rest of the code in the
3152 current file to be treated as if it came from a system header.
3153 @xref{System Headers}.
3157 @node Other Directives
3158 @chapter Other Directives
3161 The @samp{#ident} directive takes one argument, a string constant. On
3162 some systems, that string constant is copied into a special segment of
3163 the object file. On other systems, the directive is ignored.
3165 This directive is not part of the C standard, but it is not an official
3166 GNU extension either. We believe it came from System V@.
3169 The @samp{#sccs} directive is recognized on some systems, because it
3170 appears in their header files. It is a very old, obscure, extension
3171 which we did not invent, and we have been unable to find any
3172 documentation of what it should do, so GCC simply ignores it.
3174 @cindex null directive
3175 The @dfn{null directive} consists of a @samp{#} followed by a newline,
3176 with only whitespace (including comments) in between. A null directive
3177 is understood as a preprocessing directive but has no effect on the
3178 preprocessor output. The primary significance of the existence of the
3179 null directive is that an input line consisting of just a @samp{#} will
3180 produce no output, rather than a line of output containing just a
3181 @samp{#}. Supposedly some old C programs contain such lines.
3183 @node Preprocessor Output
3184 @chapter Preprocessor Output
3186 When the C preprocessor is used with the C, C++, or Objective-C
3187 compilers, it is integrated into the compiler and communicates a stream
3188 of binary tokens directly to the compiler's parser. However, it can
3189 also be used in the more conventional standalone mode, where it produces
3191 @c FIXME: Document the library interface.
3193 @cindex output format
3194 The output from the C preprocessor looks much like the input, except
3195 that all preprocessing directive lines have been replaced with blank
3196 lines and all comments with spaces. Long runs of blank lines are
3199 The ISO standard specifies that it is implementation defined whether a
3200 preprocessor preserves whitespace between tokens, or replaces it with
3201 e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed
3202 to become a single space, with the exception that the first token on a
3203 non-directive line is preceded with sufficient spaces that it appears in
3204 the same column in the preprocessed output that it appeared in the
3205 original source file. This is so the output is easy to read.
3206 @xref{Differences from previous versions}. CPP does not insert any
3207 whitespace where there was none in the original source, except where
3208 necessary to prevent an accidental token paste.
3211 Source file name and line number information is conveyed by lines
3215 # @var{linenum} @var{filename} @var{flags}
3219 These are called @dfn{linemarkers}. They are inserted as needed into
3220 the output (but never within a string or character constant). They mean
3221 that the following line originated in file @var{filename} at line
3224 After the file name comes zero or more flags, which are @samp{1},
3225 @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces
3226 separate them. Here is what the flags mean:
3230 This indicates the start of a new file.
3232 This indicates returning to a file (after having included another file).
3234 This indicates that the following text comes from a system header file,
3235 so certain warnings should be suppressed.
3237 This indicates that the following text should be treated as being
3238 wrapped in an implicit @code{extern "C"} block.
3239 @c maybe cross reference NO_IMPLICIT_EXTERN_C
3242 As an extension, the preprocessor accepts linemarkers in non-assembler
3243 input files. They are treated like the corresponding @samp{#line}
3244 directive, (@pxref{Line Control}), except that trailing flags are
3245 permitted, and are interpreted with the meanings described above. If
3246 multiple flags are given, they must be in ascending order.
3248 Some directives may be duplicated in the output of the preprocessor.
3249 These are @samp{#ident} (always), @samp{#pragma} (only if the
3250 preprocessor does not handle the pragma itself), and @samp{#define} and
3251 @samp{#undef} (with certain debugging options). If this happens, the
3252 @samp{#} of the directive will always be in the first column, and there
3253 will be no space between the @samp{#} and the directive name. If macro
3254 expansion happens to generate tokens which might be mistaken for a
3255 duplicated directive, a space will be inserted between the @samp{#} and
3258 @node Traditional Mode
3259 @chapter Traditional Mode
3261 Traditional (pre-standard) C preprocessing is rather different from
3262 the preprocessing specified by the standard. When GCC is given the
3263 @option{-traditional} option, it attempts to emulate a traditional
3264 preprocessor. We do not guarantee that GCC's behavior under
3265 @option{-traditional} matches any pre-standard preprocessor exactly.
3267 Traditional mode exists only for backward compatibility. We have no
3268 plans to augment it in any way nor will we change it except to fix
3269 catastrophic bugs. You should be aware that modern C libraries often
3270 have header files which are incompatible with traditional mode.
3272 This is a list of the differences. It may not be complete, and may not
3273 correspond exactly to the behavior of either GCC or a true traditional
3278 Traditional macro expansion pays no attention to single-quote or
3279 double-quote characters; macro argument symbols are replaced by the
3280 argument values even when they appear within apparent string or
3281 character constants.
3284 Traditionally, it is permissible for a macro expansion to end in the
3285 middle of a string or character constant. The constant continues into
3286 the text surrounding the macro call.
3289 However, the end of the line terminates a string or character constant,
3290 with no error. (This is a kluge. Traditional mode is commonly used to
3291 preprocess things which are not C, and have a different comment syntax.
3292 Single apostrophes often appear in comments. This kluge prevents the
3293 traditional preprocessor from issuing errors on such comments.)
3296 Preprocessing directives are recognized in traditional C only when their
3297 leading @samp{#} appears in the first column. There can be no
3298 whitespace between the beginning of the line and the @samp{#}.
3301 In traditional C, a comment is equivalent to no text at all. (In ISO
3302 C, a comment counts as whitespace.) It can be used sort of the same way
3303 that @samp{##} is used in ISO C, to paste macro arguments together.
3306 Traditional C does not have the concept of a preprocessing number.
3309 A macro is not suppressed within its own definition, in traditional C@.
3310 Thus, any macro that is used recursively inevitably causes an error.
3313 The @samp{#} and @samp{##} operators are not available in traditional
3317 In traditional C, the text at the end of a macro expansion can run
3318 together with the text after the macro call, to produce a single token.
3319 This is impossible in ISO C@.
3322 None of the GNU extensions to the preprocessor are available in
3323 traditional mode, with the exception of a partial implementation of
3324 assertions, and those may be removed in the future.
3327 A true traditional C preprocessor does not recognize @samp{#elif},
3328 @samp{#error}, or @samp{#pragma}. GCC supports @samp{#elif} and
3329 @samp{#error} even in traditional mode, but not @samp{#pragma}.
3332 Traditional mode is text-based, not token-based, and comments are
3333 stripped after macro expansion. Therefore, @samp{/**/} can be used to
3334 paste tokens together provided that there is no whitespace between it
3335 and the tokens to be pasted.
3338 Traditional mode preserves the amount and form of whitespace provided by
3339 the user. Hard tabs remain hard tabs. This can be useful, e.g.@: if you
3340 are preprocessing a Makefile (which we do not encourage).
3343 You can request warnings about features that did not exist, or worked
3344 differently, in traditional C with the @option{-Wtraditional} option.
3345 This works only if you do @emph{not} specify @option{-traditional}. GCC
3346 does not warn about features of ISO C which you must use when you are
3347 using a conforming compiler, such as the @samp{#} and @samp{##}
3350 Presently @option{-Wtraditional} warns about:
3354 Macro parameters that appear within string literals in the macro body.
3355 In traditional C macro replacement takes place within string literals,
3356 but does not in ISO C@.
3359 In traditional C, some preprocessor directives did not exist.
3360 Traditional preprocessors would only consider a line to be a directive
3361 if the @samp{#} appeared in column 1 on the line. Therefore
3362 @option{-Wtraditional} warns about directives that traditional C
3363 understands but would ignore because the @samp{#} does not appear as the
3364 first character on the line. It also suggests you hide directives like
3365 @samp{#pragma} not understood by traditional C by indenting them. Some
3366 traditional implementations would not recognize @samp{#elif}, so it
3367 suggests avoiding it altogether.
3370 A function-like macro that appears without an argument list. In
3371 traditional C this was an error. In ISO C it merely means that the
3372 macro is not expanded.
3375 The unary plus operator. This did not exist in traditional C@.
3378 The @samp{U} and @samp{LL} integer constant suffixes, which were not
3379 available in traditional C@. (Traditional C does support the @samp{L}
3380 suffix for simple long integer constants.) You are not warned about
3381 uses of these suffixes in macros defined in system headers. For
3382 instance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but
3383 you will not be warned if you use @code{UINT_MAX}.
3385 You can usually avoid the warning, and the related warning about
3386 constants which are so large that they are unsigned, by writing the
3387 integer constant in question in hexadecimal, with no U suffix. Take
3388 care, though, because this gives the wrong result in exotic cases.
3391 @node Implementation Details
3392 @chapter Implementation Details
3394 Here we document details of how the preprocessor's implementation
3395 affects its user-visible behavior. You should try to avoid undue
3396 reliance on behavior described here, as it is possible that it will
3397 change subtly in future implementations.
3399 Also documented here are obsolete features and changes from previous
3400 versions of GNU CPP@.
3403 * Implementation-defined behavior::
3404 * Implementation limits::
3405 * Obsolete Features::
3406 * Differences from previous versions::
3409 @node Implementation-defined behavior
3410 @section Implementation-defined behavior
3411 @cindex implementation-defined behavior
3413 This is how GNU CPP behaves in all the cases which the C standard
3414 describes as @dfn{implementation-defined}. This term means that the
3415 implementation is free to do what it likes, but must document its choice
3417 @c FIXME: Check the C++ standard for more implementation-defined stuff.
3421 @item The mapping of physical source file multi-byte characters to the
3422 execution character set.
3424 Currently, GNU cpp only supports character sets that are strict supersets
3425 of ASCII, and performs no translation of characters.
3427 @item Non-empty sequences of whitespace characters.
3429 In textual output, each whitespace sequence is collapsed to a single
3430 space. For aesthetic reasons, the first token on each non-directive
3431 line of output is preceded with sufficient spaces that it appears in the
3432 same column as it did in the original source file.
3434 @item The numeric value of character constants in preprocessor expressions.
3436 The preprocessor and compiler interpret character constants in the same
3437 way; escape sequences such as @samp{\a} are given the values they would
3438 have on the target machine.
3440 Multi-character character constants are interpreted a character at a
3441 time, shifting the previous result left by the number of bits per
3442 character on the host, and adding the new character. For example, 'ab'
3443 on an 8-bit host would be interpreted as @w{'a' * 256 + 'b'}. If there
3444 are more characters in the constant than can fit in the widest native
3445 integer type on the host, usually a @code{long}, the excess characters
3446 are ignored and a diagnostic is given.
3448 @item Source file inclusion.
3450 For a discussion on how the preprocessor locates header files,
3451 @ref{Include Operation}.
3453 @item Interpretation of the filename resulting from a macro-expanded
3454 @samp{#include} directive.
3456 @xref{Computed Includes}.
3458 @item Treatment of a @samp{#pragma} directive that after macro-expansion
3459 results in a standard pragma.
3461 No macro expansion occurs on any @samp{#pragma} directive line, so the
3462 question does not arise.
3464 Note that GCC does not yet implement any of the standard
3469 @node Implementation limits
3470 @section Implementation limits
3471 @cindex implementation limits
3473 GNU CPP has a small number of internal limits. This section lists the
3474 limits which the C standard requires to be no lower than some minimum,
3475 and all the others we are aware of. We intend there to be as few limits
3476 as possible. If you encounter an undocumented or inconvenient limit,
3477 please report that to us as a bug. (See the section on reporting bugs in
3480 Where we say something is limited @dfn{only by available memory}, that
3481 means that internal data structures impose no intrinsic limit, and space
3482 is allocated with @code{malloc} or equivalent. The actual limit will
3483 therefore depend on many things, such as the size of other things
3484 allocated by the compiler at the same time, the amount of memory
3485 consumed by other processes on the same computer, etc.
3489 @item Nesting levels of @samp{#include} files.
3491 We impose an arbitrary limit of 200 levels, to avoid runaway recursion.
3492 The standard requires at least 15 levels.
3494 @item Nesting levels of conditional inclusion.
3496 The C standard mandates this be at least 63. GNU CPP is limited only by
3499 @item Levels of parenthesised expressions within a full expression.
3501 The C standard requires this to be at least 63. In preprocessor
3502 conditional expressions, it is limited only by available memory.
3504 @item Significant initial characters in an identifier or macro name.
3506 The preprocessor treats all characters as significant. The C standard
3507 requires only that the first 63 be significant.
3509 @item Number of macros simultaneously defined in a single translation unit.
3511 The standard requires at least 4095 be possible. GNU CPP is limited only
3512 by available memory.
3514 @item Number of parameters in a macro definition and arguments in a macro call.
3516 We allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum
3517 required by the standard is 127.
3519 @item Number of characters on a logical source line.
3521 The C standard requires a minimum of 4096 be permitted. GNU CPP places
3522 no limits on this, but you may get incorrect column numbers reported in
3523 diagnostics for lines longer than 65,535 characters.
3525 @item Maximum size of a source file.
3527 The standard does not specify any lower limit on the maximum size of a
3528 source file. GNU cpp maps files into memory, so it is limited by the
3529 available address space. This is generally at least two gigabytes.
3530 Depending on the operating system, the size of physical memory may or
3531 may not be a limitation.
3535 @node Obsolete Features
3536 @section Obsolete Features
3538 GNU CPP has a number of features which are present mainly for
3539 compatibility with older programs. We discourage their use in new code.
3540 In some cases, we plan to remove the feature in a future version of GCC@.
3544 * Obsolete once-only headers::
3545 * Miscellaneous obsolete features::
3549 @subsection Assertions
3552 @dfn{Assertions} are a deprecated alternative to macros in writing
3553 conditionals to test what sort of computer or system the compiled
3554 program will run on. Assertions are usually predefined, but you can
3555 define them with preprocessing directives or command-line options.
3557 Assertions were intended to provide a more systematic way to describe
3558 the compiler's target system. However, in practice they are just as
3559 unpredictable as the system-specific predefined macros. In addition, they
3560 are not part of any standard, and only a few compilers support them.
3561 Therefore, the use of assertions is @strong{less} portable than the use
3562 of system-specific predefined macros. We recommend you do not use them at
3566 An assertion looks like this:
3569 #@var{predicate} (@var{answer})
3573 @var{predicate} must be a single identifier. @var{answer} can be any
3574 sequence of tokens; all characters are significant except for leading
3575 and trailing whitespace, and differences in internal whitespace
3576 sequences are ignored. (This is similar to the rules governing macro
3577 redefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but
3578 equivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an
3581 @cindex testing predicates
3582 To test an assertion, you write it in an @samp{#if}. For example, this
3583 conditional succeeds if either @code{vax} or @code{ns16000} has been
3584 asserted as an answer for @code{machine}.
3587 #if #machine (vax) || #machine (ns16000)
3591 You can test whether @emph{any} answer is asserted for a predicate by
3592 omitting the answer in the conditional:
3599 Assertions are made with the @samp{#assert} directive. Its sole
3600 argument is the assertion to make, without the leading @samp{#} that
3601 identifies assertions in conditionals.
3604 #assert @var{predicate} (@var{answer})
3608 You may make several assertions with the same predicate and different
3609 answers. Subsequent assertions do not override previous ones for the
3610 same predicate. All the answers for any given predicate are
3611 simultaneously true.
3613 @cindex assertions, cancelling
3615 Assertions can be cancelled with the @samp{#unassert} directive. It
3616 has the same syntax as @samp{#assert}. In that form it cancels only the
3617 answer which was specified on the @samp{#unassert} line; other answers
3618 for that predicate remain true. You can cancel an entire predicate by
3619 leaving out the answer:
3622 #unassert @var{predicate}
3626 In either form, if no such assertion has been made, @samp{#unassert} has
3629 You can also make or cancel assertions using command line options.
3632 @node Obsolete once-only headers
3633 @subsection Obsolete once-only headers
3635 GNU CPP supports two more ways of indicating that a header file should be
3636 read only once. Neither one is as portable as a wrapper @samp{#ifndef},
3637 and we recommend you do not use them in new programs.
3640 In the Objective-C language, there is a variant of @samp{#include}
3641 called @samp{#import} which includes a file, but does so at most once.
3642 If you use @samp{#import} instead of @samp{#include}, then you don't
3643 need the conditionals inside the header file to prevent multiple
3644 inclusion of the contents. GCC permits the use of @samp{#import} in C
3645 and C++ as well as Objective-C@. However, it is not in standard C or C++
3646 and should therefore not be used by portable programs.
3648 @samp{#import} is not a well designed feature. It requires the users of
3649 a header file to know that it should only be included once. It is much
3650 better for the header file's implementor to write the file so that users
3651 don't need to know this. Using a wrapper @samp{#ifndef} accomplishes
3654 In the present implementation, a single use of @samp{#import} will
3655 prevent the file from ever being read again, by either @samp{#import} or
3656 @samp{#include}. You should not rely on this; do not use both
3657 @samp{#import} and @samp{#include} to refer to the same header file.
3659 Another way to prevent a header file from being included more than once
3660 is with the @samp{#pragma once} directive. If @samp{#pragma once} is
3661 seen when scanning a header file, that file will never be read again, no
3664 @samp{#pragma once} does not have the problems that @samp{#import} does,
3665 but it is not recognized by all preprocessors, so you cannot rely on it
3666 in a portable program.
3668 @node Miscellaneous obsolete features
3669 @subsection Miscellaneous obsolete features
3671 Here are a few more obsolete features.
3674 @cindex invalid token paste
3675 @item Attempting to paste two tokens which together do not form a valid
3676 preprocessing token.
3678 The preprocessor currently warns about this and outputs the two tokens
3679 adjacently, which is probably the behavior the programmer intends. It
3680 may not work in future, though.
3682 Most of the time, when you get this warning, you will find that @samp{##}
3683 is being used superstitiously, to guard against whitespace appearing
3684 between two tokens. It is almost always safe to delete the @samp{##}.
3686 @cindex pragma poison
3687 @item @code{#pragma poison}
3689 This is the same as @code{#pragma GCC poison}. The version without the
3690 @code{GCC} prefix is deprecated. @xref{Pragmas}.
3692 @cindex multi-line string constants
3693 @item Multi-line string constants
3695 GCC currently allows a string constant to extend across multiple logical
3696 lines of the source file. This extension is deprecated and will be
3697 removed in a future version of GCC@. Such string constants are already
3698 rejected in all directives apart from @samp{#define}.
3700 Instead, make use of ISO C concatenation of adjacent string literals, or
3701 use @samp{\n} followed by a backslash-newline.
3705 @node Differences from previous versions
3706 @section Differences from previous versions
3707 @cindex differences from previous versions
3709 This section details behavior which has changed from previous versions
3710 of GNU CPP@. We do not plan to change it again in the near future, but
3711 we do not promise not to, either.
3713 The ``previous versions'' discussed here are 2.95 and before. The
3714 behavior of GCC 3.0 is mostly the same as the behavior of the widely
3715 used 2.96 and 2.97 development snapshots. Where there are differences,
3716 they generally represent bugs in the snapshots.
3720 @item Order of evaluation of @samp{#} and @samp{##} operators
3722 The standard does not specify the order of evaluation of a chain of
3723 @samp{##} operators, nor whether @samp{#} is evaluated before, after, or
3724 at the same time as @samp{##}. You should therefore not write any code
3725 which depends on any specific ordering. It is possible to guarantee an
3726 ordering, if you need one, by suitable use of nested macros.
3728 An example of where this might matter is pasting the arguments @samp{1},
3729 @samp{e} and @samp{-2}. This would be fine for left-to-right pasting,
3730 but right-to-left pasting would produce an invalid token @samp{e-2}.
3732 GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly
3733 left to right. Older versions evaluated all @samp{#} operators first,
3734 then all @samp{##} operators, in an unreliable order.
3736 @item The form of whitespace betwen tokens in preprocessor output
3738 @xref{Preprocessor Output}, for the current textual format. This is
3739 also the format used by stringification. Normally, the preprocessor
3740 communicates tokens directly to the compiler's parser, and whitespace
3741 does not come up at all.
3743 Older versions of GCC preserved all whitespace provided by the user and
3744 inserted lots more whitespace of their own, because they could not
3745 accurately predict when extra spaces were needed to prevent accidental
3748 @item Optional argument when invoking rest argument macros
3750 As an extension, GCC permits you to omit the variable arguments entirely
3751 when you use a variable argument macro. This is forbidden by the 1999 C
3752 standard, and will provoke a pedantic warning with GCC 3.0. Previous
3753 versions accepted it silently.
3755 @item @samp{##} swallowing preceding text in rest argument macros
3757 Formerly, in a macro expansion, if @samp{##} appeared before a variable
3758 arguments parameter, and the set of tokens specified for that argument
3759 in the macro invocation was empty, previous versions of GNU CPP would
3760 back up and remove the preceding sequence of non-whitespace characters
3761 (@strong{not} the preceding token). This extension is in direct
3762 conflict with the 1999 C standard and has been drastically pared back.
3764 In the current version of the preprocessor, if @samp{##} appears between
3765 a comma and a variable arguments parameter, and the variable argument is
3766 omitted entirely, the comma will be removed from the expansion. If the
3767 variable argument is empty, or the token before @samp{##} is not a
3768 comma, then @samp{##} behaves as a normal token paste.
3770 @item Traditional mode and GNU extensions
3772 Traditional mode used to be implemented in the same program as normal
3773 preprocessing. Therefore, all the GNU extensions to the preprocessor
3774 were still available in traditional mode. It is now a separate program
3775 and does not implement any of the GNU extensions, except for a partial
3776 implementation of assertions. Even those may be removed in a future
3783 @cindex command line
3785 Most often when you use the C preprocessor you will not have to invoke it
3786 explicitly: the C compiler will do so automatically. However, the
3787 preprocessor is sometimes useful on its own. All the options listed
3788 here are also acceptable to the C compiler and have the same meaning,
3789 except that the C compiler has different rules for specifying the output
3792 @strong{Note:} Whether you use the preprocessor by way of @command{gcc}
3793 or @command{cpp}, the @dfn{compiler driver} is run first. This
3794 program's purpose is to translate your command into invocations of the
3795 programs that do the actual work. Their command line interfaces are
3796 similar but not identical to the documented interface, and may change
3800 @c man begin SYNOPSIS
3801 cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
3802 [@option{-I}@var{dir}@dots{}] [@option{-W}@var{warn}@dots{}]
3803 [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
3804 [@option{-MP}] [@option{-MQ} @var{target}@dots{}] [@option{-MT} @var{target}@dots{}]
3805 [@option{-x} @var{language}] [@option{-std=}@var{standard}]
3806 @var{infile} @var{outfile}
3808 Only the most useful options are listed here; see below for the remainder.
3810 @c man begin SEEALSO
3811 gpl(7), gfdl(7), fsf-funding(7),
3812 gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
3817 @c man begin OPTIONS
3818 The C preprocessor expects two file names as arguments, @var{infile} and
3819 @var{outfile}. The preprocessor reads @var{infile} together with any
3820 other files it specifies with @samp{#include}. All the output generated
3821 by the combined input files is written in @var{outfile}.
3823 Either @var{infile} or @var{outfile} may be @option{-}, which as
3824 @var{infile} means to read from standard input and as @var{outfile}
3825 means to write to standard output. Also, if either file is omitted, it
3826 means the same as if @option{-} had been specified for that file.
3828 Unless otherwise noted, or the option ends in @samp{=}, all options
3829 which take an argument may have that argument appear either immediately
3830 after the option, or with a space between option and argument:
3831 @option{-Ifoo} and @option{-I foo} have the same effect.
3833 @cindex grouping options
3834 @cindex options, grouping
3835 Many options have multi-letter names; therefore multiple single-letter
3836 options may @emph{not} be grouped: @option{-dM} is very different from
3842 Predefine @var{name} as a macro, with definition @code{1}.
3844 @item -D @var{name}=@var{definition}
3845 Predefine @var{name} as a macro, with definition @var{definition}.
3846 There are no restrictions on the contents of @var{definition}, but if
3847 you are invoking the preprocessor from a shell or shell-like program you
3848 may need to use the shell's quoting syntax to protect characters such as
3849 spaces that have a meaning in the shell syntax. If you use more than
3850 one @option{-D} for the same @var{name}, the rightmost definition takes
3853 If you wish to define a function-like macro on the command line, write
3854 its argument list with surrounding parentheses before the equals sign
3855 (if any). Parentheses are meaningful to most shells, so you will need
3856 to quote the option. With @command{sh} and @command{csh},
3857 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
3860 Cancel any previous definition of @var{name}, either built in or
3861 provided with a @option{-D} option.
3863 All @option{-imacros @var{file}} and @option{-include @var{file}} options
3864 are processed after all @option{-D} and @option{-U} options.
3867 Do not predefine any system-specific macros. The common predefined
3868 macros remain defined.
3871 Add the directory @var{dir} to the list of directories to be searched
3872 for header files. @xref{Search Path}. Directories named by @option{-I}
3873 are searched before the standard system include directories.
3875 It is dangerous to specify a standard system include directory in an
3876 @option{-I} option. This defeats the special treatment of system
3877 headers (@pxref{System Headers}). It can also defeat the repairs to
3878 buggy system headers which GCC makes when it is installed.
3881 Write output to @var{file}. This is the same as specifying @var{file}
3882 as the second non-option argument to @command{cpp}. @command{gcc} has a
3883 different interpretation of a second non-option argument, so you must
3884 use @option{-o} to specify the output file.
3887 Turns on all optional warnings which are desirable for normal code. At
3888 present this is @option{-Wcomment} and @option{-Wtrigraphs}. Note that
3889 many of the preprocessor's warnings are on by default and have no
3890 options to control them.
3894 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
3895 comment, or whenever a backslash-newline appears in a @samp{//} comment.
3896 (Both forms have the same effect.)
3899 Warn if any trigraphs are encountered. This option used to take effect
3900 only if @option{-trigraphs} was also specified, but now works
3901 independently. Warnings are not given for trigraphs within comments, as
3902 they do not affect the meaning of the program.
3905 Warn about certain constructs that behave differently in traditional and
3906 ISO C@. Also warn about ISO C constructs that have no traditional C
3907 equivalent, and problematic constructs which should be avoided.
3908 @xref{Traditional Mode}.
3911 Warn the first time @samp{#import} is used.
3914 Warn whenever an identifier which is not a macro is encountered in an
3915 @samp{#if} directive, outside of @samp{defined}. Such identifiers are
3919 Make all warnings into hard errors. Source code which triggers warnings
3922 @item -Wsystem-headers
3923 Issue warnings for code in system headers. These are normally unhelpful
3924 in finding bugs in your own code, therefore suppressed. If you are
3925 responsible for the system library, you may want to see them.
3928 Suppress all warnings, including those which GNU CPP issues by default.
3931 Issue all the mandatory diagnostics listed in the C standard. Some of
3932 them are left out by default, since they trigger frequently on harmless
3935 @item -pedantic-errors
3936 Issue all the mandatory diagnostics, and make all mandatory diagnostics
3937 into errors. This includes mandatory diagnostics that GCC issues
3938 without @samp{-pedantic} but treats as warnings.
3941 Instead of outputting the result of preprocessing, output a rule
3942 suitable for @command{make} describing the dependencies of the main
3943 source file. The preprocessor outputs one @command{make} rule containing
3944 the object file name for that source file, a colon, and the names of all
3945 the included files, including those coming from @option{-include} or
3946 @option{-imacros} command line options.
3948 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
3949 object file name consists of the basename of the source file with any
3950 suffix replaced with object file suffix. If there are many included
3951 files then the rule is split into several lines using @samp{\}-newline.
3952 The rule has no commands.
3955 Like @option{-M}, but mention only the files included with @code{@w{#include
3956 "@var{file}"}} or with @option{-include} or @option{-imacros} command line
3957 options. System header files included with @code{@w{#include <@var{file}>}}
3960 @item -MF @var{file}
3961 When used with @option{-M} or @option{-MM}, specifies a file to write the
3962 dependencies to. This allows the preprocessor to write the preprocessed
3963 file to stdout normally. If no @option{-MF} switch is given, CPP sends
3964 the rules to stdout and suppresses normal preprocessed output.
3967 When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
3968 header files as generated files and assume they live in the same
3969 directory as the source file. It suppresses preprocessed output, as a
3970 missing header file is ordinarily an error.
3972 This feature is used in automatic updating of makefiles.
3975 This option instructs CPP to add a phony target for each dependency
3976 other than the main file, causing each to depend on nothing. These
3977 dummy rules work around errors @command{make} gives if you remove header
3978 files without updating the @file{Makefile} to match.
3980 This is typical output:
3983 test.o: test.c test.h
3988 @item -MT @var{target}
3990 Change the target of the rule emitted by dependency generation. By
3991 default CPP takes the name of the main input file, including any path,
3992 deletes any file suffix such as @samp{.c}, and appends the platform's
3993 usual object suffix. The result is the target.
3995 An @option{-MT} option will set the target to be exactly the string you
3996 specify. If you want multiple targets, you can specify them as a single
3997 argument to @option{-MT}, or use multiple @option{-MT} options.
3999 For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
4002 $(objpfx)foo.o: foo.c
4005 @item -MQ @var{target}
4007 Same as @option{-MT}, but it quotes any characters which are special to
4008 Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
4011 $$(objpfx)foo.o: foo.c
4014 The default target is automatically quoted, as if it were given with
4017 @item -MD @var{file}
4018 @itemx -MMD @var{file}
4019 @option{-MD @var{file}} is equivalent to @option{-M -MF @var{file}}, and
4020 @option{-MMD @var{file}} is equivalent to @option{-MM -MF @var{file}}.
4022 Due to limitations in the compiler driver, you must use these switches
4023 when you want to generate a dependency file as a side-effect of normal
4028 @itemx -x objective-c
4029 @itemx -x assembler-with-cpp
4030 Specify the source language: C, C++, Objective-C, or assembly. This has
4031 nothing to do with standards conformance or extensions; it merely
4032 selects which base syntax to expect. If you give none of these options,
4033 cpp will deduce the language from the extension of the source file:
4034 @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common
4035 extensions for C++ and assembly are also recognized. If cpp does not
4036 recognize the extension, it will treat the file as C; this is the most
4039 @strong{Note:} Previous versions of cpp accepted a @option{-lang} option
4040 which selected both the language and the standards conformance level.
4041 This option has been removed, because it conflicts with the @option{-l}
4044 @item -std=@var{standard}
4046 Specify the standard to which the code should conform. Currently cpp
4047 only knows about the standards for C; other language standards will be
4048 added in the future.
4055 The ISO C standard from 1990. @samp{c89} is the customary shorthand for
4056 this version of the standard.
4058 The @option{-ansi} option is equivalent to @option{-std=c89}.
4060 @item iso9899:199409
4061 The 1990 C standard, as amended in 1994.
4067 The revised ISO C standard, published in December 1999. Before
4068 publication, this was known as C9X@.
4071 The 1990 C standard plus GNU extensions. This is the default.
4075 The 1999 C standard plus GNU extensions.
4079 Split the include path. Any directories specified with @option{-I}
4080 options before @option{-I-} are searched only for headers requested with
4081 @code{@w{#include "@var{file}"}}; they are not searched for
4082 @code{@w{#include <@var{file}>}}. If additional directories are
4083 specified with @option{-I} options after the @option{-I-}, those
4084 directories are searched for all @samp{#include} directives.
4086 In addition, @option{-I-} inhibits the use of the directory of the current
4087 file directory as the first search directory for @code{@w{#include
4088 "@var{file}"}}. @xref{Search Path}.
4091 Do not search the standard system directories for header files.
4092 Only the directories you have specified with @option{-I} options
4093 (and the directory of the current file, if appropriate) are searched.
4096 Do not search for header files in the C++-specific standard directories,
4097 but do still search the other standard directories. (This option is
4098 used when building the C++ library.)
4100 @item -include @var{file}
4102 Process @var{file} as if @code{#include "file"} appeared as the first
4103 line of the primary source file. However, the first directory searched
4104 for @var{file} is the preprocessor's working directory @emph{instead of}
4105 the directory containing the main source file. If not found there, it
4106 is searched for in the remainder of the @code{#include "@dots{}"} search
4109 If multiple @option{-include} options are given, the files are included
4110 in the order they appear on the command line.
4112 @item -imacros @var{file}
4114 Exactly like @option{-include}, except that any output produced by
4115 scanning @var{file} is thrown away. Macros it defines remain defined.
4116 This allows you to acquire all the macros from a header without also
4117 processing its declarations.
4119 All files specified by @option{-imacros} are processed before all files
4120 specified by @option{-include}.
4122 @item -idirafter @var{dir}
4123 Search @var{dir} for header files, but do it @emph{after} all
4124 directories specified with @option{-I} and the standard system directories
4125 have been exhausted. @var{dir} is treated as a system include directory.
4127 @item -iprefix @var{prefix}
4128 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
4129 options. If the prefix represents a directory, you should include the
4132 @item -iwithprefix @var{dir}
4133 @itemx -iwithprefixbefore @var{dir}
4135 Append @var{dir} to the prefix specified previously with
4136 @option{-iprefix}, and add the resulting directory to the include search
4137 path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
4138 would; @option{-iwithprefix} puts it where @option{-idirafter} would.
4140 Use of these options is discouraged.
4142 @item -isystem @var{dir}
4143 Search @var{dir} for header files, after all directories specified by
4144 @option{-I} but before the standard system directories. Mark it
4145 as a system directory, so that it gets the same special treatment as
4146 is applied to the standard system directories. @xref{System Headers}.
4148 @item -fpreprocessed
4149 Indicate to the preprocessor that the input file has already been
4150 preprocessed. This suppresses things like macro expansion, trigraph
4151 conversion, escaped newline splicing, and processing of most directives.
4152 The preprocessor still recognizes and removes comments, so that you can
4153 pass a file preprocessed with @option{-C} to the compiler without
4154 problems. In this mode the integrated preprocessor is little more than
4155 a tokenizer for the front ends.
4157 @option{-fpreprocessed} is implicit if the input file has one of the
4158 extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
4159 extensions that GCC uses for preprocessed files created by
4160 @option{-save-temps}.
4162 @item -ftabstop=@var{width}
4163 Set the distance between tab stops. This helps the preprocessor report
4164 correct column numbers in warnings or errors, even if tabs appear on the
4165 line. If the value is less than 1 or greater than 100, the option is
4166 ignored. The default is 8.
4168 @item -fno-show-column
4169 Do not print column numbers in diagnostics. This may be necessary if
4170 diagnostics are being scanned by a program that does not understand the
4171 column numbers, such as @command{dejagnu}.
4173 @item -A @var{predicate}=@var{answer}
4174 Make an assertion with the predicate @var{predicate} and answer
4175 @var{answer}. This form is preferred to the older form @option{-A
4176 @var{predicate}(@var{answer})}, which is still supported, because
4177 it does not use shell special characters. @xref{Assertions}.
4179 @item -A -@var{predicate}=@var{answer}
4180 Cancel an assertion with the predicate @var{predicate} and answer
4184 Cancel all predefined assertions and all assertions preceding it on
4185 the command line. Also, undefine all predefined macros and all
4186 macros preceding it on the command line. (This is a historical wart and
4187 may change in the future.)
4190 @var{CHARS} is a sequence of one or more of the following characters,
4191 and must not be preceded by a space. Other characters are interpreted
4192 by the compiler proper, or reserved for future versions of GCC, and so
4193 are silently ignored. If you specify characters whose behavior
4194 conflicts, the result is undefined.
4198 Instead of the normal output, generate a list of @samp{#define}
4199 directives for all the macros defined during the execution of the
4200 preprocessor, including predefined macros. This gives you a way of
4201 finding out what is predefined in your version of the preprocessor.
4202 Assuming you have no file @file{foo.h}, the command
4205 touch foo.h; cpp -dM foo.h
4209 will show all the predefined macros.
4212 Like @samp{M} except in two respects: it does @emph{not} include the
4213 predefined macros, and it outputs @emph{both} the @samp{#define}
4214 directives and the result of preprocessing. Both kinds of output go to
4215 the standard output file.
4218 Like @samp{D}, but emit only the macro names, not their expansions.
4221 Output @samp{#include} directives in addition to the result of
4226 Inhibit generation of linemarkers in the output from the preprocessor.
4227 This might be useful when running the preprocessor on something that is
4228 not C code, and will be sent to a program which might be confused by the
4229 linemarkers. @xref{Preprocessor Output}.
4232 Do not discard comments. All comments are passed through to the output
4233 file, except for comments in processed directives, which are deleted
4234 along with the directive.
4236 You should be prepared for side effects when using @option{-C}; it
4237 causes the preprocessor to treat comments as tokens in their own right.
4238 For example, comments appearing at the start of what would be a
4239 directive line have the effect of turning that line into an ordinary
4240 source line, since the first token on the line is no longer a @samp{#}.
4243 Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and
4244 @sc{__gnuc_patchlevel__}. These are defined automatically when you use
4245 @command{gcc -E}; you can turn them off in that case with
4249 Try to imitate the behavior of old-fashioned C, as opposed to ISO
4250 C@. @xref{Traditional Mode}.
4253 Process trigraph sequences. @xref{Initial processing}.
4256 Enable special code to work around file systems which only permit very
4257 short file names, such as MS-DOS@.
4260 Forbid the use of @samp{$} in identifiers. The C standard allows
4261 implementations to define extra characters that can appear in
4262 identifiers. By default GNU CPP permits @samp{$}, a common extension.
4266 @itemx --target-help
4267 Print text describing all the command line options instead of
4268 preprocessing anything.
4271 Verbose mode. Print out GNU CPP's version number at the beginning of
4272 execution, and report the final form of the include path.
4275 Print the name of each header file used, in addition to other normal
4276 activities. Each name is indented to show how deep in the
4277 @samp{#include} stack it is.
4281 Print out GNU CPP's version number. With one dash, proceed to
4282 preprocess as normal. With two dashes, exit immediately.
4289 @node Index of Directives
4290 @unnumbered Index of Directives
4294 @unnumbered Concept Index