From 70d65f3b771ea760a7dc1904acb8da3666b62b1b Mon Sep 17 00:00:00 2001 From: Richard Kenner Date: Sat, 21 Sep 1996 06:34:54 -0400 Subject: [PATCH] Initial revision From-SVN: r12748 --- gcc/cpp.texi | 2861 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2861 insertions(+) create mode 100644 gcc/cpp.texi diff --git a/gcc/cpp.texi b/gcc/cpp.texi new file mode 100644 index 00000000000..cb2ee9d9e24 --- /dev/null +++ b/gcc/cpp.texi @@ -0,0 +1,2861 @@ +\input texinfo +@setfilename cpp.info +@settitle The C Preprocessor + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* Cpp: (cpp). The C preprocessor. +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c @smallbook +@c @cropmarks +@c @finalout +@setchapternewpage odd +@ifinfo +This file documents the GNU C Preprocessor. + +Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@c @finalout +@title The C Preprocessor +@subtitle Last revised July 1992 +@subtitle for GCC version 2 +@author Richard M. Stallman +@page +@vskip 2pc +This booklet is eventually intended to form the first chapter of a GNU +C Language manual. + +@vskip 0pt plus 1filll +Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free +Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@page + +@node Top, Global Actions,, (DIR) +@chapter The C Preprocessor + +The C preprocessor is a @dfn{macro processor} that is used automatically by +the C compiler to transform your program before actual compilation. It is +called a macro processor because it allows you to define @dfn{macros}, +which are brief abbreviations for longer constructs. + +The C preprocessor provides four separate facilities that you can use as +you see fit: + +@itemize @bullet +@item +Inclusion of header files. These are files of declarations that can be +substituted into your program. + +@item +Macro expansion. You can define @dfn{macros}, which are abbreviations +for arbitrary fragments of C code, and then the C preprocessor will +replace the macros with their definitions throughout the program. + +@item +Conditional compilation. Using special preprocessing directives, you +can include or exclude parts of the program according to various +conditions. + +@item +Line control. If you use a program to combine or rearrange source files into +an intermediate file which is then compiled, you can use line control +to inform the compiler of where each source line originally came from. +@end itemize + +C preprocessors vary in some details. This manual discusses the GNU C +preprocessor, the C Compatible Compiler Preprocessor. The GNU C +preprocessor provides a superset of the features of ANSI Standard C. + +ANSI Standard C requires the rejection of many harmless constructs commonly +used by today's C programs. Such incompatibility would be inconvenient for +users, so the GNU C preprocessor is configured to accept these constructs +by default. Strictly speaking, to get ANSI Standard C, you must use the +options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in +practice the consequences of having strict ANSI Standard C make it +undesirable to do this. @xref{Invocation}. + +@menu +* Global Actions:: Actions made uniformly on all input files. +* Directives:: General syntax of preprocessing directives. +* Header Files:: How and why to use header files. +* Macros:: How and why to use macros. +* Conditionals:: How and why to use conditionals. +* Combining Sources:: Use of line control when you combine source files. +* Other Directives:: Miscellaneous preprocessing directives. +* Output:: Format of output from the C preprocessor. +* Invocation:: How to invoke the preprocessor; command options. +* Concept Index:: Index of concepts and terms. +* Index:: Index of directives, predefined macros and options. +@end menu + +@node Global Actions, Directives, Top, Top +@section Transformations Made Globally + +Most C preprocessor features are inactive unless you give specific directives +to request their use. (Preprocessing directives are lines starting with +@samp{#}; @pxref{Directives}). But there are three transformations that the +preprocessor always makes on all the input it receives, even in the absence +of directives. + +@itemize @bullet +@item +All C comments are replaced with single spaces. + +@item +Backslash-Newline sequences are deleted, no matter where. This +feature allows you to break long lines for cosmetic purposes without +changing their meaning. + +@item +Predefined macro names are replaced with their expansions +(@pxref{Predefined}). +@end itemize + +The first two transformations are done @emph{before} nearly all other parsing +and before preprocessing directives are recognized. Thus, for example, you +can split a line cosmetically with Backslash-Newline anywhere (except +when trigraphs are in use; see below). + +@example +/* +*/ # /* +*/ defi\ +ne FO\ +O 10\ +20 +@end example + +@noindent +is equivalent into @samp{#define FOO 1020}. You can split even an escape +sequence with Backslash-Newline. For example, you can split @code{"foo\bar"} +between the @samp{\} and the @samp{b} to get + +@example +"foo\\ +bar" +@end example + +@noindent +This behavior is unclean: in all other contexts, a Backslash can be +inserted in a string constant as an ordinary character by writing a double +Backslash, and this creates an exception. But the ANSI C standard requires +it. (Strict ANSI C does not allow Newlines in string constants, so they +do not consider this a problem.) + +But there are a few exceptions to all three transformations. + +@itemize @bullet +@item +C comments and predefined macro names are not recognized inside a +@samp{#include} directive in which the file name is delimited with +@samp{<} and @samp{>}. + +@item +C comments and predefined macro names are never recognized within a +character or string constant. (Strictly speaking, this is the rule, +not an exception, but it is worth noting here anyway.) + +@item +Backslash-Newline may not safely be used within an ANSI ``trigraph''. +Trigraphs are converted before Backslash-Newline is deleted. If you +write what looks like a trigraph with a Backslash-Newline inside, the +Backslash-Newline is deleted as usual, but it is then too late to +recognize the trigraph. + +This exception is relevant only if you use the @samp{-trigraphs} +option to enable trigraph processing. @xref{Invocation}. +@end itemize + +@node Directives, Header Files, Global Actions, Top +@section Preprocessing Directives + +@cindex preprocessing directives +@cindex directives +Most preprocessor features are active only if you use preprocessing directives +to request their use. + +Preprocessing directives are lines in your program that start with @samp{#}. +The @samp{#} is followed by an identifier that is the @dfn{directive name}. +For example, @samp{#define} is the directive that defines a macro. +Whitespace is also allowed before and after the @samp{#}. + +The set of valid directive names is fixed. Programs cannot define new +preprocessing directives. + +Some directive names require arguments; these make up the rest of the directive +line and must be separated from the directive name by whitespace. For example, +@samp{#define} must be followed by a macro name and the intended expansion +of the macro. @xref{Simple Macros}. + +A preprocessing directive cannot be more than one line in normal circumstances. +It may be split cosmetically with Backslash-Newline, but that has no effect +on its meaning. Comments containing Newlines can also divide the +directive into multiple lines, but the comments are changed to Spaces +before the directive is interpreted. The only way a significant Newline +can occur in a preprocessing directive is within a string constant or +character constant. Note that +most C compilers that might be applied to the output from the preprocessor +do not accept string or character constants containing Newlines. + +The @samp{#} and the directive name cannot come from a macro expansion. For +example, if @samp{foo} is defined as a macro expanding to @samp{define}, +that does not make @samp{#foo} a valid preprocessing directive. + +@node Header Files, Macros, Directives, Top +@section Header Files + +@cindex header file +A header file is a file containing C declarations and macro definitions +(@pxref{Macros}) to be shared between several source files. You request +the use of a header file in your program with the C preprocessing directive +@samp{#include}. + +@menu +* Header Uses:: What header files are used for. +* Include Syntax:: How to write @samp{#include} directives. +* Include Operation:: What @samp{#include} does. +* Once-Only:: Preventing multiple inclusion of one header file. +* Inheritance:: Including one header file in another header file. +@end menu + +@node Header Uses, Include Syntax, Header Files, Header Files +@subsection Uses of Header Files + +Header files serve two kinds of purposes. + +@itemize @bullet +@item +@findex system header files +System header files declare the interfaces to parts of the operating +system. You include them in your program to supply the definitions and +declarations you need to invoke system calls and libraries. + +@item +Your own header files contain declarations for interfaces between the +source files of your program. Each time you have a group of related +declarations and macro definitions all or most of which are needed in +several different source files, it is a good idea to create a header +file for them. +@end itemize + +Including a header file produces the same results in C compilation as +copying the header file into each source file that needs it. But such +copying would be time-consuming and error-prone. With a header file, the +related declarations appear in only one place. If they need to be changed, +they can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well as +the risk that a failure to find one copy will result in inconsistencies +within a program. + +The usual convention is to give header files names that end with +@file{.h}. Avoid unusual characters in header file names, as they +reduce portability. + +@node Include Syntax, Include Operation, Header Uses, Header Files +@subsection The @samp{#include} Directive + +@findex #include +Both user and system header files are included using the preprocessing +directive @samp{#include}. It has three variants: + +@table @code +@item #include <@var{file}> +This variant is used for system header files. It searches for a file +named @var{file} in a list of directories specified by you, then in a +standard list of system directories. You specify directories to +search for header files with the command option @samp{-I} +(@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching +the standard system directories; in this case only the directories +you specify are searched. + +The parsing of this form of @samp{#include} is slightly special +because comments are not recognized within the @samp{<@dots{}>}. +Thus, in @samp{#include } the @samp{/*} does not start a comment +and the directive specifies inclusion of a system header file named +@file{x/*y}. Of course, a header file with such a name is unlikely to +exist on Unix, where shell wildcard features would make it hard to +manipulate.@refill + +The argument @var{file} may not contain a @samp{>} character. It may, +however, contain a @samp{<} character. + +@item #include "@var{file}" +This variant is used for header files of your own program. It +searches for a file named @var{file} first in the current directory, +then in the same directories used for system header files. The +current directory is the directory of the current input file. It is +tried first because it is presumed to be the location of the files +that the current input file refers to. (If the @samp{-I-} option is +used, the special treatment of the current directory is inhibited.) + +The argument @var{file} may not contain @samp{"} characters. If +backslashes occur within @var{file}, they are considered ordinary text +characters, not escape characters. None of the character escape +sequences appropriate to string constants in C are processed. Thus, +@samp{#include "x\n\\y"} specifies a filename containing three +backslashes. It is not clear why this behavior is ever useful, but +the ANSI standard specifies it. + +@item #include @var{anything else} +@cindex computed @samp{#include} +This variant is called a @dfn{computed #include}. Any @samp{#include} +directive whose argument does not fit the above two forms is a computed +include. The text @var{anything else} is checked for macro calls, +which are expanded (@pxref{Macros}). When this is done, the result +must fit one of the above two variants---in particular, the expanded +text must in the end be surrounded by either quotes or angle braces. + +This feature allows you to define a macro which controls the file name +to be used at a later point in the program. One application of this is +to allow a site-specific configuration file for your program to specify +the names of the system include files to be used. This can help in +porting the program to various operating systems in which the necessary +system header files are found in different places. +@end table + +@node Include Operation, Once-Only, Include Syntax, Header Files +@subsection How @samp{#include} Works + +The @samp{#include} directive works by directing the C preprocessor to scan +the specified file as input before continuing with the rest of the current +file. The output from the preprocessor contains the output already +generated, followed by the output resulting from the included file, +followed by the output that comes from the text after the @samp{#include} +directive. For example, given a header file @file{header.h} as follows, + +@example +char *test (); +@end example + +@noindent +and a main program called @file{program.c} that uses the header file, +like this, + +@example +int x; +#include "header.h" + +main () +@{ + printf (test ()); +@} +@end example + +@noindent +the output generated by the C preprocessor for @file{program.c} as input +would be + +@example +int x; +char *test (); + +main () +@{ + printf (test ()); +@} +@end example + +Included files are not limited to declarations and macro definitions; those +are merely the typical uses. Any fragment of a C program can be included +from another file. The include file could even contain the beginning of a +statement that is concluded in the containing file, or the end of a +statement that was started in the including file. However, a comment or a +string or character constant may not start in the included file and finish +in the including file. An unterminated comment, string constant or +character constant in an included file is considered to end (with an error +message) at the end of the file. + +It is possible for a header file to begin or end a syntactic unit such +as a function definition, but that would be very confusing, so don't do +it. + +The line following the @samp{#include} directive is always treated as a +separate line by the C preprocessor even if the included file lacks a final +newline. + +@node Once-Only, Inheritance, Include Operation, Header Files +@subsection Once-Only Include Files +@cindex repeated inclusion +@cindex including just once + +Very often, one header file includes another. It can easily result that a +certain header file is included more than once. This may lead to errors, +if the header file defines structure types or typedefs, and is certainly +wasteful. Therefore, we often wish to prevent multiple inclusion of a +header file. + +The standard way to do this is to enclose the entire real contents of the +file in a conditional, like this: + +@example +#ifndef FILE_FOO_SEEN +#define FILE_FOO_SEEN + +@var{the entire file} + +#endif /* FILE_FOO_SEEN */ +@end example + +The macro @code{FILE_FOO_SEEN} indicates that the file has been included +once already. In a user header file, the macro name should not begin +with @samp{_}. In a system header file, this name should begin with +@samp{__} to avoid conflicts with user programs. In any kind of header +file, the macro name should contain the name of the file and some +additional text, to avoid conflicts with other header files. + +The GNU C preprocessor is programmed to notice when a header file uses +this particular construct and handle it efficiently. If a header file +is contained entirely in a @samp{#ifndef} conditional, then it records +that fact. If a subsequent @samp{#include} specifies the same file, +and the macro in the @samp{#ifndef} is already defined, then the file +is entirely skipped, without even reading it. + +@findex #pragma once +There is also an explicit directive to tell the preprocessor that it need +not include a file more than once. This is called @samp{#pragma once}, +and was used @emph{in addition to} the @samp{#ifndef} conditional around +the contents of the header file. @samp{#pragma once} is now obsolete +and should not be used at all. + +@findex #import +In the Objective C language, there is a variant of @samp{#include} +called @samp{#import} which includes a file, but does so at most once. +If you use @samp{#import} @emph{instead of} @samp{#include}, then you +don't need the conditionals inside the header file to prevent multiple +execution of the contents. + +@samp{#import} is obsolete because it is not a well designed feature. +It requires the users of a header file---the applications +programmers---to know that a certain header file should only be included +once. It is much better for the header file's implementor to write the +file so that users don't need to know this. Using @samp{#ifndef} +accomplishes this goal. + +@node Inheritance,, Once-Only, Header Files +@subsection Inheritance and Header Files +@cindex inheritance +@cindex overriding a header file + +@dfn{Inheritance} is what happens when one object or file derives some +of its contents by virtual copying from another object or file. In +the case of C header files, inheritance means that one header file +includes another header file and then replaces or adds something. + +If the inheriting header file and the base header file have different +names, then inheritance is straightforward: simply write @samp{#include +"@var{base}"} in the inheriting file. + +Sometimes it is necessary to give the inheriting file the same name as +the base file. This is less straightforward. + +For example, suppose an application program uses the system header file +@file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h} +on a particular system doesn't do what the application program expects. +It might be convenient to define a ``local'' version, perhaps under the +name @file{/usr/local/include/sys/signal.h}, to override or add to the +one supplied by the system. + +You can do this by using the option @samp{-I.} for compilation, and +writing a file @file{sys/signal.h} that does what the application +program expects. But making this file include the standard +@file{sys/signal.h} is not so easy---writing @samp{#include +} in that file doesn't work, because it includes your own +version of the file, not the standard system version. Used in that file +itself, this leads to an infinite recursion and a fatal error in +compilation. + +@samp{#include } would find the proper file, +but that is not clean, since it makes an assumption about where the +system header file is found. This is bad for maintenance, since it +means that any change in where the system's header files are kept +requires a change somewhere else. + +@findex #include_next +The clean way to solve this problem is to use +@samp{#include_next}, which means, ``Include the @emph{next} file with +this name.'' This directive works like @samp{#include} except in +searching for the specified file: it starts searching the list of header +file directories @emph{after} the directory in which the current file +was found. + +Suppose you specify @samp{-I /usr/local/include}, and the list of +directories to search also includes @file{/usr/include}; and suppose that +both directories contain a file named @file{sys/signal.h}. Ordinary +@samp{#include } finds the file under +@file{/usr/local/include}. If that file contains @samp{#include_next +}, it starts searching after that directory, and finds the +file in @file{/usr/include}. + +@node Macros, Conditionals, Header Files, Top +@section Macros + +A macro is a sort of abbreviation which you can define once and then +use later. There are many complicated features associated with macros +in the C preprocessor. + +@menu +* Simple Macros:: Macros that always expand the same way. +* Argument Macros:: Macros that accept arguments that are substituted + into the macro expansion. +* Predefined:: Predefined macros that are always available. +* Stringification:: Macro arguments converted into string constants. +* Concatenation:: Building tokens from parts taken from macro arguments. +* Undefining:: Cancelling a macro's definition. +* Redefining:: Changing a macro's definition. +* Macro Pitfalls:: Macros can confuse the unwary. Here we explain + several common problems and strange features. +@end menu + +@node Simple Macros, Argument Macros, Macros, Macros +@subsection Simple Macros +@cindex simple macro +@cindex manifest constant + +A @dfn{simple macro} is a kind of abbreviation. It is a name which +stands for a fragment of code. Some people refer to these as +@dfn{manifest constants}. + +Before you can use a macro, you must @dfn{define} it explicitly with the +@samp{#define} directive. @samp{#define} is followed by the name of the +macro and then the code it should be an abbreviation for. For example, + +@example +#define BUFFER_SIZE 1020 +@end example + +@noindent +defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text +@samp{1020}. If somewhere after this @samp{#define} directive there comes +a C statement of the form + +@example +foo = (char *) xmalloc (BUFFER_SIZE); +@end example + +@noindent +then the C preprocessor will recognize and @dfn{expand} the macro +@samp{BUFFER_SIZE}, resulting in + +@example +foo = (char *) xmalloc (1020); +@end example + +The use of all upper case for macro names is a standard convention. +Programs are easier to read when it is possible to tell at a glance which +names are macros. + +Normally, a macro definition must be a single line, like all C +preprocessing directives. (You can split a long macro definition +cosmetically with Backslash-Newline.) There is one exception: Newlines +can be included in the macro definition if within a string or character +constant. This is because it is not possible for a macro definition to +contain an unbalanced quote character; the definition automatically +extends to include the matching quote character that ends the string or +character constant. Comments within a macro definition may contain +Newlines, which make no difference since the comments are entirely +replaced with Spaces regardless of their contents. + +Aside from the above, there is no restriction on what can go in a macro +body. Parentheses need not balance. The body need not resemble valid C +code. (But if it does not, you may get error messages from the C +compiler when you use the macro.) + +The C preprocessor scans your program sequentially, so macro definitions +take effect at the place you write them. Therefore, the following input to +the C preprocessor + +@example +foo = X; +#define X 4 +bar = X; +@end example + +@noindent +produces as output + +@example +foo = X; + +bar = 4; +@end example + +After the preprocessor expands a macro name, the macro's definition body is +appended to the front of the remaining input, and the check for macro calls +continues. Therefore, the macro body can contain calls to other macros. +For example, after + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +@end example + +@noindent +the name @samp{TABLESIZE} when used in the program would go through two +stages of expansion, resulting ultimately in @samp{1020}. + +This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. +The @samp{#define} for @samp{TABLESIZE} uses exactly the body you +specify---in this case, @samp{BUFSIZE}---and does not check to see whether +it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE} +that the result of its expansion is checked for more macro names. +@xref{Cascaded Macros}. + +@node Argument Macros, Predefined, Simple Macros, Macros +@subsection Macros with Arguments +@cindex macros with argument +@cindex arguments in macro definitions +@cindex function-like macro + +A simple macro always stands for exactly the same text, each time it is +used. Macros can be more flexible when they accept @dfn{arguments}. +Arguments are fragments of code that you supply each time the macro is +used. These fragments are included in the expansion of the macro +according to the directions in the macro definition. A macro that +accepts arguments is called a @dfn{function-like macro} because the +syntax for using it looks like a function call. + +@findex #define +To define a macro that uses arguments, you write a @samp{#define} directive +with a list of @dfn{argument names} in parentheses after the name of the +macro. The argument names may be any valid C identifiers, separated by +commas and optionally whitespace. The open-parenthesis must follow the +macro name immediately, with no space in between. + +For example, here is a macro that computes the minimum of two numeric +values, as it is defined in many C programs: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@end example + +@noindent +(This is not the best way to define a ``minimum'' macro in GNU C. +@xref{Side Effects}, for more information.) + +To use a macro that expects arguments, you write the name of the macro +followed by a list of @dfn{actual arguments} in parentheses, separated by +commas. The number of actual arguments you give must match the number of +arguments the macro expects. Examples of use of the macro @samp{min} +include @samp{min (1, 2)} and @samp{min (x + 28, *p)}. + +The expansion text of the macro depends on the arguments you use. +Each of the argument names of the macro is replaced, throughout the +macro definition, with the corresponding actual argument. Using the +same macro @samp{min} defined above, @samp{min (1, 2)} expands into + +@example +((1) < (2) ? (1) : (2)) +@end example + +@noindent +where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}. + +Likewise, @samp{min (x + 28, *p)} expands into + +@example +((x + 28) < (*p) ? (x + 28) : (*p)) +@end example + +Parentheses in the actual arguments must balance; a comma within +parentheses does not end an argument. However, there is no requirement +for brackets or braces to balance, and they do not prevent a comma from +separating arguments. Thus, + +@example +macro (array[x = y, x + 1]) +@end example + +@noindent +passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x + +1]}. If you want to supply @samp{array[x = y, x + 1]} as an argument, +you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C +code. + +After the actual arguments are substituted into the macro body, the entire +result is appended to the front of the remaining input, and the check for +macro calls continues. Therefore, the actual arguments can contain calls +to other macros, either with or without arguments, or even to the same +macro. The macro body can also contain calls to other macros. For +example, @samp{min (min (a, b), c)} expands into this text: + +@example +((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) +@end example + +@noindent +(Line breaks shown here for clarity would not actually be generated.) + +@cindex blank macro arguments +@cindex space as macro argument +If a macro @code{foo} takes one argument, and you want to supply an +empty argument, you must write at least some whitespace between the +parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing +no arguments, which is an error if @code{foo} expects an argument. But +@samp{foo0 ()} is the correct way to call a macro defined to take zero +arguments, like this: + +@example +#define foo0() @dots{} +@end example + +If you use the macro name followed by something other than an +open-parenthesis (after ignoring any spaces, tabs and comments that +follow), it is not a call to the macro, and the preprocessor does not +change what you have written. Therefore, it is possible for the same name +to be a variable or function in your program as well as a macro, and you +can choose in each instance whether to refer to the macro (if an actual +argument list follows) or the variable or function (if an argument list +does not follow). + +Such dual use of one name could be confusing and should be avoided +except when the two meanings are effectively synonymous: that is, when the +name is both a macro and a function and the two have similar effects. You +can think of the name simply as a function; use of the name for purposes +other than calling it (such as, to take the address) will refer to the +function, while calls will expand the macro and generate better but +equivalent code. For example, you can use a function named @samp{min} in +the same source file that defines the macro. If you write @samp{&min} with +no argument list, you refer to the function. If you write @samp{min (x, +bb)}, with an argument list, the macro is expanded. If you write +@samp{(min) (a, bb)}, where the name @samp{min} is not followed by an +open-parenthesis, the macro is not expanded, so you wind up with a call to +the function @samp{min}. + +You may not define the same name as both a simple macro and a macro with +arguments. + +In the definition of a macro with arguments, the list of argument names +must follow the macro name immediately with no space in between. If there +is a space after the macro name, the macro is defined as taking no +arguments, and all the rest of the line is taken to be the expansion. The +reason for this is that it is often useful to define a macro that takes no +arguments and whose definition begins with an identifier in parentheses. +This rule about spaces makes it possible for you to do either this: + +@example +#define FOO(x) - 1 / (x) +@end example + +@noindent +(which defines @samp{FOO} to take an argument and expand into minus the +reciprocal of that argument) or this: + +@example +#define BAR (x) - 1 / (x) +@end example + +@noindent +(which defines @samp{BAR} to take no argument and always expand into +@samp{(x) - 1 / (x)}). + +Note that the @emph{uses} of a macro with arguments can have spaces before +the left parenthesis; it's the @emph{definition} where it matters whether +there is a space. + +@node Predefined, Stringification, Argument Macros, Macros +@subsection Predefined Macros + +@cindex predefined macros +Several simple macros are predefined. You can use them without giving +definitions for them. They fall into two classes: standard macros and +system-specific macros. + +@menu +* Standard Predefined:: Standard predefined macros. +* Nonstandard Predefined:: Nonstandard predefined macros. +@end menu + +@node Standard Predefined, Nonstandard Predefined, Predefined, Predefined +@subsubsection Standard Predefined Macros +@cindex standard predefined macros + +The standard predefined macros are available with the same meanings +regardless of the machine or operating system on which you are using GNU C. +Their names all start and end with double underscores. Those preceding +@code{__GNUC__} in this table are standardized by ANSI C; the rest are +GNU C extensions. + +@table @code +@item __FILE__ +@findex __FILE__ +This macro expands to the name of the current input file, in the form of +a C string constant. The precise name returned is the one that was +specified in @samp{#include} or as the input file name argument. + +@item __LINE__ +@findex __LINE__ +This macro expands to the current input line number, in the form of a +decimal integer constant. While we call it a predefined macro, it's +a pretty strange macro, since its ``definition'' changes with each +new line of source code. + +This and @samp{__FILE__} are useful in generating an error message to +report an inconsistency detected by the program; the message can state +the source line at which the inconsistency was detected. For example, + +@smallexample +fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); +@end smallexample + +A @samp{#include} directive changes the expansions of @samp{__FILE__} +and @samp{__LINE__} to correspond to the included file. At the end of +that file, when processing resumes on the input file that contained +the @samp{#include} directive, the expansions of @samp{__FILE__} and +@samp{__LINE__} revert to the values they had before the +@samp{#include} (but @samp{__LINE__} is then incremented by one as +processing moves to the line after the @samp{#include}). + +The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered +if a @samp{#line} directive is used. @xref{Combining Sources}. + +@item __DATE__ +@findex __DATE__ +This macro expands to a string constant that describes the date on +which the preprocessor is being run. The string constant contains +eleven characters and looks like @w{@samp{"Feb 1 1996"}}. +@c After reformatting the above, check that the date remains `Feb 1 1996', +@c all on one line, with two spaces between the `Feb' and the `1'. + +@item __TIME__ +@findex __TIME__ +This macro expands to a string constant that describes the time at +which the preprocessor is being run. The string constant contains +eight characters and looks like @samp{"23:59:01"}. + +@item __STDC__ +@findex __STDC__ +This macro expands to the constant 1, to signify that this is ANSI +Standard C. (Whether that is actually true depends on what C compiler +will operate on the output from the preprocessor.) + +@item __STDC_VERSION__ +@findex __STDC_VERSION__ +This macro expands to the C Standard's version number, +a long integer constant of the form @samp{@var{yyyy}@var{mm}L} +where @var{yyyy} and @var{mm} are the year and month of the Standard version. +This signifies which version of the C Standard the preprocessor conforms to. +Like @samp{__STDC__}, whether this version number is accurate +for the entire implementation depends on what C compiler +will operate on the output from the preprocessor. + +@item __GNUC__ +@findex __GNUC__ +This macro is defined if and only if this is GNU C. This macro is +defined only when the entire GNU C compiler is in use; if you invoke the +preprocessor directly, @samp{__GNUC__} is undefined. The value +identifies the major version number of GNU CC (@samp{1} for GNU CC +version 1, which is now obsolete, and @samp{2} for version 2). + +@item __GNUC_MINOR__ +@findex __GNUC_MINOR__ +The macro contains the minor version number of the compiler. This can +be used to work around differences between different releases of the +compiler (for example, if gcc 2.6.3 is known to support a feature, you +can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}). +The last number, @samp{3} in the +example above, denotes the bugfix level of the compiler; no macro +contains this value. + +@item __GNUG__ +@findex __GNUG__ +The GNU C compiler defines this when the compilation language is +C++; use @samp{__GNUG__} to distinguish between GNU C and GNU +C++. + +@item __cplusplus +@findex __cplusplus +The draft ANSI standard for C++ used to require predefining this +variable. Though it is no longer required, GNU C++ continues to define +it, as do other popular C++ compilers. You can use @samp{__cplusplus} +to test whether a header is compiled by a C compiler or a C++ compiler. + +@item __STRICT_ANSI__ +@findex __STRICT_ANSI__ +This macro is defined if and only if the @samp{-ansi} switch was +specified when GNU C was invoked. Its definition is the null string. +This macro exists primarily to direct certain GNU header files not to +define certain traditional Unix constructs which are incompatible with +ANSI C. + +@item __BASE_FILE__ +@findex __BASE_FILE__ +This macro expands to the name of the main input file, in the form +of a C string constant. This is the source file that was specified +as an argument when the C compiler was invoked. + +@item __INCLUDE_LEVEL__ +@findex __INCLUDE_LEVEL_ +This macro expands to a decimal integer constant that represents the +depth of nesting in include files. The value of this macro is +incremented on every @samp{#include} directive and decremented at every +end of file. For input files specified by command line arguments, +the nesting level is zero. + +@item __VERSION__ +@findex __VERSION__ +This macro expands to a string which describes the version number of +GNU C. The string is normally a sequence of decimal numbers separated +by periods, such as @samp{"2.6.0"}. The only reasonable use of this +macro is to incorporate it into a string constant. + +@item __OPTIMIZE__ +@findex __OPTIMIZE__ +This macro is defined in optimizing compilations. It causes certain +GNU header files to define alternative macro definitions for some +system library functions. It is unwise to refer to or test the +definition of this macro unless you make very sure that programs will +execute with the same effect regardless. + +@item __CHAR_UNSIGNED__ +@findex __CHAR_UNSIGNED__ +This macro is defined if and only if the data type @code{char} is +unsigned on the target machine. It exists to cause the standard +header file @file{limit.h} to work correctly. It is bad practice +to refer to this macro yourself; instead, refer to the standard +macros defined in @file{limit.h}. The preprocessor uses +this macro to determine whether or not to sign-extend large character +constants written in octal; see @ref{#if Directive,,The @samp{#if} Directive}. + +@item __REGISTER_PREFIX__ +@findex __REGISTER_PREFIX__ +This macro expands to a string describing the prefix applied to cpu +registers in assembler code. It can be used to write assembler code +that is usable in multiple environments. For example, in the +@samp{m68k-aout} environment it expands to the string @samp{""}, +but in the @samp{m68k-coff} environment it expands to the string +@samp{"%"}. + +@item __USER_LABEL_PREFIX__ +@findex __USER_LABEL_PREFIX__ +This macro expands to a string describing the prefix applied to +user generated labels in assembler code. It can be used to write +assembler code that is usable in multiple environments. +For example, in the @samp{m68k-aout} environment it expands to the +string @samp{"_"}, but in the @samp{m68k-coff} environment it expands +to the string @samp{""}. +This does not work with the -mno-underscores option that the i386/osfrose +and m88k targets provide, and not with the -mcall* options of rs6000/sysv4 . +@end table + +@node Nonstandard Predefined,, Standard Predefined, Predefined +@subsubsection Nonstandard Predefined Macros + +The C preprocessor normally has several predefined macros that vary between +machines because their purpose is to indicate what type of system and +machine is in use. This manual, being for all systems and machines, cannot +tell you exactly what their names are; instead, we offer a list of some +typical ones. You can use @samp{cpp -dM} to see the values of +predefined macros; see @ref{Invocation}. + +Some nonstandard predefined macros describe the operating system in use, +with more or less specificity. For example, + +@table @code +@item unix +@findex unix +@samp{unix} is normally predefined on all Unix systems. + +@item BSD +@findex BSD +@samp{BSD} is predefined on recent versions of Berkeley Unix +(perhaps only in version 4.3). +@end table + +Other nonstandard predefined macros describe the kind of CPU, with more or +less specificity. For example, + +@table @code +@item vax +@findex vax +@samp{vax} is predefined on Vax computers. + +@item mc68000 +@findex mc68000 +@samp{mc68000} is predefined on most computers whose CPU is a Motorola +68000, 68010 or 68020. + +@item m68k +@findex m68k +@samp{m68k} is also predefined on most computers whose CPU is a 68000, +68010 or 68020; however, some makers use @samp{mc68000} and some use +@samp{m68k}. Some predefine both names. What happens in GNU C +depends on the system you are using it on. + +@item M68020 +@findex M68020 +@samp{M68020} has been observed to be predefined on some systems that +use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which +are less specific. + +@item _AM29K +@findex _AM29K +@itemx _AM29000 +@findex _AM29000 +Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000 +CPU family. + +@item ns32000 +@findex ns32000 +@samp{ns32000} is predefined on computers which use the National +Semiconductor 32000 series CPU. +@end table + +Yet other nonstandard predefined macros describe the manufacturer of +the system. For example, + +@table @code +@item sun +@findex sun +@samp{sun} is predefined on all models of Sun computers. + +@item pyr +@findex pyr +@samp{pyr} is predefined on all models of Pyramid computers. + +@item sequent +@findex sequent +@samp{sequent} is predefined on all models of Sequent computers. +@end table + +These predefined symbols are not only nonstandard, they are contrary to the +ANSI standard because their names do not start with underscores. +Therefore, the option @samp{-ansi} inhibits the definition of these +symbols. + +This tends to make @samp{-ansi} useless, since many programs depend on the +customary nonstandard predefined symbols. Even system header files check +them and will generate incorrect declarations if they do not find the names +that are expected. You might think that the header files supplied for the +Uglix computer would not need to test what machine they are running on, +because they can simply assume it is the Uglix; but often they do, and they +do so using the customary names. As a result, very few C programs will +compile with @samp{-ansi}. We intend to avoid such problems on the GNU +system. + +What, then, should you do in an ANSI C program to test the type of machine +it will run on? + +GNU C offers a parallel series of symbols for this purpose, whose names +are made from the customary ones by adding @samp{__} at the beginning +and end. Thus, the symbol @code{__vax__} would be available on a Vax, +and so on. + +The set of nonstandard predefined names in the GNU C preprocessor is +controlled (when @code{cpp} is itself compiled) by the macro +@samp{CPP_PREDEFINES}, which should be a string containing @samp{-D} +options, separated by spaces. For example, on the Sun 3, we use the +following definition: + +@example +#define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" +@end example + +@noindent +This macro is usually specified in @file{tm.h}. + +@node Stringification, Concatenation, Predefined, Macros +@subsection Stringification + +@cindex stringification +@dfn{Stringification} means turning a code fragment into a string constant +whose contents are the text for the code fragment. For example, +stringifying @samp{foo (z)} results in @samp{"foo (z)"}. + +In the C preprocessor, stringification is an option available when macro +arguments are substituted into the macro definition. In the body of the +definition, when an argument name appears, the character @samp{#} before +the name specifies stringification of the corresponding actual argument +when it is substituted at that point in the definition. The same argument +may be substituted in other places in the definition without +stringification if the argument name appears in those places with no +@samp{#}. + +Here is an example of a macro definition that uses stringification: + +@smallexample +@group +#define WARN_IF(EXP) \ +do @{ if (EXP) \ + fprintf (stderr, "Warning: " #EXP "\n"); @} \ +while (0) +@end group +@end smallexample + +@noindent +Here the actual argument for @samp{EXP} is substituted once as given, +into the @samp{if} statement, and once as stringified, into the +argument to @samp{fprintf}. The @samp{do} and @samp{while (0)} are +a kludge to make it possible to write @samp{WARN_IF (@var{arg});}, +which the resemblance of @samp{WARN_IF} to a function would make +C programmers want to do; see @ref{Swallow Semicolon}. + +The stringification feature is limited to transforming one macro argument +into one string constant: there is no way to combine the argument with +other text and then stringify it all together. But the example above shows +how an equivalent result can be obtained in ANSI Standard C using the +feature that adjacent string constants are concatenated as one string +constant. The preprocessor stringifies the actual value of @samp{EXP} +into a separate string constant, resulting in text like + +@smallexample +@group +do @{ if (x == 0) \ + fprintf (stderr, "Warning: " "x == 0" "\n"); @} \ +while (0) +@end group +@end smallexample + +@noindent +but the C compiler then sees three consecutive string constants and +concatenates them into one, producing effectively + +@smallexample +do @{ if (x == 0) \ + fprintf (stderr, "Warning: x == 0\n"); @} \ +while (0) +@end smallexample + +Stringification in C involves more than putting doublequote characters +around the fragment; it is necessary to put backslashes in front of all +doublequote characters, and all backslashes in string and character +constants, in order to get a valid C string constant with the proper +contents. Thus, stringifying @samp{p = "foo\n";} results in @samp{"p = +\"foo\\n\";"}. However, backslashes that are not inside of string or +character constants are not duplicated: @samp{\n} by itself stringifies to +@samp{"\n"}. + +Whitespace (including comments) in the text being stringified is handled +according to precise rules. All leading and trailing whitespace is ignored. +Any sequence of whitespace in the middle of the text is converted to +a single space in the stringified result. + +@node Concatenation, Undefining, Stringification, Macros +@subsection Concatenation +@cindex concatenation +@cindex @samp{##} +@dfn{Concatenation} means joining two strings into one. In the context +of macro expansion, concatenation refers to joining two lexical units +into one longer one. Specifically, an actual argument to the macro can be +concatenated with another actual argument or with fixed text to produce +a longer name. The longer name might be the name of a function, +variable or type, or a C keyword; it might even be the name of another +macro, in which case it will be expanded. + +When you define a macro, you request concatenation with the special +operator @samp{##} in the macro body. When the macro is called, +after actual arguments are substituted, all @samp{##} operators are +deleted, and so is any whitespace next to them (including whitespace +that was part of an actual argument). The result is to concatenate +the syntactic tokens on either side of the @samp{##}. + +Consider a C program that interprets named commands. There probably needs +to be a table of commands, perhaps an array of structures declared as +follows: + +@example +struct command +@{ + char *name; + void (*function) (); +@}; + +struct command commands[] = +@{ + @{ "quit", quit_command@}, + @{ "help", help_command@}, + @dots{} +@}; +@end example + +It would be cleaner not to have to give each command name twice, once in +the string constant and once in the function name. A macro which takes the +name of a command as an argument can make this unnecessary. The string +constant can be created with stringification, and the function name by +concatenating the argument with @samp{_command}. Here is how it is done: + +@example +#define COMMAND(NAME) @{ #NAME, NAME ## _command @} + +struct command commands[] = +@{ + COMMAND (quit), + COMMAND (help), + @dots{} +@}; +@end example + +The usual case of concatenation is concatenating two names (or a name and a +number) into a longer name. But this isn't the only valid case. It is +also possible to concatenate two numbers (or a number and a name, such as +@samp{1.5} and @samp{e3}) into a number. Also, multi-character operators +such as @samp{+=} can be formed by concatenation. In some cases it is even +possible to piece together a string constant. However, two pieces of text +that don't together form a valid lexical unit cannot be concatenated. For +example, concatenation with @samp{x} on one side and @samp{+} on the other +is not meaningful because those two characters can't fit together in any +lexical unit of C. The ANSI standard says that such attempts at +concatenation are undefined, but in the GNU C preprocessor it is well +defined: it puts the @samp{x} and @samp{+} side by side with no particular +special results. + +Keep in mind that the C preprocessor converts comments to whitespace before +macros are even considered. Therefore, you cannot create a comment by +concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a +comment is not a lexical unit, but rather the beginning of a ``long'' space +character. Also, you can freely use comments next to a @samp{##} in a +macro definition, or in actual arguments that will be concatenated, because +the comments will be converted to spaces at first sight, and concatenation +will later discard the spaces. + +@node Undefining, Redefining, Concatenation, Macros +@subsection Undefining Macros + +@cindex undefining macros +To @dfn{undefine} a macro means to cancel its definition. This is done +with the @samp{#undef} directive. @samp{#undef} is followed by the macro +name to be undefined. + +Like definition, undefinition occurs at a specific point in the source +file, and it applies starting from that point. The name ceases to be a +macro name, and from that point on it is treated by the preprocessor as if +it had never been a macro name. + +For example, + +@example +#define FOO 4 +x = FOO; +#undef FOO +x = FOO; +@end example + +@noindent +expands into + +@example +x = 4; + +x = FOO; +@end example + +@noindent +In this example, @samp{FOO} had better be a variable or function as well +as (temporarily) a macro, in order for the result of the expansion to be +valid C code. + +The same form of @samp{#undef} directive will cancel definitions with +arguments or definitions that don't expect arguments. The @samp{#undef} +directive has no effect when used on a name not currently defined as a macro. + +@node Redefining, Macro Pitfalls, Undefining, Macros +@subsection Redefining Macros + +@cindex redefining macros +@dfn{Redefining} a macro means defining (with @samp{#define}) a name that +is already defined as a macro. + +A redefinition is trivial if the new definition is transparently identical +to the old one. You probably wouldn't deliberately write a trivial +redefinition, but they can happen automatically when a header file is +included more than once (@pxref{Header Files}), so they are accepted +silently and without effect. + +Nontrivial redefinition is considered likely to be an error, so +it provokes a warning message from the preprocessor. However, sometimes it +is useful to change the definition of a macro in mid-compilation. You can +inhibit the warning by undefining the macro with @samp{#undef} before the +second definition. + +In order for a redefinition to be trivial, the new definition must +exactly match the one already in effect, with two possible exceptions: + +@itemize @bullet +@item +Whitespace may be added or deleted at the beginning or the end. + +@item +Whitespace may be changed in the middle (but not inside strings). +However, it may not be eliminated entirely, and it may not be added +where there was no whitespace at all. +@end itemize + +Recall that a comment counts as whitespace. + +@node Macro Pitfalls,, Redefining, Macros +@subsection Pitfalls and Subtleties of Macros +@cindex problems with macros +@cindex pitfalls of macros + +In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counterintuitive consequences that you must watch out for. + +@menu +* Misnesting:: Macros can contain unmatched parentheses. +* Macro Parentheses:: Why apparently superfluous parentheses + may be necessary to avoid incorrect grouping. +* Swallow Semicolon:: Macros that look like functions + but expand into compound statements. +* Side Effects:: Unsafe macros that cause trouble when + arguments contain side effects. +* Self-Reference:: Macros whose definitions use the macros' own names. +* Argument Prescan:: Actual arguments are checked for macro calls + before they are substituted. +* Cascaded Macros:: Macros whose definitions use other macros. +* Newlines in Args:: Sometimes line numbers get confused. +@end menu + +@node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls +@subsubsection Improperly Nested Constructs + +Recall that when a macro is called with arguments, the arguments are +substituted into the macro body and the result is checked, together with +the rest of the input file, for more macro calls. + +It is possible to piece together a macro call coming partially from the +macro body and partially from the actual arguments. For example, + +@example +#define double(x) (2*(x)) +#define call_with_1(x) x(1) +@end example + +@noindent +would expand @samp{call_with_1 (double)} into @samp{(2*(1))}. + +Macro definitions do not have to have balanced parentheses. By writing an +unbalanced open parenthesis in a macro body, it is possible to create a +macro call that begins inside the macro body but ends outside of it. For +example, + +@example +#define strange(file) fprintf (file, "%s %d", +@dots{} +strange(stderr) p, 35) +@end example + +@noindent +This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}! + +@node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls +@subsubsection Unintended Grouping of Arithmetic +@cindex parentheses in macro bodies + +You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around it. +In addition, another pair of parentheses usually surround the entire macro +definition. Here is why it is best to write macros that way. + +Suppose you define a macro as follows, + +@example +#define ceil_div(x, y) (x + y - 1) / y +@end example + +@noindent +whose purpose is to divide, rounding up. (One use for this operation is +to compute how many @samp{int} objects are needed to hold a certain +number of @samp{char} objects.) Then suppose it is used as follows: + +@example +a = ceil_div (b & c, sizeof (int)); +@end example + +@noindent +This expands into + +@example +a = (b & c + sizeof (int) - 1) / sizeof (int); +@end example + +@noindent +which does not do what is intended. The operator-precedence rules of +C make it equivalent to this: + +@example +a = (b & (c + sizeof (int) - 1)) / sizeof (int); +@end example + +@noindent +But what we want is this: + +@example +a = ((b & c) + sizeof (int) - 1)) / sizeof (int); +@end example + +@noindent +Defining the macro as + +@example +#define ceil_div(x, y) ((x) + (y) - 1) / (y) +@end example + +@noindent +provides the desired result. + +However, unintended grouping can result in another way. Consider +@samp{sizeof ceil_div(1, 2)}. That has the appearance of a C expression +that would compute the size of the type of @samp{ceil_div (1, 2)}, but in +fact it means something very different. Here is what it expands to: + +@example +sizeof ((1) + (2) - 1) / (2) +@end example + +@noindent +This would take the size of an integer and divide it by two. The precedence +rules have put the division outside the @samp{sizeof} when it was intended +to be inside. + +Parentheses around the entire macro definition can prevent such problems. +Here, then, is the recommended way to define @samp{ceil_div}: + +@example +#define ceil_div(x, y) (((x) + (y) - 1) / (y)) +@end example + +@node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls +@subsubsection Swallowing the Semicolon + +@cindex semicolons (after macro calls) +Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument @samp{p} says where to find it) across whitespace +characters: + +@example +#define SKIP_SPACES (p, limit) \ +@{ register char *lim = (limit); \ + while (p != lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} +@end example + +@noindent +Here Backslash-Newline is used to split the macro definition, which must +be a single line, so that it resembles the way such C code would be +laid out if not part of a macro definition. + +A call to this macro might be @samp{SKIP_SPACES (p, lim)}. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. But it looks like a +function call. So it minimizes confusion if you can use it like a function +call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);} + +But this can cause trouble before @samp{else} statements, because the +semicolon is actually a null statement. Suppose you write + +@example +if (*p != 0) + SKIP_SPACES (p, lim); +else @dots{} +@end example + +@noindent +The presence of two statements---the compound statement and a null +statement---in between the @samp{if} condition and the @samp{else} +makes invalid C code. + +The definition of the macro @samp{SKIP_SPACES} can be altered to solve +this problem, using a @samp{do @dots{} while} statement. Here is how: + +@example +#define SKIP_SPACES (p, limit) \ +do @{ register char *lim = (limit); \ + while (p != lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} \ +while (0) +@end example + +Now @samp{SKIP_SPACES (p, lim);} expands into + +@example +do @{@dots{}@} while (0); +@end example + +@noindent +which is one statement. + +@node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls +@subsubsection Duplication of Side Effects + +@cindex side effects (in macro arguments) +@cindex unsafe macros +Many C programs define a macro @samp{min}, for ``minimum'', like this: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@end example + +When you use this macro with an argument containing a side effect, +as shown here, + +@example +next = min (x + y, foo (z)); +@end example + +@noindent +it expands as follows: + +@example +next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); +@end example + +@noindent +where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)} +for @samp{Y}. + +The function @samp{foo} is used only once in the statement as it appears +in the program, but the expression @samp{foo (z)} has been substituted +twice into the macro expansion. As a result, @samp{foo} might be called +two times when the statement is executed. If it has side effects or +if it takes a long time to compute, the results might not be what you +intended. We say that @samp{min} is an @dfn{unsafe} macro. + +The best solution to this problem is to define @samp{min} in a way that +computes the value of @samp{foo (z)} only once. The C language offers no +standard way to do this, but it can be done with GNU C extensions as +follows: + +@example +#define min(X, Y) \ +(@{ typeof (X) __x = (X), __y = (Y); \ + (__x < __y) ? __x : __y; @}) +@end example + +If you do not wish to use GNU C extensions, the only solution is to be +careful when @emph{using} the macro @samp{min}. For example, you can +calculate the value of @samp{foo (z)}, save it in a variable, and use that +variable in @samp{min}: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@dots{} +@{ + int tem = foo (z); + next = min (x + y, tem); +@} +@end example + +@noindent +(where we assume that @samp{foo} returns type @samp{int}). + +@node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls +@subsubsection Self-Referential Macros + +@cindex self-reference +A @dfn{self-referential} macro is one whose name appears in its definition. +A special feature of ANSI Standard C is that the self-reference is not +considered a macro call. It is passed into the preprocessor output +unchanged. + +Let's consider an example: + +@example +#define foo (4 + foo) +@end example + +@noindent +where @samp{foo} is also a variable in your program. + +Following the ordinary rules, each reference to @samp{foo} will expand into +@samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4 ++ (4 + foo))}; and so on until it causes a fatal error (memory full) in the +preprocessor. + +However, the special rule about self-reference cuts this process short +after one step, at @samp{(4 + foo)}. Therefore, this macro definition +has the possibly useful effect of causing the program to add 4 to +the value of @samp{foo} wherever @samp{foo} is referred to. + +In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that @samp{foo} is a variable will +not expect that it is a macro as well. The reader will come across the +identifier @samp{foo} in the program and think its value should be that +of the variable @samp{foo}, whereas in fact the value is four greater. + +The special rule for self-reference applies also to @dfn{indirect} +self-reference. This is the case where a macro @var{x} expands to use a +macro @samp{y}, and the expansion of @samp{y} refers to the macro +@samp{x}. The resulting reference to @samp{x} comes indirectly from the +expansion of @samp{x}, so it is a self-reference and is not further +expanded. Thus, after + +@example +#define x (4 + y) +#define y (2 * x) +@end example + +@noindent +@samp{x} would expand into @samp{(4 + (2 * x))}. Clear? + +But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}. +Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference +because @samp{x} is not ``in progress''. So it does expand. However, +the expansion of @samp{x} contains a reference to @samp{y}, and that +is an indirect self-reference now because @samp{y} is ``in progress''. +The result is that @samp{y} expands to @samp{(2 * (4 + y))}. + +It is not clear that this behavior would ever be useful, but it is specified +by the ANSI C standard, so you may need to understand it. + +@node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls +@subsubsection Separate Expansion of Macro Arguments +@cindex expansion of arguments +@cindex macro argument expansion +@cindex prescan of macro arguments + +We have explained that the expansion of a macro, including the substituted +actual arguments, is scanned over again for macro calls to be expanded. + +What really happens is more subtle: first each actual argument text is scanned +separately for macro calls. Then the results of this are substituted into +the macro body to produce the macro expansion, and the macro expansion +is scanned again for macros to expand. + +The result is that the actual arguments are scanned @emph{twice} to expand +macro calls in them. + +Most of the time, this has no effect. If the actual argument contained +any macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change it. +If the actual argument were substituted as given, with no prescan, +the single remaining scan would find the same macro calls and produce +the same results. + +You might expect the double scan to change the results when a +self-referential macro is used in an actual argument of another macro +(@pxref{Self-Reference}): the self-referential macro would be expanded once +in the first scan, and a second time in the second scan. But this is not +what happens. The self-references that do not expand in the first scan are +marked so that they will not expand in the second scan either. + +The prescan is not done when an argument is stringified or concatenated. +Thus, + +@example +#define str(s) #s +#define foo 4 +str (foo) +@end example + +@noindent +expands to @samp{"foo"}. Once more, prescan has been prevented from +having any noticeable effect. + +More precisely, stringification and concatenation use the argument as +written, in un-prescanned form. The same actual argument would be used in +prescanned form if it is substituted elsewhere without stringification or +concatenation. + +@example +#define str(s) #s lose(s) +#define foo 4 +str (foo) +@end example + +expands to @samp{"foo" lose(4)}. + +You might now ask, ``Why mention the prescan, if it makes no difference? +And why not skip it and make the preprocessor faster?'' The answer is +that the prescan does make a difference in three special cases: + +@itemize @bullet +@item +Nested calls to a macro. + +@item +Macros that call other macros that stringify or concatenate. + +@item +Macros whose expansions contain unshielded commas. +@end itemize + +We say that @dfn{nested} calls to a macro occur when a macro's actual +argument contains a call to that very macro. For example, if @samp{f} +is a macro that expects one argument, @samp{f (f (1))} is a nested +pair of calls to @samp{f}. The desired expansion is made by +expanding @samp{f (1)} and substituting that into the definition of +@samp{f}. The prescan causes the expected result to happen. +Without the prescan, @samp{f (1)} itself would be substituted as +an actual argument, and the inner use of @samp{f} would appear +during the main scan as an indirect self-reference and would not +be expanded. Here, the prescan cancels an undesirable side effect +(in the medical, not computational, sense of the term) of the special +rule for self-referential macros. + +But prescan causes trouble in certain other cases of nested macro calls. +Here is an example: + +@example +#define foo a,b +#define bar(x) lose(x) +#define lose(x) (1 + (x)) + +bar(foo) +@end example + +@noindent +We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which +would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)} +expands into @samp{lose(a,b)}, and you get an error because @code{lose} +requires a single argument. In this case, the problem is easily solved +by the same parentheses that ought to be used to prevent misnesting of +arithmetic operations: + +@example +#define foo (a,b) +#define bar(x) lose((x)) +@end example + +The problem is more serious when the operands of the macro are not +expressions; for example, when they are statements. Then parentheses +are unacceptable because they would make for invalid C code: + +@example +#define foo @{ int a, b; @dots{} @} +@end example + +@noindent +In GNU C you can shield the commas using the @samp{(@{@dots{}@})} +construct which turns a compound statement into an expression: + +@example +#define foo (@{ int a, b; @dots{} @}) +@end example + +Or you can rewrite the macro definition to avoid such commas: + +@example +#define foo @{ int a; int b; @dots{} @} +@end example + +There is also one case where prescan is useful. It is possible +to use prescan to expand an argument and then stringify it---if you use +two levels of macros. Let's add a new macro @samp{xstr} to the +example shown above: + +@example +#define xstr(s) str(s) +#define str(s) #s +#define foo 4 +xstr (foo) +@end example + +This expands into @samp{"4"}, not @samp{"foo"}. The reason for the +difference is that the argument of @samp{xstr} is expanded at prescan +(because @samp{xstr} does not specify stringification or concatenation of +the argument). The result of prescan then forms the actual argument for +@samp{str}. @samp{str} uses its argument without prescan because it +performs stringification; but it cannot prevent or undo the prescanning +already done by @samp{xstr}. + +@node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls +@subsubsection Cascaded Use of Macros + +@cindex cascaded macros +@cindex macro body uses macro +A @dfn{cascade} of macros is when one macro's body contains a reference +to another macro. This is very common practice. For example, + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +@end example + +This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. +The @samp{#define} for @samp{TABLESIZE} uses exactly the body you +specify---in this case, @samp{BUFSIZE}---and does not check to see whether +it too is the name of a macro. + +It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion +is checked for more macro names. + +This makes a difference if you change the definition of @samp{BUFSIZE} +at some point in the source file. @samp{TABLESIZE}, defined as shown, +will always expand using the definition of @samp{BUFSIZE} that is +currently in effect: + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +#undef BUFSIZE +#define BUFSIZE 37 +@end example + +@noindent +Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The +@samp{#undef} is to prevent any warning about the nontrivial +redefinition of @code{BUFSIZE}.) + +@node Newlines in Args,, Cascaded Macros, Macro Pitfalls +@subsection Newlines in Macro Arguments +@cindex newlines in macro arguments + +Traditional macro processing carries forward all newlines in macro +arguments into the expansion of the macro. This means that, if some of +the arguments are substituted more than once, or not at all, or out of +order, newlines can be duplicated, lost, or moved around within the +expansion. If the expansion consists of multiple statements, then the +effect is to distort the line numbers of some of these statements. The +result can be incorrect line numbers, in error messages or displayed in +a debugger. + +The GNU C preprocessor operating in ANSI C mode adjusts appropriately +for multiple use of an argument---the first use expands all the +newlines, and subsequent uses of the same argument produce no newlines. +But even in this mode, it can produce incorrect line numbering if +arguments are used out of order, or not used at all. + +Here is an example illustrating this problem: + +@example +#define ignore_second_arg(a,b,c) a; c + +ignore_second_arg (foo (), + ignored (), + syntax error); +@end example + +@noindent +The syntax error triggered by the tokens @samp{syntax error} results +in an error message citing line four, even though the statement text +comes from line five. + +@node Conditionals, Combining Sources, Macros, Top +@section Conditionals + +@cindex conditionals +In a macro processor, a @dfn{conditional} is a directive that allows a part +of the program to be ignored during compilation, on some conditions. +In the C preprocessor, a conditional can test either an arithmetic expression +or whether a name is defined as a macro. + +A conditional in the C preprocessor resembles in some ways an @samp{if} +statement in C, but it is important to understand the difference between +them. The condition in an @samp{if} statement is tested during the execution +of your program. Its purpose is to allow your program to behave differently +from run to run, depending on the data it is operating on. The condition +in a preprocessing conditional directive is tested when your program is compiled. +Its purpose is to allow different code to be included in the program depending +on the situation at the time of compilation. + +@menu +* Uses: Conditional Uses. What conditionals are for. +* Syntax: Conditional Syntax. How conditionals are written. +* Deletion: Deleted Code. Making code into a comment. +* Macros: Conditionals-Macros. Why conditionals are used with macros. +* Assertions:: How and why to use assertions. +* Errors: #error Directive. Detecting inconsistent compilation parameters. +@end menu + +@node Conditional Uses +@subsection Why Conditionals are Used + +Generally there are three kinds of reason to use a conditional. + +@itemize @bullet +@item +A program may need to use different code depending on the machine or +operating system it is to run on. In some cases the code for one +operating system may be erroneous on another operating system; for +example, it might refer to library routines that do not exist on the +other system. When this happens, it is not enough to avoid executing +the invalid code: merely having it in the program makes it impossible +to link the program and run it. With a preprocessing conditional, the +offending code can be effectively excised from the program when it is +not valid. + +@item +You may want to be able to compile the same source file into two +different programs. Sometimes the difference between the programs is +that one makes frequent time-consuming consistency checks on its +intermediate data, or prints the values of those data for debugging, +while the other does not. + +@item +A conditional whose condition is always false is a good way to exclude +code from the program but keep it as a sort of comment for future +reference. +@end itemize + +Most simple programs that are intended to run on only one machine will +not need to use preprocessing conditionals. + +@node Conditional Syntax +@subsection Syntax of Conditionals + +@findex #if +A conditional in the C preprocessor begins with a @dfn{conditional +directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. +@xref{Conditionals-Macros}, for information on @samp{#ifdef} and +@samp{#ifndef}; only @samp{#if} is explained here. + +@menu +* If: #if Directive. Basic conditionals using @samp{#if} and @samp{#endif}. +* Else: #else Directive. Including some text if the condition fails. +* Elif: #elif Directive. Testing several alternative possibilities. +@end menu + +@node #if Directive +@subsubsection The @samp{#if} Directive + +The @samp{#if} directive in its simplest form consists of + +@example +#if @var{expression} +@var{controlled text} +#endif /* @var{expression} */ +@end example + +The comment following the @samp{#endif} is not required, but it is a good +practice because it helps people match the @samp{#endif} to the +corresponding @samp{#if}. Such comments should always be used, except in +short conditionals that are not nested. In fact, you can put anything at +all after the @samp{#endif} and it will be ignored by the GNU C preprocessor, +but only comments are acceptable in ANSI Standard C. + +@var{expression} is a C expression of integer type, subject to stringent +restrictions. It may contain + +@itemize @bullet +@item +Integer constants, which are all regarded as @code{long} or +@code{unsigned long}. + +@item +Character constants, which are interpreted according to the character +set and conventions of the machine and operating system on which the +preprocessor is running. The GNU C preprocessor uses the C data type +@samp{char} for these character constants; therefore, whether some +character codes are negative is determined by the C compiler used to +compile the preprocessor. If it treats @samp{char} as signed, then +character codes large enough to set the sign bit will be considered +negative; otherwise, no character code is considered negative. + +@item +Arithmetic operators for addition, subtraction, multiplication, +division, bitwise operations, shifts, comparisons, and logical +operations (@samp{&&} and @samp{||}). + +@item +Identifiers that are not macros, which are all treated as zero(!). + +@item +Macro calls. All macro calls in the expression are expanded before +actual computation of the expression's value begins. +@end itemize + +Note that @samp{sizeof} operators and @code{enum}-type values are not allowed. +@code{enum}-type values, like all other identifiers that are not taken +as macro calls and expanded, are treated as zero. + +The @var{controlled text} inside of a conditional can include +preprocessing directives. Then the directives inside the conditional are +obeyed only if that branch of the conditional succeeds. The text can +also contain other conditional groups. However, the @samp{#if} and +@samp{#endif} directives must balance. + +@node #else Directive +@subsubsection The @samp{#else} Directive + +@findex #else +The @samp{#else} directive can be added to a conditional to provide +alternative text to be used if the condition is false. This is what +it looks like: + +@example +#if @var{expression} +@var{text-if-true} +#else /* Not @var{expression} */ +@var{text-if-false} +#endif /* Not @var{expression} */ +@end example + +If @var{expression} is nonzero, and thus the @var{text-if-true} is +active, then @samp{#else} acts like a failing conditional and the +@var{text-if-false} is ignored. Contrariwise, if the @samp{#if} +conditional fails, the @var{text-if-false} is considered included. + +@node #elif Directive +@subsubsection The @samp{#elif} Directive + +@findex #elif +One common case of nested conditionals is used to check for more than two +possible alternatives. For example, you might have + +@example +#if X == 1 +@dots{} +#else /* X != 1 */ +#if X == 2 +@dots{} +#else /* X != 2 */ +@dots{} +#endif /* X != 2 */ +#endif /* X != 1 */ +@end example + +Another conditional directive, @samp{#elif}, allows this to be abbreviated +as follows: + +@example +#if X == 1 +@dots{} +#elif X == 2 +@dots{} +#else /* X != 2 and X != 1*/ +@dots{} +#endif /* X != 2 and X != 1*/ +@end example + +@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the +middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not +require a matching @samp{#endif} of its own. Like @samp{#if}, the +@samp{#elif} directive includes an expression to be tested. + +The text following the @samp{#elif} is processed only if the original +@samp{#if}-condition failed and the @samp{#elif} condition succeeds. +More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif} +group. Then the text after each @samp{#elif} is processed only if the +@samp{#elif} condition succeeds after the original @samp{#if} and any +previous @samp{#elif} directives within it have failed. @samp{#else} is +equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any +number of @samp{#elif} directives, but @samp{#elif} may not follow +@samp{#else}. + +@node Deleted Code +@subsection Keeping Deleted Code for Future Reference +@cindex commenting out code + +If you replace or delete a part of the program but want to keep the old +code around as a comment for future reference, the easy way to do this +is to put @samp{#if 0} before it and @samp{#endif} after it. This is +better than using comment delimiters @samp{/*} and @samp{*/} since those +won't work if the code already contains comments (C comments do not +nest). + +This works even if the code being turned off contains conditionals, but +they must be entire conditionals (balanced @samp{#if} and @samp{#endif}). + +Conversely, do not use @samp{#if 0} for comments which are not C code. +Use the comment delimiters @samp{/*} and @samp{*/} instead. The +interior of @samp{#if 0} must consist of complete tokens; in particular, +singlequote characters must balance. But comments often contain +unbalanced singlequote characters (known in English as apostrophes). +These confuse @samp{#if 0}. They do not confuse @samp{/*}. + +@node Conditionals-Macros +@subsection Conditionals and Macros + +Conditionals are useful in connection with macros or assertions, because +those are the only ways that an expression's value can vary from one +compilation to another. A @samp{#if} directive whose expression uses no +macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you +might as well determine which one, by computing the value of the +expression yourself, and then simplify the program. + +For example, here is a conditional that tests the expression +@samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro. + +@example +#if BUFSIZE == 1020 + printf ("Large buffers!\n"); +#endif /* BUFSIZE is large */ +@end example + +(Programmers often wish they could test the size of a variable or data +type in @samp{#if}, but this does not work. The preprocessor does not +understand @code{sizeof}, or typedef names, or even the type keywords +such as @code{int}.) + +@findex defined +The special operator @samp{defined} is used in @samp{#if} expressions to +test whether a certain name is defined as a macro. Either @samp{defined +@var{name}} or @samp{defined (@var{name})} is an expression whose value +is 1 if @var{name} is defined as macro at the current point in the +program, and 0 otherwise. For the @samp{defined} operator it makes no +difference what the definition of the macro is; all that matters is +whether there is a definition. Thus, for example,@refill + +@example +#if defined (vax) || defined (ns16000) +@end example + +@noindent +would succeed if either of the names @samp{vax} and @samp{ns16000} is +defined as a macro. You can test the same condition using assertions +(@pxref{Assertions}), like this: + +@example +#if #cpu (vax) || #cpu (ns16000) +@end example + +If a macro is defined and later undefined with @samp{#undef}, +subsequent use of the @samp{defined} operator returns 0, because +the name is no longer defined. If the macro is defined again with +another @samp{#define}, @samp{defined} will recommence returning 1. + +@findex #ifdef +@findex #ifndef +Conditionals that test whether just one name is defined are very common, +so there are two special short conditional directives for this case. + +@table @code +@item #ifdef @var{name} +is equivalent to @samp{#if defined (@var{name})}. + +@item #ifndef @var{name} +is equivalent to @samp{#if ! defined (@var{name})}. +@end table + +Macro definitions can vary between compilations for several reasons. + +@itemize @bullet +@item +Some macros are predefined on each kind of machine. For example, on a +Vax, the name @samp{vax} is a predefined macro. On other machines, it +would not be defined. + +@item +Many more macros are defined by system header files. Different +systems and machines define different macros, or give them different +values. It is useful to test these macros with conditionals to avoid +using a system feature on a machine where it is not implemented. + +@item +Macros are a common way of allowing users to customize a program for +different machines or applications. For example, the macro +@samp{BUFSIZE} might be defined in a configuration file for your +program that is included as a header file in each source file. You +would use @samp{BUFSIZE} in a preprocessing conditional in order to +generate different code depending on the chosen configuration. + +@item +Macros can be defined or undefined with @samp{-D} and @samp{-U} +command options when you compile the program. You can arrange to +compile the same source file into two different programs by choosing +a macro name to specify which program you want, writing conditionals +to test whether or how this macro is defined, and then controlling +the state of the macro with compiler command options. +@xref{Invocation}. +@end itemize + +@ifinfo +Assertions are usually predefined, but can be defined with preprocessor +directives or command-line options. +@end ifinfo + +@node Assertions +@subsection Assertions + +@cindex assertions +@dfn{Assertions} are a more systematic alternative to macros in writing +conditionals to test what sort of computer or system the compiled +program will run on. Assertions are usually predefined, but you can +define them with preprocessing directives or command-line options. + +@cindex predicates +The macros traditionally used to describe the type of target are not +classified in any way according to which question they answer; they may +indicate a hardware architecture, a particular hardware model, an +operating system, a particular version of an operating system, or +specific configuration options. These are jumbled together in a single +namespace. In contrast, each assertion consists of a named question and +an answer. The question is usually called the @dfn{predicate}. +An assertion looks like this: + +@example +#@var{predicate} (@var{answer}) +@end example + +@noindent +You must use a properly formed identifier for @var{predicate}. The +value of @var{answer} can be any sequence of words; all characters are +significant except for leading and trailing whitespace, and differences +in internal whitespace sequences are ignored. Thus, @samp{x + y} is +different from @samp{x+y} but equivalent to @samp{x + y}. @samp{)} is +not allowed in an answer. + +@cindex testing predicates +Here is a conditional to test whether the answer @var{answer} is asserted +for the predicate @var{predicate}: + +@example +#if #@var{predicate} (@var{answer}) +@end example + +@noindent +There may be more than one answer asserted for a given predicate. If +you omit the answer, you can test whether @emph{any} answer is asserted +for @var{predicate}: + +@example +#if #@var{predicate} +@end example + +@findex #system +@findex #machine +@findex #cpu +Most of the time, the assertions you test will be predefined assertions. +GNU C provides three predefined predicates: @code{system}, @code{cpu}, +and @code{machine}. @code{system} is for assertions about the type of +software, @code{cpu} describes the type of computer architecture, and +@code{machine} gives more information about the computer. For example, +on a GNU system, the following assertions would be true: + +@example +#system (gnu) +#system (mach) +#system (mach 3) +#system (mach 3.@var{subversion}) +#system (hurd) +#system (hurd @var{version}) +@end example + +@noindent +and perhaps others. The alternatives with +more or less version information let you ask more or less detailed +questions about the type of system software. + +On a Unix system, you would find @code{#system (unix)} and perhaps one of: +@code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)}, +@code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)}, +@code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)} +with possible version numbers following. + +Other values for @code{system} are @code{#system (mvs)} +and @code{#system (vms)}. + +@strong{Portability note:} Many Unix C compilers provide only one answer +for the @code{system} assertion: @code{#system (unix)}, if they support +assertions at all. This is less than useful. + +An assertion with a multi-word answer is completely different from several +assertions with individual single-word answers. For example, the presence +of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true. +It also does not directly imply @code{system (mach)}, but in GNU C, that +last will normally be asserted as well. + +The current list of possible assertion values for @code{cpu} is: +@code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu +(clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu +(tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)}, +@code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu +(m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)}, +@code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)}, +@code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu +(tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}. + +@findex #assert +You can create assertions within a C program using @samp{#assert}, like +this: + +@example +#assert @var{predicate} (@var{answer}) +@end example + +@noindent +(Note the absence of a @samp{#} before @var{predicate}.) + +@cindex unassert +@cindex assertions, undoing +@cindex retracting assertions +@findex #unassert +Each time you do this, you assert a new true answer for @var{predicate}. +Asserting one answer does not invalidate previously asserted answers; +they all remain true. The only way to remove an assertion is with +@samp{#unassert}. @samp{#unassert} has the same syntax as +@samp{#assert}. You can also remove all assertions about +@var{predicate} like this: + +@example +#unassert @var{predicate} +@end example + +You can also add or cancel assertions using command options +when you run @code{gcc} or @code{cpp}. @xref{Invocation}. + +@node #error Directive +@subsection The @samp{#error} and @samp{#warning} Directives + +@findex #error +The directive @samp{#error} causes the preprocessor to report a fatal +error. The rest of the line that follows @samp{#error} is used as the +error message. + +You would use @samp{#error} inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a Vax, you might write + +@smallexample +@group +#ifdef __vax__ +#error Won't work on Vaxen. See comments at get_last_object. +#endif +@end group +@end smallexample + +@noindent +@xref{Nonstandard Predefined}, for why this works. + +If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with @samp{#error}. For example, + +@smallexample +#if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ + || HASH_TABLE_SIZE % 5 == 0 +#error HASH_TABLE_SIZE should not be divisible by a small prime +#endif +@end smallexample + +@findex #warning +The directive @samp{#warning} is like the directive @samp{#error}, but causes +the preprocessor to issue a warning and continue preprocessing. The rest of +the line that follows @samp{#warning} is used as the warning message. + +You might use @samp{#warning} in obsolete header files, with a message +directing the user to the header file which should be used instead. + +@node Combining Sources, Other Directives, Conditionals, Top +@section Combining Source Files + +@cindex line control +One of the jobs of the C preprocessor is to inform the C compiler of where +each line of C code came from: which source file and which line number. + +C code can come from multiple source files if you use @samp{#include}; +both @samp{#include} and the use of conditionals and macros can cause +the line number of a line in the preprocessor output to be different +from the line's number in the original source file. You will appreciate +the value of making both the C compiler (in error messages) and symbolic +debuggers such as GDB use the line numbers in your source file. + +The C preprocessor builds on this feature by offering a directive by which +you can control the feature explicitly. This is useful when a file for +input to the C preprocessor is the output from another program such as the +@code{bison} parser generator, which operates on another file that is the +true source file. Parts of the output from @code{bison} are generated from +scratch, other parts come from a standard parser file. The rest are copied +nearly verbatim from the source file, but their line numbers in the +@code{bison} output are not the same as their original line numbers. +Naturally you would like compiler error messages and symbolic debuggers to +know the original source file and line number of each line in the +@code{bison} input. + +@findex #line +@code{bison} arranges this by writing @samp{#line} directives into the output +file. @samp{#line} is a directive that specifies the original line number +and source file name for subsequent input in the current preprocessor input +file. @samp{#line} has three variants: + +@table @code +@item #line @var{linenum} +Here @var{linenum} is a decimal integer constant. This specifies that +the line number of the following line of input, in its original source file, +was @var{linenum}. + +@item #line @var{linenum} @var{filename} +Here @var{linenum} is a decimal integer constant and @var{filename} +is a string constant. This specifies that the following line of input +came originally from source file @var{filename} and its line number there +was @var{linenum}. Keep in mind that @var{filename} is not just a +file name; it is surrounded by doublequote characters so that it looks +like a string constant. + +@item #line @var{anything else} +@var{anything else} is checked for macro calls, which are expanded. +The result should be a decimal integer constant followed optionally +by a string constant, as described above. +@end table + +@samp{#line} directives alter the results of the @samp{__FILE__} and +@samp{__LINE__} predefined macros from that point on. @xref{Standard +Predefined}. + +The output of the preprocessor (which is the input for the rest of the +compiler) contains directives that look much like @samp{#line} directives. +They start with just @samp{#} instead of @samp{#line}, but this is +followed by a line number and file name as in @samp{#line}. @xref{Output}. + +@node Other Directives, Output, Combining Sources, Top +@section Miscellaneous Preprocessing Directives + +@cindex null directive +This section describes three additional preprocessing directives. They are +not very useful, but are mentioned for completeness. + +The @dfn{null directive} consists of a @samp{#} followed by a Newline, with +only whitespace (including comments) in between. A null directive is +understood as a preprocessing directive but has no effect on the preprocessor +output. The primary significance of the existence of the null directive is +that an input line consisting of just a @samp{#} will produce no output, +rather than a line of output containing just a @samp{#}. Supposedly +some old C programs contain such lines. + +@findex #pragma +The ANSI standard specifies that the @samp{#pragma} directive has an +arbitrary, implementation-defined effect. In the GNU C preprocessor, +@samp{#pragma} directives are not used, except for @samp{#pragma once} +(@pxref{Once-Only}). However, they are left in the preprocessor output, +so they are available to the compilation pass. + +@findex #ident +The @samp{#ident} directive is supported for compatibility with certain +other systems. It is followed by a line of text. On some systems, the +text is copied into a special place in the object file; on most systems, +the text is ignored and this directive has no effect. Typically +@samp{#ident} is only used in header files supplied with those systems +where it is meaningful. + +@node Output, Invocation, Other Directives, Top +@section C Preprocessor Output + +@cindex output format +The output from the C preprocessor looks much like the input, except +that all preprocessing directive lines have been replaced with blank lines +and all comments with spaces. Whitespace within a line is not altered; +however, unless @samp{-traditional} is used, spaces may be inserted into +the expansions of macro calls to prevent tokens from being concatenated. + +Source file name and line number information is conveyed by lines of +the form + +@example +# @var{linenum} @var{filename} @var{flags} +@end example + +@noindent +which are inserted as needed into the middle of the input (but never +within a string or character constant). Such a line means that the +following line originated in file @var{filename} at line @var{linenum}. + +After the file name comes zero or more flags, which are @samp{1}, +@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces separate +them. Here is what the flags mean: + +@table @samp +@item 1 +This indicates the start of a new file. +@item 2 +This indicates returning to a file (after having included another file). +@item 3 +This indicates that the following text comes from a system header file, +so certain warnings should be suppressed. +@item 4 +This indicates that the following text should be treated as C. +@c maybe cross reference NO_IMPLICIT_EXTERN_C +@end table + +@node Invocation, Concept Index, Output, Top +@section Invoking the C Preprocessor +@cindex invocation of the preprocessor + +Most often when you use the C preprocessor you will not have to invoke it +explicitly: the C compiler will do so automatically. However, the +preprocessor is sometimes useful on its own. + +The C preprocessor expects two file names as arguments, @var{infile} and +@var{outfile}. The preprocessor reads @var{infile} together with any other +files it specifies with @samp{#include}. All the output generated by the +combined input files is written in @var{outfile}. + +Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile} +means to read from standard input and as @var{outfile} means to write to +standard output. Also, if @var{outfile} or both file names are omitted, +the standard output and standard input are used for the omitted file names. + +@cindex options +Here is a table of command options accepted by the C preprocessor. +These options can also be given when compiling a C program; they are +passed along automatically to the preprocessor when it is invoked by the +compiler. + +@table @samp +@item -P +@findex -P +Inhibit generation of @samp{#}-lines with line-number information in +the output from the preprocessor (@pxref{Output}). This might be +useful when running the preprocessor on something that is not C code +and will be sent to a program which might be confused by the +@samp{#}-lines. + +@item -C +@findex -C +Do not discard comments: pass them through to the output file. +Comments appearing in arguments of a macro call will be copied to the +output before the expansion of the macro call. + +@item -traditional +@findex -traditional +Try to imitate the behavior of old-fashioned C, as opposed to ANSI C. + +@itemize @bullet +@item +Traditional macro expansion pays no attention to singlequote or +doublequote characters; macro argument symbols are replaced by the +argument values even when they appear within apparent string or +character constants. + +@item +Traditionally, it is permissible for a macro expansion to end in the +middle of a string or character constant. The constant continues into +the text surrounding the macro call. + +@item +However, traditionally the end of the line terminates a string or +character constant, with no error. + +@item +In traditional C, a comment is equivalent to no text at all. (In ANSI +C, a comment counts as whitespace.) + +@item +Traditional C does not have the concept of a ``preprocessing number''. +It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+}, +and @samp{4}. + +@item +A macro is not suppressed within its own definition, in traditional C. +Thus, any macro that is used recursively inevitably causes an error. + +@item +The character @samp{#} has no special meaning within a macro definition +in traditional C. + +@item +In traditional C, the text at the end of a macro expansion can run +together with the text after the macro call, to produce a single token. +(This is impossible in ANSI C.) + +@item +Traditionally, @samp{\} inside a macro argument suppresses the syntactic +significance of the following character. +@end itemize + +@item -trigraphs +@findex -trigraphs +Process ANSI standard trigraph sequences. These are three-character +sequences, all starting with @samp{??}, that are defined by ANSI C to +stand for single characters. For example, @samp{??/} stands for +@samp{\}, so @samp{'??/n'} is a character constant for a newline. +Strictly speaking, the GNU C preprocessor does not support all +programs in ANSI Standard C unless @samp{-trigraphs} is used, but if +you ever notice the difference it will be with relief. + +You don't want to know any more about trigraphs. + +@item -pedantic +@findex -pedantic +Issue warnings required by the ANSI C standard in certain cases such +as when text other than a comment follows @samp{#else} or @samp{#endif}. + +@item -pedantic-errors +@findex -pedantic-errors +Like @samp{-pedantic}, except that errors are produced rather than +warnings. + +@item -Wtrigraphs +@findex -Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). + +@item -Wcomment +@findex -Wcomment +@ignore +@c "Not worth documenting" both singular and plural forms of this +@c option, per RMS. But also unclear which is better; hence may need to +@c switch this at some future date. pesch@cygnus.com, 2jan92. +@itemx -Wcomments +(Both forms have the same effect). +@end ignore +Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} +comment, or whenever a Backslash-Newline appears in a @samp{//} comment. + +@item -Wall +@findex -Wall +Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not +@samp{-Wtraditional}). + +@item -Wtraditional +@findex -Wtraditional +Warn about certain constructs that behave differently in traditional and +ANSI C. + +@item -I @var{directory} +@findex -I +Add the directory @var{directory} to the head of the list of +directories to be searched for header files (@pxref{Include Syntax}). +This can be used to override a system header file, substituting your +own version, since these directories are searched before the system +header file directories. If you use more than one @samp{-I} option, +the directories are scanned in left-to-right order; the standard +system directories come after. + +@item -I- +Any directories specified with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. + +In addition, the @samp{-I-} option inhibits the use of the current +directory as the first search directory for @samp{#include "@var{file}"}. +Therefore, the current directory is searched only if it is requested +explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.} +allows you to control precisely which directories are searched before +the current one and which are searched after. + +@item -nostdinc +@findex -nostdinc +Do not search the standard system directories for header files. +Only the directories you have specified with @samp{-I} options +(and the current directory, if appropriate) are searched. + +@item -nostdinc++ +@findex -nostdinc++ +Do not search for header files in the C++-specific standard directories, +but do still search the other standard directories. +(This option is used when building libg++.) + +@item -D @var{name} +@findex -D +Predefine @var{name} as a macro, with definition @samp{1}. + +@item -D @var{name}=@var{definition} +Predefine @var{name} as a macro, with definition @var{definition}. +There are no restrictions on the contents of @var{definition}, but if +you are invoking the preprocessor from a shell or shell-like program you +may need to use the shell's quoting syntax to protect characters such as +spaces that have a meaning in the shell syntax. If you use more than +one @samp{-D} for the same @var{name}, the rightmost definition takes +effect. + +@item -U @var{name} +@findex -U +Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are +specified for one name, the @samp{-U} beats the @samp{-D} and the name +is not predefined. + +@item -undef +@findex -undef +Do not predefine any nonstandard macros. + +@item -A @var{predicate}(@var{answer}) +@findex -A +Make an assertion with the predicate @var{predicate} and answer +@var{answer}. @xref{Assertions}. + +@noindent +You can use @samp{-A-} to disable all predefined assertions; it also +undefines all predefined macros that identify the type of target system. + +@item -dM +@findex -dM +Instead of outputting the result of preprocessing, output a list of +@samp{#define} directives for all the macros defined during the +execution of the preprocessor, including predefined macros. This gives +you a way of finding out what is predefined in your version of the +preprocessor; assuming you have no file @samp{foo.h}, the command + +@example +touch foo.h; cpp -dM foo.h +@end example + +@noindent +will show the values of any predefined macros. + +@item -dD +@findex -dD +Like @samp{-dM} except in two respects: it does @emph{not} include the +predefined macros, and it outputs @emph{both} the @samp{#define} +directives and the result of preprocessing. Both kinds of output go to +the standard output file. + +@item -M [-MG] +@findex -M +Instead of outputting the result of preprocessing, output a rule +suitable for @code{make} describing the dependencies of the main +source file. The preprocessor outputs one @code{make} rule containing +the object file name for that source file, a colon, and the names of +all the included files. If there are many included files then the +rule is split into several lines using @samp{\}-newline. + +@samp{-MG} says to treat missing header files as generated files and assume +they live in the same directory as the source file. It must be specified +in addition to @samp{-M}. + +This feature is used in automatic updating of makefiles. + +@item -MM [-MG] +@findex -MM +Like @samp{-M} but mention only the files included with @samp{#include +"@var{file}"}. System header files included with @samp{#include +<@var{file}>} are omitted. + +@item -MD @var{file} +@findex -MD +Like @samp{-M} but the dependency information is written to @var{file}. +This is in addition to compiling the file as specified---@samp{-MD} does +not inhibit ordinary compilation the way @samp{-M} does. + +When invoking gcc, do not specify the @var{file} argument. +Gcc will create file names made by replacing ".c" with ".d" at +the end of the input file names. + +In Mach, you can use the utility @code{md} to merge multiple dependency +files into a single dependency file suitable for using with the @samp{make} +command. + +@item -MMD @var{file} +@findex -MMD +Like @samp{-MD} except mention only user header files, not system +header files. + +@item -H +@findex -H +Print the name of each header file used, in addition to other normal +activities. + +@item -imacros @var{file} +@findex -imacros +Process @var{file} as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +@var{file} is discarded, the only effect of @samp{-imacros @var{file}} +is to make the macros defined in @var{file} available for use in the +main input. + +@item -include @var{file} +@findex -include +Process @var{file} as input, and include all the resulting output, +before processing the regular input file. + +@item -idirafter @var{dir} +@findex -idirafter +@cindex second include path +Add the directory @var{dir} to the second include path. The directories +on the second include path are searched when a header file is not found +in any of the directories in the main include path (the one that +@samp{-I} adds to). + +@item -iprefix @var{prefix} +@findex -iprefix +Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} +options. + +@item -iwithprefix @var{dir} +@findex -iwithprefix +Add a directory to the second include path. The directory's name is +made by concatenating @var{prefix} and @var{dir}, where @var{prefix} +was specified previously with @samp{-iprefix}. + +@item -isystem @var{dir} +@findex -isystem +Add a directory to the beginning of the second include path, marking it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. + +@item -lang-c +@itemx -lang-c89 +@itemx -lang-c++ +@itemx -lang-objc +@itemx -lang-objc++ +@findex -lang-c +@findex -lang-c89 +@findex -lang-c++ +@findex -lang-objc +@findex -lang-objc++ +Specify the source language. @samp{-lang-c} is the default; it +allows recognition of C++ comments (comments that begin with +@samp{//} and end at end of line), since this is +a common feature and it will most likely be in the next C standard. +@samp{-lang-c89} disables recognition of C++ comments. @samp{-lang-c++} +handles C++ comment syntax and includes extra default include +directories for C++. @samp{-lang-objc} enables the Objective C +@samp{#import} directive. @samp{-lang-objc++} enables both C++ and Objective C +extensions. + +These options are generated by the compiler driver @code{gcc}, but not +passed from the @samp{gcc} command line unless you use the driver's +@samp{-Wp} option. + +@item -lint +Look for commands to the program checker @code{lint} embedded in +comments, and emit them preceded by @samp{#pragma lint}. For example, +the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint +NOTREACHED}. + +This option is available only when you call @code{cpp} directly; +@code{gcc} will not pass it from its command line. + +@item -$ +@findex -$ +Forbid the use of @samp{$} in identifiers. This is required for ANSI +conformance. @code{gcc} automatically supplies this option to the +preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't +recognize the @samp{-$} option itself---to use it without the other +effects of @samp{-ansi}, you must call the preprocessor directly. + +@end table + +@node Concept Index, Index, Invocation, Top +@unnumbered Concept Index +@printindex cp + +@node Index,, Concept Index, Top +@unnumbered Index of Directives, Macros and Options +@printindex fn + +@contents +@bye -- 2.30.2