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
1980 @node System-specific Predefined Macros
1981 @subsection System-specific Predefined Macros
1983 @cindex system-specific predefined macros
1984 @cindex predefined macros, system-specific
1985 @cindex reserved namespace
1987 The C preprocessor normally predefines several macros that indicate what
1988 type of system and machine is in use. They are obviously different on
1989 each target supported by GCC@. This manual, being for all systems and
1990 machines, cannot tell you what their names are, but you can use
1991 @command{cpp -dM} to see them all. @xref{Invocation}. All system-specific
1992 predefined macros expand to the constant 1, so you can test them with
1993 either @samp{#ifdef} or @samp{#if}.
1995 The C standard requires that all system-specific macros be part of the
1996 @dfn{reserved namespace}. All names which begin with two underscores,
1997 or an underscore and a capital letter, are reserved for the compiler and
1998 library to use as they wish. However, historically system-specific
1999 macros have had names with no special prefix; for instance, it is common
2000 to find @code{unix} defined on Unix systems. For all such macros, GCC
2001 provides a parallel macro with two underscores added at the beginning
2002 and the end. If @code{unix} is defined, @code{__unix__} will be defined
2003 too. There will never be more than two underscores; the parallel of
2004 @code{_mips} is @code{__mips__}.
2006 When the @option{-ansi} option, or any @option{-std} option that
2007 requests strict conformance, is given to the compiler, all the
2008 system-specific predefined macros outside the reserved namespace are
2009 suppressed. The parallel macros, inside the reserved namespace, remain
2012 We are slowly phasing out all predefined macros which are outside the
2013 reserved namespace. You should never use them in new programs, and we
2014 encourage you to correct older code to use the parallel macros whenever
2015 you find it. We don't recommend you use the system-specific macros that
2016 are in the reserved namespace, either. It is better in the long run to
2017 check specifically for features you need, using a tool such as
2020 @node C++ Named Operators
2021 @subsection C++ Named Operators
2022 @cindex named operators
2023 @cindex C++ named operators
2026 In C++, there are eleven keywords which are simply alternate spellings
2027 of operators normally written with punctuation. These keywords are
2028 treated as such even in the preprocessor. They function as operators in
2029 @samp{#if}, and they cannot be defined as macros or poisoned. In C, you
2030 can request that those keywords take their C++ meaning by including
2031 @file{iso646.h}. That header defines each one as a normal object-like
2032 macro expanding to the appropriate punctuator.
2034 These are the named operators and their corresponding punctuators:
2036 @multitable {Named Operator} {Punctuator}
2037 @item Named Operator @tab Punctuator
2038 @item @code{and} @tab @code{&&}
2039 @item @code{and_eq} @tab @code{&=}
2040 @item @code{bitand} @tab @code{&}
2041 @item @code{bitor} @tab @code{|}
2042 @item @code{compl} @tab @code{~}
2043 @item @code{not} @tab @code{!}
2044 @item @code{not_eq} @tab @code{!=}
2045 @item @code{or} @tab @code{||}
2046 @item @code{or_eq} @tab @code{|=}
2047 @item @code{xor} @tab @code{^}
2048 @item @code{xor_eq} @tab @code{^=}
2051 @node Undefining and Redefining Macros
2052 @section Undefining and Redefining Macros
2053 @cindex undefining macros
2054 @cindex redefining macros
2057 If a macro ceases to be useful, it may be @dfn{undefined} with the
2058 @samp{#undef} directive. @samp{#undef} takes a single argument, the
2059 name of the macro to undefine. You use the bare macro name, even if the
2060 macro is function-like. It is an error if anything appears on the line
2061 after the macro name. @samp{#undef} has no effect if the name is not a
2066 x = FOO; @expansion{} x = 4;
2068 x = FOO; @expansion{} x = FOO;
2071 Once a macro has been undefined, that identifier may be @dfn{redefined}
2072 as a macro by a subsequent @samp{#define} directive. The new definition
2073 need not have any resemblance to the old definition.
2075 However, if an identifier which is currently a macro is redefined, then
2076 the new definition must be @dfn{effectively the same} as the old one.
2077 Two macro definitions are effectively the same if:
2079 @item Both are the same type of macro (object- or function-like).
2080 @item All the tokens of the replacement list are the same.
2081 @item If there are any parameters, they are the same.
2082 @item Whitespace appears in the same places in both. It need not be
2083 exactly the same amount of whitespace, though. Remember that comments
2084 count as whitespace.
2088 These definitions are effectively the same:
2090 #define FOUR (2 + 2)
2091 #define FOUR (2 + 2)
2092 #define FOUR (2 /* two */ + 2)
2097 #define FOUR (2 + 2)
2098 #define FOUR ( 2+2 )
2099 #define FOUR (2 * 2)
2100 #define FOUR(score,and,seven,years,ago) (2 + 2)
2103 If a macro is redefined with a definition that is not effectively the
2104 same as the old one, the preprocessor issues a warning and changes the
2105 macro to use the new definition. If the new definition is effectively
2106 the same, the redefinition is silently ignored. This allows, for
2107 instance, two different headers to define a common macro. The
2108 preprocessor will only complain if the definitions do not match.
2110 @node Macro Pitfalls
2111 @section Macro Pitfalls
2112 @cindex problems with macros
2113 @cindex pitfalls of macros
2115 In this section we describe some special rules that apply to macros and
2116 macro expansion, and point out certain cases in which the rules have
2117 counter-intuitive consequences that you must watch out for.
2121 * Operator Precedence Problems::
2122 * Swallowing the Semicolon::
2123 * Duplication of Side Effects::
2124 * Self-Referential Macros::
2125 * Argument Prescan::
2126 * Newlines in Arguments::
2130 @subsection Misnesting
2132 When a macro is called with arguments, the arguments are substituted
2133 into the macro body and the result is checked, together with the rest of
2134 the input file, for more macro calls. It is possible to piece together
2135 a macro call coming partially from the macro body and partially from the
2136 arguments. For example,
2139 #define twice(x) (2*(x))
2140 #define call_with_1(x) x(1)
2142 @expansion{} twice(1)
2143 @expansion{} (2*(1))
2146 Macro definitions do not have to have balanced parentheses. By writing
2147 an unbalanced open parenthesis in a macro body, it is possible to create
2148 a macro call that begins inside the macro body but ends outside of it.
2152 #define strange(file) fprintf (file, "%s %d",
2154 strange(stderr) p, 35)
2155 @expansion{} fprintf (stderr, "%s %d", p, 35)
2158 The ability to piece together a macro call can be useful, but the use of
2159 unbalanced open parentheses in a macro body is just confusing, and
2162 @node Operator Precedence Problems
2163 @subsection Operator Precedence Problems
2164 @cindex parentheses in macro bodies
2166 You may have noticed that in most of the macro definition examples shown
2167 above, each occurrence of a macro argument name had parentheses around
2168 it. In addition, another pair of parentheses usually surround the
2169 entire macro definition. Here is why it is best to write macros that
2172 Suppose you define a macro as follows,
2175 #define ceil_div(x, y) (x + y - 1) / y
2179 whose purpose is to divide, rounding up. (One use for this operation is
2180 to compute how many @code{int} objects are needed to hold a certain
2181 number of @code{char} objects.) Then suppose it is used as follows:
2184 a = ceil_div (b & c, sizeof (int));
2185 @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int);
2189 This does not do what is intended. The operator-precedence rules of
2190 C make it equivalent to this:
2193 a = (b & (c + sizeof (int) - 1)) / sizeof (int);
2197 What we want is this:
2200 a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
2204 Defining the macro as
2207 #define ceil_div(x, y) ((x) + (y) - 1) / (y)
2211 provides the desired result.
2213 Unintended grouping can result in another way. Consider @code{sizeof
2214 ceil_div(1, 2)}. That has the appearance of a C expression that would
2215 compute the size of the type of @code{ceil_div (1, 2)}, but in fact it
2216 means something very different. Here is what it expands to:
2219 sizeof ((1) + (2) - 1) / (2)
2223 This would take the size of an integer and divide it by two. The
2224 precedence rules have put the division outside the @code{sizeof} when it
2225 was intended to be inside.
2227 Parentheses around the entire macro definition prevent such problems.
2228 Here, then, is the recommended way to define @code{ceil_div}:
2231 #define ceil_div(x, y) (((x) + (y) - 1) / (y))
2234 @node Swallowing the Semicolon
2235 @subsection Swallowing the Semicolon
2236 @cindex semicolons (after macro calls)
2238 Often it is desirable to define a macro that expands into a compound
2239 statement. Consider, for example, the following macro, that advances a
2240 pointer (the argument @code{p} says where to find it) across whitespace
2244 #define SKIP_SPACES(p, limit) \
2245 @{ char *lim = (limit); \
2246 while (p < lim) @{ \
2247 if (*p++ != ' ') @{ \
2252 Here backslash-newline is used to split the macro definition, which must
2253 be a single logical line, so that it resembles the way such code would
2254 be laid out if not part of a macro definition.
2256 A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly
2257 speaking, the call expands to a compound statement, which is a complete
2258 statement with no need for a semicolon to end it. However, since it
2259 looks like a function call, it minimizes confusion if you can use it
2260 like a function call, writing a semicolon afterward, as in
2261 @code{SKIP_SPACES (p, lim);}
2263 This can cause trouble before @code{else} statements, because the
2264 semicolon is actually a null statement. Suppose you write
2268 SKIP_SPACES (p, lim);
2273 The presence of two statements---the compound statement and a null
2274 statement---in between the @code{if} condition and the @code{else}
2275 makes invalid C code.
2277 The definition of the macro @code{SKIP_SPACES} can be altered to solve
2278 this problem, using a @code{do @dots{} while} statement. Here is how:
2281 #define SKIP_SPACES(p, limit) \
2282 do @{ char *lim = (limit); \
2283 while (p < lim) @{ \
2284 if (*p++ != ' ') @{ \
2285 p--; break; @}@}@} \
2289 Now @code{SKIP_SPACES (p, lim);} expands into
2292 do @{@dots{}@} while (0);
2296 which is one statement. The loop executes exactly once; most compilers
2297 generate no extra code for it.
2299 @node Duplication of Side Effects
2300 @subsection Duplication of Side Effects
2302 @cindex side effects (in macro arguments)
2303 @cindex unsafe macros
2304 Many C programs define a macro @code{min}, for ``minimum'', like this:
2307 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
2310 When you use this macro with an argument containing a side effect,
2314 next = min (x + y, foo (z));
2318 it expands as follows:
2321 next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
2325 where @code{x + y} has been substituted for @code{X} and @code{foo (z)}
2328 The function @code{foo} is used only once in the statement as it appears
2329 in the program, but the expression @code{foo (z)} has been substituted
2330 twice into the macro expansion. As a result, @code{foo} might be called
2331 two times when the statement is executed. If it has side effects or if
2332 it takes a long time to compute, the results might not be what you
2333 intended. We say that @code{min} is an @dfn{unsafe} macro.
2335 The best solution to this problem is to define @code{min} in a way that
2336 computes the value of @code{foo (z)} only once. The C language offers
2337 no standard way to do this, but it can be done with GNU extensions as
2342 (@{ typeof (X) x_ = (X); \
2343 typeof (Y) y_ = (Y); \
2344 (x_ < y_) ? x_ : y_; @})
2347 The @samp{(@{ @dots{} @})} notation produces a compound statement that
2348 acts as an expression. Its value is the value of its last statement.
2349 This permits us to define local variables and assign each argument to
2350 one. The local variables have underscores after their names to reduce
2351 the risk of conflict with an identifier of wider scope (it is impossible
2352 to avoid this entirely). Now each argument is evaluated exactly once.
2354 If you do not wish to use GNU C extensions, the only solution is to be
2355 careful when @emph{using} the macro @code{min}. For example, you can
2356 calculate the value of @code{foo (z)}, save it in a variable, and use
2357 that variable in @code{min}:
2361 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
2365 next = min (x + y, tem);
2371 (where we assume that @code{foo} returns type @code{int}).
2373 @node Self-Referential Macros
2374 @subsection Self-Referential Macros
2375 @cindex self-reference
2377 A @dfn{self-referential} macro is one whose name appears in its
2378 definition. Recall that all macro definitions are rescanned for more
2379 macros to replace. If the self-reference were considered a use of the
2380 macro, it would produce an infinitely large expansion. To prevent this,
2381 the self-reference is not considered a macro call. It is passed into
2382 the preprocessor output unchanged. Let's consider an example:
2385 #define foo (4 + foo)
2389 where @code{foo} is also a variable in your program.
2391 Following the ordinary rules, each reference to @code{foo} will expand
2392 into @code{(4 + foo)}; then this will be rescanned and will expand into
2393 @code{(4 + (4 + foo))}; and so on until the computer runs out of memory.
2395 The self-reference rule cuts this process short after one step, at
2396 @code{(4 + foo)}. Therefore, this macro definition has the possibly
2397 useful effect of causing the program to add 4 to the value of @code{foo}
2398 wherever @code{foo} is referred to.
2400 In most cases, it is a bad idea to take advantage of this feature. A
2401 person reading the program who sees that @code{foo} is a variable will
2402 not expect that it is a macro as well. The reader will come across the
2403 identifier @code{foo} in the program and think its value should be that
2404 of the variable @code{foo}, whereas in fact the value is four greater.
2406 One common, useful use of self-reference is to create a macro which
2407 expands to itself. If you write
2414 then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is
2415 left alone by the preprocessor whenever it's used in running text. You
2416 can tell that it's a macro with @samp{#ifdef}. You might do this if you
2417 want to define numeric constants with an @code{enum}, but have
2418 @samp{#ifdef} be true for each constant.
2420 If a macro @code{x} expands to use a macro @code{y}, and the expansion of
2421 @code{y} refers to the macro @code{x}, that is an @dfn{indirect
2422 self-reference} of @code{x}. @code{x} is not expanded in this case
2423 either. Thus, if we have
2431 then @code{x} and @code{y} expand as follows:
2435 x @expansion{} (4 + y)
2436 @expansion{} (4 + (2 * x))
2438 y @expansion{} (2 * x)
2439 @expansion{} (2 * (4 + y))
2444 Each macro is expanded when it appears in the definition of the other
2445 macro, but not when it indirectly appears in its own definition.
2447 @node Argument Prescan
2448 @subsection Argument Prescan
2449 @cindex expansion of arguments
2450 @cindex macro argument expansion
2451 @cindex prescan of macro arguments
2453 Macro arguments are completely macro-expanded before they are
2454 substituted into a macro body, unless they are stringified or pasted
2455 with other tokens. After substitution, the entire macro body, including
2456 the substituted arguments, is scanned again for macros to be expanded.
2457 The result is that the arguments are scanned @emph{twice} to expand
2458 macro calls in them.
2460 Most of the time, this has no effect. If the argument contained any
2461 macro calls, they are expanded during the first scan. The result
2462 therefore contains no macro calls, so the second scan does not change
2463 it. If the argument were substituted as given, with no prescan, the
2464 single remaining scan would find the same macro calls and produce the
2467 You might expect the double scan to change the results when a
2468 self-referential macro is used in an argument of another macro
2469 (@pxref{Self-Referential Macros}): the self-referential macro would be
2470 expanded once in the first scan, and a second time in the second scan.
2471 However, this is not what happens. The self-references that do not
2472 expand in the first scan are marked so that they will not expand in the
2475 You might wonder, ``Why mention the prescan, if it makes no difference?
2476 And why not skip it and make the preprocessor faster?'' The answer is
2477 that the prescan does make a difference in three special cases:
2481 Nested calls to a macro.
2483 We say that @dfn{nested} calls to a macro occur when a macro's argument
2484 contains a call to that very macro. For example, if @code{f} is a macro
2485 that expects one argument, @code{f (f (1))} is a nested pair of calls to
2486 @code{f}. The desired expansion is made by expanding @code{f (1)} and
2487 substituting that into the definition of @code{f}. The prescan causes
2488 the expected result to happen. Without the prescan, @code{f (1)} itself
2489 would be substituted as an argument, and the inner use of @code{f} would
2490 appear during the main scan as an indirect self-reference and would not
2494 Macros that call other macros that stringify or concatenate.
2496 If an argument is stringified or concatenated, the prescan does not
2497 occur. If you @emph{want} to expand a macro, then stringify or
2498 concatenate its expansion, you can do that by causing one macro to call
2499 another macro that does the stringification or concatenation. For
2500 instance, if you have
2503 #define AFTERX(x) X_ ## x
2504 #define XAFTERX(x) AFTERX(x)
2505 #define TABLESIZE 1024
2506 #define BUFSIZE TABLESIZE
2509 then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and
2510 @code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to
2511 @code{X_TABLESIZE}. Prescan always does a complete expansion.)
2514 Macros used in arguments, whose expansions contain unshielded commas.
2516 This can cause a macro expanded on the second scan to be called with the
2517 wrong number of arguments. Here is an example:
2521 #define bar(x) lose(x)
2522 #define lose(x) (1 + (x))
2525 We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which
2526 would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)}
2527 expands into @code{lose(a,b)}, and you get an error because @code{lose}
2528 requires a single argument. In this case, the problem is easily solved
2529 by the same parentheses that ought to be used to prevent misnesting of
2530 arithmetic operations:
2535 #define bar(x) lose((x))
2538 The extra pair of parentheses prevents the comma in @code{foo}'s
2539 definition from being interpreted as an argument separator.
2543 @node Newlines in Arguments
2544 @subsection Newlines in Arguments
2545 @cindex newlines in macro arguments
2547 The invocation of a function-like macro can extend over many logical
2548 lines. However, in the present implementation, the entire expansion
2549 comes out on one line. Thus line numbers emitted by the compiler or
2550 debugger refer to the line the invocation started on, which might be
2551 different to the line containing the argument causing the problem.
2553 Here is an example illustrating this:
2556 #define ignore_second_arg(a,b,c) a; c
2558 ignore_second_arg (foo (),
2564 The syntax error triggered by the tokens @code{syntax error} results in
2565 an error message citing line three---the line of ignore_second_arg---
2566 even though the problematic code comes from line five.
2568 We consider this a bug, and intend to fix it in the near future.
2571 @chapter Conditionals
2572 @cindex conditionals
2574 A @dfn{conditional} is a directive that instructs the preprocessor to
2575 select whether or not to include a chunk of code in the final token
2576 stream passed to the compiler. Preprocessor conditionals can test
2577 arithmetic expressions, or whether a name is defined as a macro, or both
2578 simultaneously using the special @code{defined} operator.
2580 A conditional in the C preprocessor resembles in some ways an @code{if}
2581 statement in C, but it is important to understand the difference between
2582 them. The condition in an @code{if} statement is tested during the
2583 execution of your program. Its purpose is to allow your program to
2584 behave differently from run to run, depending on the data it is
2585 operating on. The condition in a preprocessing conditional directive is
2586 tested when your program is compiled. Its purpose is to allow different
2587 code to be included in the program depending on the situation at the
2588 time of compilation.
2590 However, the distinction is becoming less clear. Modern compilers often
2591 do test @code{if} statements when a program is compiled, if their
2592 conditions are known not to vary at run time, and eliminate code which
2593 can never be executed. If you can count on your compiler to do this,
2594 you may find that your program is more readable if you use @code{if}
2595 statements with constant conditions (perhaps determined by macros). Of
2596 course, you can only use this to exclude code, not type definitions or
2597 other preprocessing directives, and you can only do it if the code
2598 remains syntactically valid when it is not to be used.
2600 GCC version 3 eliminates this kind of never-executed code even when
2601 not optimizing. Older versions did it only when optimizing.
2604 * Conditional Uses::
2605 * Conditional Syntax::
2609 @node Conditional Uses
2610 @section Conditional Uses
2612 There are three general reasons to use a conditional.
2616 A program may need to use different code depending on the machine or
2617 operating system it is to run on. In some cases the code for one
2618 operating system may be erroneous on another operating system; for
2619 example, it might refer to data types or constants that do not exist on
2620 the other system. When this happens, it is not enough to avoid
2621 executing the invalid code. Its mere presence will cause the compiler
2622 to reject the program. With a preprocessing conditional, the offending
2623 code can be effectively excised from the program when it is not valid.
2626 You may want to be able to compile the same source file into two
2627 different programs. One version might make frequent time-consuming
2628 consistency checks on its intermediate data, or print the values of
2629 those data for debugging, and the other not.
2632 A conditional whose condition is always false is one way to exclude code
2633 from the program but keep it as a sort of comment for future reference.
2636 Simple programs that do not need system-specific logic or complex
2637 debugging hooks generally will not need to use preprocessing
2640 @node Conditional Syntax
2641 @section Conditional Syntax
2644 A conditional in the C preprocessor begins with a @dfn{conditional
2645 directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
2660 The simplest sort of conditional is
2666 @var{controlled text}
2668 #endif /* @var{MACRO} */
2672 @cindex conditional group
2673 This block is called a @dfn{conditional group}. @var{controlled text}
2674 will be included in the output of the preprocessor if and only if
2675 @var{MACRO} is defined. We say that the conditional @dfn{succeeds} if
2676 @var{MACRO} is defined, @dfn{fails} if it is not.
2678 The @var{controlled text} inside of a conditional can include
2679 preprocessing directives. They are executed only if the conditional
2680 succeeds. You can nest conditional groups inside other conditional
2681 groups, but they must be completely nested. In other words,
2682 @samp{#endif} always matches the nearest @samp{#ifdef} (or
2683 @samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional
2684 group in one file and end it in another.
2686 Even if a conditional fails, the @var{controlled text} inside it is
2687 still run through initial transformations and tokenization. Therefore,
2688 it must all be lexically valid C@. Normally the only way this matters is
2689 that all comments and string literals inside a failing conditional group
2690 must still be properly ended.
2692 The comment following the @samp{#endif} is not required, but it is a
2693 good practice if there is a lot of @var{controlled text}, because it
2694 helps people match the @samp{#endif} to the corresponding @samp{#ifdef}.
2695 Older programs sometimes put @var{MACRO} directly after the
2696 @samp{#endif} without enclosing it in a comment. This is invalid code
2697 according to the C standard. GNU CPP accepts it with a warning. It
2698 never affects which @samp{#ifndef} the @samp{#endif} matches.
2701 Sometimes you wish to use some code if a macro is @emph{not} defined.
2702 You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}.
2703 One common use of @samp{#ifndef} is to include code only the first
2704 time a header file is included. @xref{Once-Only Headers}.
2706 Macro definitions can vary between compilations for several reasons.
2707 Here are some samples.
2711 Some macros are predefined on each kind of machine
2712 (@pxref{System-specific Predefined Macros}). This allows you to provide
2713 code specially tuned for a particular machine.
2716 System header files define more macros, associated with the features
2717 they implement. You can test these macros with conditionals to avoid
2718 using a system feature on a machine where it is not implemented.
2721 Macros can be defined or undefined with the @option{-D} and @option{-U}
2722 command line options when you compile the program. You can arrange to
2723 compile the same source file into two different programs by choosing a
2724 macro name to specify which program you want, writing conditionals to
2725 test whether or how this macro is defined, and then controlling the
2726 state of the macro with command line options, perhaps set in the
2727 Makefile. @xref{Invocation}.
2730 Your program might have a special header file (often called
2731 @file{config.h}) that is adjusted when the program is compiled. It can
2732 define or not define macros depending on the features of the system and
2733 the desired capabilities of the program. The adjustment can be
2734 automated by a tool such as @command{autoconf}, or done by hand.
2740 The @samp{#if} directive allows you to test the value of an arithmetic
2741 expression, rather than the mere existence of one macro. Its syntax is
2745 #if @var{expression}
2747 @var{controlled text}
2749 #endif /* @var{expression} */
2753 @var{expression} is a C expression of integer type, subject to stringent
2754 restrictions. It may contain
2761 Character constants, which are interpreted as they would be in normal
2765 Arithmetic operators for addition, subtraction, multiplication,
2766 division, bitwise operations, shifts, comparisons, and logical
2767 operations (@code{&&} and @code{||}). The latter two obey the usual
2768 short-circuiting rules of standard C@.
2771 Macros. All macros in the expression are expanded before actual
2772 computation of the expression's value begins.
2775 Uses of the @code{defined} operator, which lets you check whether macros
2776 are defined in the middle of an @samp{#if}.
2779 Identifiers that are not macros, which are all considered to be the
2780 number zero. This allows you to write @code{@w{#if MACRO}} instead of
2781 @code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will
2782 always have a nonzero value. Function-like macros used without their
2783 function call parentheses are also treated as zero.
2785 In some contexts this shortcut is undesirable. The @option{-Wundef}
2786 option causes GCC to warn whenever it encounters an identifier which is
2787 not a macro in an @samp{#if}.
2790 The preprocessor does not know anything about types in the language.
2791 Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and
2792 neither are @code{enum} constants. They will be taken as identifiers
2793 which are not macros, and replaced by zero. In the case of
2794 @code{sizeof}, this is likely to cause the expression to be invalid.
2796 The preprocessor calculates the value of @var{expression}. It carries
2797 out all calculations in the widest integer type known to the compiler;
2798 on most machines supported by GCC this is 64 bits. This is not the same
2799 rule as the compiler uses to calculate the value of a constant
2800 expression, and may give different results in some cases. If the value
2801 comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled
2802 text} is included; otherwise it is skipped.
2804 If @var{expression} is not correctly formed, GCC issues an error and
2805 treats the conditional as having failed.
2810 @cindex @code{defined}
2811 The special operator @code{defined} is used in @samp{#if} and
2812 @samp{#elif} expressions to test whether a certain name is defined as a
2813 macro. @code{defined @var{name}} and @code{defined (@var{name})} are
2814 both expressions whose value is 1 if @var{name} is defined as a macro at
2815 the current point in the program, and 0 otherwise. Thus, @code{@w{#if
2816 defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}.
2818 @code{defined} is useful when you wish to test more than one macro for
2819 existence at once. For example,
2822 #if defined (__vax__) || defined (__ns16000__)
2826 would succeed if either of the names @code{__vax__} or
2827 @code{__ns16000__} is defined as a macro.
2829 Conditionals written like this:
2832 #if defined BUFSIZE && BUFSIZE >= 1024
2836 can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}},
2837 since if @code{BUFSIZE} is not defined, it will be interpreted as having
2840 If the @code{defined} operator appears as a result of a macro expansion,
2841 the C standard says the behavior is undefined. GNU cpp treats it as a
2842 genuine @code{defined} operator and evaluates it normally. It will warn
2843 wherever your code uses this feature if you use the command-line option
2844 @option{-pedantic}, since other compilers may handle it differently.
2850 The @samp{#else} directive can be added to a conditional to provide
2851 alternative text to be used if the condition fails. This is what it
2856 #if @var{expression}
2858 #else /* Not @var{expression} */
2860 #endif /* Not @var{expression} */
2865 If @var{expression} is nonzero, the @var{text-if-true} is included and
2866 the @var{text-if-false} is skipped. If @var{expression} is zero, the
2869 You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too.
2875 One common case of nested conditionals is used to check for more than two
2876 possible alternatives. For example, you might have
2890 Another conditional directive, @samp{#elif}, allows this to be
2891 abbreviated as follows:
2898 #else /* X != 2 and X != 1*/
2900 #endif /* X != 2 and X != 1*/
2903 @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
2904 middle of a conditional group and subdivides it; it does not require a
2905 matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif}
2906 directive includes an expression to be tested. The text following the
2907 @samp{#elif} is processed only if the original @samp{#if}-condition
2908 failed and the @samp{#elif} condition succeeds.
2910 More than one @samp{#elif} can go in the same conditional group. Then
2911 the text after each @samp{#elif} is processed only if the @samp{#elif}
2912 condition succeeds after the original @samp{#if} and all previous
2913 @samp{#elif} directives within it have failed.
2915 @samp{#else} is allowed after any number of @samp{#elif} directives, but
2916 @samp{#elif} may not follow @samp{#else}.
2919 @section Deleted Code
2920 @cindex commenting out code
2922 If you replace or delete a part of the program but want to keep the old
2923 code around for future reference, you often cannot simply comment it
2924 out. Block comments do not nest, so the first comment inside the old
2925 code will end the commenting-out. The probable result is a flood of
2928 One way to avoid this problem is to use an always-false conditional
2929 instead. For instance, put @code{#if 0} before the deleted code and
2930 @code{#endif} after it. This works even if the code being turned
2931 off contains conditionals, but they must be entire conditionals
2932 (balanced @samp{#if} and @samp{#endif}).
2934 Some people use @code{#ifdef notdef} instead. This is risky, because
2935 @code{notdef} might be accidentally defined as a macro, and then the
2936 conditional would succeed. @code{#if 0} can be counted on to fail.
2938 Do not use @code{#if 0} for comments which are not C code. Use a real
2939 comment, instead. The interior of @code{#if 0} must consist of complete
2940 tokens; in particular, single-quote characters must balance. Comments
2941 often contain unbalanced single-quote characters (known in English as
2942 apostrophes). These confuse @code{#if 0}. They don't confuse
2946 @chapter Diagnostics
2948 @cindex reporting errors
2949 @cindex reporting warnings
2952 The directive @samp{#error} causes the preprocessor to report a fatal
2953 error. The tokens forming the rest of the line following @samp{#error}
2954 are used as the error message.
2956 You would use @samp{#error} inside of a conditional that detects a
2957 combination of parameters which you know the program does not properly
2958 support. For example, if you know that the program will not run
2959 properly on a VAX, you might write
2964 #error "Won't work on VAXen. See comments at get_last_object."
2969 If you have several configuration parameters that must be set up by
2970 the installation in a consistent way, you can use conditionals to detect
2971 an inconsistency and report it with @samp{#error}. For example,
2974 #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
2975 #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
2980 The directive @samp{#warning} is like @samp{#error}, but causes the
2981 preprocessor to issue a warning and continue preprocessing. The tokens
2982 following @samp{#warning} are used as the warning message.
2984 You might use @samp{#warning} in obsolete header files, with a message
2985 directing the user to the header file which should be used instead.
2987 Neither @samp{#error} nor @samp{#warning} macro-expands its argument.
2988 Internal whitespace sequences are each replaced with a single space.
2989 The line must consist of complete tokens. It is wisest to make the
2990 argument of these directives be a single string constant; this avoids
2991 problems with apostrophes and the like.
2994 @chapter Line Control
2995 @cindex line control
2997 The C preprocessor informs the C compiler of the location in your source
2998 code where each token came from. Presently, this is just the file name
2999 and line number. All the tokens resulting from macro expansion are
3000 reported as having appeared on the line of the source file where the
3001 outermost macro was used. We intend to be more accurate in the future.
3003 If you write a program which generates source code, such as the
3004 @command{bison} parser generator, you may want to adjust the preprocessor's
3005 notion of the current file name and line number by hand. Parts of the
3006 output from @command{bison} are generated from scratch, other parts come
3007 from a standard parser file. The rest are copied verbatim from
3008 @command{bison}'s input. You would like compiler error messages and
3009 symbolic debuggers to be able to refer to @code{bison}'s input file.
3012 @command{bison} or any such program can arrange this by writing
3013 @samp{#line} directives into the output file. @samp{#line} is a
3014 directive that specifies the original line number and source file name
3015 for subsequent input in the current preprocessor input file.
3016 @samp{#line} has three variants:
3019 @item #line @var{linenum}
3020 @var{linenum} is a non-negative decimal integer constant. It specifies
3021 the line number which should be reported for the following line of
3022 input. Subsequent lines are counted from @var{linenum}.
3024 @item #line @var{linenum} @var{filename}
3025 @var{linenum} is the same as for the first form, and has the same
3026 effect. In addition, @var{filename} is a string constant. The
3027 following line and all subsequent lines are reported to come from the
3028 file it specifies, until something else happens to change that.
3030 @item #line @var{anything else}
3031 @var{anything else} is checked for macro calls, which are expanded.
3032 The result should match one of the above two forms.
3035 @samp{#line} directives alter the results of the @code{__FILE__} and
3036 @code{__LINE__} predefined macros from that point on. @xref{Standard
3037 Predefined Macros}. They do not have any effect on @samp{#include}'s
3038 idea of the directory containing the current file.
3043 The @samp{#pragma} directive is the method specified by the C standard
3044 for providing additional information to the compiler, beyond what is
3045 conveyed in the language itself. Three forms of this directive
3046 (commonly known as @dfn{pragmas}) are specified by the 1999 C standard.
3047 A C compiler is free to attach any meaning it likes to other pragmas.
3049 GCC has historically preferred to use extensions to the syntax of the
3050 language, such as @code{__attribute__}, for this purpose. However, GCC
3051 does define a few pragmas of its own. These mostly have effects on the
3052 entire translation unit or source file.
3054 In GCC version 3, all GNU-defined, supported pragmas have been given a
3055 @code{GCC} prefix. This is in line with the @code{STDC} prefix on all
3056 pragmas defined by C99. For backward compatibility, pragmas which were
3057 recognized by previous versions are still recognized without the
3058 @code{GCC} prefix, but that usage is deprecated. Some older pragmas are
3059 deprecated in their entirety. They are not recognized with the
3060 @code{GCC} prefix. @xref{Obsolete Features}.
3062 @cindex @code{_Pragma}
3063 C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a
3064 major problem with @samp{#pragma}: being a directive, it cannot be
3065 produced as the result of macro expansion. @code{@w{_Pragma}} is an
3066 operator, much like @code{sizeof} or @code{defined}, and can be embedded
3069 Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where
3070 @var{string-literal} can be either a normal or wide-character string
3071 literal. It is destringized, by replacing all @samp{\\} with a single
3072 @samp{\} and all @samp{\"} with a @samp{"}. The result is then
3073 processed as if it had appeared as the right hand side of a
3074 @samp{#pragma} directive. For example,
3077 _Pragma ("GCC dependency \"parse.y\"")
3081 has the same effect as @code{#pragma GCC dependency "parse.y"}. The
3082 same effect could be achieved using macros, for example
3085 #define DO_PRAGMA(x) _Pragma (#x)
3086 DO_PRAGMA (GCC dependency "parse.y")
3089 The standard is unclear on where a @code{_Pragma} operator can appear.
3090 The preprocessor does not accept it within a preprocessing conditional
3091 directive like @samp{#if}. To be safe, you are probably best keeping it
3092 out of directives other than @samp{#define}, and putting it on a line of
3095 This manual documents the pragmas which are meaningful to the
3096 preprocessor itself. Other pragmas are meaningful to the C or C++
3097 compilers. They are documented in the GCC manual.
3100 @item #pragma GCC dependency
3101 @code{#pragma GCC dependency} allows you to check the relative dates of
3102 the current file and another file. If the other file is more recent than
3103 the current file, a warning is issued. This is useful if the current
3104 file is derived from the other file, and should be regenerated. The
3105 other file is searched for using the normal include search path.
3106 Optional trailing text can be used to give more information in the
3110 #pragma GCC dependency "parse.y"
3111 #pragma GCC dependency "/usr/include/time.h" rerun fixincludes
3114 @item #pragma GCC poison
3115 Sometimes, there is an identifier that you want to remove completely
3116 from your program, and make sure that it never creeps back in. To
3117 enforce this, you can @dfn{poison} the identifier with this pragma.
3118 @code{#pragma GCC poison} is followed by a list of identifiers to
3119 poison. If any of those identifiers appears anywhere in the source
3120 after the directive, it is a hard error. For example,
3123 #pragma GCC poison printf sprintf fprintf
3124 sprintf(some_string, "hello");
3128 will produce an error.
3130 If a poisoned identifier appears as part of the expansion of a macro
3131 which was defined before the identifier was poisoned, it will @emph{not}
3132 cause an error. This lets you poison an identifier without worrying
3133 about system headers defining macros that use it.
3138 #define strrchr rindex
3139 #pragma GCC poison rindex
3140 strrchr(some_string, 'h');
3144 will not produce an error.
3146 @item #pragma GCC system_header
3147 This pragma takes no arguments. It causes the rest of the code in the
3148 current file to be treated as if it came from a system header.
3149 @xref{System Headers}.
3153 @node Other Directives
3154 @chapter Other Directives
3157 The @samp{#ident} directive takes one argument, a string constant. On
3158 some systems, that string constant is copied into a special segment of
3159 the object file. On other systems, the directive is ignored.
3161 This directive is not part of the C standard, but it is not an official
3162 GNU extension either. We believe it came from System V@.
3165 The @samp{#sccs} directive is recognized on some systems, because it
3166 appears in their header files. It is a very old, obscure, extension
3167 which we did not invent, and we have been unable to find any
3168 documentation of what it should do, so GCC simply ignores it.
3170 @cindex null directive
3171 The @dfn{null directive} consists of a @samp{#} followed by a newline,
3172 with only whitespace (including comments) in between. A null directive
3173 is understood as a preprocessing directive but has no effect on the
3174 preprocessor output. The primary significance of the existence of the
3175 null directive is that an input line consisting of just a @samp{#} will
3176 produce no output, rather than a line of output containing just a
3177 @samp{#}. Supposedly some old C programs contain such lines.
3179 @node Preprocessor Output
3180 @chapter Preprocessor Output
3182 When the C preprocessor is used with the C, C++, or Objective-C
3183 compilers, it is integrated into the compiler and communicates a stream
3184 of binary tokens directly to the compiler's parser. However, it can
3185 also be used in the more conventional standalone mode, where it produces
3187 @c FIXME: Document the library interface.
3189 @cindex output format
3190 The output from the C preprocessor looks much like the input, except
3191 that all preprocessing directive lines have been replaced with blank
3192 lines and all comments with spaces. Long runs of blank lines are
3195 The ISO standard specifies that it is implementation defined whether a
3196 preprocessor preserves whitespace between tokens, or replaces it with
3197 e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed
3198 to become a single space, with the exception that the first token on a
3199 non-directive line is preceded with sufficient spaces that it appears in
3200 the same column in the preprocessed output that it appeared in the
3201 original source file. This is so the output is easy to read.
3202 @xref{Differences from previous versions}. CPP does not insert any
3203 whitespace where there was none in the original source, except where
3204 necessary to prevent an accidental token paste.
3207 Source file name and line number information is conveyed by lines
3211 # @var{linenum} @var{filename} @var{flags}
3215 These are called @dfn{linemarkers}. They are inserted as needed into
3216 the output (but never within a string or character constant). They mean
3217 that the following line originated in file @var{filename} at line
3220 After the file name comes zero or more flags, which are @samp{1},
3221 @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces
3222 separate them. Here is what the flags mean:
3226 This indicates the start of a new file.
3228 This indicates returning to a file (after having included another file).
3230 This indicates that the following text comes from a system header file,
3231 so certain warnings should be suppressed.
3233 This indicates that the following text should be treated as being
3234 wrapped in an implicit @code{extern "C"} block.
3235 @c maybe cross reference NO_IMPLICIT_EXTERN_C
3238 As an extension, the preprocessor accepts linemarkers in non-assembler
3239 input files. They are treated like the corresponding @samp{#line}
3240 directive, (@pxref{Line Control}), except that trailing flags are
3241 permitted, and are interpreted with the meanings described above. If
3242 multiple flags are given, they must be in ascending order.
3244 Some directives may be duplicated in the output of the preprocessor.
3245 These are @samp{#ident} (always), @samp{#pragma} (only if the
3246 preprocessor does not handle the pragma itself), and @samp{#define} and
3247 @samp{#undef} (with certain debugging options). If this happens, the
3248 @samp{#} of the directive will always be in the first column, and there
3249 will be no space between the @samp{#} and the directive name. If macro
3250 expansion happens to generate tokens which might be mistaken for a
3251 duplicated directive, a space will be inserted between the @samp{#} and
3254 @node Traditional Mode
3255 @chapter Traditional Mode
3257 Traditional (pre-standard) C preprocessing is rather different from
3258 the preprocessing specified by the standard. When GCC is given the
3259 @option{-traditional} option, it attempts to emulate a traditional
3260 preprocessor. We do not guarantee that GCC's behavior under
3261 @option{-traditional} matches any pre-standard preprocessor exactly.
3263 Traditional mode exists only for backward compatibility. We have no
3264 plans to augment it in any way nor will we change it except to fix
3265 catastrophic bugs. You should be aware that modern C libraries often
3266 have header files which are incompatible with traditional mode.
3268 This is a list of the differences. It may not be complete, and may not
3269 correspond exactly to the behavior of either GCC or a true traditional
3274 Traditional macro expansion pays no attention to single-quote or
3275 double-quote characters; macro argument symbols are replaced by the
3276 argument values even when they appear within apparent string or
3277 character constants.
3280 Traditionally, it is permissible for a macro expansion to end in the
3281 middle of a string or character constant. The constant continues into
3282 the text surrounding the macro call.
3285 However, the end of the line terminates a string or character constant,
3286 with no error. (This is a kluge. Traditional mode is commonly used to
3287 preprocess things which are not C, and have a different comment syntax.
3288 Single apostrophes often appear in comments. This kluge prevents the
3289 traditional preprocessor from issuing errors on such comments.)
3292 Preprocessing directives are recognized in traditional C only when their
3293 leading @samp{#} appears in the first column. There can be no
3294 whitespace between the beginning of the line and the @samp{#}.
3297 In traditional C, a comment is equivalent to no text at all. (In ISO
3298 C, a comment counts as whitespace.) It can be used sort of the same way
3299 that @samp{##} is used in ISO C, to paste macro arguments together.
3302 Traditional C does not have the concept of a preprocessing number.
3305 A macro is not suppressed within its own definition, in traditional C@.
3306 Thus, any macro that is used recursively inevitably causes an error.
3309 The @samp{#} and @samp{##} operators are not available in traditional
3313 In traditional C, the text at the end of a macro expansion can run
3314 together with the text after the macro call, to produce a single token.
3315 This is impossible in ISO C@.
3318 None of the GNU extensions to the preprocessor are available in
3319 traditional mode, with the exception of a partial implementation of
3320 assertions, and those may be removed in the future.
3323 A true traditional C preprocessor does not recognize @samp{#elif},
3324 @samp{#error}, or @samp{#pragma}. GCC supports @samp{#elif} and
3325 @samp{#error} even in traditional mode, but not @samp{#pragma}.
3328 Traditional mode is text-based, not token-based, and comments are
3329 stripped after macro expansion. Therefore, @samp{/**/} can be used to
3330 paste tokens together provided that there is no whitespace between it
3331 and the tokens to be pasted.
3334 Traditional mode preserves the amount and form of whitespace provided by
3335 the user. Hard tabs remain hard tabs. This can be useful, e.g.@: if you
3336 are preprocessing a Makefile (which we do not encourage).
3339 You can request warnings about features that did not exist, or worked
3340 differently, in traditional C with the @option{-Wtraditional} option.
3341 This works only if you do @emph{not} specify @option{-traditional}. GCC
3342 does not warn about features of ISO C which you must use when you are
3343 using a conforming compiler, such as the @samp{#} and @samp{##}
3346 Presently @option{-Wtraditional} warns about:
3350 Macro parameters that appear within string literals in the macro body.
3351 In traditional C macro replacement takes place within string literals,
3352 but does not in ISO C@.
3355 In traditional C, some preprocessor directives did not exist.
3356 Traditional preprocessors would only consider a line to be a directive
3357 if the @samp{#} appeared in column 1 on the line. Therefore
3358 @option{-Wtraditional} warns about directives that traditional C
3359 understands but would ignore because the @samp{#} does not appear as the
3360 first character on the line. It also suggests you hide directives like
3361 @samp{#pragma} not understood by traditional C by indenting them. Some
3362 traditional implementations would not recognize @samp{#elif}, so it
3363 suggests avoiding it altogether.
3366 A function-like macro that appears without an argument list. In
3367 traditional C this was an error. In ISO C it merely means that the
3368 macro is not expanded.
3371 The unary plus operator. This did not exist in traditional C@.
3374 The @samp{U} and @samp{LL} integer constant suffixes, which were not
3375 available in traditional C@. (Traditional C does support the @samp{L}
3376 suffix for simple long integer constants.) You are not warned about
3377 uses of these suffixes in macros defined in system headers. For
3378 instance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but
3379 you will not be warned if you use @code{UINT_MAX}.
3381 You can usually avoid the warning, and the related warning about
3382 constants which are so large that they are unsigned, by writing the
3383 integer constant in question in hexadecimal, with no U suffix. Take
3384 care, though, because this gives the wrong result in exotic cases.
3387 @node Implementation Details
3388 @chapter Implementation Details
3390 Here we document details of how the preprocessor's implementation
3391 affects its user-visible behavior. You should try to avoid undue
3392 reliance on behavior described here, as it is possible that it will
3393 change subtly in future implementations.
3395 Also documented here are obsolete features and changes from previous
3396 versions of GNU CPP@.
3399 * Implementation-defined behavior::
3400 * Implementation limits::
3401 * Obsolete Features::
3402 * Differences from previous versions::
3405 @node Implementation-defined behavior
3406 @section Implementation-defined behavior
3407 @cindex implementation-defined behavior
3409 This is how GNU CPP behaves in all the cases which the C standard
3410 describes as @dfn{implementation-defined}. This term means that the
3411 implementation is free to do what it likes, but must document its choice
3413 @c FIXME: Check the C++ standard for more implementation-defined stuff.
3417 @item The mapping of physical source file multi-byte characters to the
3418 execution character set.
3420 Currently, GNU cpp only supports character sets that are strict supersets
3421 of ASCII, and performs no translation of characters.
3423 @item Non-empty sequences of whitespace characters.
3425 In textual output, each whitespace sequence is collapsed to a single
3426 space. For aesthetic reasons, the first token on each non-directive
3427 line of output is preceded with sufficient spaces that it appears in the
3428 same column as it did in the original source file.
3430 @item The numeric value of character constants in preprocessor expressions.
3432 The preprocessor and compiler interpret character constants in the same
3433 way; escape sequences such as @samp{\a} are given the values they would
3434 have on the target machine.
3436 Multi-character character constants are interpreted a character at a
3437 time, shifting the previous result left by the number of bits per
3438 character on the host, and adding the new character. For example, 'ab'
3439 on an 8-bit host would be interpreted as @w{'a' * 256 + 'b'}. If there
3440 are more characters in the constant than can fit in the widest native
3441 integer type on the host, usually a @code{long}, the excess characters
3442 are ignored and a diagnostic is given.
3444 @item Source file inclusion.
3446 For a discussion on how the preprocessor locates header files,
3447 @ref{Include Operation}.
3449 @item Interpretation of the filename resulting from a macro-expanded
3450 @samp{#include} directive.
3452 @xref{Computed Includes}.
3454 @item Treatment of a @samp{#pragma} directive that after macro-expansion
3455 results in a standard pragma.
3457 No macro expansion occurs on any @samp{#pragma} directive line, so the
3458 question does not arise.
3460 Note that GCC does not yet implement any of the standard
3465 @node Implementation limits
3466 @section Implementation limits
3467 @cindex implementation limits
3469 GNU CPP has a small number of internal limits. This section lists the
3470 limits which the C standard requires to be no lower than some minimum,
3471 and all the others we are aware of. We intend there to be as few limits
3472 as possible. If you encounter an undocumented or inconvenient limit,
3473 please report that to us as a bug. (See the section on reporting bugs in
3476 Where we say something is limited @dfn{only by available memory}, that
3477 means that internal data structures impose no intrinsic limit, and space
3478 is allocated with @code{malloc} or equivalent. The actual limit will
3479 therefore depend on many things, such as the size of other things
3480 allocated by the compiler at the same time, the amount of memory
3481 consumed by other processes on the same computer, etc.
3485 @item Nesting levels of @samp{#include} files.
3487 We impose an arbitrary limit of 200 levels, to avoid runaway recursion.
3488 The standard requires at least 15 levels.
3490 @item Nesting levels of conditional inclusion.
3492 The C standard mandates this be at least 63. GNU CPP is limited only by
3495 @item Levels of parenthesised expressions within a full expression.
3497 The C standard requires this to be at least 63. In preprocessor
3498 conditional expressions, it is limited only by available memory.
3500 @item Significant initial characters in an identifier or macro name.
3502 The preprocessor treats all characters as significant. The C standard
3503 requires only that the first 63 be significant.
3505 @item Number of macros simultaneously defined in a single translation unit.
3507 The standard requires at least 4095 be possible. GNU CPP is limited only
3508 by available memory.
3510 @item Number of parameters in a macro definition and arguments in a macro call.
3512 We allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum
3513 required by the standard is 127.
3515 @item Number of characters on a logical source line.
3517 The C standard requires a minimum of 4096 be permitted. GNU CPP places
3518 no limits on this, but you may get incorrect column numbers reported in
3519 diagnostics for lines longer than 65,535 characters.
3521 @item Maximum size of a source file.
3523 The standard does not specify any lower limit on the maximum size of a
3524 source file. GNU cpp maps files into memory, so it is limited by the
3525 available address space. This is generally at least two gigabytes.
3526 Depending on the operating system, the size of physical memory may or
3527 may not be a limitation.
3531 @node Obsolete Features
3532 @section Obsolete Features
3534 GNU CPP has a number of features which are present mainly for
3535 compatibility with older programs. We discourage their use in new code.
3536 In some cases, we plan to remove the feature in a future version of GCC@.
3540 * Obsolete once-only headers::
3541 * Miscellaneous obsolete features::
3545 @subsection Assertions
3548 @dfn{Assertions} are a deprecated alternative to macros in writing
3549 conditionals to test what sort of computer or system the compiled
3550 program will run on. Assertions are usually predefined, but you can
3551 define them with preprocessing directives or command-line options.
3553 Assertions were intended to provide a more systematic way to describe
3554 the compiler's target system. However, in practice they are just as
3555 unpredictable as the system-specific predefined macros. In addition, they
3556 are not part of any standard, and only a few compilers support them.
3557 Therefore, the use of assertions is @strong{less} portable than the use
3558 of system-specific predefined macros. We recommend you do not use them at
3562 An assertion looks like this:
3565 #@var{predicate} (@var{answer})
3569 @var{predicate} must be a single identifier. @var{answer} can be any
3570 sequence of tokens; all characters are significant except for leading
3571 and trailing whitespace, and differences in internal whitespace
3572 sequences are ignored. (This is similar to the rules governing macro
3573 redefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but
3574 equivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an
3577 @cindex testing predicates
3578 To test an assertion, you write it in an @samp{#if}. For example, this
3579 conditional succeeds if either @code{vax} or @code{ns16000} has been
3580 asserted as an answer for @code{machine}.
3583 #if #machine (vax) || #machine (ns16000)
3587 You can test whether @emph{any} answer is asserted for a predicate by
3588 omitting the answer in the conditional:
3595 Assertions are made with the @samp{#assert} directive. Its sole
3596 argument is the assertion to make, without the leading @samp{#} that
3597 identifies assertions in conditionals.
3600 #assert @var{predicate} (@var{answer})
3604 You may make several assertions with the same predicate and different
3605 answers. Subsequent assertions do not override previous ones for the
3606 same predicate. All the answers for any given predicate are
3607 simultaneously true.
3609 @cindex assertions, cancelling
3611 Assertions can be cancelled with the @samp{#unassert} directive. It
3612 has the same syntax as @samp{#assert}. In that form it cancels only the
3613 answer which was specified on the @samp{#unassert} line; other answers
3614 for that predicate remain true. You can cancel an entire predicate by
3615 leaving out the answer:
3618 #unassert @var{predicate}
3622 In either form, if no such assertion has been made, @samp{#unassert} has
3625 You can also make or cancel assertions using command line options.
3628 @node Obsolete once-only headers
3629 @subsection Obsolete once-only headers
3631 GNU CPP supports two more ways of indicating that a header file should be
3632 read only once. Neither one is as portable as a wrapper @samp{#ifndef},
3633 and we recommend you do not use them in new programs.
3636 In the Objective-C language, there is a variant of @samp{#include}
3637 called @samp{#import} which includes a file, but does so at most once.
3638 If you use @samp{#import} instead of @samp{#include}, then you don't
3639 need the conditionals inside the header file to prevent multiple
3640 inclusion of the contents. GCC permits the use of @samp{#import} in C
3641 and C++ as well as Objective-C@. However, it is not in standard C or C++
3642 and should therefore not be used by portable programs.
3644 @samp{#import} is not a well designed feature. It requires the users of
3645 a header file to know that it should only be included once. It is much
3646 better for the header file's implementor to write the file so that users
3647 don't need to know this. Using a wrapper @samp{#ifndef} accomplishes
3650 In the present implementation, a single use of @samp{#import} will
3651 prevent the file from ever being read again, by either @samp{#import} or
3652 @samp{#include}. You should not rely on this; do not use both
3653 @samp{#import} and @samp{#include} to refer to the same header file.
3655 Another way to prevent a header file from being included more than once
3656 is with the @samp{#pragma once} directive. If @samp{#pragma once} is
3657 seen when scanning a header file, that file will never be read again, no
3660 @samp{#pragma once} does not have the problems that @samp{#import} does,
3661 but it is not recognized by all preprocessors, so you cannot rely on it
3662 in a portable program.
3664 @node Miscellaneous obsolete features
3665 @subsection Miscellaneous obsolete features
3667 Here are a few more obsolete features.
3670 @cindex invalid token paste
3671 @item Attempting to paste two tokens which together do not form a valid
3672 preprocessing token.
3674 The preprocessor currently warns about this and outputs the two tokens
3675 adjacently, which is probably the behavior the programmer intends. It
3676 may not work in future, though.
3678 Most of the time, when you get this warning, you will find that @samp{##}
3679 is being used superstitiously, to guard against whitespace appearing
3680 between two tokens. It is almost always safe to delete the @samp{##}.
3682 @cindex pragma poison
3683 @item @code{#pragma poison}
3685 This is the same as @code{#pragma GCC poison}. The version without the
3686 @code{GCC} prefix is deprecated. @xref{Pragmas}.
3688 @cindex multi-line string constants
3689 @item Multi-line string constants
3691 GCC currently allows a string constant to extend across multiple logical
3692 lines of the source file. This extension is deprecated and will be
3693 removed in a future version of GCC@. Such string constants are already
3694 rejected in all directives apart from @samp{#define}.
3696 Instead, make use of ISO C concatenation of adjacent string literals, or
3697 use @samp{\n} followed by a backslash-newline.
3701 @node Differences from previous versions
3702 @section Differences from previous versions
3703 @cindex differences from previous versions
3705 This section details behavior which has changed from previous versions
3706 of GNU CPP@. We do not plan to change it again in the near future, but
3707 we do not promise not to, either.
3709 The ``previous versions'' discussed here are 2.95 and before. The
3710 behavior of GCC 3.0 is mostly the same as the behavior of the widely
3711 used 2.96 and 2.97 development snapshots. Where there are differences,
3712 they generally represent bugs in the snapshots.
3716 @item Order of evaluation of @samp{#} and @samp{##} operators
3718 The standard does not specify the order of evaluation of a chain of
3719 @samp{##} operators, nor whether @samp{#} is evaluated before, after, or
3720 at the same time as @samp{##}. You should therefore not write any code
3721 which depends on any specific ordering. It is possible to guarantee an
3722 ordering, if you need one, by suitable use of nested macros.
3724 An example of where this might matter is pasting the arguments @samp{1},
3725 @samp{e} and @samp{-2}. This would be fine for left-to-right pasting,
3726 but right-to-left pasting would produce an invalid token @samp{e-2}.
3728 GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly
3729 left to right. Older versions evaluated all @samp{#} operators first,
3730 then all @samp{##} operators, in an unreliable order.
3732 @item The form of whitespace betwen tokens in preprocessor output
3734 @xref{Preprocessor Output}, for the current textual format. This is
3735 also the format used by stringification. Normally, the preprocessor
3736 communicates tokens directly to the compiler's parser, and whitespace
3737 does not come up at all.
3739 Older versions of GCC preserved all whitespace provided by the user and
3740 inserted lots more whitespace of their own, because they could not
3741 accurately predict when extra spaces were needed to prevent accidental
3744 @item Optional argument when invoking rest argument macros
3746 As an extension, GCC permits you to omit the variable arguments entirely
3747 when you use a variable argument macro. This is forbidden by the 1999 C
3748 standard, and will provoke a pedantic warning with GCC 3.0. Previous
3749 versions accepted it silently.
3751 @item @samp{##} swallowing preceding text in rest argument macros
3753 Formerly, in a macro expansion, if @samp{##} appeared before a variable
3754 arguments parameter, and the set of tokens specified for that argument
3755 in the macro invocation was empty, previous versions of GNU CPP would
3756 back up and remove the preceding sequence of non-whitespace characters
3757 (@strong{not} the preceding token). This extension is in direct
3758 conflict with the 1999 C standard and has been drastically pared back.
3760 In the current version of the preprocessor, if @samp{##} appears between
3761 a comma and a variable arguments parameter, and the variable argument is
3762 omitted entirely, the comma will be removed from the expansion. If the
3763 variable argument is empty, or the token before @samp{##} is not a
3764 comma, then @samp{##} behaves as a normal token paste.
3766 @item Traditional mode and GNU extensions
3768 Traditional mode used to be implemented in the same program as normal
3769 preprocessing. Therefore, all the GNU extensions to the preprocessor
3770 were still available in traditional mode. It is now a separate program
3771 and does not implement any of the GNU extensions, except for a partial
3772 implementation of assertions. Even those may be removed in a future
3779 @cindex command line
3781 Most often when you use the C preprocessor you will not have to invoke it
3782 explicitly: the C compiler will do so automatically. However, the
3783 preprocessor is sometimes useful on its own. All the options listed
3784 here are also acceptable to the C compiler and have the same meaning,
3785 except that the C compiler has different rules for specifying the output
3788 @strong{Note:} Whether you use the preprocessor by way of @command{gcc}
3789 or @command{cpp}, the @dfn{compiler driver} is run first. This
3790 program's purpose is to translate your command into invocations of the
3791 programs that do the actual work. Their command line interfaces are
3792 similar but not identical to the documented interface, and may change
3796 @c man begin SYNOPSIS
3797 cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
3798 [@option{-I}@var{dir}@dots{}] [@option{-W}@var{warn}@dots{}]
3799 [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
3800 [@option{-MP}] [@option{-MQ} @var{target}@dots{}] [@option{-MT} @var{target}@dots{}]
3801 [@option{-x} @var{language}] [@option{-std=}@var{standard}]
3802 @var{infile} @var{outfile}
3804 Only the most useful options are listed here; see below for the remainder.
3806 @c man begin SEEALSO
3807 gpl(7), gfdl(7), fsf-funding(7),
3808 gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
3813 @c man begin OPTIONS
3814 The C preprocessor expects two file names as arguments, @var{infile} and
3815 @var{outfile}. The preprocessor reads @var{infile} together with any
3816 other files it specifies with @samp{#include}. All the output generated
3817 by the combined input files is written in @var{outfile}.
3819 Either @var{infile} or @var{outfile} may be @option{-}, which as
3820 @var{infile} means to read from standard input and as @var{outfile}
3821 means to write to standard output. Also, if either file is omitted, it
3822 means the same as if @option{-} had been specified for that file.
3824 Unless otherwise noted, or the option ends in @samp{=}, all options
3825 which take an argument may have that argument appear either immediately
3826 after the option, or with a space between option and argument:
3827 @option{-Ifoo} and @option{-I foo} have the same effect.
3829 @cindex grouping options
3830 @cindex options, grouping
3831 Many options have multi-letter names; therefore multiple single-letter
3832 options may @emph{not} be grouped: @option{-dM} is very different from
3838 Predefine @var{name} as a macro, with definition @code{1}.
3840 @item -D @var{name}=@var{definition}
3841 Predefine @var{name} as a macro, with definition @var{definition}.
3842 There are no restrictions on the contents of @var{definition}, but if
3843 you are invoking the preprocessor from a shell or shell-like program you
3844 may need to use the shell's quoting syntax to protect characters such as
3845 spaces that have a meaning in the shell syntax. If you use more than
3846 one @option{-D} for the same @var{name}, the rightmost definition takes
3849 If you wish to define a function-like macro on the command line, write
3850 its argument list with surrounding parentheses before the equals sign
3851 (if any). Parentheses are meaningful to most shells, so you will need
3852 to quote the option. With @command{sh} and @command{csh},
3853 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
3856 Cancel any previous definition of @var{name}, either built in or
3857 provided with a @option{-D} option.
3859 All @option{-imacros @var{file}} and @option{-include @var{file}} options
3860 are processed after all @option{-D} and @option{-U} options.
3863 Do not predefine any system-specific macros. The common predefined
3864 macros remain defined.
3867 Add the directory @var{dir} to the list of directories to be searched
3868 for header files. @xref{Search Path}. Directories named by @option{-I}
3869 are searched before the standard system include directories.
3871 It is dangerous to specify a standard system include directory in an
3872 @option{-I} option. This defeats the special treatment of system
3873 headers (@pxref{System Headers}). It can also defeat the repairs to
3874 buggy system headers which GCC makes when it is installed.
3877 Write output to @var{file}. This is the same as specifying @var{file}
3878 as the second non-option argument to @command{cpp}. @command{gcc} has a
3879 different interpretation of a second non-option argument, so you must
3880 use @option{-o} to specify the output file.
3883 Turns on all optional warnings which are desirable for normal code. At
3884 present this is @option{-Wcomment} and @option{-Wtrigraphs}. Note that
3885 many of the preprocessor's warnings are on by default and have no
3886 options to control them.
3890 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
3891 comment, or whenever a backslash-newline appears in a @samp{//} comment.
3892 (Both forms have the same effect.)
3895 Warn if any trigraphs are encountered. This option used to take effect
3896 only if @option{-trigraphs} was also specified, but now works
3897 independently. Warnings are not given for trigraphs within comments, as
3898 they do not affect the meaning of the program.
3901 Warn about certain constructs that behave differently in traditional and
3902 ISO C@. Also warn about ISO C constructs that have no traditional C
3903 equivalent, and problematic constructs which should be avoided.
3904 @xref{Traditional Mode}.
3907 Warn the first time @samp{#import} is used.
3910 Warn whenever an identifier which is not a macro is encountered in an
3911 @samp{#if} directive, outside of @samp{defined}. Such identifiers are
3915 Make all warnings into hard errors. Source code which triggers warnings
3918 @item -Wsystem-headers
3919 Issue warnings for code in system headers. These are normally unhelpful
3920 in finding bugs in your own code, therefore suppressed. If you are
3921 responsible for the system library, you may want to see them.
3924 Suppress all warnings, including those which GNU CPP issues by default.
3927 Issue all the mandatory diagnostics listed in the C standard. Some of
3928 them are left out by default, since they trigger frequently on harmless
3931 @item -pedantic-errors
3932 Issue all the mandatory diagnostics, and make all mandatory diagnostics
3933 into errors. This includes mandatory diagnostics that GCC issues
3934 without @samp{-pedantic} but treats as warnings.
3937 Instead of outputting the result of preprocessing, output a rule
3938 suitable for @command{make} describing the dependencies of the main
3939 source file. The preprocessor outputs one @command{make} rule containing
3940 the object file name for that source file, a colon, and the names of all
3941 the included files, including those coming from @option{-include} or
3942 @option{-imacros} command line options.
3944 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
3945 object file name consists of the basename of the source file with any
3946 suffix replaced with object file suffix. If there are many included
3947 files then the rule is split into several lines using @samp{\}-newline.
3948 The rule has no commands.
3951 Like @option{-M}, but mention only the files included with @code{@w{#include
3952 "@var{file}"}} or with @option{-include} or @option{-imacros} command line
3953 options. System header files included with @code{@w{#include <@var{file}>}}
3956 @item -MF @var{file}
3957 When used with @option{-M} or @option{-MM}, specifies a file to write the
3958 dependencies to. This allows the preprocessor to write the preprocessed
3959 file to stdout normally. If no @option{-MF} switch is given, CPP sends
3960 the rules to stdout and suppresses normal preprocessed output.
3963 When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
3964 header files as generated files and assume they live in the same
3965 directory as the source file. It suppresses preprocessed output, as a
3966 missing header file is ordinarily an error.
3968 This feature is used in automatic updating of makefiles.
3971 This option instructs CPP to add a phony target for each dependency
3972 other than the main file, causing each to depend on nothing. These
3973 dummy rules work around errors @command{make} gives if you remove header
3974 files without updating the @file{Makefile} to match.
3976 This is typical output:
3979 test.o: test.c test.h
3984 @item -MT @var{target}
3986 Change the target of the rule emitted by dependency generation. By
3987 default CPP takes the name of the main input file, including any path,
3988 deletes any file suffix such as @samp{.c}, and appends the platform's
3989 usual object suffix. The result is the target.
3991 An @option{-MT} option will set the target to be exactly the string you
3992 specify. If you want multiple targets, you can specify them as a single
3993 argument to @option{-MT}, or use multiple @option{-MT} options.
3995 For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
3998 $(objpfx)foo.o: foo.c
4001 @item -MQ @var{target}
4003 Same as @option{-MT}, but it quotes any characters which are special to
4004 Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
4007 $$(objpfx)foo.o: foo.c
4010 The default target is automatically quoted, as if it were given with
4013 @item -MD @var{file}
4014 @itemx -MMD @var{file}
4015 @option{-MD @var{file}} is equivalent to @option{-M -MF @var{file}}, and
4016 @option{-MMD @var{file}} is equivalent to @option{-MM -MF @var{file}}.
4018 Due to limitations in the compiler driver, you must use these switches
4019 when you want to generate a dependency file as a side-effect of normal
4024 @itemx -x objective-c
4025 @itemx -x assembler-with-cpp
4026 Specify the source language: C, C++, Objective-C, or assembly. This has
4027 nothing to do with standards conformance or extensions; it merely
4028 selects which base syntax to expect. If you give none of these options,
4029 cpp will deduce the language from the extension of the source file:
4030 @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common
4031 extensions for C++ and assembly are also recognized. If cpp does not
4032 recognize the extension, it will treat the file as C; this is the most
4035 @strong{Note:} Previous versions of cpp accepted a @option{-lang} option
4036 which selected both the language and the standards conformance level.
4037 This option has been removed, because it conflicts with the @option{-l}
4040 @item -std=@var{standard}
4042 Specify the standard to which the code should conform. Currently cpp
4043 only knows about the standards for C; other language standards will be
4044 added in the future.
4051 The ISO C standard from 1990. @samp{c89} is the customary shorthand for
4052 this version of the standard.
4054 The @option{-ansi} option is equivalent to @option{-std=c89}.
4056 @item iso9899:199409
4057 The 1990 C standard, as amended in 1994.
4063 The revised ISO C standard, published in December 1999. Before
4064 publication, this was known as C9X@.
4067 The 1990 C standard plus GNU extensions. This is the default.
4071 The 1999 C standard plus GNU extensions.
4075 Split the include path. Any directories specified with @option{-I}
4076 options before @option{-I-} are searched only for headers requested with
4077 @code{@w{#include "@var{file}"}}; they are not searched for
4078 @code{@w{#include <@var{file}>}}. If additional directories are
4079 specified with @option{-I} options after the @option{-I-}, those
4080 directories are searched for all @samp{#include} directives.
4082 In addition, @option{-I-} inhibits the use of the directory of the current
4083 file directory as the first search directory for @code{@w{#include
4084 "@var{file}"}}. @xref{Search Path}.
4087 Do not search the standard system directories for header files.
4088 Only the directories you have specified with @option{-I} options
4089 (and the directory of the current file, if appropriate) are searched.
4092 Do not search for header files in the C++-specific standard directories,
4093 but do still search the other standard directories. (This option is
4094 used when building the C++ library.)
4096 @item -include @var{file}
4098 Process @var{file} as if @code{#include "file"} appeared as the first
4099 line of the primary source file. However, the first directory searched
4100 for @var{file} is the preprocessor's working directory @emph{instead of}
4101 the directory containing the main source file. If not found there, it
4102 is searched for in the remainder of the @code{#include "@dots{}"} search
4105 If multiple @option{-include} options are given, the files are included
4106 in the order they appear on the command line.
4108 @item -imacros @var{file}
4110 Exactly like @option{-include}, except that any output produced by
4111 scanning @var{file} is thrown away. Macros it defines remain defined.
4112 This allows you to acquire all the macros from a header without also
4113 processing its declarations.
4115 All files specified by @option{-imacros} are processed before all files
4116 specified by @option{-include}.
4118 @item -idirafter @var{dir}
4119 Search @var{dir} for header files, but do it @emph{after} all
4120 directories specified with @option{-I} and the standard system directories
4121 have been exhausted. @var{dir} is treated as a system include directory.
4123 @item -iprefix @var{prefix}
4124 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
4125 options. If the prefix represents a directory, you should include the
4128 @item -iwithprefix @var{dir}
4129 @itemx -iwithprefixbefore @var{dir}
4131 Append @var{dir} to the prefix specified previously with
4132 @option{-iprefix}, and add the resulting directory to the include search
4133 path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
4134 would; @option{-iwithprefix} puts it where @option{-idirafter} would.
4136 Use of these options is discouraged.
4138 @item -isystem @var{dir}
4139 Search @var{dir} for header files, after all directories specified by
4140 @option{-I} but before the standard system directories. Mark it
4141 as a system directory, so that it gets the same special treatment as
4142 is applied to the standard system directories. @xref{System Headers}.
4144 @item -fpreprocessed
4145 Indicate to the preprocessor that the input file has already been
4146 preprocessed. This suppresses things like macro expansion, trigraph
4147 conversion, escaped newline splicing, and processing of most directives.
4148 The preprocessor still recognizes and removes comments, so that you can
4149 pass a file preprocessed with @option{-C} to the compiler without
4150 problems. In this mode the integrated preprocessor is little more than
4151 a tokenizer for the front ends.
4153 @option{-fpreprocessed} is implicit if the input file has one of the
4154 extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
4155 extensions that GCC uses for preprocessed files created by
4156 @option{-save-temps}.
4158 @item -ftabstop=@var{width}
4159 Set the distance between tab stops. This helps the preprocessor report
4160 correct column numbers in warnings or errors, even if tabs appear on the
4161 line. If the value is less than 1 or greater than 100, the option is
4162 ignored. The default is 8.
4164 @item -fno-show-column
4165 Do not print column numbers in diagnostics. This may be necessary if
4166 diagnostics are being scanned by a program that does not understand the
4167 column numbers, such as @command{dejagnu}.
4169 @item -A @var{predicate}=@var{answer}
4170 Make an assertion with the predicate @var{predicate} and answer
4171 @var{answer}. This form is preferred to the older form @option{-A
4172 @var{predicate}(@var{answer})}, which is still supported, because
4173 it does not use shell special characters. @xref{Assertions}.
4175 @item -A -@var{predicate}=@var{answer}
4176 Cancel an assertion with the predicate @var{predicate} and answer
4180 Cancel all predefined assertions and all assertions preceding it on
4181 the command line. Also, undefine all predefined macros and all
4182 macros preceding it on the command line. (This is a historical wart and
4183 may change in the future.)
4186 @var{CHARS} is a sequence of one or more of the following characters,
4187 and must not be preceded by a space. Other characters are interpreted
4188 by the compiler proper, or reserved for future versions of GCC, and so
4189 are silently ignored. If you specify characters whose behavior
4190 conflicts, the result is undefined.
4194 Instead of the normal output, generate a list of @samp{#define}
4195 directives for all the macros defined during the execution of the
4196 preprocessor, including predefined macros. This gives you a way of
4197 finding out what is predefined in your version of the preprocessor.
4198 Assuming you have no file @file{foo.h}, the command
4201 touch foo.h; cpp -dM foo.h
4205 will show all the predefined macros.
4208 Like @samp{M} except in two respects: it does @emph{not} include the
4209 predefined macros, and it outputs @emph{both} the @samp{#define}
4210 directives and the result of preprocessing. Both kinds of output go to
4211 the standard output file.
4214 Like @samp{D}, but emit only the macro names, not their expansions.
4217 Output @samp{#include} directives in addition to the result of
4222 Inhibit generation of linemarkers in the output from the preprocessor.
4223 This might be useful when running the preprocessor on something that is
4224 not C code, and will be sent to a program which might be confused by the
4225 linemarkers. @xref{Preprocessor Output}.
4228 Do not discard comments. All comments are passed through to the output
4229 file, except for comments in processed directives, which are deleted
4230 along with the directive.
4232 You should be prepared for side effects when using @option{-C}; it
4233 causes the preprocessor to treat comments as tokens in their own right.
4234 For example, comments appearing at the start of what would be a
4235 directive line have the effect of turning that line into an ordinary
4236 source line, since the first token on the line is no longer a @samp{#}.
4239 Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and
4240 @sc{__gnuc_patchlevel__}. These are defined automatically when you use
4241 @command{gcc -E}; you can turn them off in that case with
4245 Try to imitate the behavior of old-fashioned C, as opposed to ISO
4246 C@. @xref{Traditional Mode}.
4249 Process trigraph sequences. @xref{Initial processing}.
4252 Enable special code to work around file systems which only permit very
4253 short file names, such as MS-DOS@.
4256 Forbid the use of @samp{$} in identifiers. The C standard allows
4257 implementations to define extra characters that can appear in
4258 identifiers. By default GNU CPP permits @samp{$}, a common extension.
4262 @itemx --target-help
4263 Print text describing all the command line options instead of
4264 preprocessing anything.
4267 Verbose mode. Print out GNU CPP's version number at the beginning of
4268 execution, and report the final form of the include path.
4271 Print the name of each header file used, in addition to other normal
4272 activities. Each name is indented to show how deep in the
4273 @samp{#include} stack it is.
4277 Print out GNU CPP's version number. With one dash, proceed to
4278 preprocess as normal. With two dashes, exit immediately.
4285 @node Index of Directives
4286 @unnumbered Index of Directives
4290 @unnumbered Concept Index