1 This is Info file cpp.info, produced by Makeinfo version 1.67 from the
4 This file documents the GNU C Preprocessor.
6 Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
9 Permission is granted to make and distribute verbatim copies of this
10 manual provided the copyright notice and this permission notice are
11 preserved on all copies.
13 Permission is granted to copy and distribute modified versions of
14 this manual under the conditions for verbatim copying, provided also
15 that the entire resulting derived work is distributed under the terms
16 of a permission notice identical to this one.
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
23 File: cpp.info, Node: Top, Next: Global Actions, Up: (DIR)
28 The C preprocessor is a "macro processor" that is used automatically
29 by the C compiler to transform your program before actual compilation.
30 It is called a macro processor because it allows you to define "macros",
31 which are brief abbreviations for longer constructs.
33 The C preprocessor provides four separate facilities that you can
36 * Inclusion of header files. These are files of declarations that
37 can be substituted into your program.
39 * Macro expansion. You can define "macros", which are abbreviations
40 for arbitrary fragments of C code, and then the C preprocessor will
41 replace the macros with their definitions throughout the program.
43 * Conditional compilation. Using special preprocessing directives,
44 you can include or exclude parts of the program according to
47 * Line control. If you use a program to combine or rearrange source
48 files into an intermediate file which is then compiled, you can
49 use line control to inform the compiler of where each source line
52 C preprocessors vary in some details. This manual discusses the GNU
53 C preprocessor, the C Compatible Compiler Preprocessor. The GNU C
54 preprocessor provides a superset of the features of ANSI Standard C.
56 ANSI Standard C requires the rejection of many harmless constructs
57 commonly used by today's C programs. Such incompatibility would be
58 inconvenient for users, so the GNU C preprocessor is configured to
59 accept these constructs by default. Strictly speaking, to get ANSI
60 Standard C, you must use the options `-trigraphs', `-undef' and
61 `-pedantic', but in practice the consequences of having strict ANSI
62 Standard C make it undesirable to do this. *Note Invocation::.
66 * Global Actions:: Actions made uniformly on all input files.
67 * Directives:: General syntax of preprocessing directives.
68 * Header Files:: How and why to use header files.
69 * Macros:: How and why to use macros.
70 * Conditionals:: How and why to use conditionals.
71 * Combining Sources:: Use of line control when you combine source files.
72 * Other Directives:: Miscellaneous preprocessing directives.
73 * Output:: Format of output from the C preprocessor.
74 * Invocation:: How to invoke the preprocessor; command options.
75 * Concept Index:: Index of concepts and terms.
76 * Index:: Index of directives, predefined macros and options.
79 File: cpp.info, Node: Global Actions, Next: Directives, Prev: Top, Up: Top
81 Transformations Made Globally
82 =============================
84 Most C preprocessor features are inactive unless you give specific
85 directives to request their use. (Preprocessing directives are lines
86 starting with `#'; *note Directives::.). But there are three
87 transformations that the preprocessor always makes on all the input it
88 receives, even in the absence of directives.
90 * All C comments are replaced with single spaces.
92 * Backslash-Newline sequences are deleted, no matter where. This
93 feature allows you to break long lines for cosmetic purposes
94 without changing their meaning.
96 * Predefined macro names are replaced with their expansions (*note
99 The first two transformations are done *before* nearly all other
100 parsing and before preprocessing directives are recognized. Thus, for
101 example, you can split a line cosmetically with Backslash-Newline
102 anywhere (except when trigraphs are in use; see below).
111 is equivalent into `#define FOO 1020'. You can split even an escape
112 sequence with Backslash-Newline. For example, you can split `"foo\bar"'
113 between the `\' and the `b' to get
118 This behavior is unclean: in all other contexts, a Backslash can be
119 inserted in a string constant as an ordinary character by writing a
120 double Backslash, and this creates an exception. But the ANSI C
121 standard requires it. (Strict ANSI C does not allow Newlines in string
122 constants, so they do not consider this a problem.)
124 But there are a few exceptions to all three transformations.
126 * C comments and predefined macro names are not recognized inside a
127 `#include' directive in which the file name is delimited with `<'
130 * C comments and predefined macro names are never recognized within a
131 character or string constant. (Strictly speaking, this is the
132 rule, not an exception, but it is worth noting here anyway.)
134 * Backslash-Newline may not safely be used within an ANSI "trigraph".
135 Trigraphs are converted before Backslash-Newline is deleted. If
136 you write what looks like a trigraph with a Backslash-Newline
137 inside, the Backslash-Newline is deleted as usual, but it is then
138 too late to recognize the trigraph.
140 This exception is relevant only if you use the `-trigraphs' option
141 to enable trigraph processing. *Note Invocation::.
144 File: cpp.info, Node: Directives, Next: Header Files, Prev: Global Actions, Up: Top
146 Preprocessing Directives
147 ========================
149 Most preprocessor features are active only if you use preprocessing
150 directives to request their use.
152 Preprocessing directives are lines in your program that start with
153 `#'. The `#' is followed by an identifier that is the "directive name".
154 For example, `#define' is the directive that defines a macro.
155 Whitespace is also allowed before and after the `#'.
157 The set of valid directive names is fixed. Programs cannot define
158 new preprocessing directives.
160 Some directive names require arguments; these make up the rest of
161 the directive line and must be separated from the directive name by
162 whitespace. For example, `#define' must be followed by a macro name
163 and the intended expansion of the macro. *Note Simple Macros::.
165 A preprocessing directive cannot be more than one line in normal
166 circumstances. It may be split cosmetically with Backslash-Newline,
167 but that has no effect on its meaning. Comments containing Newlines
168 can also divide the directive into multiple lines, but the comments are
169 changed to Spaces before the directive is interpreted. The only way a
170 significant Newline can occur in a preprocessing directive is within a
171 string constant or character constant. Note that most C compilers that
172 might be applied to the output from the preprocessor do not accept
173 string or character constants containing Newlines.
175 The `#' and the directive name cannot come from a macro expansion.
176 For example, if `foo' is defined as a macro expanding to `define', that
177 does not make `#foo' a valid preprocessing directive.
180 File: cpp.info, Node: Header Files, Next: Macros, Prev: Directives, Up: Top
185 A header file is a file containing C declarations and macro
186 definitions (*note Macros::.) to be shared between several source
187 files. You request the use of a header file in your program with the C
188 preprocessing directive `#include'.
192 * Header Uses:: What header files are used for.
193 * Include Syntax:: How to write `#include' directives.
194 * Include Operation:: What `#include' does.
195 * Once-Only:: Preventing multiple inclusion of one header file.
196 * Inheritance:: Including one header file in another header file.
199 File: cpp.info, Node: Header Uses, Next: Include Syntax, Prev: Header Files, Up: Header Files
204 Header files serve two kinds of purposes.
206 * System header files declare the interfaces to parts of the
207 operating system. You include them in your program to supply the
208 definitions and declarations you need to invoke system calls and
211 * Your own header files contain declarations for interfaces between
212 the source files of your program. Each time you have a group of
213 related declarations and macro definitions all or most of which
214 are needed in several different source files, it is a good idea to
215 create a header file for them.
217 Including a header file produces the same results in C compilation as
218 copying the header file into each source file that needs it. But such
219 copying would be time-consuming and error-prone. With a header file,
220 the related declarations appear in only one place. If they need to be
221 changed, they can be changed in one place, and programs that include
222 the header file will automatically use the new version when next
223 recompiled. The header file eliminates the labor of finding and
224 changing all the copies as well as the risk that a failure to find one
225 copy will result in inconsistencies within a program.
227 The usual convention is to give header files names that end with
228 `.h'. Avoid unusual characters in header file names, as they reduce
232 File: cpp.info, Node: Include Syntax, Next: Include Operation, Prev: Header Uses, Up: Header Files
234 The `#include' Directive
235 ------------------------
237 Both user and system header files are included using the
238 preprocessing directive `#include'. It has three variants:
241 This variant is used for system header files. It searches for a
242 file named FILE in a list of directories specified by you, then in
243 a standard list of system directories. You specify directories to
244 search for header files with the command option `-I' (*note
245 Invocation::.). The option `-nostdinc' inhibits searching the
246 standard system directories; in this case only the directories you
247 specify are searched.
249 The parsing of this form of `#include' is slightly special because
250 comments are not recognized within the `<...>'. Thus, in
251 `#include <x/*y>' the `/*' does not start a comment and the
252 directive specifies inclusion of a system header file named
253 `x/*y'. Of course, a header file with such a name is unlikely to
254 exist on Unix, where shell wildcard features would make it hard to
257 The argument FILE may not contain a `>' character. It may,
258 however, contain a `<' character.
261 This variant is used for header files of your own program. It
262 searches for a file named FILE first in the current directory,
263 then in the same directories used for system header files. The
264 current directory is the directory of the current input file. It
265 is tried first because it is presumed to be the location of the
266 files that the current input file refers to. (If the `-I-' option
267 is used, the special treatment of the current directory is
270 The argument FILE may not contain `"' characters. If backslashes
271 occur within FILE, they are considered ordinary text characters,
272 not escape characters. None of the character escape sequences
273 appropriate to string constants in C are processed. Thus,
274 `#include "x\n\\y"' specifies a filename containing three
275 backslashes. It is not clear why this behavior is ever useful, but
276 the ANSI standard specifies it.
278 `#include ANYTHING ELSE'
279 This variant is called a "computed #include". Any `#include'
280 directive whose argument does not fit the above two forms is a
281 computed include. The text ANYTHING ELSE is checked for macro
282 calls, which are expanded (*note Macros::.). When this is done,
283 the result must fit one of the above two variants--in particular,
284 the expanded text must in the end be surrounded by either quotes
287 This feature allows you to define a macro which controls the file
288 name to be used at a later point in the program. One application
289 of this is to allow a site-specific configuration file for your
290 program to specify the names of the system include files to be
291 used. This can help in porting the program to various operating
292 systems in which the necessary system header files are found in
296 File: cpp.info, Node: Include Operation, Next: Once-Only, Prev: Include Syntax, Up: Header Files
301 The `#include' directive works by directing the C preprocessor to
302 scan the specified file as input before continuing with the rest of the
303 current file. The output from the preprocessor contains the output
304 already generated, followed by the output resulting from the included
305 file, followed by the output that comes from the text after the
306 `#include' directive. For example, given a header file `header.h' as
311 and a main program called `program.c' that uses the header file, like
322 the output generated by the C preprocessor for `program.c' as input
333 Included files are not limited to declarations and macro
334 definitions; those are merely the typical uses. Any fragment of a C
335 program can be included from another file. The include file could even
336 contain the beginning of a statement that is concluded in the
337 containing file, or the end of a statement that was started in the
338 including file. However, a comment or a string or character constant
339 may not start in the included file and finish in the including file.
340 An unterminated comment, string constant or character constant in an
341 included file is considered to end (with an error message) at the end
344 It is possible for a header file to begin or end a syntactic unit
345 such as a function definition, but that would be very confusing, so
348 The line following the `#include' directive is always treated as a
349 separate line by the C preprocessor even if the included file lacks a
353 File: cpp.info, Node: Once-Only, Next: Inheritance, Prev: Include Operation, Up: Header Files
355 Once-Only Include Files
356 -----------------------
358 Very often, one header file includes another. It can easily result
359 that a certain header file is included more than once. This may lead
360 to errors, if the header file defines structure types or typedefs, and
361 is certainly wasteful. Therefore, we often wish to prevent multiple
362 inclusion of a header file.
364 The standard way to do this is to enclose the entire real contents
365 of the file in a conditional, like this:
367 #ifndef FILE_FOO_SEEN
368 #define FILE_FOO_SEEN
372 #endif /* FILE_FOO_SEEN */
374 The macro `FILE_FOO_SEEN' indicates that the file has been included
375 once already. In a user header file, the macro name should not begin
376 with `_'. In a system header file, this name should begin with `__' to
377 avoid conflicts with user programs. In any kind of header file, the
378 macro name should contain the name of the file and some additional
379 text, to avoid conflicts with other header files.
381 The GNU C preprocessor is programmed to notice when a header file
382 uses this particular construct and handle it efficiently. If a header
383 file is contained entirely in a `#ifndef' conditional, then it records
384 that fact. If a subsequent `#include' specifies the same file, and the
385 macro in the `#ifndef' is already defined, then the file is entirely
386 skipped, without even reading it.
388 There is also an explicit directive to tell the preprocessor that it
389 need not include a file more than once. This is called `#pragma once',
390 and was used *in addition to* the `#ifndef' conditional around the
391 contents of the header file. `#pragma once' is now obsolete and should
394 In the Objective C language, there is a variant of `#include' called
395 `#import' which includes a file, but does so at most once. If you use
396 `#import' *instead of* `#include', then you don't need the conditionals
397 inside the header file to prevent multiple execution of the contents.
399 `#import' is obsolete because it is not a well designed feature. It
400 requires the users of a header file--the applications programmers--to
401 know that a certain header file should only be included once. It is
402 much better for the header file's implementor to write the file so that
403 users don't need to know this. Using `#ifndef' accomplishes this goal.
406 File: cpp.info, Node: Inheritance, Prev: Once-Only, Up: Header Files
408 Inheritance and Header Files
409 ----------------------------
411 "Inheritance" is what happens when one object or file derives some
412 of its contents by virtual copying from another object or file. In the
413 case of C header files, inheritance means that one header file includes
414 another header file and then replaces or adds something.
416 If the inheriting header file and the base header file have different
417 names, then inheritance is straightforward: simply write `#include
418 "BASE"' in the inheriting file.
420 Sometimes it is necessary to give the inheriting file the same name
421 as the base file. This is less straightforward.
423 For example, suppose an application program uses the system header
424 file `sys/signal.h', but the version of `/usr/include/sys/signal.h' on
425 a particular system doesn't do what the application program expects.
426 It might be convenient to define a "local" version, perhaps under the
427 name `/usr/local/include/sys/signal.h', to override or add to the one
428 supplied by the system.
430 You can do this by using the option `-I.' for compilation, and
431 writing a file `sys/signal.h' that does what the application program
432 expects. But making this file include the standard `sys/signal.h' is
433 not so easy--writing `#include <sys/signal.h>' in that file doesn't
434 work, because it includes your own version of the file, not the
435 standard system version. Used in that file itself, this leads to an
436 infinite recursion and a fatal error in compilation.
438 `#include </usr/include/sys/signal.h>' would find the proper file,
439 but that is not clean, since it makes an assumption about where the
440 system header file is found. This is bad for maintenance, since it
441 means that any change in where the system's header files are kept
442 requires a change somewhere else.
444 The clean way to solve this problem is to use `#include_next', which
445 means, "Include the *next* file with this name." This directive works
446 like `#include' except in searching for the specified file: it starts
447 searching the list of header file directories *after* the directory in
448 which the current file was found.
450 Suppose you specify `-I /usr/local/include', and the list of
451 directories to search also includes `/usr/include'; and suppose that
452 both directories contain a file named `sys/signal.h'. Ordinary
453 `#include <sys/signal.h>' finds the file under `/usr/local/include'.
454 If that file contains `#include_next <sys/signal.h>', it starts
455 searching after that directory, and finds the file in `/usr/include'.
458 File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top
463 A macro is a sort of abbreviation which you can define once and then
464 use later. There are many complicated features associated with macros
465 in the C preprocessor.
469 * Simple Macros:: Macros that always expand the same way.
470 * Argument Macros:: Macros that accept arguments that are substituted
471 into the macro expansion.
472 * Predefined:: Predefined macros that are always available.
473 * Stringification:: Macro arguments converted into string constants.
474 * Concatenation:: Building tokens from parts taken from macro arguments.
475 * Undefining:: Cancelling a macro's definition.
476 * Redefining:: Changing a macro's definition.
477 * Macro Pitfalls:: Macros can confuse the unwary. Here we explain
478 several common problems and strange features.
481 File: cpp.info, Node: Simple Macros, Next: Argument Macros, Prev: Macros, Up: Macros
486 A "simple macro" is a kind of abbreviation. It is a name which
487 stands for a fragment of code. Some people refer to these as "manifest
490 Before you can use a macro, you must "define" it explicitly with the
491 `#define' directive. `#define' is followed by the name of the macro
492 and then the code it should be an abbreviation for. For example,
494 #define BUFFER_SIZE 1020
496 defines a macro named `BUFFER_SIZE' as an abbreviation for the text
497 `1020'. If somewhere after this `#define' directive there comes a C
498 statement of the form
500 foo = (char *) xmalloc (BUFFER_SIZE);
502 then the C preprocessor will recognize and "expand" the macro
503 `BUFFER_SIZE', resulting in
505 foo = (char *) xmalloc (1020);
507 The use of all upper case for macro names is a standard convention.
508 Programs are easier to read when it is possible to tell at a glance
509 which names are macros.
511 Normally, a macro definition must be a single line, like all C
512 preprocessing directives. (You can split a long macro definition
513 cosmetically with Backslash-Newline.) There is one exception: Newlines
514 can be included in the macro definition if within a string or character
515 constant. This is because it is not possible for a macro definition to
516 contain an unbalanced quote character; the definition automatically
517 extends to include the matching quote character that ends the string or
518 character constant. Comments within a macro definition may contain
519 Newlines, which make no difference since the comments are entirely
520 replaced with Spaces regardless of their contents.
522 Aside from the above, there is no restriction on what can go in a
523 macro body. Parentheses need not balance. The body need not resemble
524 valid C code. (But if it does not, you may get error messages from the
525 C compiler when you use the macro.)
527 The C preprocessor scans your program sequentially, so macro
528 definitions take effect at the place you write them. Therefore, the
529 following input to the C preprocessor
541 After the preprocessor expands a macro name, the macro's definition
542 body is appended to the front of the remaining input, and the check for
543 macro calls continues. Therefore, the macro body can contain calls to
544 other macros. For example, after
547 #define TABLESIZE BUFSIZE
549 the name `TABLESIZE' when used in the program would go through two
550 stages of expansion, resulting ultimately in `1020'.
552 This is not at all the same as defining `TABLESIZE' to be `1020'.
553 The `#define' for `TABLESIZE' uses exactly the body you specify--in
554 this case, `BUFSIZE'--and does not check to see whether it too is the
555 name of a macro. It's only when you *use* `TABLESIZE' that the result
556 of its expansion is checked for more macro names. *Note Cascaded
560 File: cpp.info, Node: Argument Macros, Next: Predefined, Prev: Simple Macros, Up: Macros
562 Macros with Arguments
563 ---------------------
565 A simple macro always stands for exactly the same text, each time it
566 is used. Macros can be more flexible when they accept "arguments".
567 Arguments are fragments of code that you supply each time the macro is
568 used. These fragments are included in the expansion of the macro
569 according to the directions in the macro definition. A macro that
570 accepts arguments is called a "function-like macro" because the syntax
571 for using it looks like a function call.
573 To define a macro that uses arguments, you write a `#define'
574 directive with a list of "argument names" in parentheses after the name
575 of the macro. The argument names may be any valid C identifiers,
576 separated by commas and optionally whitespace. The open-parenthesis
577 must follow the macro name immediately, with no space in between.
579 For example, here is a macro that computes the minimum of two numeric
580 values, as it is defined in many C programs:
582 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
584 (This is not the best way to define a "minimum" macro in GNU C. *Note
585 Side Effects::, for more information.)
587 To use a macro that expects arguments, you write the name of the
588 macro followed by a list of "actual arguments" in parentheses,
589 separated by commas. The number of actual arguments you give must
590 match the number of arguments the macro expects. Examples of use of
591 the macro `min' include `min (1, 2)' and `min (x + 28, *p)'.
593 The expansion text of the macro depends on the arguments you use.
594 Each of the argument names of the macro is replaced, throughout the
595 macro definition, with the corresponding actual argument. Using the
596 same macro `min' defined above, `min (1, 2)' expands into
598 ((1) < (2) ? (1) : (2))
600 where `1' has been substituted for `X' and `2' for `Y'.
602 Likewise, `min (x + 28, *p)' expands into
604 ((x + 28) < (*p) ? (x + 28) : (*p))
606 Parentheses in the actual arguments must balance; a comma within
607 parentheses does not end an argument. However, there is no requirement
608 for brackets or braces to balance, and they do not prevent a comma from
609 separating arguments. Thus,
611 macro (array[x = y, x + 1])
613 passes two arguments to `macro': `array[x = y' and `x + 1]'. If you
614 want to supply `array[x = y, x + 1]' as an argument, you must write it
615 as `array[(x = y, x + 1)]', which is equivalent C code.
617 After the actual arguments are substituted into the macro body, the
618 entire result is appended to the front of the remaining input, and the
619 check for macro calls continues. Therefore, the actual arguments can
620 contain calls to other macros, either with or without arguments, or
621 even to the same macro. The macro body can also contain calls to other
622 macros. For example, `min (min (a, b), c)' expands into this text:
624 ((((a) < (b) ? (a) : (b))) < (c)
625 ? (((a) < (b) ? (a) : (b)))
628 (Line breaks shown here for clarity would not actually be generated.)
630 If a macro `foo' takes one argument, and you want to supply an empty
631 argument, you must write at least some whitespace between the
632 parentheses, like this: `foo ( )'. Just `foo ()' is providing no
633 arguments, which is an error if `foo' expects an argument. But `foo0
634 ()' is the correct way to call a macro defined to take zero arguments,
639 If you use the macro name followed by something other than an
640 open-parenthesis (after ignoring any spaces, tabs and comments that
641 follow), it is not a call to the macro, and the preprocessor does not
642 change what you have written. Therefore, it is possible for the same
643 name to be a variable or function in your program as well as a macro,
644 and you can choose in each instance whether to refer to the macro (if
645 an actual argument list follows) or the variable or function (if an
646 argument list does not follow).
648 Such dual use of one name could be confusing and should be avoided
649 except when the two meanings are effectively synonymous: that is, when
650 the name is both a macro and a function and the two have similar
651 effects. You can think of the name simply as a function; use of the
652 name for purposes other than calling it (such as, to take the address)
653 will refer to the function, while calls will expand the macro and
654 generate better but equivalent code. For example, you can use a
655 function named `min' in the same source file that defines the macro.
656 If you write `&min' with no argument list, you refer to the function.
657 If you write `min (x, bb)', with an argument list, the macro is
658 expanded. If you write `(min) (a, bb)', where the name `min' is not
659 followed by an open-parenthesis, the macro is not expanded, so you wind
660 up with a call to the function `min'.
662 You may not define the same name as both a simple macro and a macro
665 In the definition of a macro with arguments, the list of argument
666 names must follow the macro name immediately with no space in between.
667 If there is a space after the macro name, the macro is defined as
668 taking no arguments, and all the rest of the line is taken to be the
669 expansion. The reason for this is that it is often useful to define a
670 macro that takes no arguments and whose definition begins with an
671 identifier in parentheses. This rule about spaces makes it possible
672 for you to do either this:
674 #define FOO(x) - 1 / (x)
676 (which defines `FOO' to take an argument and expand into minus the
677 reciprocal of that argument) or this:
679 #define BAR (x) - 1 / (x)
681 (which defines `BAR' to take no argument and always expand into `(x) -
684 Note that the *uses* of a macro with arguments can have spaces before
685 the left parenthesis; it's the *definition* where it matters whether
689 File: cpp.info, Node: Predefined, Next: Stringification, Prev: Argument Macros, Up: Macros
694 Several simple macros are predefined. You can use them without
695 giving definitions for them. They fall into two classes: standard
696 macros and system-specific macros.
700 * Standard Predefined:: Standard predefined macros.
701 * Nonstandard Predefined:: Nonstandard predefined macros.
704 File: cpp.info, Node: Standard Predefined, Next: Nonstandard Predefined, Prev: Predefined, Up: Predefined
706 Standard Predefined Macros
707 ..........................
709 The standard predefined macros are available with the same meanings
710 regardless of the machine or operating system on which you are using
711 GNU C. Their names all start and end with double underscores. Those
712 preceding `__GNUC__' in this table are standardized by ANSI C; the rest
713 are GNU C extensions.
716 This macro expands to the name of the current input file, in the
717 form of a C string constant. The precise name returned is the one
718 that was specified in `#include' or as the input file name
722 This macro expands to the current input line number, in the form
723 of a decimal integer constant. While we call it a predefined
724 macro, it's a pretty strange macro, since its "definition" changes
725 with each new line of source code.
727 This and `__FILE__' are useful in generating an error message to
728 report an inconsistency detected by the program; the message can
729 state the source line at which the inconsistency was detected.
732 fprintf (stderr, "Internal error: "
733 "negative string length "
734 "%d at %s, line %d.",
735 length, __FILE__, __LINE__);
737 A `#include' directive changes the expansions of `__FILE__' and
738 `__LINE__' to correspond to the included file. At the end of that
739 file, when processing resumes on the input file that contained the
740 `#include' directive, the expansions of `__FILE__' and `__LINE__'
741 revert to the values they had before the `#include' (but
742 `__LINE__' is then incremented by one as processing moves to the
743 line after the `#include').
745 The expansions of both `__FILE__' and `__LINE__' are altered if a
746 `#line' directive is used. *Note Combining Sources::.
749 This macro expands to a string constant that describes the date on
750 which the preprocessor is being run. The string constant contains
751 eleven characters and looks like `"Jan 29 1987"' or `"Apr 1 1905"'.
754 This macro expands to a string constant that describes the time at
755 which the preprocessor is being run. The string constant contains
756 eight characters and looks like `"23:59:01"'.
759 This macro expands to the constant 1, to signify that this is ANSI
760 Standard C. (Whether that is actually true depends on what C
761 compiler will operate on the output from the preprocessor.)
764 This macro expands to the C Standard's version number, a long
765 integer constant of the form `YYYYMML' where YYYY and MM are the
766 year and month of the Standard version. This signifies which
767 version of the C Standard the preprocessor conforms to. Like
768 `__STDC__', whether this version number is accurate for the entire
769 implementation depends on what C compiler will operate on the
770 output from the preprocessor.
773 This macro is defined if and only if this is GNU C. This macro is
774 defined only when the entire GNU C compiler is in use; if you
775 invoke the preprocessor directly, `__GNUC__' is undefined. The
776 value identifies the major version number of GNU CC (`1' for GNU CC
777 version 1, which is now obsolete, and `2' for version 2).
780 The macro contains the minor version number of the compiler. This
781 can be used to work around differences between different releases
782 of the compiler (for example, if gcc 2.6.3 is known to support a
783 feature, you can test for `__GNUC__ > 2 || (__GNUC__ == 2 &&
784 __GNUC_MINOR__ >= 6)'). The last number, `3' in the example
785 above, denotes the bugfix level of the compiler; no macro contains
789 The GNU C compiler defines this when the compilation language is
790 C++; use `__GNUG__' to distinguish between GNU C and GNU C++.
793 The draft ANSI standard for C++ used to require predefining this
794 variable. Though it is no longer required, GNU C++ continues to
795 define it, as do other popular C++ compilers. You can use
796 `__cplusplus' to test whether a header is compiled by a C compiler
800 This macro is defined if and only if the `-ansi' switch was
801 specified when GNU C was invoked. Its definition is the null
802 string. This macro exists primarily to direct certain GNU header
803 files not to define certain traditional Unix constructs which are
804 incompatible with ANSI C.
807 This macro expands to the name of the main input file, in the form
808 of a C string constant. This is the source file that was specified
809 as an argument when the C compiler was invoked.
812 This macro expands to a decimal integer constant that represents
813 the depth of nesting in include files. The value of this macro is
814 incremented on every `#include' directive and decremented at every
815 end of file. For input files specified by command line arguments,
816 the nesting level is zero.
819 This macro expands to a string which describes the version number
820 of GNU C. The string is normally a sequence of decimal numbers
821 separated by periods, such as `"2.6.0"'. The only reasonable use
822 of this macro is to incorporate it into a string constant.
825 This macro is defined in optimizing compilations. It causes
826 certain GNU header files to define alternative macro definitions
827 for some system library functions. It is unwise to refer to or
828 test the definition of this macro unless you make very sure that
829 programs will execute with the same effect regardless.
832 This macro is defined if and only if the data type `char' is
833 unsigned on the target machine. It exists to cause the standard
834 header file `limit.h' to work correctly. It is bad practice to
835 refer to this macro yourself; instead, refer to the standard
836 macros defined in `limit.h'. The preprocessor uses this macro to
837 determine whether or not to sign-extend large character constants
838 written in octal; see *Note The `#if' Directive: #if Directive.
840 `__REGISTER_PREFIX__'
841 This macro expands to a string describing the prefix applied to cpu
842 registers in assembler code. It can be used to write assembler
843 code that is usable in multiple environments. For example, in the
844 `m68k-aout' environment it expands to the string `""', but in the
845 `m68k-coff' environment it expands to the string `"%"'.
847 `__USER_LABEL_PREFIX__'
848 This macro expands to a string describing the prefix applied to
849 user generated labels in assembler code. It can be used to write
850 assembler code that is usable in multiple environments. For
851 example, in the `m68k-aout' environment it expands to the string
852 `"_"', but in the `m68k-coff' environment it expands to the string
856 File: cpp.info, Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined
858 Nonstandard Predefined Macros
859 .............................
861 The C preprocessor normally has several predefined macros that vary
862 between machines because their purpose is to indicate what type of
863 system and machine is in use. This manual, being for all systems and
864 machines, cannot tell you exactly what their names are; instead, we
865 offer a list of some typical ones. You can use `cpp -dM' to see the
866 values of predefined macros; see *Note Invocation::.
868 Some nonstandard predefined macros describe the operating system in
869 use, with more or less specificity. For example,
872 `unix' is normally predefined on all Unix systems.
875 `BSD' is predefined on recent versions of Berkeley Unix (perhaps
876 only in version 4.3).
878 Other nonstandard predefined macros describe the kind of CPU, with
879 more or less specificity. For example,
882 `vax' is predefined on Vax computers.
885 `mc68000' is predefined on most computers whose CPU is a Motorola
886 68000, 68010 or 68020.
889 `m68k' is also predefined on most computers whose CPU is a 68000,
890 68010 or 68020; however, some makers use `mc68000' and some use
891 `m68k'. Some predefine both names. What happens in GNU C depends
892 on the system you are using it on.
895 `M68020' has been observed to be predefined on some systems that
896 use 68020 CPUs--in addition to `mc68000' and `m68k', which are
901 Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU
905 `ns32000' is predefined on computers which use the National
906 Semiconductor 32000 series CPU.
908 Yet other nonstandard predefined macros describe the manufacturer of
909 the system. For example,
912 `sun' is predefined on all models of Sun computers.
915 `pyr' is predefined on all models of Pyramid computers.
918 `sequent' is predefined on all models of Sequent computers.
920 These predefined symbols are not only nonstandard, they are contrary
921 to the ANSI standard because their names do not start with underscores.
922 Therefore, the option `-ansi' inhibits the definition of these symbols.
924 This tends to make `-ansi' useless, since many programs depend on the
925 customary nonstandard predefined symbols. Even system header files
926 check them and will generate incorrect declarations if they do not find
927 the names that are expected. You might think that the header files
928 supplied for the Uglix computer would not need to test what machine
929 they are running on, because they can simply assume it is the Uglix;
930 but often they do, and they do so using the customary names. As a
931 result, very few C programs will compile with `-ansi'. We intend to
932 avoid such problems on the GNU system.
934 What, then, should you do in an ANSI C program to test the type of
935 machine it will run on?
937 GNU C offers a parallel series of symbols for this purpose, whose
938 names are made from the customary ones by adding `__' at the beginning
939 and end. Thus, the symbol `__vax__' would be available on a Vax, and
942 The set of nonstandard predefined names in the GNU C preprocessor is
943 controlled (when `cpp' is itself compiled) by the macro
944 `CPP_PREDEFINES', which should be a string containing `-D' options,
945 separated by spaces. For example, on the Sun 3, we use the following
948 #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
950 This macro is usually specified in `tm.h'.
953 File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Predefined, Up: Macros
958 "Stringification" means turning a code fragment into a string
959 constant whose contents are the text for the code fragment. For
960 example, stringifying `foo (z)' results in `"foo (z)"'.
962 In the C preprocessor, stringification is an option available when
963 macro arguments are substituted into the macro definition. In the body
964 of the definition, when an argument name appears, the character `#'
965 before the name specifies stringification of the corresponding actual
966 argument when it is substituted at that point in the definition. The
967 same argument may be substituted in other places in the definition
968 without stringification if the argument name appears in those places
971 Here is an example of a macro definition that uses stringification:
973 #define WARN_IF(EXP) \
975 fprintf (stderr, "Warning: " #EXP "\n"); } \
978 Here the actual argument for `EXP' is substituted once as given, into
979 the `if' statement, and once as stringified, into the argument to
980 `fprintf'. The `do' and `while (0)' are a kludge to make it possible
981 to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a
982 function would make C programmers want to do; see *Note Swallow
985 The stringification feature is limited to transforming one macro
986 argument into one string constant: there is no way to combine the
987 argument with other text and then stringify it all together. But the
988 example above shows how an equivalent result can be obtained in ANSI
989 Standard C using the feature that adjacent string constants are
990 concatenated as one string constant. The preprocessor stringifies the
991 actual value of `EXP' into a separate string constant, resulting in
995 fprintf (stderr, "Warning: " "x == 0" "\n"); } \
998 but the C compiler then sees three consecutive string constants and
999 concatenates them into one, producing effectively
1002 fprintf (stderr, "Warning: x == 0\n"); } \
1005 Stringification in C involves more than putting doublequote
1006 characters around the fragment; it is necessary to put backslashes in
1007 front of all doublequote characters, and all backslashes in string and
1008 character constants, in order to get a valid C string constant with the
1009 proper contents. Thus, stringifying `p = "foo\n";' results in `"p =
1010 \"foo\\n\";"'. However, backslashes that are not inside of string or
1011 character constants are not duplicated: `\n' by itself stringifies to
1014 Whitespace (including comments) in the text being stringified is
1015 handled according to precise rules. All leading and trailing
1016 whitespace is ignored. Any sequence of whitespace in the middle of the
1017 text is converted to a single space in the stringified result.
1020 File: cpp.info, Node: Concatenation, Next: Undefining, Prev: Stringification, Up: Macros
1025 "Concatenation" means joining two strings into one. In the context
1026 of macro expansion, concatenation refers to joining two lexical units
1027 into one longer one. Specifically, an actual argument to the macro can
1028 be concatenated with another actual argument or with fixed text to
1029 produce a longer name. The longer name might be the name of a function,
1030 variable or type, or a C keyword; it might even be the name of another
1031 macro, in which case it will be expanded.
1033 When you define a macro, you request concatenation with the special
1034 operator `##' in the macro body. When the macro is called, after
1035 actual arguments are substituted, all `##' operators are deleted, and
1036 so is any whitespace next to them (including whitespace that was part
1037 of an actual argument). The result is to concatenate the syntactic
1038 tokens on either side of the `##'.
1040 Consider a C program that interprets named commands. There probably
1041 needs to be a table of commands, perhaps an array of structures
1042 declared as follows:
1047 void (*function) ();
1050 struct command commands[] =
1052 { "quit", quit_command},
1053 { "help", help_command},
1057 It would be cleaner not to have to give each command name twice,
1058 once in the string constant and once in the function name. A macro
1059 which takes the name of a command as an argument can make this
1060 unnecessary. The string constant can be created with stringification,
1061 and the function name by concatenating the argument with `_command'.
1062 Here is how it is done:
1064 #define COMMAND(NAME) { #NAME, NAME ## _command }
1066 struct command commands[] =
1073 The usual case of concatenation is concatenating two names (or a
1074 name and a number) into a longer name. But this isn't the only valid
1075 case. It is also possible to concatenate two numbers (or a number and
1076 a name, such as `1.5' and `e3') into a number. Also, multi-character
1077 operators such as `+=' can be formed by concatenation. In some cases
1078 it is even possible to piece together a string constant. However, two
1079 pieces of text that don't together form a valid lexical unit cannot be
1080 concatenated. For example, concatenation with `x' on one side and `+'
1081 on the other is not meaningful because those two characters can't fit
1082 together in any lexical unit of C. The ANSI standard says that such
1083 attempts at concatenation are undefined, but in the GNU C preprocessor
1084 it is well defined: it puts the `x' and `+' side by side with no
1085 particular special results.
1087 Keep in mind that the C preprocessor converts comments to whitespace
1088 before macros are even considered. Therefore, you cannot create a
1089 comment by concatenating `/' and `*': the `/*' sequence that starts a
1090 comment is not a lexical unit, but rather the beginning of a "long"
1091 space character. Also, you can freely use comments next to a `##' in a
1092 macro definition, or in actual arguments that will be concatenated,
1093 because the comments will be converted to spaces at first sight, and
1094 concatenation will later discard the spaces.
1097 File: cpp.info, Node: Undefining, Next: Redefining, Prev: Concatenation, Up: Macros
1102 To "undefine" a macro means to cancel its definition. This is done
1103 with the `#undef' directive. `#undef' is followed by the macro name to
1106 Like definition, undefinition occurs at a specific point in the
1107 source file, and it applies starting from that point. The name ceases
1108 to be a macro name, and from that point on it is treated by the
1109 preprocessor as if it had never been a macro name.
1124 In this example, `FOO' had better be a variable or function as well as
1125 (temporarily) a macro, in order for the result of the expansion to be
1128 The same form of `#undef' directive will cancel definitions with
1129 arguments or definitions that don't expect arguments. The `#undef'
1130 directive has no effect when used on a name not currently defined as a
1134 File: cpp.info, Node: Redefining, Next: Macro Pitfalls, Prev: Undefining, Up: Macros
1139 "Redefining" a macro means defining (with `#define') a name that is
1140 already defined as a macro.
1142 A redefinition is trivial if the new definition is transparently
1143 identical to the old one. You probably wouldn't deliberately write a
1144 trivial redefinition, but they can happen automatically when a header
1145 file is included more than once (*note Header Files::.), so they are
1146 accepted silently and without effect.
1148 Nontrivial redefinition is considered likely to be an error, so it
1149 provokes a warning message from the preprocessor. However, sometimes it
1150 is useful to change the definition of a macro in mid-compilation. You
1151 can inhibit the warning by undefining the macro with `#undef' before the
1154 In order for a redefinition to be trivial, the new definition must
1155 exactly match the one already in effect, with two possible exceptions:
1157 * Whitespace may be added or deleted at the beginning or the end.
1159 * Whitespace may be changed in the middle (but not inside strings).
1160 However, it may not be eliminated entirely, and it may not be added
1161 where there was no whitespace at all.
1163 Recall that a comment counts as whitespace.
1166 File: cpp.info, Node: Macro Pitfalls, Prev: Redefining, Up: Macros
1168 Pitfalls and Subtleties of Macros
1169 ---------------------------------
1171 In this section we describe some special rules that apply to macros
1172 and macro expansion, and point out certain cases in which the rules have
1173 counterintuitive consequences that you must watch out for.
1177 * Misnesting:: Macros can contain unmatched parentheses.
1178 * Macro Parentheses:: Why apparently superfluous parentheses
1179 may be necessary to avoid incorrect grouping.
1180 * Swallow Semicolon:: Macros that look like functions
1181 but expand into compound statements.
1182 * Side Effects:: Unsafe macros that cause trouble when
1183 arguments contain side effects.
1184 * Self-Reference:: Macros whose definitions use the macros' own names.
1185 * Argument Prescan:: Actual arguments are checked for macro calls
1186 before they are substituted.
1187 * Cascaded Macros:: Macros whose definitions use other macros.
1188 * Newlines in Args:: Sometimes line numbers get confused.