## SYNOPSIS

           cpp [-Dmacro[=defn]...] [-Umacro]
               [-Idir...] [-Wwarn...]
               [-M|-MM] [-MG] [-MF filename]
               [-MP] [-MQ target...] [-MT target...]
               [-x language] [-std=standard]
               infile outfile

           Only the most useful options are listed here; see below
           for the remainder.

## DESCRIPTION

           The C preprocessor, often known as cpp, is a macro proces
           sor that is used automatically by the C compiler to trans
           form your program before compilation.  It is called a
           macro processor because it allows you to define macros,
           which are brief abbreviations for longer constructs.

           The C preprocessor is intended to be used only with C,
           C++, and Objective-C source code.  In the past, it has
           been abused as a general text processor.  It will choke on
           input which does not obey C's lexical rules.  For example,
           apostrophes will be interpreted as the beginning of char
           acter constants, and cause errors.  Also, you cannot rely
           on it preserving characteristics of the input which are
           not significant to C-family languages.  If a Makefile is
           preprocessed, all the hard tabs will be removed, and the
           Makefile will not work.

           Having said that, you can often get away with using cpp on
           things which are not C.  Other Algol-ish programming lan
           guages are often safe (Pascal, Ada, etc.) So is assembly,
           with caution.  -traditional-cpp mode preserves more white
           space, and is otherwise more permissive.  Many of the
           problems can be avoided by writing C or C++ style comments
           instead of native language comments, and keeping macros
           simple.

           Wherever possible, you should use a preprocessor geared to
           the language you are writing in.  Modern versions of the
           GNU assembler have macro facilities.  Most high level pro
           gramming languages have their own conditional compilation
           and inclusion mechanism.  If all else fails, try a true
           general text processor, such as GNU M4.

           C preprocessors vary in some details.  This manual dis
           cusses the GNU C preprocessor, which provides a small
           superset of the features of ISO Standard C.  In its
           default mode, the GNU C preprocessor does not do a few
           things required by the standard.  These are features which
           are rarely, if ever, used, and may cause surprising
           changes to the meaning of a program which does not expect

## OPTIONS

           The C preprocessor expects two file names as arguments,
           infile and outfile.  The preprocessor reads infile
           together with any other files it specifies with #include.
           All the output generated by the combined input files is
           written in outfile.

           Either infile or outfile may be -, which as infile means
           to read from standard input and as outfile means to write
           to standard output.  Also, if either file is omitted, it
           means the same as if - had been specified for that file.

           Unless otherwise noted, or the option ends in =, all
           options which take an argument may have that argument
           appear either immediately after the option, or with a
           space between option and argument: -Ifoo and -I foo have
           the same effect.

           Many options have multi-letter names; therefore multiple
           single-letter options may not be grouped: -dM is very dif
           ferent from -d -M.

           -D name
               Predefine name as a macro, with definition 1.

           -D name=definition
               Predefine name as a macro, with definition definition.
               There are no restrictions on the contents of defini
               tion, 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 wish to define a function-like macro on the
               command line, write its argument list with surrounding
               parentheses before the equals sign (if any).  Paren
               theses are meaningful to most shells, so you will need
               to quote the option.  With sh and csh,
               -D'name(args...)=definition' works.

               -D and -U options are processed in the order they are
               given on the command line.  All -imacros file and
               -include file options are processed after all -D and
               -U options.

           -U name
               Cancel any previous definition of name, either built
               in or provided with a -D option.

           -undef
               Do not predefine any system-specific macros.  The com
               Write output to file.  This is the same as specifying
               file as the second non-option argument to cpp.  gcc
               has a different interpretation of a second non-option
               argument, so you must use -o to specify the output
               file.

           -Wall
               Turns on all optional warnings which are desirable for
               normal code.  At present this is -Wcomment and -Wtri
               graphs.  Note that many of the preprocessor's warnings
               are on by default and have no options to control them.

           -Wcomment
           -Wcomments
               Warn whenever a comment-start sequence /* appears in a
               /* comment, or whenever a backslash-newline appears in
               a // comment.  (Both forms have the same effect.)

           -Wtrigraphs
               Warn if any trigraphs are encountered.  This option
               used to take effect only if -trigraphs was also speci
               fied, but now works independently.  Warnings are not
               given for trigraphs within comments, as they do not
               affect the meaning of the program.

           -Wtraditional
               Warn about certain constructs that behave differently
               in traditional and ISO C.  Also warn about ISO C con
               structs that have no traditional C equivalent, and
               problematic constructs which should be avoided.

           -Wimport
               Warn the first time #import is used.

           -Wundef
               Warn whenever an identifier which is not a macro is
               encountered in an #if directive, outside of defined.
               Such identifiers are replaced with zero.

           -Wunused-macros
               Warn about macros defined in the main file that are
               unused.  A macro is used if it is expanded or tested
               for existence at least once.  The preprocessor will
               also warn if the macro has not been used at the time
               it is redefined or undefined.

               Built-in macros, macros defined on the command line,
               and macros defined in include files are not warned
               about.

               Note: If a macro is actually used, but only used in
               skipped conditional blocks, then CPP will report it as
                       #if FOO
                       ...
                       #else FOO
                       ...
                       #endif FOO

               The second and third "FOO" should be in comments, but
               often are not in older programs.  This warning is on
               by default.

           -Werror
               Make all warnings into hard errors.  Source code which
               triggers warnings will be rejected.

           -Wsystem-headers
               Issue warnings for code in system headers.  These are
               normally unhelpful in finding bugs in your own code,
               therefore suppressed.  If you are responsible for the
               system library, you may want to see them.

           -w  Suppress all warnings, including those which GNU CPP
               issues by default.

           -pedantic
               Issue all the mandatory diagnostics listed in the C
               standard.  Some of them are left out by default, since
               they trigger frequently on harmless code.

           -pedantic-errors
               Issue all the mandatory diagnostics, and make all
               mandatory diagnostics into errors.  This includes
               mandatory diagnostics that GCC issues without -pedan
               tic but treats as warnings.

           -M  Instead of outputting the result of preprocessing,
               output a rule suitable for make describing the depen
               dencies of the main source file.  The preprocessor
               outputs one make rule containing the object file name
               for that source file, a colon, and the names of all
               the included files, including those coming from
               -include or -imacros command line options.

               Unless specified explicitly (with -MT or -MQ), the
               object file name consists of the basename of the
               source file with any suffix replaced with object file
               suffix.  If there are many included files then the
               rule is split into several lines using \-newline.  The
               rule has no commands.

               This option does not suppress the preprocessor's debug
               output, such as -dM.  To avoid mixing such debug out
               put with the dependency rules you should explicitly
               ble quotes in an #include directive does not in itself
               determine whether that header will appear in -MM
               dependency output.  This is a slight change in seman
               tics from GCC versions 3.0 and earlier.

           -MF file
               @anchor{-MF} When used with -M or -MM, specifies a
               file to write the dependencies to.  If no -MF switch
               is given the preprocessor sends the rules to the same
               place it would have sent preprocessed output.

               When used with the driver options -MD or -MMD, -MF
               overrides the default dependency output file.

           -MG In conjunction with an option such as -M requesting
               dependency generation, -MG assumes missing header
               files are generated files and adds them to the depen
               dency list without raising an error.  The dependency
               filename is taken directly from the "#include" direc
               tive without prepending any path.  -MG also suppresses
               preprocessed output, as a missing header file renders
               this useless.

               This feature is used in automatic updating of make
               files.

           -MP This option instructs CPP to add a phony target for
               each dependency other than the main file, causing each
               to depend on nothing.  These dummy rules work around
               errors make gives if you remove header files without
               updating the Makefile to match.

               This is typical output:

                       test.o: test.c test.h

                       test.h:

           -MT target
               Change the target of the rule emitted by dependency
               generation.  By default CPP takes the name of the main
               input file, including any path, deletes any file suf
               fix such as .c, and appends the platform's usual
               object suffix.  The result is the target.

               An -MT option will set the target to be exactly the
               string you specify.  If you want multiple targets, you
               can specify them as a single argument to -MT, or use
               multiple -MT options.

               For example, -MT '$(objpfx)foo.o' might give

               uses its argument but with a suffix of .d, otherwise
               it take the basename of the input file and applies a
               .d suffix.

               If -MD is used in conjunction with -E, any -o switch
               is understood to specify the dependency output file
               (but @pxref{-MF}), but if used without -E, each -o is
               understood to specify a target object file.

               Since -E is not implied, -MD can be used to generate a
               dependency output file as a side-effect of the compi
               lation process.

           -MMD
               Like -MD except mention only user header files, not
               system -header files.

           -x c
           -x c++
           -x objective-c
           -x assembler-with-cpp
               Specify the source language: C, C++, Objective-C, or
               assembly.  This has nothing to do with standards con
               formance or extensions; it merely selects which base
               syntax to expect.  If you give none of these options,
               cpp will deduce the language from the extension of the
               source file: .c, .cc, .m, or .S.  Some other common
               extensions for C++ and assembly are also recognized.
               If cpp does not recognize the extension, it will treat
               the file as C; this is the most generic mode.

               Note: Previous versions of cpp accepted a -lang option
               which selected both the language and the standards
               conformance level.  This option has been removed,
               because it conflicts with the -l option.

           -std=standard
           -ansi
               Specify the standard to which the code should conform.
               Currently CPP knows about C and C++ standards; others
               may be added in the future.

               standard may be one of:

               "iso9899:1990"
               "c89"
                   The ISO C standard from 1990.  c89 is the custom
                   ary shorthand for this version of the standard.

                   The -ansi option is equivalent to -std=c89.

               "iso9899:199409"
               "gnu9x"
                   The 1999 C standard plus GNU extensions.

               "c++98"
                   The 1998 ISO C++ standard plus amendments.

               "gnu++98"
                   The same as -std=c++98 plus GNU extensions.  This
                   is the default for C++ code.

           -I- Split the include path.  Any directories specified
               with -I options before -I- are searched only for head
               ers requested with "#include "file""; they are not
               searched for "#include <file>".  If additional direc
               tories are specified with -I options after the -I-,
               those directories are searched for all #include direc
               tives.

               In addition, -I- inhibits the use of the directory of
               the current file directory as the first search direc
               tory for "#include "file"".

           -nostdinc
               Do not search the standard system directories for
               header files.  Only the directories you have specified
               with -I options (and the directory of the current
               file, if appropriate) are searched.

           -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 the C++ library.)

           -include file
               Process file as if "#include "file"" appeared as the
               first line of the primary source file.  However, the
               first directory searched for file is the preproces
               sor's working directory instead of the directory con
               taining the main source file.  If not found there, it
               is searched for in the remainder of the "#include
               "..."" search chain as normal.

               If multiple -include options are given, the files are
               included in the order they appear on the command line.

           -imacros file
               Exactly like -include, except that any output produced
               by scanning file is thrown away.  Macros it defines
               remain defined.  This allows you to acquire all the
               macros from a header without also processing its dec
               larations.

           -iwithprefix dir
           -iwithprefixbefore dir
               Append dir to the prefix specified previously with
               -iprefix, and add the resulting directory to the
               include search path.  -iwithprefixbefore puts it in
               the same place -I would; -iwithprefix puts it where
               -idirafter would.

               Use of these options is discouraged.

           -isystem dir
               Search dir for header files, after all directories
               specified by -I but before the standard system direc
               tories.  Mark it as a system directory, so that it
               gets the same special treatment as is applied to the
               standard system directories.

           -fpreprocessed
               Indicate to the preprocessor that the input file has
               already been preprocessed.  This suppresses things
               like macro expansion, trigraph conversion, escaped
               newline splicing, and processing of most directives.
               The preprocessor still recognizes and removes com
               ments, so that you can pass a file preprocessed with
               -C to the compiler without problems.  In this mode the
               integrated preprocessor is little more than a tok
               enizer for the front ends.

               -fpreprocessed is implicit if the input file has one
               of the extensions .i, .ii or .mi.  These are the
               extensions that GCC uses for preprocessed files cre
               ated by -save-temps.

           -ftabstop=width
               Set the distance between tab stops.  This helps the
               preprocessor report correct column numbers in warnings
               or errors, even if tabs appear on the line.  If the
               value is less than 1 or greater than 100, the option
               is ignored.  The default is 8.

           -fno-show-column
               Do not print column numbers in diagnostics.  This may
               be necessary if diagnostics are being scanned by a
               program that does not understand the column numbers,
               such as dejagnu.

           -A predicate=answer
               Make an assertion with the predicate predicate and
               answer answer.  This form is preferred to the older
               form -A predicate(answer), which is still supported,
               because it does not use shell special characters.
               Other characters are interpreted by the compiler
               proper, or reserved for future versions of GCC, and so
               are silently ignored.  If you specify characters whose
               behavior conflicts, the result is undefined.

               M   Instead of the normal output, generate a list of
                   #define directives for all the macros defined dur
                   ing the execution of the preprocessor, including
                   predefined macros.  This gives you a way of find
                   ing out what is predefined in your version of the
                   preprocessor.  Assuming you have no file foo.h,
                   the command

                           touch foo.h; cpp -dM foo.h

                   will show all the predefined macros.

               D   Like M except in two respects: it does not include
                   the predefined macros, and it outputs both the
                   #define directives and the result of preprocess
                   ing.  Both kinds of output go to the standard out
                   put file.

               N   Like D, but emit only the macro names, not their
                   expansions.

               I   Output #include directives in addition to the
                   result of preprocessing.

           -P  Inhibit generation of linemarkers in the output from
               the preprocessor.  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 linemarkers.

           -C  Do not discard comments.  All comments are passed
               through to the output file, except for comments in
               processed directives, which are deleted along with the
               directive.

               You should be prepared for side effects when using -C;
               it causes the preprocessor to treat comments as tokens
               in their own right.  For example, comments appearing
               at the start of what would be a directive line have
               the effect of turning that line into an ordinary
               source line, since the first token on the line is no
               longer a #.

           -CC Do not discard comments, including during macro expan
               sion.  This is like -C, except that comments contained
               within macros are also passed through to the output
               file where the macro is expanded.
               case with -no-gcc.

           -traditional-cpp
               Try to imitate the behavior of old-fashioned C prepro
               cessors, as opposed to ISO C preprocessors.

           -trigraphs
               Process trigraph sequences.

           -remap
               Enable special code to work around file systems which
               only permit very short file names, such as MS-DOS.

           --help
           --target-help
               Print text describing all the command line options
               instead of preprocessing anything.

           -v  Verbose mode.  Print out GNU CPP's version number at
               the beginning of execution, and report the final form
               of the include path.

           -H  Print the name of each header file used, in addition
               to other normal activities.  Each name is indented to
               show how deep in the #include stack it is.

           -version
           --version
               Print out GNU CPP's version number.  With one dash,
               proceed to preprocess as normal.  With two dashes,
               exit immediately.

## ENVIRONMENT

           This section describes the environment variables that
           affect how CPP operates.  You can use them to specify
           directories or prefixes to use when searching for include
           files, or to control dependency output.

           Note that you can also specify places to search using
           options such as -I, and control dependency output with
           options like -M.  These take precedence over environment
           variables, which in turn take precedence over the configu
           ration of GCC.

           CPATH
           C_INCLUDE_PATH
           CPLUS_INCLUDE_PATH
           OBJC_INCLUDE_PATH
               Each variable's value is a list of directories sepa
               rated by a special character, much like PATH, in which
               to look for header files.  The special character,
               "PATH_SEPARATOR", is target-dependent and determined
               with -isystem options on the command line.

               In all these variables, an empty element instructs the
               compiler to search its current working directory.
               Empty elements can appear at the beginning or end of a
               path.  For instance, if the value of CPATH is ":/spe
               cial/include", that has the same effect as -I. -I/spe
               cial/include.

           DEPENDENCIES_OUTPUT
               If this variable is set, its value specifies how to
               output dependencies for Make based on the non-system
               header files processed by the compiler.  System header
               files are ignored in the dependency output.

               The value of DEPENDENCIES_OUTPUT can be just a file
               name, in which case the Make rules are written to that
               file, guessing the target name from the source file
               name.  Or the value can have the form file target, in
               which case the rules are written to file file using
               target as the target name.

               In other words, this environment variable is equiva
               lent to combining the options -MM and -MF, with an
               optional -MT switch too.

           SUNPRO_DEPENDENCIES
               This variable is the same as DEPENDENCIES_OUTPUT (see
               above), except that system header files are not
               ignored, so it implies -M rather than -MM.  However,
               the dependence on the main input file is omitted.

## SEE ALSO

           gpl(7), gfdl(7), fsf-funding(7), gcc(1), as(1), ld(1), and
           the Info entries for cpp, gcc, and binutils.

## COPYRIGHT

           Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995,
           1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Soft
           ware Foundation, Inc.

           Permission is granted to copy, distribute and/or modify
           this document under the terms of the GNU Free Documenta
           tion License, Version 1.1 or any later version published
           by the Free Software Foundation.  A copy of the license is
           included in the man page gfdl(7).  This manual contains no
           Invariant Sections.  The Front-Cover Texts are (a) (see
           below), and the Back-Cover Texts are (b) (see below).

           (a) The FSF's Front-Cover Text is:

                A GNU Manual