Return to cpp.info-3 CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/cpp.info-3, revision 1.1.1.3

1.1.1.3 ! root        1: This is Info file cpp.info, produced by Makeinfo-1.55 from the input
1.1       root        2: file cpp.texi.
                      3: 
                      4:    This file documents the GNU C Preprocessor.
                      5: 
1.1.1.3 ! root        6:    Copyright 1987, 1989, 1991, 1992, 1993, 1994 Free Software
        !             7: Foundation, Inc.
1.1       root        8: 
                      9:    Permission is granted to make and distribute verbatim copies of this
                     10: manual provided the copyright notice and this permission notice are
                     11: preserved on all copies.
                     12: 
                     13:    Permission is granted to copy and distribute modified versions of
                     14: this manual under the conditions for verbatim copying, provided also
                     15: that the entire resulting derived work is distributed under the terms
                     16: of a permission notice identical to this one.
                     17: 
                     18:    Permission is granted to copy and distribute translations of this
                     19: manual into another language, under the above conditions for modified
                     20: versions.
                     21: 
                     22: 
1.1.1.3 ! root       23: File: cpp.info,  Node: Invocation,  Next: Concept Index,  Prev: Output,  Up: Top
        !            24: 
        !            25: Invoking the C Preprocessor
        !            26: ===========================
        !            27: 
        !            28:    Most often when you use the C preprocessor you will not have to
        !            29: invoke it explicitly: the C compiler will do so automatically.
        !            30: However, the preprocessor is sometimes useful on its own.
        !            31: 
        !            32:    The C preprocessor expects two file names as arguments, INFILE and
        !            33: OUTFILE.  The preprocessor reads INFILE together with any other files
        !            34: it specifies with `#include'.  All the output generated by the combined
        !            35: input files is written in OUTFILE.
        !            36: 
        !            37:    Either INFILE or OUTFILE may be `-', which as INFILE means to read
        !            38: from standard input and as OUTFILE means to write to standard output.
        !            39: Also, if OUTFILE or both file names are omitted, the standard output
        !            40: and standard input are used for the omitted file names.
        !            41: 
        !            42:    Here is a table of command options accepted by the C preprocessor.
        !            43: These options can also be given when compiling a C program; they are
        !            44: passed along automatically to the preprocessor when it is invoked by the
        !            45: compiler.
        !            46: 
        !            47: `-P'
        !            48:      Inhibit generation of `#'-lines with line-number information in
        !            49:      the output from the preprocessor (*note Output::.).  This might be
        !            50:      useful when running the preprocessor on something that is not C
        !            51:      code and will be sent to a program which might be confused by the
        !            52:      `#'-lines.
        !            53: 
        !            54: `-C'
        !            55:      Do not discard comments: pass them through to the output file.
        !            56:      Comments appearing in arguments of a macro call will be copied to
        !            57:      the output before the expansion of the macro call.
        !            58: 
        !            59: `-traditional'
        !            60:      Try to imitate the behavior of old-fashioned C, as opposed to ANSI
        !            61:      C.
        !            62: 
        !            63:         * Traditional macro expansion pays no attention to singlequote
        !            64:           or doublequote characters; macro argument symbols are
        !            65:           replaced by the argument values even when they appear within
        !            66:           apparent string or character constants.
        !            67: 
        !            68:         * Traditionally, it is permissible for a macro expansion to end
        !            69:           in the middle of a string or character constant.  The
        !            70:           constant continues into the text surrounding the macro call.
        !            71: 
        !            72:         * However, traditionally the end of the line terminates a
        !            73:           string or character constant, with no error.
        !            74: 
        !            75:         * In traditional C, a comment is equivalent to no text at all.
        !            76:           (In ANSI C, a comment counts as whitespace.)
        !            77: 
        !            78:         * Traditional C does not have the concept of a "preprocessing
        !            79:           number".  It considers `1.0e+4' to be three tokens: `1.0e',
        !            80:           `+', and `4'.
        !            81: 
        !            82:         * A macro is not suppressed within its own definition, in
        !            83:           traditional C.  Thus, any macro that is used recursively
        !            84:           inevitably causes an error.
        !            85: 
        !            86:         * The character `#' has no special meaning within a macro
        !            87:           definition in traditional C.
        !            88: 
        !            89:         * In traditional C, the text at the end of a macro expansion
        !            90:           can run together with the text after the macro call, to
        !            91:           produce a single token.  (This is impossible in ANSI C.)
        !            92: 
        !            93:         * Traditionally, `\' inside a macro argument suppresses the
        !            94:           syntactic significance of the following character.
        !            95: 
        !            96: `-trigraphs'
        !            97:      Process ANSI standard trigraph sequences.  These are
        !            98:      three-character sequences, all starting with `??', that are
        !            99:      defined by ANSI C to stand for single characters.  For example,
        !           100:      `??/' stands for `\', so `'??/n'' is a character constant for a
        !           101:      newline.  Strictly speaking, the GNU C preprocessor does not
        !           102:      support all programs in ANSI Standard C unless `-trigraphs' is
        !           103:      used, but if you ever notice the difference it will be with relief.
        !           104: 
        !           105:      You don't want to know any more about trigraphs.
        !           106: 
        !           107: `-pedantic'
        !           108:      Issue warnings required by the ANSI C standard in certain cases
        !           109:      such as when text other than a comment follows `#else' or `#endif'.
        !           110: 
        !           111: `-pedantic-errors'
        !           112:      Like `-pedantic', except that errors are produced rather than
        !           113:      warnings.
        !           114: 
        !           115: `-Wtrigraphs'
        !           116:      Warn if any trigraphs are encountered (assuming they are enabled).
        !           117: 
        !           118: `-Wcomment'
        !           119:      Warn whenever a comment-start sequence `/*' appears in a comment.
        !           120: 
        !           121: `-Wall'
        !           122:      Requests both `-Wtrigraphs' and `-Wcomment' (but not
        !           123:      `-Wtraditional').
        !           124: 
        !           125: `-Wtraditional'
        !           126:      Warn about certain constructs that behave differently in
        !           127:      traditional and ANSI C.
        !           128: 
        !           129: `-I DIRECTORY'
        !           130:      Add the directory DIRECTORY to the end of the list of directories
        !           131:      to be searched for header files (*note Include Syntax::.).  This
        !           132:      can be used to override a system header file, substituting your
        !           133:      own version, since these directories are searched before the system
        !           134:      header file directories.  If you use more than one `-I' option,
        !           135:      the directories are scanned in left-to-right order; the standard
        !           136:      system directories come after.
        !           137: 
        !           138: `-I-'
        !           139:      Any directories specified with `-I' options before the `-I-'
        !           140:      option are searched only for the case of `#include "FILE"'; they
        !           141:      are not searched for `#include <FILE>'.
        !           142: 
        !           143:      If additional directories are specified with `-I' options after
        !           144:      the `-I-', these directories are searched for all `#include'
        !           145:      commands.
        !           146: 
        !           147:      In addition, the `-I-' option inhibits the use of the current
        !           148:      directory as the first search directory for `#include "FILE"'.
        !           149:      Therefore, the current directory is searched only if it is
        !           150:      requested explicitly with `-I.'.  Specifying both `-I-' and `-I.'
        !           151:      allows you to control precisely which directories are searched
        !           152:      before the current one and which are searched after.
        !           153: 
        !           154: `-nostdinc'
        !           155:      Do not search the standard system directories for header files.
        !           156:      Only the directories you have specified with `-I' options (and the
        !           157:      current directory, if appropriate) are searched.
        !           158: 
        !           159: `-nostdinc++'
        !           160:      Do not search for header files in the C++-specific standard
        !           161:      directories, but do still search the other standard directories.
        !           162:      (This option is used when building libg++.)
        !           163: 
        !           164: `-D NAME'
        !           165:      Predefine NAME as a macro, with definition `1'.
        !           166: 
        !           167: `-D NAME=DEFINITION'
        !           168:      Predefine NAME as a macro, with definition DEFINITION.  There are
        !           169:      no restrictions on the contents of DEFINITION, but if you are
        !           170:      invoking the preprocessor from a shell or shell-like program you
        !           171:      may need to use the shell's quoting syntax to protect characters
        !           172:      such as spaces that have a meaning in the shell syntax.  If you
        !           173:      use more than one `-D' for the same NAME, the rightmost definition
        !           174:      takes effect.
        !           175: 
        !           176: `-U NAME'
        !           177:      Do not predefine NAME.  If both `-U' and `-D' are specified for
        !           178:      one name, the `-U' beats the `-D' and the name is not predefined.
        !           179: 
        !           180: `-undef'
        !           181:      Do not predefine any nonstandard macros.
        !           182: 
        !           183: `-A PREDICATE(ANSWER)'
        !           184:      Make an assertion with the predicate PREDICATE and answer ANSWER.
        !           185:      *Note Assertions::.
        !           186: 
        !           187:      You can use `-A-' to disable all predefined assertions; it also
        !           188:      undefines all predefined macros that identify the type of target
        !           189:      system.
        !           190: 
        !           191: `-dM'
        !           192:      Instead of outputting the result of preprocessing, output a list of
        !           193:      `#define' commands for all the macros defined during the execution
        !           194:      of the preprocessor, including predefined macros.  This gives you
        !           195:      a way of finding out what is predefined in your version of the
        !           196:      preprocessor; assuming you have no file `foo.h', the command
        !           197: 
        !           198:           touch foo.h; cpp -dM foo.h
        !           199: 
        !           200:      will show the values of any predefined macros.
        !           201: 
        !           202: `-dD'
        !           203:      Like `-dM' except in two respects: it does *not* include the
        !           204:      predefined macros, and it outputs *both* the `#define' commands
        !           205:      and the result of preprocessing.  Both kinds of output go to the
        !           206:      standard output file.
        !           207: 
        !           208: `-M [-MG]'
        !           209:      Instead of outputting the result of preprocessing, output a rule
        !           210:      suitable for `make' describing the dependencies of the main source
        !           211:      file.  The preprocessor outputs one `make' rule containing the
        !           212:      object file name for that source file, a colon, and the names of
        !           213:      all the included files.  If there are many included files then the
        !           214:      rule is split into several lines using `\'-newline.
        !           215: 
        !           216:      `-MG' says to treat missing header files as generated files and
        !           217:      assume they live in the same directory as the source file.  It
        !           218:      must be specified in addition to `-M'.
        !           219: 
        !           220:      This feature is used in automatic updating of makefiles.
        !           221: 
        !           222: `-MM [-MG]'
        !           223:      Like `-M' but mention only the files included with `#include
        !           224:      "FILE"'.  System header files included with `#include <FILE>' are
        !           225:      omitted.
        !           226: 
        !           227: `-MD FILE'
        !           228:      Like `-M' but the dependency information is written to FILE.  This
        !           229:      is in addition to compiling the file as specified--`-MD' does not
        !           230:      inhibit ordinary compilation the way `-M' does.
        !           231: 
        !           232:      When invoking gcc, do not specify the FILE argument.  Gcc will
        !           233:      create file names made by replacing ".c" with ".d" at the end of
        !           234:      the input file names.
        !           235: 
        !           236:      In Mach, you can use the utility `md' to merge multiple dependency
        !           237:      files into a single dependency file suitable for using with the
        !           238:      `make' command.
        !           239: 
        !           240: `-MMD FILE'
        !           241:      Like `-MD' except mention only user header files, not system
        !           242:      header files.
        !           243: 
        !           244: `-H'
        !           245:      Print the name of each header file used, in addition to other
        !           246:      normal activities.
        !           247: 
        !           248: `-imacros FILE'
        !           249:      Process FILE as input, discarding the resulting output, before
        !           250:      processing the regular input file.  Because the output generated
        !           251:      from FILE is discarded, the only effect of `-imacros FILE' is to
        !           252:      make the macros defined in FILE available for use in the main
        !           253:      input.
        !           254: 
        !           255: `-include FILE'
        !           256:      Process FILE as input, and include all the resulting output,
        !           257:      before processing the regular input file.
        !           258: 
        !           259: `-idirafter DIR'
        !           260:      Add the directory DIR to the second include path.  The directories
        !           261:      on the second include path are searched when a header file is not
        !           262:      found in any of the directories in the main include path (the one
        !           263:      that `-I' adds to).
        !           264: 
        !           265: `-iprefix PREFIX'
        !           266:      Specify PREFIX as the prefix for subsequent `-iwithprefix' options.
        !           267: 
        !           268: `-iwithprefix DIR'
        !           269:      Add a directory to the second include path.  The directory's name
        !           270:      is made by concatenating PREFIX and DIR, where PREFIX was
        !           271:      specified previously with `-iprefix'.
        !           272: 
        !           273: `-isystem DIR'
        !           274:      Add a directory to the beginning of the second include path,
        !           275:      marking it as a system directory, so that it gets the same special
        !           276:      treatment as is applied to the standard system directories.
        !           277: 
        !           278: `-lang-c'
        !           279: `-lang-c++'
        !           280: `-lang-objc'
        !           281: `-lang-objc++'
        !           282:      Specify the source language.  `-lang-c++' makes the preprocessor
        !           283:      handle C++ comment syntax (comments may begin with `//', in which
        !           284:      case they end at end of line), and includes extra default include
        !           285:      directories for C++; and `-lang-objc' enables the Objective C
        !           286:      `#import' command.  `-lang-c' explicitly turns off both of these
        !           287:      extensions, and `-lang-objc++' enables both.
        !           288: 
        !           289:      These options are generated by the compiler driver `gcc', but not
        !           290:      passed from the `gcc' command line.
        !           291: 
        !           292: `-lint'
        !           293:      Look for commands to the program checker `lint' embedded in
        !           294:      comments, and emit them preceded by `#pragma lint'.  For example,
        !           295:      the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'.
        !           296: 
        !           297:      This option is available only when you call `cpp' directly; `gcc'
        !           298:      will not pass it from its command line.
        !           299: 
        !           300: `-$'
        !           301:      Forbid the use of `$' in identifiers.  This is required for ANSI
        !           302:      conformance.  `gcc' automatically supplies this option to the
        !           303:      preprocessor if you specify `-ansi', but `gcc' doesn't recognize
        !           304:      the `-$' option itself--to use it without the other effects of
        !           305:      `-ansi', you must call the preprocessor directly.
        !           306: 
        !           307: 
        !           308: File: cpp.info,  Node: Concept Index,  Next: Index,  Prev: Invocation,  Up: Top
        !           309: 
        !           310: Concept Index
        !           311: *************
        !           312: 
        !           313: * Menu:
        !           314: 
        !           315: * ##:                                   Concatenation.
        !           316: * arguments in macro definitions:       Argument Macros.
        !           317: * assertions:                           Assertions.
        !           318: * assertions, undoing:                  Assertions.
        !           319: * blank macro arguments:                Argument Macros.
        !           320: * cascaded macros:                      Cascaded Macros.
        !           321: * commands:                             Commands.
        !           322: * commenting out code:                  Deleted Code.
        !           323: * computed #include:                    Include Syntax.
        !           324: * concatenation:                        Concatenation.
        !           325: * conditionals:                         Conditionals.
        !           326: * expansion of arguments:               Argument Prescan.
        !           327: * function-like macro:                  Argument Macros.
        !           328: * header file:                          Header Files.
        !           329: * including just once:                  Once-Only.
        !           330: * inheritance:                          Inheritance.
        !           331: * invocation of the preprocessor:       Invocation.
        !           332: * line control:                         Combining Sources.
        !           333: * macro argument expansion:             Argument Prescan.
        !           334: * macro body uses macro:                Cascaded Macros.
        !           335: * macros with argument:                 Argument Macros.
        !           336: * manifest constant:                    Simple Macros.
        !           337: * newlines in macro arguments:          Newlines in Args.
        !           338: * null command:                         Other Commands.
        !           339: * options:                              Invocation.
        !           340: * output format:                        Output.
        !           341: * overriding a header file:             Inheritance.
        !           342: * parentheses in macro bodies:          Macro Parentheses.
        !           343: * pitfalls of macros:                   Macro Pitfalls.
        !           344: * predefined macros:                    Predefined.
        !           345: * predicates:                           Assertions.
        !           346: * preprocessor commands:                Commands.
        !           347: * prescan of macro arguments:           Argument Prescan.
        !           348: * problems with macros:                 Macro Pitfalls.
        !           349: * redefining macros:                    Redefining.
        !           350: * repeated inclusion:                   Once-Only.
        !           351: * retracting assertions:                Assertions.
        !           352: * second include path:                  Invocation.
        !           353: * self-reference:                       Self-Reference.
        !           354: * semicolons (after macro calls):       Swallow Semicolon.
        !           355: * side effects (in macro arguments):    Side Effects.
        !           356: * simple macro:                         Simple Macros.
        !           357: * space as macro argument:              Argument Macros.
        !           358: * standard predefined macros:           Standard Predefined.
        !           359: * stringification:                      Stringification.
        !           360: * testing predicates:                   Assertions.
        !           361: * unassert:                             Assertions.
        !           362: * undefining macros:                    Undefining.
        !           363: * unsafe macros:                        Side Effects.
        !           364: 
        !           365: 
1.1       root      366: File: cpp.info,  Node: Index,  Prev: Concept Index,  Up: Top
                    367: 
                    368: Index of Commands, Macros and Options
                    369: *************************************
                    370: 
                    371: * Menu:
                    372: 
                    373: * #assert:                              Assertions.
1.1.1.3 ! root      374: * #cpu:                                 Assertions.
        !           375: * #define:                              Argument Macros.
1.1       root      376: * #elif:                                #elif Command.
                    377: * #else:                                #else Command.
                    378: * #error:                               #error Command.
                    379: * #ident:                               Other Commands.
                    380: * #if:                                  Conditional Syntax.
                    381: * #ifdef:                               Conditionals-Macros.
                    382: * #ifndef:                              Conditionals-Macros.
1.1.1.3 ! root      383: * #import:                              Once-Only.
1.1       root      384: * #include:                             Include Syntax.
                    385: * #include_next:                        Inheritance.
                    386: * #line:                                Combining Sources.
1.1.1.3 ! root      387: * #machine:                             Assertions.
1.1       root      388: * #pragma:                              Other Commands.
                    389: * #pragma once:                         Once-Only.
1.1.1.3 ! root      390: * #system:                              Assertions.
1.1       root      391: * #unassert:                            Assertions.
                    392: * #warning:                             #error Command.
1.1.1.2   root      393: * -$:                                   Invocation.
1.1       root      394: * -A:                                   Invocation.
                    395: * -C:                                   Invocation.
                    396: * -D:                                   Invocation.
                    397: * -dD:                                  Invocation.
                    398: * -dM:                                  Invocation.
                    399: * -H:                                   Invocation.
                    400: * -I:                                   Invocation.
1.1.1.2   root      401: * -idirafter:                           Invocation.
1.1       root      402: * -imacros:                             Invocation.
                    403: * -include:                             Invocation.
1.1.1.2   root      404: * -iprefix:                             Invocation.
1.1.1.3 ! root      405: * -isystem:                             Invocation.
1.1.1.2   root      406: * -iwithprefix:                         Invocation.
                    407: * -lang-c:                              Invocation.
                    408: * -lang-c++:                            Invocation.
                    409: * -lang-objc:                           Invocation.
                    410: * -lang-objc++:                         Invocation.
1.1       root      411: * -M:                                   Invocation.
                    412: * -MD:                                  Invocation.
                    413: * -MM:                                  Invocation.
                    414: * -MMD:                                 Invocation.
1.1.1.2   root      415: * -nostdinc:                            Invocation.
                    416: * -nostdinc++:                          Invocation.
1.1       root      417: * -P:                                   Invocation.
                    418: * -pedantic:                            Invocation.
                    419: * -pedantic-errors:                     Invocation.
                    420: * -traditional:                         Invocation.
                    421: * -trigraphs:                           Invocation.
                    422: * -U:                                   Invocation.
1.1.1.2   root      423: * -undef:                               Invocation.
1.1       root      424: * -Wall:                                Invocation.
                    425: * -Wcomment:                            Invocation.
                    426: * -Wtraditional:                        Invocation.
1.1.1.2   root      427: * -Wtrigraphs:                          Invocation.
1.1       root      428: * BSD:                                  Nonstandard Predefined.
                    429: * defined:                              Conditionals-Macros.
                    430: * M68020:                               Nonstandard Predefined.
                    431: * m68k:                                 Nonstandard Predefined.
                    432: * mc68000:                              Nonstandard Predefined.
                    433: * ns32000:                              Nonstandard Predefined.
                    434: * pyr:                                  Nonstandard Predefined.
                    435: * sequent:                              Nonstandard Predefined.
                    436: * sun:                                  Nonstandard Predefined.
                    437: * system header files:                  Header Uses.
                    438: * unix:                                 Nonstandard Predefined.
                    439: * vax:                                  Nonstandard Predefined.
                    440: * _AM29000:                             Nonstandard Predefined.
                    441: * _AM29K:                               Nonstandard Predefined.
                    442: * __BASE_FILE__:                        Standard Predefined.
1.1.1.3 ! root      443: * __CHAR_UNSIGNED__:                    Standard Predefined.
        !           444: * __cplusplus:                          Standard Predefined.
1.1       root      445: * __DATE__:                             Standard Predefined.
                    446: * __FILE__:                             Standard Predefined.
1.1.1.3 ! root      447: * __GNUC__:                             Standard Predefined.
        !           448: * __GNUG__:                             Standard Predefined.
1.1       root      449: * __INCLUDE_LEVEL_:                     Standard Predefined.
                    450: * __LINE__:                             Standard Predefined.
1.1.1.3 ! root      451: * __OPTIMIZE__:                         Standard Predefined.
1.1       root      452: * __STDC__:                             Standard Predefined.
1.1.1.3 ! root      453: * __STRICT_ANSI__:                      Standard Predefined.
1.1       root      454: * __TIME__:                             Standard Predefined.
1.1.1.3 ! root      455: * __VERSION__:                          Standard Predefined.
1.1       root      456: 
                    457: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.