Added gccHEADmaster

1 files changed, 1254 insertions, 0 deletions

diff --git a/gcc-1.40/cpp.info-1 b/gcc-1.40/cpp.info-1
new file mode 100644
index 0000000..7b07416
--- /dev/null
+++ b/gcc-1.40/cpp.info-1
@@ -0,0 +1,1254 @@
+Info file cpp.info, produced by Makeinfo, -*- Text -*- from input
+file cpp.texinfo.
+
+This file documents the GNU C Preprocessor.
+
+Copyright (C) 1987, 1989 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.
+
+
+
+File: cpp.info,  Node: Top,  Next: Global Actions,  Up: (DIR)
+
+The C Preprocessor
+******************
+
+The C preprocessor is a "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 "macros", which are brief abbreviations for longer constructs.
+
+The C preprocessor provides four separate facilities that you can use
+as you see fit:
+
+   * Inclusion of header files.  These are files of declarations that
+     can be substituted into your program.
+
+   * Macro expansion.  You can define "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.
+
+   * Conditional compilation.  Using special preprocessor commands,
+     you can include or exclude parts of the program according to
+     various conditions.
+
+   * 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.
+
+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 `-trigraphs', `-undef' and
+`-pedantic', but in practice the consequences of having strict ANSI
+Standard C make it undesirable to do this.  *Note Invocation::.
+
+* Menu:
+
+* Global Actions::    Actions made uniformly on all input files.
+* Commands::          General syntax of preprocessor commands.
+* 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 Commands::    Miscellaneous preprocessor commands.
+* 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 commands, predefined macros and options.
+
+ 
+
+File: cpp.info,  Node: Global Actions,  Next: Commands,  Prev: Top,  Up: Top
+
+Transformations Made Globally
+=============================
+
+Most C preprocessor features are inactive unless you give specific
+commands to request their use.  (Preprocessor commands are lines
+starting with `#'; *note Commands::.).  But there are three
+transformations that the preprocessor always makes on all the input
+it receives, even in the absence of commands.
+
+   * All C comments are replaced with single spaces.
+
+   * Backslash-Newline sequences are deleted, no matter where.  This
+     feature allows you to break long lines for cosmetic purposes
+     without changing their meaning.
+
+   * Predefined macro names are replaced with their expansions (*note
+     Predefined::.).
+
+The first two transformations are done *before* nearly all other
+parsing and before preprocessor commands are recognized.  Thus, for
+example, you can split a line cosmetically with Backslash-Newline
+anywhere (except when trigraphs are in use; see below).
+
+     /*
+     */ # /*
+     */ defi\
+     ne FO\
+     O 10\
+     20
+
+is equivalent into `#define FOO 1020'.  You can split even an escape
+sequence with Backslash-Newline.  For example, you can split
+`"foo\bar"' between the `\' and the `b' to get
+
+     "foo\\
+     bar"
+
+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.
+
+   * C comments and predefined macro names are not recognized inside
+     a `#include' command in which the file name is delimited with
+     `<' and `>'.
+
+   * 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.)
+
+   * 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 `-trigraphs'
+     option to enable trigraph processing.  *Note Invocation::.
+
+
+
+File: cpp.info,  Node: Commands,  Next: Header Files,  Prev: Global Actions,  Up: Top
+
+Preprocessor Commands
+=====================
+
+Most preprocessor features are active only if you use preprocessor
+commands to request their use.
+
+Preprocessor commands are lines in your program that start with `#'. 
+The `#' is followed by an identifier that is the "command name".  For
+example, `#define' is the command that defines a macro.  Whitespace
+is also allowed before and after the `#'.
+
+The set of valid command names is fixed.  Programs cannot define new
+preprocessor commands.
+
+Some command names require arguments; these make up the rest of the
+command line and must be separated from the command name by
+whitespace.  For example, `#define' must be followed by a macro name
+and the intended expansion of the macro.
+
+A preprocessor command 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 command into multiple lines, but the comments are
+changed to Spaces before the command is interpreted.  The only way a
+significant Newline can occur in a preprocessor command 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 `#' and the command name cannot come from a macro expansion.  For
+example, if `foo' is defined as a macro expanding to `define', that
+does not make `#foo' a valid preprocessor command.
+
+
+
+File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Commands,  Up: Top
+
+Header Files
+============
+
+A header file is a file containing C declarations and macro
+definitions (*note Macros::.) to be shared between several source
+files.  You request the use of a header file in your program with the
+C preprocessor command `#include'.
+
+* Menu:
+
+* Header Uses::         What header files are used for.
+* Include Syntax::      How to write `#include' commands.
+* Include Operation::   What `#include' does.
+* Once-Only::		Preventing multiple inclusion of one header file.
+
+ 
+
+File: cpp.info,  Node: Header Uses,  Next: Include Syntax,  Prev: Header Files,  Up: Header Files
+
+Uses of Header Files
+--------------------
+
+Header files serve two kinds of purposes.
+
+   * System header files declare the interfaces to parts of the
+     operating system.  You include them in your program to supply
+     the definitions you need to invoke system calls and libraries.
+
+   * 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.
+
+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 `.h'.
+
+
+
+File: cpp.info,  Node: Include Syntax,  Next: Include Operation,  Prev: Header Uses,  Up: Header Files
+
+The `#include' Command
+----------------------
+
+Both user and system header files are included using the preprocessor
+command `#include'.  It has three variants:
+
+`#include <FILE>'
+     This variant is used for system header files.  It searches for a
+     file named 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
+     `-I' (*note Invocation::.).  The option `-nostdinc' inhibits
+     searching the standard system directories; in this case only the
+     directories you specify are searched.
+
+     The parsing of this form of `#include' is slightly special
+     because comments are not recognized within the `<...>'.  Thus,
+     in `#include <x/*y>' the `/*' does not start a comment and the
+     command specifies inclusion of a system header file named
+     `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.
+
+     The argument FILE may not contain a `>' character.  It may,
+     however, contain a `<' character.
+
+`#include "FILE"'
+     This variant is used for header files of your own program.  It
+     searches for a file named 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 `-I-'
+     option is used, the special treatment of the current directory
+     is inhibited.)
+
+     The argument FILE may not contain `"' characters.  If
+     backslashes occur within 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, `#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.
+
+`#include ANYTHING ELSE'
+     This variant is called a "computed #include".  Any `#include'
+     command whose argument does not fit the above two forms is a
+     computed include.  The text ANYTHING ELSE is checked for macro
+     calls, which are expanded (*note Macros::.).  When this is done,
+     the result must fit one of the above two variants.
+
+     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-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.
+
+
+
+File: cpp.info,  Node: Include Operation,  Next: Once-Only,  Prev: Include Syntax,  Up: Header Files
+
+How `#include' Works
+--------------------
+
+The `#include' command 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
+`#include' command.  For example, given two files as follows:
+
+     /* File program.c */
+     int x;
+     #include "header.h"
+     
+     main ()
+     {
+       printf (test ());
+     }
+     
+     
+     /* File header.h */
+     char *test ();
+
+the output generated by the C preprocessor for `program.c' as input
+would be
+
+     int x;
+     char *test ();
+     
+     main ()
+     {
+       printf (test ());
+     }
+
+Included files are not limited to declarations and macro definitions;
+they are merely the typical use.  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.
+
+The line following the `#include' command is always treated as a
+separate line by the C preprocessor even if the included file lacks a
+final newline.
+
+
+
+File: cpp.info,  Node: Once-Only,  Prev: Include Operation,  Up: Header Files
+
+Once-Only Include Files
+-----------------------
+
+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:
+
+     #ifndef __FILE_FOO_SEEN__
+     #define __FILE_FOO_SEEN__
+     
+     THE ENTIRE FILE
+     
+     #endif /* __FILE_FOO_SEEN__ */
+
+The macro `__FILE_FOO_SEEN__' indicates that the file has been
+included once already; its name should begin with `__', and should
+contain the name of the file to avoid accidental conflicts.
+
+One drawback of this method is that the preprocessor must scan the
+input file completely in order to determine that all of it is to be
+ignored.  This makes compilation slower.  You can avoid the delay by
+inserting the following command near the beginning of file *in
+addition to the conditionals described above*:
+
+     #pragma once
+
+This command tells the GNU C preprocessor to ignore any future
+commands to include the same file (whichever file the `#pragma'
+appears in).
+
+You should not *rely* on `#pragma once' to prevent multiple inclusion
+of the file.  It is just a hint, and a nonstandard one at that.  Most
+C compilers will ignore it entirely.  For this reason, you still need
+the conditionals if you want to make certain that the file's contents
+are not included twice.
+
+Note that `#pragma once' works by file name; if a file has more than
+one name, it can be included once under each name, even in GNU CC,
+despite `#pragma once'.
+
+
+
+File: cpp.info,  Node: Macros,  Next: Conditionals,  Prev: Header Files,  Up: Top
+
+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.
+
+ 
+
+File: cpp.info,  Node: Simple Macros,  Next: Argument Macros,  Prev: Macros,  Up: Macros
+
+Simple Macros
+-------------
+
+A "simple macro" is a kind of abbreviation.  It is a name which
+stands for a fragment of code.
+
+Before you can use a macro, you must "define" it explicitly with the
+`#define' command.  `#define' is followed by the name of the macro
+and then the code it should be an abbreviation for.  For example,
+
+     #define BUFFER_SIZE 1020
+
+defines a macro named `BUFFER_SIZE' as an abbreviation for the text
+`1020'.  Therefore, if somewhere after this `#define' command there
+comes a C statement of the form
+
+     foo = (char *) xmalloc (BUFFER_SIZE);
+
+then the C preprocessor will recognize and "expand" the macro
+`BUFFER_SIZE', resulting in
+
+     foo = (char *) xmalloc (1020);
+
+the definition must be a single line; however, it may not end in the
+middle of a multi-line string constant or character constant.
+
+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
+preprocessor commands.  (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.  By the same token, 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.  (Of course, you might 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
+
+     foo = X;
+     #define X 4
+     bar = X;
+
+produces as output
+
+     foo = X;
+     
+     bar = 4;
+
+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
+
+     #define BUFSIZE 1020
+     #define TABLESIZE BUFSIZE
+
+the name `TABLESIZE' when used in the program would go through two
+stages of expansion, resulting ultimately in `1020'.
+
+This is not at all the same as defining `TABLESIZE' to be `1020'. 
+The `#define' for `TABLESIZE' uses exactly the body you specify--in
+this case, `BUFSIZE'--and does not check to see whether it too is the
+name of a macro.  It's only when you *use* `TABLESIZE' that the
+result of its expansion is checked for more macro names.  *Note
+Cascaded Macros::.
+
+
+
+File: cpp.info,  Node: Argument Macros,  Next: Predefined,  Prev: Simple Macros,  Up: Macros
+
+Macros with Arguments
+---------------------
+
+A simple macro always stands for exactly the same text, each time it
+is used.  Macros can be more flexible when they accept "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.
+
+To define a macro that uses arguments, you write a `#define' command
+with a list of "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:
+
+     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+
+(This is not the best way to define a "minimum" macro in GNU C. 
+*Note Side Effects::, for more information.)
+
+To use a macro that expects arguments, you write the name of the
+macro followed by a list of "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 `min' include `min (1, 2)' and `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 `min' defined above, `min (1, 2)' expands into
+
+     ((1) < (2) ? (1) : (2))
+
+where `1' has been substituted for `X' and `2' for `Y'.
+
+Likewise, `min (x + 28, *p)' expands into
+
+     ((x + 28) < (*p) ? (x + 28) : (*p))
+
+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; thus, if you want to
+supply `array[x = y, x + 1]' as an argument, you must write it as
+`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, `min (min (a, b), c)' expands into
+
+     ((((a) < (b) ? (a) : (b))) < (c)
+      ? (((a) < (b) ? (a) : (b)))
+      : (c))
+
+(Line breaks shown here for clarity would not actually be generated.)
+
+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 leaves
+the name unaltered.  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 `min' in the same source file that defines the
+macro.  If you write `&min' with no argument list, you refer to the
+function.  If you write `min (x, bb)', with an argument list, the
+macro is expanded.  If you write `(min) (a, bb)', where the name
+`min' is not followed by an open-parenthesis, the macro is not
+expanded, so you wind up with a call to the function `min'.
+
+It is not allowed to 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 name 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:
+
+     #define FOO(x) - 1 / (x)
+
+(which defines `FOO' to take an argument and expand into minus the
+reciprocal of that argument) or this:
+
+     #define BAR (x) - 1 / (x)
+
+(which defines `BAR' to take no argument and always expand into `(x)
+- 1 / (x)').
+
+Note that the *uses* of a macro with arguments can have spaces before
+the left parenthesis; it's the *definition* where it matters whether
+there is a space.
+
+
+
+File: cpp.info,  Node: Predefined,  Next: Stringification,  Prev: Argument Macros,  Up: Macros
+
+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.
+
+ 
+
+File: cpp.info,  Node: Standard Predefined,  Next: Nonstandard Predefined,  Prev: Predefined,  Up: Predefined
+
+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 `__GNUC__' in this table are standardized by ANSI C; the
+rest are GNU C extensions.
+
+`__FILE__'
+     This macro expands to the name of the current input file, in the
+     form of a C string constant.
+
+`__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.
+
+`__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 `__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,
+
+          fprintf (stderr, "Internal error: negative string length "
+                           "%d at %s, line %d.",
+                   length, __FILE__, __LINE__);
+
+     A `#include' command changes the expansions of `__FILE__' and
+     `__LINE__' to correspond to the included file.  At the end of
+     that file, when processing resumes on the input file that
+     contained the `#include' command, the expansions of `__FILE__'
+     and `__LINE__' revert to the values they had before the
+     `#include' (but `__LINE__' is then incremented by one as
+     processing moves to the line after the `#include').
+
+     The expansions of both `__FILE__' and `__LINE__' are altered if
+     a `#line' command is used.  *Note Combining Sources::.
+
+`__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 `"Jan 29 1987"' or
+     `"Apr 1 1905"'.
+
+`__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 `"23:59:01"'.
+
+`__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.)
+
+`__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, `__GNUC__' is undefined.
+
+`__STRICT_ANSI__'
+     This macro is defined if and only if the `-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.
+
+`__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 `"1.18"'.  The only
+     reasonable use of this macro is to incorporate it into a string
+     constant.
+
+`__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.
+
+`__CHAR_UNSIGNED__'
+     This macro is defined if and only if the data type `char' is
+     unsigned on the target machine.  It exists to cause the standard
+     header file `limit.h' to work correctly.  It is bad practice to
+     refer to this macro yourself; instead, refer to the standard
+     macros defined in `limit.h'.
+
+
+
+File: cpp.info,  Node: Nonstandard Predefined,  Prev: Standard Predefined,  Up: Predefined
+
+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.
+
+Some nonstandard predefined macros describe the operating system in
+use, with more or less specificity.  For example,
+
+`unix'
+     `unix' is normally predefined on all Unix systems.
+
+`BSD'
+     `BSD' is predefined on recent versions of Berkeley Unix (perhaps
+     only in version 4.3).
+
+Other nonstandard predefined macros describe the kind of CPU, with
+more or less specificity.  For example,
+
+`vax'
+     `vax' is predefined on Vax computers.
+
+`mc68000'
+     `mc68000' is predefined on most computers whose CPU is a
+     Motorola 68000, 68010 or 68020.
+
+`m68k'
+     `m68k' is also predefined on most computers whose CPU is a
+     68000, 68010 or 68020; however, some makers use `mc68000' and
+     some use `m68k'.  Some predefine both names.  What happens in
+     GNU C depends on the system you are using it on.
+
+`M68020'
+     `M68020' has been observed to be predefined on some systems that
+     use 68020 CPUs--in addition to `mc68000' and `m68k' that are
+     less specific.
+
+`ns32000'
+     `ns32000' is predefined on computers which use the National
+     Semiconductor 32000 series CPU.
+
+Yet other nonstandard predefined macros describe the manufacturer of
+the system.  For example,
+
+`sun'
+     `sun' is predefined on all models of Sun computers.
+
+`pyr'
+     `pyr' is predefined on all models of Pyramid computers.
+
+`sequent'
+     `sequent' is predefined on all models of Sequent computers.
+
+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 `-ansi' inhibits the definition of these symbols.
+
+This tends to make `-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 `-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 is to run on?
+
+GNU C offers a parallel series of symbols for this purpose, whose
+names are made from the customary ones by adding `__' at the
+beginning and end.  Thus, the symbol `__vax__' would be available on
+a vax, and so on.
+
+The set of nonstandard predefined names in the GNU C preprocessor is
+controlled by the macro `CPP_PREDEFINES', which should be a string
+containing `-D' options, separated by spaces.  For example, on the
+Sun 3, we use the following definition:
+
+     #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
+
+
+
+File: cpp.info,  Node: Stringification,  Next: Concatenation,  Prev: Predefined,  Up: Macros
+
+Stringification
+---------------
+
+"Stringification" means turning a code fragment into a string
+constant whose contents are the text for the code fragment.  For
+example, stringifying `foo (z)' results in `"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
+`#' 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 `#'.
+
+Here is an example of a macro definition that uses stringification:
+
+     #define WARN_IF(EXP) \
+     do { if (EXP) fprintf (stderr, "Warning: " #EXP "\n"); } while (0)
+
+Here the actual argument for `EXP' is substituted once as given, into
+the `if' statement, and once as stringified, into the argument to
+`fprintf'.  The `do' and `while (0)' are a kludge to make it possible
+to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a
+function would make C programmers want to do; *note 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
+`EXP''s actual argument into a separate string constant, resulting in
+text like
+
+     do { if (x == 0) fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0)
+
+but the C compiler then sees three consecutive string constants and
+concatenates them into one, producing effectively
+
+     do { if (x == 0) fprintf (stderr, "Warning: x == 0\n"); } while (0)
+
+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 `p = "foo\n";' results
+in `"p = \"foo\\n\";"'.  However, backslashes that are not inside of
+string or character constants are not duplicated: `\n' by itself
+stringifies to `"\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.
+
+
+
+File: cpp.info,  Node: Concatenation,  Next: Undefining,  Prev: Stringification,  Up: Macros
+
+Concatenation
+-------------
+
+"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 `##' in the macro body.  When the macro is called, after
+actual arguments are substituted, all `##' 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 `##'.
+
+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:
+
+     struct command
+     {
+       char *name;
+       void (*function) ();
+     };
+     
+     struct command commands[] =
+     {
+       { "quit", quit_command},
+       { "help", help_command},
+       ...
+     };
+
+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 `_command'.  Here is
+how it is done:
+
+     #define COMMAND(NAME)  { #NAME, NAME ## _command }
+     
+     struct command commands[] =
+     {
+       COMMAND (quit),
+       COMMAND (help),
+       ...
+     };
+
+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 `1.5' and `e3') into a number.  Also,
+multi-character operators such as `+=' 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 `x' on one side and `+' 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 `x' and `+' 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 `/' and `*': the `/*' 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 `##' 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.
+
+
+
+File: cpp.info,  Node: Undefining,  Next: Redefining,  Prev: Concatenation,  Up: Macros
+
+Undefining Macros
+-----------------
+
+To "undefine" a macro means to cancel its definition.  This is done
+with the `#undef' command.  `#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,
+
+     #define FOO 4
+     x = FOO;
+     #undef FOO
+     x = FOO;
+
+expands into
+
+     x = 4;
+     
+     x = FOO;
+
+In this example, `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 `#undef' command will cancel definitions with
+arguments or definitions that don't expect arguments.  The `#undef'
+command has no effect when used on a name not currently defined as a
+macro.
+
+
+
+File: cpp.info,  Node: Redefining,  Next: Macro Pitfalls,  Prev: Undefining,  Up: Macros
+
+Redefining Macros
+-----------------
+
+"Redefining" a macro means defining (with `#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 (*note 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 `#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:
+
+   * Whitespace may be added or deleted at the beginning or the end.
+
+   * 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.
+
+Recall that a comment counts as whitespace.
+
+
+
+File: cpp.info,  Node: Macro Pitfalls,  Prev: Redefining,  Up: Macros
+
+Pitfalls and Subtleties 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.
+
+ 
+
+File: cpp.info,  Node: Misnesting,  Next: Macro Parentheses,  Prev: Macro Pitfalls,  Up: Macro Pitfalls
+
+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,
+
+     #define double(x) (2*(x))
+     #define call_with_1(x) x(1)
+
+would expand `call_with_1 (double)' into `(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,
+
+     #define strange(file) fprintf (file, "%s %d",
+     ...
+     strange(stderr) p, 35)
+
+This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
+
+
+
+File: cpp.info,  Node: Macro Parentheses,  Next: Swallow Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
+
+Unintended Grouping of Arithmetic
+.................................
+
+ 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,
+
+     #define ceil_div(x, y) (x + y - 1) / y
+
+whose purpose is to divide, rounding up.  (One use for this operation
+is to compute how many `int''s are needed to hold a certain number of
+`char''s.)  Then suppose it is used as follows:
+
+     a = ceil_div (b & c, sizeof (int));
+
+This expands into
+
+     a = (b & c + sizeof (int) - 1) / sizeof (int);
+
+which does not do what is intended.  The operator-precedence rules of
+C make it equivalent to this:
+
+     a = (b & (c + sizeof (int) - 1)) / sizeof (int);
+
+But what we want is this:
+
+     a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
+
+Defining the macro as
+
+     #define ceil_div(x, y) ((x) + (y) - 1) / (y)
+
+provides the desired result.
+
+However, unintended grouping can result in another way.  Consider
+`sizeof ceil_div(1, 2)'.  That has the appearance of a C expression
+that would compute the size of the type of `ceil_div (1, 2)', but in
+fact it means something very different.  Here is what it expands to:
+
+     sizeof ((1) + (2) - 1) / (2)
+
+This would take the size of an integer and divide it by two.  The
+precedence rules have put the division outside the `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 `ceil_div':
+
+     #define ceil_div(x, y) (((x) + (y) - 1) / (y))
+
+
+
+File: cpp.info,  Node: Swallow Semicolon,  Next: Side Effects,  Prev: Macro Parentheses,  Up: Macro Pitfalls
+
+Swallowing the Semicolon
+........................
+
+ 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 `p' says where to find it) across whitespace
+characters:
+
+     #define SKIP_SPACES (p, limit)  \
+     { register char *lim = (limit); \
+       while (p != lim) {            \
+         if (*p++ != ' ') {          \
+           p--; break; }}}
+
+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 `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
+`SKIP_SPACES (p, lim);'
+
+But this can cause trouble before `else' statements, because the
+semicolon is actually a null statement.  Suppose you write
+
+     if (*p != 0)
+       SKIP_SPACES (p, lim);
+     else ...
+
+ The presence of two statements--the compound statement and a null
+statement--in between the `if' condition and the `else' makes invalid
+C code.
+
+The definition of the macro `SKIP_SPACES' can be altered to solve
+this problem, using a `do ... while' statement.  Here is how:
+
+     #define SKIP_SPACES (p, limit)     \
+     do { register char *lim = (limit); \
+          while (p != lim) {            \
+            if (*p++ != ' ') {          \
+              p--; break; }}}           \
+     while (0)
+
+Now `SKIP_SPACES (p, lim);' expands into
+
+     do {...} while (0);
+
+which is one statement.
+
+
+
+File: cpp.info,  Node: Side Effects,  Next: Self-Reference,  Prev: Swallow Semicolon,  Up: Macro Pitfalls
+
+Duplication of Side Effects
+...........................
+
+ Many C programs define a macro `min', for "minimum", like this:
+
+     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+
+When you use this macro with an argument containing a side effect, as
+shown here,
+
+     next = min (x + y, foo (z));
+
+it expands as follows:
+
+     next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
+
+where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
+
+The function `foo' is used only once in the statement as it appears
+in the program, but the expression `foo (z)' has been substituted
+twice into the macro expansion.  As a result, `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 `min' is an "unsafe" macro.
+
+The best solution to this problem is to define `min' in a way that
+computes the value of `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:
+
+     #define min(X, Y)                     \
+     ({ typeof (X) __x = (X), __y = (Y);   \
+        (__x < __y) ? __x : __y; })
+
+If you do not wish to use GNU C extensions, the only solution is to
+be careful when *using* the macro `min'.  For example, you can
+calculate the value of `foo (z)', save it in a variable, and use that
+variable in `min':
+
+     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+     ...
+     {
+       int tem = foo (z);
+       next = min (x + y, tem);
+     }
+
+(where I assume that `foo' returns type `int').
+
+