--- /dev/null
+\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 <x/*y>} 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
+<sys/signal.h>} 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 </usr/include/sys/signal.h>} 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 <sys/signal.h>} finds the file under
+@file{/usr/local/include}. If that file contains @samp{#include_next
+<sys/signal.h>}, 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
OSDN Git Service
