3 @settitle The C Preprocessor
9 * Cpp: (cpp). The C preprocessor.
18 @setchapternewpage odd
20 This file documents the GNU C Preprocessor.
22 Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided also that
38 the entire resulting derived work is distributed under the terms of a
39 permission notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions.
47 @title The C Preprocessor
48 @subtitle Last revised July 1992
49 @subtitle for GCC version 2
50 @author Richard M. Stallman
53 This booklet is eventually intended to form the first chapter of a GNU
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free
58 Software Foundation, Inc.
60 Permission is granted to make and distribute verbatim copies of
61 this manual provided the copyright notice and this permission notice
62 are preserved on all copies.
64 Permission is granted to copy and distribute modified versions of this
65 manual under the conditions for verbatim copying, provided also that
66 the entire resulting derived work is distributed under the terms of a
67 permission notice identical to this one.
69 Permission is granted to copy and distribute translations of this manual
70 into another language, under the above conditions for modified versions.
74 @node Top, Global Actions,, (DIR)
75 @chapter The C Preprocessor
77 The C preprocessor is a @dfn{macro processor} that is used automatically by
78 the C compiler to transform your program before actual compilation. It is
79 called a macro processor because it allows you to define @dfn{macros},
80 which are brief abbreviations for longer constructs.
82 The C preprocessor provides four separate facilities that you can use as
87 Inclusion of header files. These are files of declarations that can be
88 substituted into your program.
91 Macro expansion. You can define @dfn{macros}, which are abbreviations
92 for arbitrary fragments of C code, and then the C preprocessor will
93 replace the macros with their definitions throughout the program.
96 Conditional compilation. Using special preprocessing directives, you
97 can include or exclude parts of the program according to various
101 Line control. If you use a program to combine or rearrange source files into
102 an intermediate file which is then compiled, you can use line control
103 to inform the compiler of where each source line originally came from.
106 C preprocessors vary in some details. This manual discusses the GNU C
107 preprocessor, the C Compatible Compiler Preprocessor. The GNU C
108 preprocessor provides a superset of the features of ANSI Standard C.
110 ANSI Standard C requires the rejection of many harmless constructs commonly
111 used by today's C programs. Such incompatibility would be inconvenient for
112 users, so the GNU C preprocessor is configured to accept these constructs
113 by default. Strictly speaking, to get ANSI Standard C, you must use the
114 options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in
115 practice the consequences of having strict ANSI Standard C make it
116 undesirable to do this. @xref{Invocation}.
119 * Global Actions:: Actions made uniformly on all input files.
120 * Directives:: General syntax of preprocessing directives.
121 * Header Files:: How and why to use header files.
122 * Macros:: How and why to use macros.
123 * Conditionals:: How and why to use conditionals.
124 * Combining Sources:: Use of line control when you combine source files.
125 * Other Directives:: Miscellaneous preprocessing directives.
126 * Output:: Format of output from the C preprocessor.
127 * Invocation:: How to invoke the preprocessor; command options.
128 * Concept Index:: Index of concepts and terms.
129 * Index:: Index of directives, predefined macros and options.
132 @node Global Actions, Directives, Top, Top
133 @section Transformations Made Globally
135 Most C preprocessor features are inactive unless you give specific directives
136 to request their use. (Preprocessing directives are lines starting with
137 @samp{#}; @pxref{Directives}). But there are three transformations that the
138 preprocessor always makes on all the input it receives, even in the absence
143 All C comments are replaced with single spaces.
146 Backslash-Newline sequences are deleted, no matter where. This
147 feature allows you to break long lines for cosmetic purposes without
148 changing their meaning.
151 Predefined macro names are replaced with their expansions
152 (@pxref{Predefined}).
155 The first two transformations are done @emph{before} nearly all other parsing
156 and before preprocessing directives are recognized. Thus, for example, you
157 can split a line cosmetically with Backslash-Newline anywhere (except
158 when trigraphs are in use; see below).
170 is equivalent into @samp{#define FOO 1020}. You can split even an escape
171 sequence with Backslash-Newline. For example, you can split @code{"foo\bar"}
172 between the @samp{\} and the @samp{b} to get
180 This behavior is unclean: in all other contexts, a Backslash can be
181 inserted in a string constant as an ordinary character by writing a double
182 Backslash, and this creates an exception. But the ANSI C standard requires
183 it. (Strict ANSI C does not allow Newlines in string constants, so they
184 do not consider this a problem.)
186 But there are a few exceptions to all three transformations.
190 C comments and predefined macro names are not recognized inside a
191 @samp{#include} directive in which the file name is delimited with
192 @samp{<} and @samp{>}.
195 C comments and predefined macro names are never recognized within a
196 character or string constant. (Strictly speaking, this is the rule,
197 not an exception, but it is worth noting here anyway.)
200 Backslash-Newline may not safely be used within an ANSI ``trigraph''.
201 Trigraphs are converted before Backslash-Newline is deleted. If you
202 write what looks like a trigraph with a Backslash-Newline inside, the
203 Backslash-Newline is deleted as usual, but it is then too late to
204 recognize the trigraph.
206 This exception is relevant only if you use the @samp{-trigraphs}
207 option to enable trigraph processing. @xref{Invocation}.
210 @node Directives, Header Files, Global Actions, Top
211 @section Preprocessing Directives
213 @cindex preprocessing directives
215 Most preprocessor features are active only if you use preprocessing directives
216 to request their use.
218 Preprocessing directives are lines in your program that start with @samp{#}.
219 The @samp{#} is followed by an identifier that is the @dfn{directive name}.
220 For example, @samp{#define} is the directive that defines a macro.
221 Whitespace is also allowed before and after the @samp{#}.
223 The set of valid directive names is fixed. Programs cannot define new
224 preprocessing directives.
226 Some directive names require arguments; these make up the rest of the directive
227 line and must be separated from the directive name by whitespace. For example,
228 @samp{#define} must be followed by a macro name and the intended expansion
229 of the macro. @xref{Simple Macros}.
231 A preprocessing directive cannot be more than one line in normal circumstances.
232 It may be split cosmetically with Backslash-Newline, but that has no effect
233 on its meaning. Comments containing Newlines can also divide the
234 directive into multiple lines, but the comments are changed to Spaces
235 before the directive is interpreted. The only way a significant Newline
236 can occur in a preprocessing directive is within a string constant or
237 character constant. Note that
238 most C compilers that might be applied to the output from the preprocessor
239 do not accept string or character constants containing Newlines.
241 The @samp{#} and the directive name cannot come from a macro expansion. For
242 example, if @samp{foo} is defined as a macro expanding to @samp{define},
243 that does not make @samp{#foo} a valid preprocessing directive.
245 @node Header Files, Macros, Directives, Top
246 @section Header Files
249 A header file is a file containing C declarations and macro definitions
250 (@pxref{Macros}) to be shared between several source files. You request
251 the use of a header file in your program with the C preprocessing directive
255 * Header Uses:: What header files are used for.
256 * Include Syntax:: How to write @samp{#include} directives.
257 * Include Operation:: What @samp{#include} does.
258 * Once-Only:: Preventing multiple inclusion of one header file.
259 * Inheritance:: Including one header file in another header file.
262 @node Header Uses, Include Syntax, Header Files, Header Files
263 @subsection Uses of Header Files
265 Header files serve two kinds of purposes.
269 @findex system header files
270 System header files declare the interfaces to parts of the operating
271 system. You include them in your program to supply the definitions and
272 declarations you need to invoke system calls and libraries.
275 Your own header files contain declarations for interfaces between the
276 source files of your program. Each time you have a group of related
277 declarations and macro definitions all or most of which are needed in
278 several different source files, it is a good idea to create a header
282 Including a header file produces the same results in C compilation as
283 copying the header file into each source file that needs it. But such
284 copying would be time-consuming and error-prone. With a header file, the
285 related declarations appear in only one place. If they need to be changed,
286 they can be changed in one place, and programs that include the header file
287 will automatically use the new version when next recompiled. The header
288 file eliminates the labor of finding and changing all the copies as well as
289 the risk that a failure to find one copy will result in inconsistencies
292 The usual convention is to give header files names that end with
293 @file{.h}. Avoid unusual characters in header file names, as they
296 @node Include Syntax, Include Operation, Header Uses, Header Files
297 @subsection The @samp{#include} Directive
300 Both user and system header files are included using the preprocessing
301 directive @samp{#include}. It has three variants:
304 @item #include <@var{file}>
305 This variant is used for system header files. It searches for a file
306 named @var{file} in a list of directories specified by you, then in a
307 standard list of system directories. You specify directories to
308 search for header files with the command option @samp{-I}
309 (@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching
310 the standard system directories; in this case only the directories
311 you specify are searched.
313 The parsing of this form of @samp{#include} is slightly special
314 because comments are not recognized within the @samp{<@dots{}>}.
315 Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment
316 and the directive specifies inclusion of a system header file named
317 @file{x/*y}. Of course, a header file with such a name is unlikely to
318 exist on Unix, where shell wildcard features would make it hard to
321 The argument @var{file} may not contain a @samp{>} character. It may,
322 however, contain a @samp{<} character.
324 @item #include "@var{file}"
325 This variant is used for header files of your own program. It
326 searches for a file named @var{file} first in the current directory,
327 then in the same directories used for system header files. The
328 current directory is the directory of the current input file. It is
329 tried first because it is presumed to be the location of the files
330 that the current input file refers to. (If the @samp{-I-} option is
331 used, the special treatment of the current directory is inhibited.)
333 The argument @var{file} may not contain @samp{"} characters. If
334 backslashes occur within @var{file}, they are considered ordinary text
335 characters, not escape characters. None of the character escape
336 sequences appropriate to string constants in C are processed. Thus,
337 @samp{#include "x\n\\y"} specifies a filename containing three
338 backslashes. It is not clear why this behavior is ever useful, but
339 the ANSI standard specifies it.
341 @item #include @var{anything else}
342 @cindex computed @samp{#include}
343 This variant is called a @dfn{computed #include}. Any @samp{#include}
344 directive whose argument does not fit the above two forms is a computed
345 include. The text @var{anything else} is checked for macro calls,
346 which are expanded (@pxref{Macros}). When this is done, the result
347 must fit one of the above two variants---in particular, the expanded
348 text must in the end be surrounded by either quotes or angle braces.
350 This feature allows you to define a macro which controls the file name
351 to be used at a later point in the program. One application of this is
352 to allow a site-specific configuration file for your program to specify
353 the names of the system include files to be used. This can help in
354 porting the program to various operating systems in which the necessary
355 system header files are found in different places.
358 @node Include Operation, Once-Only, Include Syntax, Header Files
359 @subsection How @samp{#include} Works
361 The @samp{#include} directive works by directing the C preprocessor to scan
362 the specified file as input before continuing with the rest of the current
363 file. The output from the preprocessor contains the output already
364 generated, followed by the output resulting from the included file,
365 followed by the output that comes from the text after the @samp{#include}
366 directive. For example, given a header file @file{header.h} as follows,
373 and a main program called @file{program.c} that uses the header file,
387 the output generated by the C preprocessor for @file{program.c} as input
400 Included files are not limited to declarations and macro definitions; those
401 are merely the typical uses. Any fragment of a C program can be included
402 from another file. The include file could even contain the beginning of a
403 statement that is concluded in the containing file, or the end of a
404 statement that was started in the including file. However, a comment or a
405 string or character constant may not start in the included file and finish
406 in the including file. An unterminated comment, string constant or
407 character constant in an included file is considered to end (with an error
408 message) at the end of the file.
410 It is possible for a header file to begin or end a syntactic unit such
411 as a function definition, but that would be very confusing, so don't do
414 The line following the @samp{#include} directive is always treated as a
415 separate line by the C preprocessor even if the included file lacks a final
418 @node Once-Only, Inheritance, Include Operation, Header Files
419 @subsection Once-Only Include Files
420 @cindex repeated inclusion
421 @cindex including just once
423 Very often, one header file includes another. It can easily result that a
424 certain header file is included more than once. This may lead to errors,
425 if the header file defines structure types or typedefs, and is certainly
426 wasteful. Therefore, we often wish to prevent multiple inclusion of a
429 The standard way to do this is to enclose the entire real contents of the
430 file in a conditional, like this:
433 #ifndef FILE_FOO_SEEN
434 #define FILE_FOO_SEEN
436 @var{the entire file}
438 #endif /* FILE_FOO_SEEN */
441 The macro @code{FILE_FOO_SEEN} indicates that the file has been included
442 once already. In a user header file, the macro name should not begin
443 with @samp{_}. In a system header file, this name should begin with
444 @samp{__} to avoid conflicts with user programs. In any kind of header
445 file, the macro name should contain the name of the file and some
446 additional text, to avoid conflicts with other header files.
448 The GNU C preprocessor is programmed to notice when a header file uses
449 this particular construct and handle it efficiently. If a header file
450 is contained entirely in a @samp{#ifndef} conditional, then it records
451 that fact. If a subsequent @samp{#include} specifies the same file,
452 and the macro in the @samp{#ifndef} is already defined, then the file
453 is entirely skipped, without even reading it.
456 There is also an explicit directive to tell the preprocessor that it need
457 not include a file more than once. This is called @samp{#pragma once},
458 and was used @emph{in addition to} the @samp{#ifndef} conditional around
459 the contents of the header file. @samp{#pragma once} is now obsolete
460 and should not be used at all.
463 In the Objective C language, there is a variant of @samp{#include}
464 called @samp{#import} which includes a file, but does so at most once.
465 If you use @samp{#import} @emph{instead of} @samp{#include}, then you
466 don't need the conditionals inside the header file to prevent multiple
467 execution of the contents.
469 @samp{#import} is obsolete because it is not a well designed feature.
470 It requires the users of a header file---the applications
471 programmers---to know that a certain header file should only be included
472 once. It is much better for the header file's implementor to write the
473 file so that users don't need to know this. Using @samp{#ifndef}
474 accomplishes this goal.
476 @node Inheritance,, Once-Only, Header Files
477 @subsection Inheritance and Header Files
479 @cindex overriding a header file
481 @dfn{Inheritance} is what happens when one object or file derives some
482 of its contents by virtual copying from another object or file. In
483 the case of C header files, inheritance means that one header file
484 includes another header file and then replaces or adds something.
486 If the inheriting header file and the base header file have different
487 names, then inheritance is straightforward: simply write @samp{#include
488 "@var{base}"} in the inheriting file.
490 Sometimes it is necessary to give the inheriting file the same name as
491 the base file. This is less straightforward.
493 For example, suppose an application program uses the system header file
494 @file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h}
495 on a particular system doesn't do what the application program expects.
496 It might be convenient to define a ``local'' version, perhaps under the
497 name @file{/usr/local/include/sys/signal.h}, to override or add to the
498 one supplied by the system.
500 You can do this by using the option @samp{-I.} for compilation, and
501 writing a file @file{sys/signal.h} that does what the application
502 program expects. But making this file include the standard
503 @file{sys/signal.h} is not so easy---writing @samp{#include
504 <sys/signal.h>} in that file doesn't work, because it includes your own
505 version of the file, not the standard system version. Used in that file
506 itself, this leads to an infinite recursion and a fatal error in
509 @samp{#include </usr/include/sys/signal.h>} would find the proper file,
510 but that is not clean, since it makes an assumption about where the
511 system header file is found. This is bad for maintenance, since it
512 means that any change in where the system's header files are kept
513 requires a change somewhere else.
515 @findex #include_next
516 The clean way to solve this problem is to use
517 @samp{#include_next}, which means, ``Include the @emph{next} file with
518 this name.'' This directive works like @samp{#include} except in
519 searching for the specified file: it starts searching the list of header
520 file directories @emph{after} the directory in which the current file
523 Suppose you specify @samp{-I /usr/local/include}, and the list of
524 directories to search also includes @file{/usr/include}; and suppose that
525 both directories contain a file named @file{sys/signal.h}. Ordinary
526 @samp{#include <sys/signal.h>} finds the file under
527 @file{/usr/local/include}. If that file contains @samp{#include_next
528 <sys/signal.h>}, it starts searching after that directory, and finds the
529 file in @file{/usr/include}.
531 @node Macros, Conditionals, Header Files, Top
534 A macro is a sort of abbreviation which you can define once and then
535 use later. There are many complicated features associated with macros
536 in the C preprocessor.
539 * Simple Macros:: Macros that always expand the same way.
540 * Argument Macros:: Macros that accept arguments that are substituted
541 into the macro expansion.
542 * Predefined:: Predefined macros that are always available.
543 * Stringification:: Macro arguments converted into string constants.
544 * Concatenation:: Building tokens from parts taken from macro arguments.
545 * Undefining:: Cancelling a macro's definition.
546 * Redefining:: Changing a macro's definition.
547 * Macro Pitfalls:: Macros can confuse the unwary. Here we explain
548 several common problems and strange features.
551 @node Simple Macros, Argument Macros, Macros, Macros
552 @subsection Simple Macros
554 @cindex manifest constant
556 A @dfn{simple macro} is a kind of abbreviation. It is a name which
557 stands for a fragment of code. Some people refer to these as
558 @dfn{manifest constants}.
560 Before you can use a macro, you must @dfn{define} it explicitly with the
561 @samp{#define} directive. @samp{#define} is followed by the name of the
562 macro and then the code it should be an abbreviation for. For example,
565 #define BUFFER_SIZE 1020
569 defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text
570 @samp{1020}. If somewhere after this @samp{#define} directive there comes
571 a C statement of the form
574 foo = (char *) xmalloc (BUFFER_SIZE);
578 then the C preprocessor will recognize and @dfn{expand} the macro
579 @samp{BUFFER_SIZE}, resulting in
582 foo = (char *) xmalloc (1020);
585 The use of all upper case for macro names is a standard convention.
586 Programs are easier to read when it is possible to tell at a glance which
589 Normally, a macro definition must be a single line, like all C
590 preprocessing directives. (You can split a long macro definition
591 cosmetically with Backslash-Newline.) There is one exception: Newlines
592 can be included in the macro definition if within a string or character
593 constant. This is because it is not possible for a macro definition to
594 contain an unbalanced quote character; the definition automatically
595 extends to include the matching quote character that ends the string or
596 character constant. Comments within a macro definition may contain
597 Newlines, which make no difference since the comments are entirely
598 replaced with Spaces regardless of their contents.
600 Aside from the above, there is no restriction on what can go in a macro
601 body. Parentheses need not balance. The body need not resemble valid C
602 code. (But if it does not, you may get error messages from the C
603 compiler when you use the macro.)
605 The C preprocessor scans your program sequentially, so macro definitions
606 take effect at the place you write them. Therefore, the following input to
624 After the preprocessor expands a macro name, the macro's definition body is
625 appended to the front of the remaining input, and the check for macro calls
626 continues. Therefore, the macro body can contain calls to other macros.
631 #define TABLESIZE BUFSIZE
635 the name @samp{TABLESIZE} when used in the program would go through two
636 stages of expansion, resulting ultimately in @samp{1020}.
638 This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
639 The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
640 specify---in this case, @samp{BUFSIZE}---and does not check to see whether
641 it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE}
642 that the result of its expansion is checked for more macro names.
643 @xref{Cascaded Macros}.
645 @node Argument Macros, Predefined, Simple Macros, Macros
646 @subsection Macros with Arguments
647 @cindex macros with argument
648 @cindex arguments in macro definitions
649 @cindex function-like macro
651 A simple macro always stands for exactly the same text, each time it is
652 used. Macros can be more flexible when they accept @dfn{arguments}.
653 Arguments are fragments of code that you supply each time the macro is
654 used. These fragments are included in the expansion of the macro
655 according to the directions in the macro definition. A macro that
656 accepts arguments is called a @dfn{function-like macro} because the
657 syntax for using it looks like a function call.
660 To define a macro that uses arguments, you write a @samp{#define} directive
661 with a list of @dfn{argument names} in parentheses after the name of the
662 macro. The argument names may be any valid C identifiers, separated by
663 commas and optionally whitespace. The open-parenthesis must follow the
664 macro name immediately, with no space in between.
666 For example, here is a macro that computes the minimum of two numeric
667 values, as it is defined in many C programs:
670 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
674 (This is not the best way to define a ``minimum'' macro in GNU C.
675 @xref{Side Effects}, for more information.)
677 To use a macro that expects arguments, you write the name of the macro
678 followed by a list of @dfn{actual arguments} in parentheses, separated by
679 commas. The number of actual arguments you give must match the number of
680 arguments the macro expects. Examples of use of the macro @samp{min}
681 include @samp{min (1, 2)} and @samp{min (x + 28, *p)}.
683 The expansion text of the macro depends on the arguments you use.
684 Each of the argument names of the macro is replaced, throughout the
685 macro definition, with the corresponding actual argument. Using the
686 same macro @samp{min} defined above, @samp{min (1, 2)} expands into
689 ((1) < (2) ? (1) : (2))
693 where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}.
695 Likewise, @samp{min (x + 28, *p)} expands into
698 ((x + 28) < (*p) ? (x + 28) : (*p))
701 Parentheses in the actual arguments must balance; a comma within
702 parentheses does not end an argument. However, there is no requirement
703 for brackets or braces to balance, and they do not prevent a comma from
704 separating arguments. Thus,
707 macro (array[x = y, x + 1])
711 passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x +
712 1]}. If you want to supply @samp{array[x = y, x + 1]} as an argument,
713 you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C
716 After the actual arguments are substituted into the macro body, the entire
717 result is appended to the front of the remaining input, and the check for
718 macro calls continues. Therefore, the actual arguments can contain calls
719 to other macros, either with or without arguments, or even to the same
720 macro. The macro body can also contain calls to other macros. For
721 example, @samp{min (min (a, b), c)} expands into this text:
724 ((((a) < (b) ? (a) : (b))) < (c)
725 ? (((a) < (b) ? (a) : (b)))
730 (Line breaks shown here for clarity would not actually be generated.)
732 @cindex blank macro arguments
733 @cindex space as macro argument
734 If a macro @code{foo} takes one argument, and you want to supply an
735 empty argument, you must write at least some whitespace between the
736 parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing
737 no arguments, which is an error if @code{foo} expects an argument. But
738 @samp{foo0 ()} is the correct way to call a macro defined to take zero
739 arguments, like this:
742 #define foo0() @dots{}
745 If you use the macro name followed by something other than an
746 open-parenthesis (after ignoring any spaces, tabs and comments that
747 follow), it is not a call to the macro, and the preprocessor does not
748 change what you have written. Therefore, it is possible for the same name
749 to be a variable or function in your program as well as a macro, and you
750 can choose in each instance whether to refer to the macro (if an actual
751 argument list follows) or the variable or function (if an argument list
754 Such dual use of one name could be confusing and should be avoided
755 except when the two meanings are effectively synonymous: that is, when the
756 name is both a macro and a function and the two have similar effects. You
757 can think of the name simply as a function; use of the name for purposes
758 other than calling it (such as, to take the address) will refer to the
759 function, while calls will expand the macro and generate better but
760 equivalent code. For example, you can use a function named @samp{min} in
761 the same source file that defines the macro. If you write @samp{&min} with
762 no argument list, you refer to the function. If you write @samp{min (x,
763 bb)}, with an argument list, the macro is expanded. If you write
764 @samp{(min) (a, bb)}, where the name @samp{min} is not followed by an
765 open-parenthesis, the macro is not expanded, so you wind up with a call to
766 the function @samp{min}.
768 You may not define the same name as both a simple macro and a macro with
771 In the definition of a macro with arguments, the list of argument names
772 must follow the macro name immediately with no space in between. If there
773 is a space after the macro name, the macro is defined as taking no
774 arguments, and all the rest of the line is taken to be the expansion. The
775 reason for this is that it is often useful to define a macro that takes no
776 arguments and whose definition begins with an identifier in parentheses.
777 This rule about spaces makes it possible for you to do either this:
780 #define FOO(x) - 1 / (x)
784 (which defines @samp{FOO} to take an argument and expand into minus the
785 reciprocal of that argument) or this:
788 #define BAR (x) - 1 / (x)
792 (which defines @samp{BAR} to take no argument and always expand into
793 @samp{(x) - 1 / (x)}).
795 Note that the @emph{uses} of a macro with arguments can have spaces before
796 the left parenthesis; it's the @emph{definition} where it matters whether
799 @node Predefined, Stringification, Argument Macros, Macros
800 @subsection Predefined Macros
802 @cindex predefined macros
803 Several simple macros are predefined. You can use them without giving
804 definitions for them. They fall into two classes: standard macros and
805 system-specific macros.
808 * Standard Predefined:: Standard predefined macros.
809 * Nonstandard Predefined:: Nonstandard predefined macros.
812 @node Standard Predefined, Nonstandard Predefined, Predefined, Predefined
813 @subsubsection Standard Predefined Macros
814 @cindex standard predefined macros
816 The standard predefined macros are available with the same meanings
817 regardless of the machine or operating system on which you are using GNU C.
818 Their names all start and end with double underscores. Those preceding
819 @code{__GNUC__} in this table are standardized by ANSI C; the rest are
825 This macro expands to the name of the current input file, in the form of
826 a C string constant. The precise name returned is the one that was
827 specified in @samp{#include} or as the input file name argument.
831 This macro expands to the current input line number, in the form of a
832 decimal integer constant. While we call it a predefined macro, it's
833 a pretty strange macro, since its ``definition'' changes with each
834 new line of source code.
836 This and @samp{__FILE__} are useful in generating an error message to
837 report an inconsistency detected by the program; the message can state
838 the source line at which the inconsistency was detected. For example,
841 fprintf (stderr, "Internal error: "
842 "negative string length "
843 "%d at %s, line %d.",
844 length, __FILE__, __LINE__);
847 A @samp{#include} directive changes the expansions of @samp{__FILE__}
848 and @samp{__LINE__} to correspond to the included file. At the end of
849 that file, when processing resumes on the input file that contained
850 the @samp{#include} directive, the expansions of @samp{__FILE__} and
851 @samp{__LINE__} revert to the values they had before the
852 @samp{#include} (but @samp{__LINE__} is then incremented by one as
853 processing moves to the line after the @samp{#include}).
855 The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered
856 if a @samp{#line} directive is used. @xref{Combining Sources}.
860 This macro expands to a string constant that describes the date on
861 which the preprocessor is being run. The string constant contains
862 eleven characters and looks like @w{@samp{"Feb 1 1996"}}.
863 @c After reformatting the above, check that the date remains `Feb 1 1996',
864 @c all on one line, with two spaces between the `Feb' and the `1'.
868 This macro expands to a string constant that describes the time at
869 which the preprocessor is being run. The string constant contains
870 eight characters and looks like @samp{"23:59:01"}.
874 This macro expands to the constant 1, to signify that this is ANSI
875 Standard C. (Whether that is actually true depends on what C compiler
876 will operate on the output from the preprocessor.)
878 @item __STDC_VERSION__
879 @findex __STDC_VERSION__
880 This macro expands to the C Standard's version number,
881 a long integer constant of the form @samp{@var{yyyy}@var{mm}L}
882 where @var{yyyy} and @var{mm} are the year and month of the Standard version.
883 This signifies which version of the C Standard the preprocessor conforms to.
884 Like @samp{__STDC__}, whether this version number is accurate
885 for the entire implementation depends on what C compiler
886 will operate on the output from the preprocessor.
890 This macro is defined if and only if this is GNU C. This macro is
891 defined only when the entire GNU C compiler is in use; if you invoke the
892 preprocessor directly, @samp{__GNUC__} is undefined. The value
893 identifies the major version number of GNU CC (@samp{1} for GNU CC
894 version 1, which is now obsolete, and @samp{2} for version 2).
897 @findex __GNUC_MINOR__
898 The macro contains the minor version number of the compiler. This can
899 be used to work around differences between different releases of the
900 compiler (for example, if gcc 2.6.3 is known to support a feature, you
901 can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}).
902 The last number, @samp{3} in the
903 example above, denotes the bugfix level of the compiler; no macro
908 The GNU C compiler defines this when the compilation language is
909 C++; use @samp{__GNUG__} to distinguish between GNU C and GNU
914 The draft ANSI standard for C++ used to require predefining this
915 variable. Though it is no longer required, GNU C++ continues to define
916 it, as do other popular C++ compilers. You can use @samp{__cplusplus}
917 to test whether a header is compiled by a C compiler or a C++ compiler.
919 @item __STRICT_ANSI__
920 @findex __STRICT_ANSI__
921 This macro is defined if and only if the @samp{-ansi} switch was
922 specified when GNU C was invoked. Its definition is the null string.
923 This macro exists primarily to direct certain GNU header files not to
924 define certain traditional Unix constructs which are incompatible with
928 @findex __BASE_FILE__
929 This macro expands to the name of the main input file, in the form
930 of a C string constant. This is the source file that was specified
931 as an argument when the C compiler was invoked.
933 @item __INCLUDE_LEVEL__
934 @findex __INCLUDE_LEVEL_
935 This macro expands to a decimal integer constant that represents the
936 depth of nesting in include files. The value of this macro is
937 incremented on every @samp{#include} directive and decremented at every
938 end of file. For input files specified by command line arguments,
939 the nesting level is zero.
943 This macro expands to a string which describes the version number of
944 GNU C. The string is normally a sequence of decimal numbers separated
945 by periods, such as @samp{"2.6.0"}. The only reasonable use of this
946 macro is to incorporate it into a string constant.
950 This macro is defined in optimizing compilations. It causes certain
951 GNU header files to define alternative macro definitions for some
952 system library functions. It is unwise to refer to or test the
953 definition of this macro unless you make very sure that programs will
954 execute with the same effect regardless.
956 @item __CHAR_UNSIGNED__
957 @findex __CHAR_UNSIGNED__
958 This macro is defined if and only if the data type @code{char} is
959 unsigned on the target machine. It exists to cause the standard
960 header file @file{limit.h} to work correctly. It is bad practice
961 to refer to this macro yourself; instead, refer to the standard
962 macros defined in @file{limit.h}. The preprocessor uses
963 this macro to determine whether or not to sign-extend large character
964 constants written in octal; see @ref{#if Directive,,The @samp{#if} Directive}.
966 @item __REGISTER_PREFIX__
967 @findex __REGISTER_PREFIX__
968 This macro expands to a string describing the prefix applied to cpu
969 registers in assembler code. It can be used to write assembler code
970 that is usable in multiple environments. For example, in the
971 @samp{m68k-aout} environment it expands to the string @samp{""},
972 but in the @samp{m68k-coff} environment it expands to the string
975 @item __USER_LABEL_PREFIX__
976 @findex __USER_LABEL_PREFIX__
977 This macro expands to a string describing the prefix applied to user
978 generated labels in assembler code. It can be used to write assembler
979 code that is usable in multiple environments. For example, in the
980 @samp{m68k-aout} environment it expands to the string @samp{"_"}, but in
981 the @samp{m68k-coff} environment it expands to the string @samp{""}.
982 This does not work with the @samp{-mno-underscores} option that the
983 i386 OSF/rose and m88k targets provide nor with the @samp{-mcall*} options
984 of the rs6000 System V Release 4 target.
987 @node Nonstandard Predefined,, Standard Predefined, Predefined
988 @subsubsection Nonstandard Predefined Macros
990 The C preprocessor normally has several predefined macros that vary between
991 machines because their purpose is to indicate what type of system and
992 machine is in use. This manual, being for all systems and machines, cannot
993 tell you exactly what their names are; instead, we offer a list of some
994 typical ones. You can use @samp{cpp -dM} to see the values of
995 predefined macros; see @ref{Invocation}.
997 Some nonstandard predefined macros describe the operating system in use,
998 with more or less specificity. For example,
1003 @samp{unix} is normally predefined on all Unix systems.
1007 @samp{BSD} is predefined on recent versions of Berkeley Unix
1008 (perhaps only in version 4.3).
1011 Other nonstandard predefined macros describe the kind of CPU, with more or
1012 less specificity. For example,
1017 @samp{vax} is predefined on Vax computers.
1021 @samp{mc68000} is predefined on most computers whose CPU is a Motorola
1022 68000, 68010 or 68020.
1026 @samp{m68k} is also predefined on most computers whose CPU is a 68000,
1027 68010 or 68020; however, some makers use @samp{mc68000} and some use
1028 @samp{m68k}. Some predefine both names. What happens in GNU C
1029 depends on the system you are using it on.
1033 @samp{M68020} has been observed to be predefined on some systems that
1034 use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which
1041 Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000
1046 @samp{ns32000} is predefined on computers which use the National
1047 Semiconductor 32000 series CPU.
1050 Yet other nonstandard predefined macros describe the manufacturer of
1051 the system. For example,
1056 @samp{sun} is predefined on all models of Sun computers.
1060 @samp{pyr} is predefined on all models of Pyramid computers.
1064 @samp{sequent} is predefined on all models of Sequent computers.
1067 These predefined symbols are not only nonstandard, they are contrary to the
1068 ANSI standard because their names do not start with underscores.
1069 Therefore, the option @samp{-ansi} inhibits the definition of these
1072 This tends to make @samp{-ansi} useless, since many programs depend on the
1073 customary nonstandard predefined symbols. Even system header files check
1074 them and will generate incorrect declarations if they do not find the names
1075 that are expected. You might think that the header files supplied for the
1076 Uglix computer would not need to test what machine they are running on,
1077 because they can simply assume it is the Uglix; but often they do, and they
1078 do so using the customary names. As a result, very few C programs will
1079 compile with @samp{-ansi}. We intend to avoid such problems on the GNU
1082 What, then, should you do in an ANSI C program to test the type of machine
1085 GNU C offers a parallel series of symbols for this purpose, whose names
1086 are made from the customary ones by adding @samp{__} at the beginning
1087 and end. Thus, the symbol @code{__vax__} would be available on a Vax,
1090 The set of nonstandard predefined names in the GNU C preprocessor is
1091 controlled (when @code{cpp} is itself compiled) by the macro
1092 @samp{CPP_PREDEFINES}, which should be a string containing @samp{-D}
1093 options, separated by spaces. For example, on the Sun 3, we use the
1094 following definition:
1097 #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
1101 This macro is usually specified in @file{tm.h}.
1103 @node Stringification, Concatenation, Predefined, Macros
1104 @subsection Stringification
1106 @cindex stringification
1107 @dfn{Stringification} means turning a code fragment into a string constant
1108 whose contents are the text for the code fragment. For example,
1109 stringifying @samp{foo (z)} results in @samp{"foo (z)"}.
1111 In the C preprocessor, stringification is an option available when macro
1112 arguments are substituted into the macro definition. In the body of the
1113 definition, when an argument name appears, the character @samp{#} before
1114 the name specifies stringification of the corresponding actual argument
1115 when it is substituted at that point in the definition. The same argument
1116 may be substituted in other places in the definition without
1117 stringification if the argument name appears in those places with no
1120 Here is an example of a macro definition that uses stringification:
1124 #define WARN_IF(EXP) \
1126 fprintf (stderr, "Warning: " #EXP "\n"); @} \
1132 Here the actual argument for @samp{EXP} is substituted once as given,
1133 into the @samp{if} statement, and once as stringified, into the
1134 argument to @samp{fprintf}. The @samp{do} and @samp{while (0)} are
1135 a kludge to make it possible to write @samp{WARN_IF (@var{arg});},
1136 which the resemblance of @samp{WARN_IF} to a function would make
1137 C programmers want to do; see @ref{Swallow Semicolon}.
1139 The stringification feature is limited to transforming one macro argument
1140 into one string constant: there is no way to combine the argument with
1141 other text and then stringify it all together. But the example above shows
1142 how an equivalent result can be obtained in ANSI Standard C using the
1143 feature that adjacent string constants are concatenated as one string
1144 constant. The preprocessor stringifies the actual value of @samp{EXP}
1145 into a separate string constant, resulting in text like
1150 fprintf (stderr, "Warning: " "x == 0" "\n"); @} \
1156 but the C compiler then sees three consecutive string constants and
1157 concatenates them into one, producing effectively
1161 fprintf (stderr, "Warning: x == 0\n"); @} \
1165 Stringification in C involves more than putting doublequote characters
1166 around the fragment; it is necessary to put backslashes in front of all
1167 doublequote characters, and all backslashes in string and character
1168 constants, in order to get a valid C string constant with the proper
1169 contents. Thus, stringifying @samp{p = "foo\n";} results in @samp{"p =
1170 \"foo\\n\";"}. However, backslashes that are not inside of string or
1171 character constants are not duplicated: @samp{\n} by itself stringifies to
1174 Whitespace (including comments) in the text being stringified is handled
1175 according to precise rules. All leading and trailing whitespace is ignored.
1176 Any sequence of whitespace in the middle of the text is converted to
1177 a single space in the stringified result.
1179 @node Concatenation, Undefining, Stringification, Macros
1180 @subsection Concatenation
1181 @cindex concatenation
1183 @dfn{Concatenation} means joining two strings into one. In the context
1184 of macro expansion, concatenation refers to joining two lexical units
1185 into one longer one. Specifically, an actual argument to the macro can be
1186 concatenated with another actual argument or with fixed text to produce
1187 a longer name. The longer name might be the name of a function,
1188 variable or type, or a C keyword; it might even be the name of another
1189 macro, in which case it will be expanded.
1191 When you define a macro, you request concatenation with the special
1192 operator @samp{##} in the macro body. When the macro is called,
1193 after actual arguments are substituted, all @samp{##} operators are
1194 deleted, and so is any whitespace next to them (including whitespace
1195 that was part of an actual argument). The result is to concatenate
1196 the syntactic tokens on either side of the @samp{##}.
1198 Consider a C program that interprets named commands. There probably needs
1199 to be a table of commands, perhaps an array of structures declared as
1206 void (*function) ();
1209 struct command commands[] =
1211 @{ "quit", quit_command@},
1212 @{ "help", help_command@},
1217 It would be cleaner not to have to give each command name twice, once in
1218 the string constant and once in the function name. A macro which takes the
1219 name of a command as an argument can make this unnecessary. The string
1220 constant can be created with stringification, and the function name by
1221 concatenating the argument with @samp{_command}. Here is how it is done:
1224 #define COMMAND(NAME) @{ #NAME, NAME ## _command @}
1226 struct command commands[] =
1234 The usual case of concatenation is concatenating two names (or a name and a
1235 number) into a longer name. But this isn't the only valid case. It is
1236 also possible to concatenate two numbers (or a number and a name, such as
1237 @samp{1.5} and @samp{e3}) into a number. Also, multi-character operators
1238 such as @samp{+=} can be formed by concatenation. In some cases it is even
1239 possible to piece together a string constant. However, two pieces of text
1240 that don't together form a valid lexical unit cannot be concatenated. For
1241 example, concatenation with @samp{x} on one side and @samp{+} on the other
1242 is not meaningful because those two characters can't fit together in any
1243 lexical unit of C. The ANSI standard says that such attempts at
1244 concatenation are undefined, but in the GNU C preprocessor it is well
1245 defined: it puts the @samp{x} and @samp{+} side by side with no particular
1248 Keep in mind that the C preprocessor converts comments to whitespace before
1249 macros are even considered. Therefore, you cannot create a comment by
1250 concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a
1251 comment is not a lexical unit, but rather the beginning of a ``long'' space
1252 character. Also, you can freely use comments next to a @samp{##} in a
1253 macro definition, or in actual arguments that will be concatenated, because
1254 the comments will be converted to spaces at first sight, and concatenation
1255 will later discard the spaces.
1257 @node Undefining, Redefining, Concatenation, Macros
1258 @subsection Undefining Macros
1260 @cindex undefining macros
1261 To @dfn{undefine} a macro means to cancel its definition. This is done
1262 with the @samp{#undef} directive. @samp{#undef} is followed by the macro
1263 name to be undefined.
1265 Like definition, undefinition occurs at a specific point in the source
1266 file, and it applies starting from that point. The name ceases to be a
1267 macro name, and from that point on it is treated by the preprocessor as if
1268 it had never been a macro name.
1289 In this example, @samp{FOO} had better be a variable or function as well
1290 as (temporarily) a macro, in order for the result of the expansion to be
1293 The same form of @samp{#undef} directive will cancel definitions with
1294 arguments or definitions that don't expect arguments. The @samp{#undef}
1295 directive has no effect when used on a name not currently defined as a macro.
1297 @node Redefining, Macro Pitfalls, Undefining, Macros
1298 @subsection Redefining Macros
1300 @cindex redefining macros
1301 @dfn{Redefining} a macro means defining (with @samp{#define}) a name that
1302 is already defined as a macro.
1304 A redefinition is trivial if the new definition is transparently identical
1305 to the old one. You probably wouldn't deliberately write a trivial
1306 redefinition, but they can happen automatically when a header file is
1307 included more than once (@pxref{Header Files}), so they are accepted
1308 silently and without effect.
1310 Nontrivial redefinition is considered likely to be an error, so
1311 it provokes a warning message from the preprocessor. However, sometimes it
1312 is useful to change the definition of a macro in mid-compilation. You can
1313 inhibit the warning by undefining the macro with @samp{#undef} before the
1316 In order for a redefinition to be trivial, the new definition must
1317 exactly match the one already in effect, with two possible exceptions:
1321 Whitespace may be added or deleted at the beginning or the end.
1324 Whitespace may be changed in the middle (but not inside strings).
1325 However, it may not be eliminated entirely, and it may not be added
1326 where there was no whitespace at all.
1329 Recall that a comment counts as whitespace.
1331 @node Macro Pitfalls,, Redefining, Macros
1332 @subsection Pitfalls and Subtleties of Macros
1333 @cindex problems with macros
1334 @cindex pitfalls of macros
1336 In this section we describe some special rules that apply to macros and
1337 macro expansion, and point out certain cases in which the rules have
1338 counterintuitive consequences that you must watch out for.
1341 * Misnesting:: Macros can contain unmatched parentheses.
1342 * Macro Parentheses:: Why apparently superfluous parentheses
1343 may be necessary to avoid incorrect grouping.
1344 * Swallow Semicolon:: Macros that look like functions
1345 but expand into compound statements.
1346 * Side Effects:: Unsafe macros that cause trouble when
1347 arguments contain side effects.
1348 * Self-Reference:: Macros whose definitions use the macros' own names.
1349 * Argument Prescan:: Actual arguments are checked for macro calls
1350 before they are substituted.
1351 * Cascaded Macros:: Macros whose definitions use other macros.
1352 * Newlines in Args:: Sometimes line numbers get confused.
1355 @node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls
1356 @subsubsection Improperly Nested Constructs
1358 Recall that when a macro is called with arguments, the arguments are
1359 substituted into the macro body and the result is checked, together with
1360 the rest of the input file, for more macro calls.
1362 It is possible to piece together a macro call coming partially from the
1363 macro body and partially from the actual arguments. For example,
1366 #define double(x) (2*(x))
1367 #define call_with_1(x) x(1)
1371 would expand @samp{call_with_1 (double)} into @samp{(2*(1))}.
1373 Macro definitions do not have to have balanced parentheses. By writing an
1374 unbalanced open parenthesis in a macro body, it is possible to create a
1375 macro call that begins inside the macro body but ends outside of it. For
1379 #define strange(file) fprintf (file, "%s %d",
1381 strange(stderr) p, 35)
1385 This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}!
1387 @node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls
1388 @subsubsection Unintended Grouping of Arithmetic
1389 @cindex parentheses in macro bodies
1391 You may have noticed that in most of the macro definition examples shown
1392 above, each occurrence of a macro argument name had parentheses around it.
1393 In addition, another pair of parentheses usually surround the entire macro
1394 definition. Here is why it is best to write macros that way.
1396 Suppose you define a macro as follows,
1399 #define ceil_div(x, y) (x + y - 1) / y
1403 whose purpose is to divide, rounding up. (One use for this operation is
1404 to compute how many @samp{int} objects are needed to hold a certain
1405 number of @samp{char} objects.) Then suppose it is used as follows:
1408 a = ceil_div (b & c, sizeof (int));
1415 a = (b & c + sizeof (int) - 1) / sizeof (int);
1419 which does not do what is intended. The operator-precedence rules of
1420 C make it equivalent to this:
1423 a = (b & (c + sizeof (int) - 1)) / sizeof (int);
1427 But what we want is this:
1430 a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
1434 Defining the macro as
1437 #define ceil_div(x, y) ((x) + (y) - 1) / (y)
1441 provides the desired result.
1443 However, unintended grouping can result in another way. Consider
1444 @samp{sizeof ceil_div(1, 2)}. That has the appearance of a C expression
1445 that would compute the size of the type of @samp{ceil_div (1, 2)}, but in
1446 fact it means something very different. Here is what it expands to:
1449 sizeof ((1) + (2) - 1) / (2)
1453 This would take the size of an integer and divide it by two. The precedence
1454 rules have put the division outside the @samp{sizeof} when it was intended
1457 Parentheses around the entire macro definition can prevent such problems.
1458 Here, then, is the recommended way to define @samp{ceil_div}:
1461 #define ceil_div(x, y) (((x) + (y) - 1) / (y))
1464 @node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls
1465 @subsubsection Swallowing the Semicolon
1467 @cindex semicolons (after macro calls)
1468 Often it is desirable to define a macro that expands into a compound
1469 statement. Consider, for example, the following macro, that advances a
1470 pointer (the argument @samp{p} says where to find it) across whitespace
1474 #define SKIP_SPACES (p, limit) \
1475 @{ register char *lim = (limit); \
1476 while (p != lim) @{ \
1477 if (*p++ != ' ') @{ \
1482 Here Backslash-Newline is used to split the macro definition, which must
1483 be a single line, so that it resembles the way such C code would be
1484 laid out if not part of a macro definition.
1486 A call to this macro might be @samp{SKIP_SPACES (p, lim)}. Strictly
1487 speaking, the call expands to a compound statement, which is a complete
1488 statement with no need for a semicolon to end it. But it looks like a
1489 function call. So it minimizes confusion if you can use it like a function
1490 call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);}
1492 But this can cause trouble before @samp{else} statements, because the
1493 semicolon is actually a null statement. Suppose you write
1497 SKIP_SPACES (p, lim);
1502 The presence of two statements---the compound statement and a null
1503 statement---in between the @samp{if} condition and the @samp{else}
1504 makes invalid C code.
1506 The definition of the macro @samp{SKIP_SPACES} can be altered to solve
1507 this problem, using a @samp{do @dots{} while} statement. Here is how:
1510 #define SKIP_SPACES (p, limit) \
1511 do @{ register char *lim = (limit); \
1512 while (p != lim) @{ \
1513 if (*p++ != ' ') @{ \
1514 p--; break; @}@}@} \
1518 Now @samp{SKIP_SPACES (p, lim);} expands into
1521 do @{@dots{}@} while (0);
1525 which is one statement.
1527 @node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls
1528 @subsubsection Duplication of Side Effects
1530 @cindex side effects (in macro arguments)
1531 @cindex unsafe macros
1532 Many C programs define a macro @samp{min}, for ``minimum'', like this:
1535 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1538 When you use this macro with an argument containing a side effect,
1542 next = min (x + y, foo (z));
1546 it expands as follows:
1549 next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
1553 where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)}
1556 The function @samp{foo} is used only once in the statement as it appears
1557 in the program, but the expression @samp{foo (z)} has been substituted
1558 twice into the macro expansion. As a result, @samp{foo} might be called
1559 two times when the statement is executed. If it has side effects or
1560 if it takes a long time to compute, the results might not be what you
1561 intended. We say that @samp{min} is an @dfn{unsafe} macro.
1563 The best solution to this problem is to define @samp{min} in a way that
1564 computes the value of @samp{foo (z)} only once. The C language offers no
1565 standard way to do this, but it can be done with GNU C extensions as
1570 (@{ typeof (X) __x = (X), __y = (Y); \
1571 (__x < __y) ? __x : __y; @})
1574 If you do not wish to use GNU C extensions, the only solution is to be
1575 careful when @emph{using} the macro @samp{min}. For example, you can
1576 calculate the value of @samp{foo (z)}, save it in a variable, and use that
1577 variable in @samp{min}:
1580 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1584 next = min (x + y, tem);
1589 (where we assume that @samp{foo} returns type @samp{int}).
1591 @node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls
1592 @subsubsection Self-Referential Macros
1594 @cindex self-reference
1595 A @dfn{self-referential} macro is one whose name appears in its definition.
1596 A special feature of ANSI Standard C is that the self-reference is not
1597 considered a macro call. It is passed into the preprocessor output
1600 Let's consider an example:
1603 #define foo (4 + foo)
1607 where @samp{foo} is also a variable in your program.
1609 Following the ordinary rules, each reference to @samp{foo} will expand into
1610 @samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4
1611 + (4 + foo))}; and so on until it causes a fatal error (memory full) in the
1614 However, the special rule about self-reference cuts this process short
1615 after one step, at @samp{(4 + foo)}. Therefore, this macro definition
1616 has the possibly useful effect of causing the program to add 4 to
1617 the value of @samp{foo} wherever @samp{foo} is referred to.
1619 In most cases, it is a bad idea to take advantage of this feature. A
1620 person reading the program who sees that @samp{foo} is a variable will
1621 not expect that it is a macro as well. The reader will come across the
1622 identifier @samp{foo} in the program and think its value should be that
1623 of the variable @samp{foo}, whereas in fact the value is four greater.
1625 The special rule for self-reference applies also to @dfn{indirect}
1626 self-reference. This is the case where a macro @var{x} expands to use a
1627 macro @samp{y}, and the expansion of @samp{y} refers to the macro
1628 @samp{x}. The resulting reference to @samp{x} comes indirectly from the
1629 expansion of @samp{x}, so it is a self-reference and is not further
1630 expanded. Thus, after
1638 @samp{x} would expand into @samp{(4 + (2 * x))}. Clear?
1640 But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}.
1641 Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference
1642 because @samp{x} is not ``in progress''. So it does expand. However,
1643 the expansion of @samp{x} contains a reference to @samp{y}, and that
1644 is an indirect self-reference now because @samp{y} is ``in progress''.
1645 The result is that @samp{y} expands to @samp{(2 * (4 + y))}.
1647 It is not clear that this behavior would ever be useful, but it is specified
1648 by the ANSI C standard, so you may need to understand it.
1650 @node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls
1651 @subsubsection Separate Expansion of Macro Arguments
1652 @cindex expansion of arguments
1653 @cindex macro argument expansion
1654 @cindex prescan of macro arguments
1656 We have explained that the expansion of a macro, including the substituted
1657 actual arguments, is scanned over again for macro calls to be expanded.
1659 What really happens is more subtle: first each actual argument text is scanned
1660 separately for macro calls. Then the results of this are substituted into
1661 the macro body to produce the macro expansion, and the macro expansion
1662 is scanned again for macros to expand.
1664 The result is that the actual arguments are scanned @emph{twice} to expand
1665 macro calls in them.
1667 Most of the time, this has no effect. If the actual argument contained
1668 any macro calls, they are expanded during the first scan. The result
1669 therefore contains no macro calls, so the second scan does not change it.
1670 If the actual argument were substituted as given, with no prescan,
1671 the single remaining scan would find the same macro calls and produce
1674 You might expect the double scan to change the results when a
1675 self-referential macro is used in an actual argument of another macro
1676 (@pxref{Self-Reference}): the self-referential macro would be expanded once
1677 in the first scan, and a second time in the second scan. But this is not
1678 what happens. The self-references that do not expand in the first scan are
1679 marked so that they will not expand in the second scan either.
1681 The prescan is not done when an argument is stringified or concatenated.
1691 expands to @samp{"foo"}. Once more, prescan has been prevented from
1692 having any noticeable effect.
1694 More precisely, stringification and concatenation use the argument as
1695 written, in un-prescanned form. The same actual argument would be used in
1696 prescanned form if it is substituted elsewhere without stringification or
1700 #define str(s) #s lose(s)
1705 expands to @samp{"foo" lose(4)}.
1707 You might now ask, ``Why mention the prescan, if it makes no difference?
1708 And why not skip it and make the preprocessor faster?'' The answer is
1709 that the prescan does make a difference in three special cases:
1713 Nested calls to a macro.
1716 Macros that call other macros that stringify or concatenate.
1719 Macros whose expansions contain unshielded commas.
1722 We say that @dfn{nested} calls to a macro occur when a macro's actual
1723 argument contains a call to that very macro. For example, if @samp{f}
1724 is a macro that expects one argument, @samp{f (f (1))} is a nested
1725 pair of calls to @samp{f}. The desired expansion is made by
1726 expanding @samp{f (1)} and substituting that into the definition of
1727 @samp{f}. The prescan causes the expected result to happen.
1728 Without the prescan, @samp{f (1)} itself would be substituted as
1729 an actual argument, and the inner use of @samp{f} would appear
1730 during the main scan as an indirect self-reference and would not
1731 be expanded. Here, the prescan cancels an undesirable side effect
1732 (in the medical, not computational, sense of the term) of the special
1733 rule for self-referential macros.
1735 But prescan causes trouble in certain other cases of nested macro calls.
1740 #define bar(x) lose(x)
1741 #define lose(x) (1 + (x))
1747 We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which
1748 would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)}
1749 expands into @samp{lose(a,b)}, and you get an error because @code{lose}
1750 requires a single argument. In this case, the problem is easily solved
1751 by the same parentheses that ought to be used to prevent misnesting of
1752 arithmetic operations:
1756 #define bar(x) lose((x))
1759 The problem is more serious when the operands of the macro are not
1760 expressions; for example, when they are statements. Then parentheses
1761 are unacceptable because they would make for invalid C code:
1764 #define foo @{ int a, b; @dots{} @}
1768 In GNU C you can shield the commas using the @samp{(@{@dots{}@})}
1769 construct which turns a compound statement into an expression:
1772 #define foo (@{ int a, b; @dots{} @})
1775 Or you can rewrite the macro definition to avoid such commas:
1778 #define foo @{ int a; int b; @dots{} @}
1781 There is also one case where prescan is useful. It is possible
1782 to use prescan to expand an argument and then stringify it---if you use
1783 two levels of macros. Let's add a new macro @samp{xstr} to the
1784 example shown above:
1787 #define xstr(s) str(s)
1793 This expands into @samp{"4"}, not @samp{"foo"}. The reason for the
1794 difference is that the argument of @samp{xstr} is expanded at prescan
1795 (because @samp{xstr} does not specify stringification or concatenation of
1796 the argument). The result of prescan then forms the actual argument for
1797 @samp{str}. @samp{str} uses its argument without prescan because it
1798 performs stringification; but it cannot prevent or undo the prescanning
1799 already done by @samp{xstr}.
1801 @node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls
1802 @subsubsection Cascaded Use of Macros
1804 @cindex cascaded macros
1805 @cindex macro body uses macro
1806 A @dfn{cascade} of macros is when one macro's body contains a reference
1807 to another macro. This is very common practice. For example,
1810 #define BUFSIZE 1020
1811 #define TABLESIZE BUFSIZE
1814 This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
1815 The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
1816 specify---in this case, @samp{BUFSIZE}---and does not check to see whether
1817 it too is the name of a macro.
1819 It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion
1820 is checked for more macro names.
1822 This makes a difference if you change the definition of @samp{BUFSIZE}
1823 at some point in the source file. @samp{TABLESIZE}, defined as shown,
1824 will always expand using the definition of @samp{BUFSIZE} that is
1825 currently in effect:
1828 #define BUFSIZE 1020
1829 #define TABLESIZE BUFSIZE
1835 Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The
1836 @samp{#undef} is to prevent any warning about the nontrivial
1837 redefinition of @code{BUFSIZE}.)
1839 @node Newlines in Args,, Cascaded Macros, Macro Pitfalls
1840 @subsection Newlines in Macro Arguments
1841 @cindex newlines in macro arguments
1843 Traditional macro processing carries forward all newlines in macro
1844 arguments into the expansion of the macro. This means that, if some of
1845 the arguments are substituted more than once, or not at all, or out of
1846 order, newlines can be duplicated, lost, or moved around within the
1847 expansion. If the expansion consists of multiple statements, then the
1848 effect is to distort the line numbers of some of these statements. The
1849 result can be incorrect line numbers, in error messages or displayed in
1852 The GNU C preprocessor operating in ANSI C mode adjusts appropriately
1853 for multiple use of an argument---the first use expands all the
1854 newlines, and subsequent uses of the same argument produce no newlines.
1855 But even in this mode, it can produce incorrect line numbering if
1856 arguments are used out of order, or not used at all.
1858 Here is an example illustrating this problem:
1861 #define ignore_second_arg(a,b,c) a; c
1863 ignore_second_arg (foo (),
1869 The syntax error triggered by the tokens @samp{syntax error} results
1870 in an error message citing line four, even though the statement text
1871 comes from line five.
1873 @node Conditionals, Combining Sources, Macros, Top
1874 @section Conditionals
1876 @cindex conditionals
1877 In a macro processor, a @dfn{conditional} is a directive that allows a part
1878 of the program to be ignored during compilation, on some conditions.
1879 In the C preprocessor, a conditional can test either an arithmetic expression
1880 or whether a name is defined as a macro.
1882 A conditional in the C preprocessor resembles in some ways an @samp{if}
1883 statement in C, but it is important to understand the difference between
1884 them. The condition in an @samp{if} statement is tested during the execution
1885 of your program. Its purpose is to allow your program to behave differently
1886 from run to run, depending on the data it is operating on. The condition
1887 in a preprocessing conditional directive is tested when your program is compiled.
1888 Its purpose is to allow different code to be included in the program depending
1889 on the situation at the time of compilation.
1892 * Uses: Conditional Uses. What conditionals are for.
1893 * Syntax: Conditional Syntax. How conditionals are written.
1894 * Deletion: Deleted Code. Making code into a comment.
1895 * Macros: Conditionals-Macros. Why conditionals are used with macros.
1896 * Assertions:: How and why to use assertions.
1897 * Errors: #error Directive. Detecting inconsistent compilation parameters.
1900 @node Conditional Uses
1901 @subsection Why Conditionals are Used
1903 Generally there are three kinds of reason to use a conditional.
1907 A program may need to use different code depending on the machine or
1908 operating system it is to run on. In some cases the code for one
1909 operating system may be erroneous on another operating system; for
1910 example, it might refer to library routines that do not exist on the
1911 other system. When this happens, it is not enough to avoid executing
1912 the invalid code: merely having it in the program makes it impossible
1913 to link the program and run it. With a preprocessing conditional, the
1914 offending code can be effectively excised from the program when it is
1918 You may want to be able to compile the same source file into two
1919 different programs. Sometimes the difference between the programs is
1920 that one makes frequent time-consuming consistency checks on its
1921 intermediate data, or prints the values of those data for debugging,
1922 while the other does not.
1925 A conditional whose condition is always false is a good way to exclude
1926 code from the program but keep it as a sort of comment for future
1930 Most simple programs that are intended to run on only one machine will
1931 not need to use preprocessing conditionals.
1933 @node Conditional Syntax
1934 @subsection Syntax of Conditionals
1937 A conditional in the C preprocessor begins with a @dfn{conditional
1938 directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
1939 @xref{Conditionals-Macros}, for information on @samp{#ifdef} and
1940 @samp{#ifndef}; only @samp{#if} is explained here.
1943 * If: #if Directive. Basic conditionals using @samp{#if} and @samp{#endif}.
1944 * Else: #else Directive. Including some text if the condition fails.
1945 * Elif: #elif Directive. Testing several alternative possibilities.
1949 @subsubsection The @samp{#if} Directive
1951 The @samp{#if} directive in its simplest form consists of
1954 #if @var{expression}
1955 @var{controlled text}
1956 #endif /* @var{expression} */
1959 The comment following the @samp{#endif} is not required, but it is a good
1960 practice because it helps people match the @samp{#endif} to the
1961 corresponding @samp{#if}. Such comments should always be used, except in
1962 short conditionals that are not nested. In fact, you can put anything at
1963 all after the @samp{#endif} and it will be ignored by the GNU C preprocessor,
1964 but only comments are acceptable in ANSI Standard C.
1966 @var{expression} is a C expression of integer type, subject to stringent
1967 restrictions. It may contain
1971 Integer constants, which are all regarded as @code{long} or
1972 @code{unsigned long}.
1975 Character constants, which are interpreted according to the character
1976 set and conventions of the machine and operating system on which the
1977 preprocessor is running. The GNU C preprocessor uses the C data type
1978 @samp{char} for these character constants; therefore, whether some
1979 character codes are negative is determined by the C compiler used to
1980 compile the preprocessor. If it treats @samp{char} as signed, then
1981 character codes large enough to set the sign bit will be considered
1982 negative; otherwise, no character code is considered negative.
1985 Arithmetic operators for addition, subtraction, multiplication,
1986 division, bitwise operations, shifts, comparisons, and logical
1987 operations (@samp{&&} and @samp{||}).
1990 Identifiers that are not macros, which are all treated as zero(!).
1993 Macro calls. All macro calls in the expression are expanded before
1994 actual computation of the expression's value begins.
1997 Note that @samp{sizeof} operators and @code{enum}-type values are not allowed.
1998 @code{enum}-type values, like all other identifiers that are not taken
1999 as macro calls and expanded, are treated as zero.
2001 The @var{controlled text} inside of a conditional can include
2002 preprocessing directives. Then the directives inside the conditional are
2003 obeyed only if that branch of the conditional succeeds. The text can
2004 also contain other conditional groups. However, the @samp{#if} and
2005 @samp{#endif} directives must balance.
2007 @node #else Directive
2008 @subsubsection The @samp{#else} Directive
2011 The @samp{#else} directive can be added to a conditional to provide
2012 alternative text to be used if the condition is false. This is what
2016 #if @var{expression}
2018 #else /* Not @var{expression} */
2020 #endif /* Not @var{expression} */
2023 If @var{expression} is nonzero, and thus the @var{text-if-true} is
2024 active, then @samp{#else} acts like a failing conditional and the
2025 @var{text-if-false} is ignored. Contrariwise, if the @samp{#if}
2026 conditional fails, the @var{text-if-false} is considered included.
2028 @node #elif Directive
2029 @subsubsection The @samp{#elif} Directive
2032 One common case of nested conditionals is used to check for more than two
2033 possible alternatives. For example, you might have
2047 Another conditional directive, @samp{#elif}, allows this to be abbreviated
2055 #else /* X != 2 and X != 1*/
2057 #endif /* X != 2 and X != 1*/
2060 @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
2061 middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not
2062 require a matching @samp{#endif} of its own. Like @samp{#if}, the
2063 @samp{#elif} directive includes an expression to be tested.
2065 The text following the @samp{#elif} is processed only if the original
2066 @samp{#if}-condition failed and the @samp{#elif} condition succeeds.
2067 More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif}
2068 group. Then the text after each @samp{#elif} is processed only if the
2069 @samp{#elif} condition succeeds after the original @samp{#if} and any
2070 previous @samp{#elif} directives within it have failed. @samp{#else} is
2071 equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any
2072 number of @samp{#elif} directives, but @samp{#elif} may not follow
2076 @subsection Keeping Deleted Code for Future Reference
2077 @cindex commenting out code
2079 If you replace or delete a part of the program but want to keep the old
2080 code around as a comment for future reference, the easy way to do this
2081 is to put @samp{#if 0} before it and @samp{#endif} after it. This is
2082 better than using comment delimiters @samp{/*} and @samp{*/} since those
2083 won't work if the code already contains comments (C comments do not
2086 This works even if the code being turned off contains conditionals, but
2087 they must be entire conditionals (balanced @samp{#if} and @samp{#endif}).
2089 Conversely, do not use @samp{#if 0} for comments which are not C code.
2090 Use the comment delimiters @samp{/*} and @samp{*/} instead. The
2091 interior of @samp{#if 0} must consist of complete tokens; in particular,
2092 singlequote characters must balance. But comments often contain
2093 unbalanced singlequote characters (known in English as apostrophes).
2094 These confuse @samp{#if 0}. They do not confuse @samp{/*}.
2096 @node Conditionals-Macros
2097 @subsection Conditionals and Macros
2099 Conditionals are useful in connection with macros or assertions, because
2100 those are the only ways that an expression's value can vary from one
2101 compilation to another. A @samp{#if} directive whose expression uses no
2102 macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you
2103 might as well determine which one, by computing the value of the
2104 expression yourself, and then simplify the program.
2106 For example, here is a conditional that tests the expression
2107 @samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro.
2111 printf ("Large buffers!\n");
2112 #endif /* BUFSIZE is large */
2115 (Programmers often wish they could test the size of a variable or data
2116 type in @samp{#if}, but this does not work. The preprocessor does not
2117 understand @code{sizeof}, or typedef names, or even the type keywords
2118 such as @code{int}.)
2121 The special operator @samp{defined} is used in @samp{#if} expressions to
2122 test whether a certain name is defined as a macro. Either @samp{defined
2123 @var{name}} or @samp{defined (@var{name})} is an expression whose value
2124 is 1 if @var{name} is defined as macro at the current point in the
2125 program, and 0 otherwise. For the @samp{defined} operator it makes no
2126 difference what the definition of the macro is; all that matters is
2127 whether there is a definition. Thus, for example,@refill
2130 #if defined (vax) || defined (ns16000)
2134 would succeed if either of the names @samp{vax} and @samp{ns16000} is
2135 defined as a macro. You can test the same condition using assertions
2136 (@pxref{Assertions}), like this:
2139 #if #cpu (vax) || #cpu (ns16000)
2142 If a macro is defined and later undefined with @samp{#undef},
2143 subsequent use of the @samp{defined} operator returns 0, because
2144 the name is no longer defined. If the macro is defined again with
2145 another @samp{#define}, @samp{defined} will recommence returning 1.
2149 Conditionals that test whether just one name is defined are very common,
2150 so there are two special short conditional directives for this case.
2153 @item #ifdef @var{name}
2154 is equivalent to @samp{#if defined (@var{name})}.
2156 @item #ifndef @var{name}
2157 is equivalent to @samp{#if ! defined (@var{name})}.
2160 Macro definitions can vary between compilations for several reasons.
2164 Some macros are predefined on each kind of machine. For example, on a
2165 Vax, the name @samp{vax} is a predefined macro. On other machines, it
2166 would not be defined.
2169 Many more macros are defined by system header files. Different
2170 systems and machines define different macros, or give them different
2171 values. It is useful to test these macros with conditionals to avoid
2172 using a system feature on a machine where it is not implemented.
2175 Macros are a common way of allowing users to customize a program for
2176 different machines or applications. For example, the macro
2177 @samp{BUFSIZE} might be defined in a configuration file for your
2178 program that is included as a header file in each source file. You
2179 would use @samp{BUFSIZE} in a preprocessing conditional in order to
2180 generate different code depending on the chosen configuration.
2183 Macros can be defined or undefined with @samp{-D} and @samp{-U}
2184 command options when you compile the program. You can arrange to
2185 compile the same source file into two different programs by choosing
2186 a macro name to specify which program you want, writing conditionals
2187 to test whether or how this macro is defined, and then controlling
2188 the state of the macro with compiler command options.
2193 Assertions are usually predefined, but can be defined with preprocessor
2194 directives or command-line options.
2198 @subsection Assertions
2201 @dfn{Assertions} are a more systematic alternative to macros in writing
2202 conditionals to test what sort of computer or system the compiled
2203 program will run on. Assertions are usually predefined, but you can
2204 define them with preprocessing directives or command-line options.
2207 The macros traditionally used to describe the type of target are not
2208 classified in any way according to which question they answer; they may
2209 indicate a hardware architecture, a particular hardware model, an
2210 operating system, a particular version of an operating system, or
2211 specific configuration options. These are jumbled together in a single
2212 namespace. In contrast, each assertion consists of a named question and
2213 an answer. The question is usually called the @dfn{predicate}.
2214 An assertion looks like this:
2217 #@var{predicate} (@var{answer})
2221 You must use a properly formed identifier for @var{predicate}. The
2222 value of @var{answer} can be any sequence of words; all characters are
2223 significant except for leading and trailing whitespace, and differences
2224 in internal whitespace sequences are ignored. Thus, @samp{x + y} is
2225 different from @samp{x+y} but equivalent to @samp{x + y}. @samp{)} is
2226 not allowed in an answer.
2228 @cindex testing predicates
2229 Here is a conditional to test whether the answer @var{answer} is asserted
2230 for the predicate @var{predicate}:
2233 #if #@var{predicate} (@var{answer})
2237 There may be more than one answer asserted for a given predicate. If
2238 you omit the answer, you can test whether @emph{any} answer is asserted
2239 for @var{predicate}:
2242 #if #@var{predicate}
2248 Most of the time, the assertions you test will be predefined assertions.
2249 GNU C provides three predefined predicates: @code{system}, @code{cpu},
2250 and @code{machine}. @code{system} is for assertions about the type of
2251 software, @code{cpu} describes the type of computer architecture, and
2252 @code{machine} gives more information about the computer. For example,
2253 on a GNU system, the following assertions would be true:
2259 #system (mach 3.@var{subversion})
2261 #system (hurd @var{version})
2265 and perhaps others. The alternatives with
2266 more or less version information let you ask more or less detailed
2267 questions about the type of system software.
2269 On a Unix system, you would find @code{#system (unix)} and perhaps one of:
2270 @code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)},
2271 @code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)},
2272 @code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)}
2273 with possible version numbers following.
2275 Other values for @code{system} are @code{#system (mvs)}
2276 and @code{#system (vms)}.
2278 @strong{Portability note:} Many Unix C compilers provide only one answer
2279 for the @code{system} assertion: @code{#system (unix)}, if they support
2280 assertions at all. This is less than useful.
2282 An assertion with a multi-word answer is completely different from several
2283 assertions with individual single-word answers. For example, the presence
2284 of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true.
2285 It also does not directly imply @code{system (mach)}, but in GNU C, that
2286 last will normally be asserted as well.
2288 The current list of possible assertion values for @code{cpu} is:
2289 @code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu
2290 (clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu
2291 (tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)},
2292 @code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu
2293 (m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)},
2294 @code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)},
2295 @code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu
2296 (tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}.
2299 You can create assertions within a C program using @samp{#assert}, like
2303 #assert @var{predicate} (@var{answer})
2307 (Note the absence of a @samp{#} before @var{predicate}.)
2310 @cindex assertions, undoing
2311 @cindex retracting assertions
2313 Each time you do this, you assert a new true answer for @var{predicate}.
2314 Asserting one answer does not invalidate previously asserted answers;
2315 they all remain true. The only way to remove an assertion is with
2316 @samp{#unassert}. @samp{#unassert} has the same syntax as
2317 @samp{#assert}. You can also remove all assertions about
2318 @var{predicate} like this:
2321 #unassert @var{predicate}
2324 You can also add or cancel assertions using command options
2325 when you run @code{gcc} or @code{cpp}. @xref{Invocation}.
2327 @node #error Directive
2328 @subsection The @samp{#error} and @samp{#warning} Directives
2331 The directive @samp{#error} causes the preprocessor to report a fatal
2332 error. The rest of the line that follows @samp{#error} is used as the
2333 error message. The line must consist of complete tokens.
2335 You would use @samp{#error} inside of a conditional that detects a
2336 combination of parameters which you know the program does not properly
2337 support. For example, if you know that the program will not run
2338 properly on a Vax, you might write
2343 #error "Won't work on Vaxen. See comments at get_last_object."
2349 @xref{Nonstandard Predefined}, for why this works.
2351 If you have several configuration parameters that must be set up by
2352 the installation in a consistent way, you can use conditionals to detect
2353 an inconsistency and report it with @samp{#error}. For example,
2356 #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
2357 || HASH_TABLE_SIZE % 5 == 0
2358 #error HASH_TABLE_SIZE should not be divisible by a small prime
2363 The directive @samp{#warning} is like the directive @samp{#error}, but causes
2364 the preprocessor to issue a warning and continue preprocessing. The rest of
2365 the line that follows @samp{#warning} is used as the warning message.
2367 You might use @samp{#warning} in obsolete header files, with a message
2368 directing the user to the header file which should be used instead.
2370 @node Combining Sources, Other Directives, Conditionals, Top
2371 @section Combining Source Files
2373 @cindex line control
2374 One of the jobs of the C preprocessor is to inform the C compiler of where
2375 each line of C code came from: which source file and which line number.
2377 C code can come from multiple source files if you use @samp{#include};
2378 both @samp{#include} and the use of conditionals and macros can cause
2379 the line number of a line in the preprocessor output to be different
2380 from the line's number in the original source file. You will appreciate
2381 the value of making both the C compiler (in error messages) and symbolic
2382 debuggers such as GDB use the line numbers in your source file.
2384 The C preprocessor builds on this feature by offering a directive by which
2385 you can control the feature explicitly. This is useful when a file for
2386 input to the C preprocessor is the output from another program such as the
2387 @code{bison} parser generator, which operates on another file that is the
2388 true source file. Parts of the output from @code{bison} are generated from
2389 scratch, other parts come from a standard parser file. The rest are copied
2390 nearly verbatim from the source file, but their line numbers in the
2391 @code{bison} output are not the same as their original line numbers.
2392 Naturally you would like compiler error messages and symbolic debuggers to
2393 know the original source file and line number of each line in the
2397 @code{bison} arranges this by writing @samp{#line} directives into the output
2398 file. @samp{#line} is a directive that specifies the original line number
2399 and source file name for subsequent input in the current preprocessor input
2400 file. @samp{#line} has three variants:
2403 @item #line @var{linenum}
2404 Here @var{linenum} is a decimal integer constant. This specifies that
2405 the line number of the following line of input, in its original source file,
2408 @item #line @var{linenum} @var{filename}
2409 Here @var{linenum} is a decimal integer constant and @var{filename}
2410 is a string constant. This specifies that the following line of input
2411 came originally from source file @var{filename} and its line number there
2412 was @var{linenum}. Keep in mind that @var{filename} is not just a
2413 file name; it is surrounded by doublequote characters so that it looks
2414 like a string constant.
2416 @item #line @var{anything else}
2417 @var{anything else} is checked for macro calls, which are expanded.
2418 The result should be a decimal integer constant followed optionally
2419 by a string constant, as described above.
2422 @samp{#line} directives alter the results of the @samp{__FILE__} and
2423 @samp{__LINE__} predefined macros from that point on. @xref{Standard
2426 The output of the preprocessor (which is the input for the rest of the
2427 compiler) contains directives that look much like @samp{#line} directives.
2428 They start with just @samp{#} instead of @samp{#line}, but this is
2429 followed by a line number and file name as in @samp{#line}. @xref{Output}.
2431 @node Other Directives, Output, Combining Sources, Top
2432 @section Miscellaneous Preprocessing Directives
2434 @cindex null directive
2435 This section describes three additional preprocessing directives. They are
2436 not very useful, but are mentioned for completeness.
2438 The @dfn{null directive} consists of a @samp{#} followed by a Newline, with
2439 only whitespace (including comments) in between. A null directive is
2440 understood as a preprocessing directive but has no effect on the preprocessor
2441 output. The primary significance of the existence of the null directive is
2442 that an input line consisting of just a @samp{#} will produce no output,
2443 rather than a line of output containing just a @samp{#}. Supposedly
2444 some old C programs contain such lines.
2447 The ANSI standard specifies that the @samp{#pragma} directive has an
2448 arbitrary, implementation-defined effect. In the GNU C preprocessor,
2449 @samp{#pragma} directives are not used, except for @samp{#pragma once}
2450 (@pxref{Once-Only}). However, they are left in the preprocessor output,
2451 so they are available to the compilation pass.
2454 The @samp{#ident} directive is supported for compatibility with certain
2455 other systems. It is followed by a line of text. On some systems, the
2456 text is copied into a special place in the object file; on most systems,
2457 the text is ignored and this directive has no effect. Typically
2458 @samp{#ident} is only used in header files supplied with those systems
2459 where it is meaningful.
2461 @node Output, Invocation, Other Directives, Top
2462 @section C Preprocessor Output
2464 @cindex output format
2465 The output from the C preprocessor looks much like the input, except
2466 that all preprocessing directive lines have been replaced with blank lines
2467 and all comments with spaces. Whitespace within a line is not altered;
2468 however, unless @samp{-traditional} is used, spaces may be inserted into
2469 the expansions of macro calls to prevent tokens from being concatenated.
2471 Source file name and line number information is conveyed by lines of
2475 # @var{linenum} @var{filename} @var{flags}
2479 which are inserted as needed into the middle of the input (but never
2480 within a string or character constant). Such a line means that the
2481 following line originated in file @var{filename} at line @var{linenum}.
2483 After the file name comes zero or more flags, which are @samp{1},
2484 @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces separate
2485 them. Here is what the flags mean:
2489 This indicates the start of a new file.
2491 This indicates returning to a file (after having included another file).
2493 This indicates that the following text comes from a system header file,
2494 so certain warnings should be suppressed.
2496 This indicates that the following text should be treated as C.
2497 @c maybe cross reference NO_IMPLICIT_EXTERN_C
2500 @node Invocation, Concept Index, Output, Top
2501 @section Invoking the C Preprocessor
2502 @cindex invocation of the preprocessor
2504 Most often when you use the C preprocessor you will not have to invoke it
2505 explicitly: the C compiler will do so automatically. However, the
2506 preprocessor is sometimes useful on its own.
2508 The C preprocessor expects two file names as arguments, @var{infile} and
2509 @var{outfile}. The preprocessor reads @var{infile} together with any other
2510 files it specifies with @samp{#include}. All the output generated by the
2511 combined input files is written in @var{outfile}.
2513 Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
2514 means to read from standard input and as @var{outfile} means to write to
2515 standard output. Also, if @var{outfile} or both file names are omitted,
2516 the standard output and standard input are used for the omitted file names.
2519 Here is a table of command options accepted by the C preprocessor.
2520 These options can also be given when compiling a C program; they are
2521 passed along automatically to the preprocessor when it is invoked by the
2527 Inhibit generation of @samp{#}-lines with line-number information in
2528 the output from the preprocessor (@pxref{Output}). This might be
2529 useful when running the preprocessor on something that is not C code
2530 and will be sent to a program which might be confused by the
2535 Do not discard comments: pass them through to the output file.
2536 Comments appearing in arguments of a macro call will be copied to the
2537 output before the expansion of the macro call.
2540 @findex -traditional
2541 Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
2545 Traditional macro expansion pays no attention to singlequote or
2546 doublequote characters; macro argument symbols are replaced by the
2547 argument values even when they appear within apparent string or
2548 character constants.
2551 Traditionally, it is permissible for a macro expansion to end in the
2552 middle of a string or character constant. The constant continues into
2553 the text surrounding the macro call.
2556 However, traditionally the end of the line terminates a string or
2557 character constant, with no error.
2560 In traditional C, a comment is equivalent to no text at all. (In ANSI
2561 C, a comment counts as whitespace.)
2564 Traditional C does not have the concept of a ``preprocessing number''.
2565 It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+},
2569 A macro is not suppressed within its own definition, in traditional C.
2570 Thus, any macro that is used recursively inevitably causes an error.
2573 The character @samp{#} has no special meaning within a macro definition
2577 In traditional C, the text at the end of a macro expansion can run
2578 together with the text after the macro call, to produce a single token.
2579 (This is impossible in ANSI C.)
2582 Traditionally, @samp{\} inside a macro argument suppresses the syntactic
2583 significance of the following character.
2588 Process ANSI standard trigraph sequences. These are three-character
2589 sequences, all starting with @samp{??}, that are defined by ANSI C to
2590 stand for single characters. For example, @samp{??/} stands for
2591 @samp{\}, so @samp{'??/n'} is a character constant for a newline.
2592 Strictly speaking, the GNU C preprocessor does not support all
2593 programs in ANSI Standard C unless @samp{-trigraphs} is used, but if
2594 you ever notice the difference it will be with relief.
2596 You don't want to know any more about trigraphs.
2600 Issue warnings required by the ANSI C standard in certain cases such
2601 as when text other than a comment follows @samp{#else} or @samp{#endif}.
2603 @item -pedantic-errors
2604 @findex -pedantic-errors
2605 Like @samp{-pedantic}, except that errors are produced rather than
2610 Warn if any trigraphs are encountered (assuming they are enabled).
2615 @c "Not worth documenting" both singular and plural forms of this
2616 @c option, per RMS. But also unclear which is better; hence may need to
2617 @c switch this at some future date. pesch@cygnus.com, 2jan92.
2619 (Both forms have the same effect).
2621 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2622 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2626 Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
2627 @samp{-Wtraditional}).
2630 @findex -Wtraditional
2631 Warn about certain constructs that behave differently in traditional and
2634 @item -I @var{directory}
2636 Add the directory @var{directory} to the head of the list of
2637 directories to be searched for header files (@pxref{Include Syntax}).
2638 This can be used to override a system header file, substituting your
2639 own version, since these directories are searched before the system
2640 header file directories. If you use more than one @samp{-I} option,
2641 the directories are scanned in left-to-right order; the standard
2642 system directories come after.
2645 Any directories specified with @samp{-I} options before the @samp{-I-}
2646 option are searched only for the case of @samp{#include "@var{file}"};
2647 they are not searched for @samp{#include <@var{file}>}.
2649 If additional directories are specified with @samp{-I} options after
2650 the @samp{-I-}, these directories are searched for all @samp{#include}
2653 In addition, the @samp{-I-} option inhibits the use of the current
2654 directory as the first search directory for @samp{#include "@var{file}"}.
2655 Therefore, the current directory is searched only if it is requested
2656 explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.}
2657 allows you to control precisely which directories are searched before
2658 the current one and which are searched after.
2662 Do not search the standard system directories for header files.
2663 Only the directories you have specified with @samp{-I} options
2664 (and the current directory, if appropriate) are searched.
2668 Do not search for header files in the C++-specific standard directories,
2669 but do still search the other standard directories.
2670 (This option is used when building libg++.)
2674 Predefine @var{name} as a macro, with definition @samp{1}.
2676 @item -D @var{name}=@var{definition}
2677 Predefine @var{name} as a macro, with definition @var{definition}.
2678 There are no restrictions on the contents of @var{definition}, but if
2679 you are invoking the preprocessor from a shell or shell-like program you
2680 may need to use the shell's quoting syntax to protect characters such as
2681 spaces that have a meaning in the shell syntax. If you use more than
2682 one @samp{-D} for the same @var{name}, the rightmost definition takes
2687 Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are
2688 specified for one name, the @samp{-U} beats the @samp{-D} and the name
2693 Do not predefine any nonstandard macros.
2695 @item -A @var{predicate}(@var{answer})
2697 Make an assertion with the predicate @var{predicate} and answer
2698 @var{answer}. @xref{Assertions}.
2701 You can use @samp{-A-} to disable all predefined assertions; it also
2702 undefines all predefined macros that identify the type of target system.
2706 Instead of outputting the result of preprocessing, output a list of
2707 @samp{#define} directives for all the macros defined during the
2708 execution of the preprocessor, including predefined macros. This gives
2709 you a way of finding out what is predefined in your version of the
2710 preprocessor; assuming you have no file @samp{foo.h}, the command
2713 touch foo.h; cpp -dM foo.h
2717 will show the values of any predefined macros.
2721 Like @samp{-dM} except in two respects: it does @emph{not} include the
2722 predefined macros, and it outputs @emph{both} the @samp{#define}
2723 directives and the result of preprocessing. Both kinds of output go to
2724 the standard output file.
2728 Instead of outputting the result of preprocessing, output a rule
2729 suitable for @code{make} describing the dependencies of the main
2730 source file. The preprocessor outputs one @code{make} rule containing
2731 the object file name for that source file, a colon, and the names of
2732 all the included files. If there are many included files then the
2733 rule is split into several lines using @samp{\}-newline.
2735 @samp{-MG} says to treat missing header files as generated files and assume
2736 they live in the same directory as the source file. It must be specified
2737 in addition to @samp{-M}.
2739 This feature is used in automatic updating of makefiles.
2743 Like @samp{-M} but mention only the files included with @samp{#include
2744 "@var{file}"}. System header files included with @samp{#include
2745 <@var{file}>} are omitted.
2747 @item -MD @var{file}
2749 Like @samp{-M} but the dependency information is written to @var{file}.
2750 This is in addition to compiling the file as specified---@samp{-MD} does
2751 not inhibit ordinary compilation the way @samp{-M} does.
2753 When invoking gcc, do not specify the @var{file} argument.
2754 Gcc will create file names made by replacing ".c" with ".d" at
2755 the end of the input file names.
2757 In Mach, you can use the utility @code{md} to merge multiple dependency
2758 files into a single dependency file suitable for using with the @samp{make}
2761 @item -MMD @var{file}
2763 Like @samp{-MD} except mention only user header files, not system
2768 Print the name of each header file used, in addition to other normal
2771 @item -imacros @var{file}
2773 Process @var{file} as input, discarding the resulting output, before
2774 processing the regular input file. Because the output generated from
2775 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2776 is to make the macros defined in @var{file} available for use in the
2779 @item -include @var{file}
2781 Process @var{file} as input, and include all the resulting output,
2782 before processing the regular input file.
2784 @item -idirafter @var{dir}
2786 @cindex second include path
2787 Add the directory @var{dir} to the second include path. The directories
2788 on the second include path are searched when a header file is not found
2789 in any of the directories in the main include path (the one that
2792 @item -iprefix @var{prefix}
2794 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2797 @item -iwithprefix @var{dir}
2798 @findex -iwithprefix
2799 Add a directory to the second include path. The directory's name is
2800 made by concatenating @var{prefix} and @var{dir}, where @var{prefix}
2801 was specified previously with @samp{-iprefix}.
2803 @item -isystem @var{dir}
2805 Add a directory to the beginning of the second include path, marking it
2806 as a system directory, so that it gets the same special treatment as
2807 is applied to the standard system directories.
2818 @findex -lang-objc++
2819 Specify the source language. @samp{-lang-c} is the default; it
2820 allows recognition of C++ comments (comments that begin with
2821 @samp{//} and end at end of line) and hexadecimal floating-point constants,
2822 since these features will most likely appear in the next C standard.
2823 @samp{-lang-c89} disables recognition of C++ comments and
2824 hexadecimal floating-point constants. @samp{-lang-c++}
2825 handles C++ comment syntax and includes extra default include
2826 directories for C++. @samp{-lang-objc} enables the Objective C
2827 @samp{#import} directive. @samp{-lang-objc++} enables both C++ and Objective C
2830 These options are generated by the compiler driver @code{gcc}, but not
2831 passed from the @samp{gcc} command line unless you use the driver's
2835 Look for commands to the program checker @code{lint} embedded in
2836 comments, and emit them preceded by @samp{#pragma lint}. For example,
2837 the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint
2840 This option is available only when you call @code{cpp} directly;
2841 @code{gcc} will not pass it from its command line.
2845 Forbid the use of @samp{$} in identifiers. This was formerly required
2846 for strict conformance to the C Standard before the standard was
2849 This option is available only when you call @code{cpp} directly;
2850 @code{gcc} will not pass it from its command line.
2854 @node Concept Index, Index, Invocation, Top
2855 @unnumbered Concept Index
2858 @node Index,, Concept Index, Top
2859 @unnumbered Index of Directives, Macros and Options