1013 lines
30 KiB
Groff
1013 lines
30 KiB
Groff
.\" $NetBSD: cpp-contrib.1,v 1.1 2009/04/30 00:45:47 joerg Exp $
|
|
.Dd April 30, 2009
|
|
.Dt CPP 1
|
|
.Os
|
|
.Sh NAME
|
|
cpp - The C Preprocessor
|
|
.Sh SYNOPSIS
|
|
cpp
|
|
.Op Fl D Ns Ar macro Ns = Ns Ar defn...
|
|
.Op Fl U Ns Ar macro
|
|
.Op Fl I Ns Ar dir...
|
|
.Op Fl iquote Ns Ar dir...
|
|
.Op Fl W Ns Ar warn...
|
|
.Oo Fl M
|
|
|
|
|
.Fl MM Oc
|
|
.Op Fl MG
|
|
.Op Fl MF Ar filename
|
|
.Op Fl MP
|
|
.Op Fl MQ Ar target...
|
|
.Op Fl MT Ar target...
|
|
.Op Fl P
|
|
.Op Fl fno-working-directory
|
|
.Op Fl x Ar language
|
|
.Op Fl std= Ns Ar standard
|
|
.Em infile
|
|
.Em outfile
|
|
.Pp
|
|
Only the most useful options are listed here; see below for the remainder.
|
|
.Sh DESCRIPTION
|
|
The C preprocessor, often known as
|
|
.Em cpp ,
|
|
is a
|
|
.Em macro processor
|
|
that is used automatically by the C compiler to transform your program before compilation.
|
|
It is called a macro processor because it allows you to define
|
|
.Em macros ,
|
|
which are brief abbreviations for longer constructs.
|
|
.Pp
|
|
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 character 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.
|
|
.Pp
|
|
Having said that, you can often get away with using cpp on things which are not C.
|
|
Other Algol-ish programming languages are often safe (Pascal, Ada, etc.) So is assembly, with caution.
|
|
.Fl 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.
|
|
.Pp
|
|
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 programming languages have their own conditional compilation and inclusion mechanism.
|
|
If all else fails, try a true general text processor, such as GNU M4.
|
|
.Pp
|
|
C preprocessors vary in some details.
|
|
This manual discusses 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 them.
|
|
To get strict ISO Standard C, you should use the
|
|
.Fl std=c89
|
|
or
|
|
.Fl std=c99
|
|
options, depending on which version of the standard you want.
|
|
To get all the mandatory diagnostics, you must also use
|
|
.Fl pedantic .
|
|
.Pp
|
|
This manual describes the behavior of the ISO preprocessor.
|
|
To minimize gratuitous differences, where the ISO preprocessor's behavior does not conflict with traditional semantics, the traditional preprocessor should behave the same way.
|
|
The various differences that do exist are detailed in the section
|
|
.Sy Traditional Mode .
|
|
.Pp
|
|
For clarity, unless noted otherwise, references to
|
|
.Sy CPP
|
|
in this manual refer to GNU CPP.
|
|
.Sh OPTIONS
|
|
The C preprocessor expects two file names as arguments,
|
|
.Em infile
|
|
and
|
|
.Em outfile .
|
|
The preprocessor reads
|
|
.Em infile
|
|
together with any other files it specifies with
|
|
.Sy #include .
|
|
All the output generated by the combined input files is written in
|
|
.Em outfile .
|
|
.Pp
|
|
Either
|
|
.Em infile
|
|
or
|
|
.Em outfile
|
|
may be
|
|
.Sy - ,
|
|
which as
|
|
.Em infile
|
|
means to read from standard input and as
|
|
.Em outfile
|
|
means to write to standard output.
|
|
Also, if either file is omitted, it means the same as if
|
|
.Sy -
|
|
had been specified for that file.
|
|
.Pp
|
|
Unless otherwise noted, or the option ends in
|
|
.Sy = ,
|
|
all options which take an argument may have that argument appear either immediately after the option, or with a space between option and argument:
|
|
.Fl Ifoo
|
|
and
|
|
.Fl I Ar foo
|
|
have the same effect.
|
|
.Pp
|
|
Many options have multi-letter names; therefore multiple single-letter options may
|
|
.Em not
|
|
be grouped:
|
|
.Fl dM
|
|
is very different from
|
|
.Fl d Fl M .
|
|
.Pp
|
|
.Bl -tag -width xx
|
|
.It Fl D Ar name
|
|
Predefine
|
|
.Em name
|
|
as a macro, with definition
|
|
.Va 1 .
|
|
.Pp
|
|
.It Fl D Ar name Ns = Ns Ar definition
|
|
The contents of
|
|
.Em definition
|
|
are tokenized and processed as if they appeared during translation phase three in a
|
|
.Sy #define
|
|
directive.
|
|
In particular, the definition will be truncated by embedded newline characters.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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).
|
|
Parentheses are meaningful to most shells, so you will need to quote the option.
|
|
With
|
|
.Sy sh
|
|
and
|
|
.Sy csh ,
|
|
.Sy -D'
|
|
.Em name
|
|
.Sy (
|
|
.Em args...
|
|
.Sy )=
|
|
.Em definition
|
|
.Sy '
|
|
works.
|
|
.Pp
|
|
.Fl D
|
|
and
|
|
.Fl U
|
|
options are processed in the order they are given on the command line.
|
|
All
|
|
.Fl imacros Ar file
|
|
and
|
|
.Fl include Ar file
|
|
options are processed after all
|
|
.Fl D
|
|
and
|
|
.Fl U
|
|
options.
|
|
.Pp
|
|
.It Fl U Ar name
|
|
Cancel any previous definition of
|
|
.Em name ,
|
|
either built in or provided with a
|
|
.Fl D
|
|
option.
|
|
.Pp
|
|
.It Fl undef
|
|
Do not predefine any system-specific or GCC-specific macros.
|
|
The standard predefined macros remain defined.
|
|
.Pp
|
|
.It Fl I Ar dir
|
|
Add the directory
|
|
.Em dir
|
|
to the list of directories to be searched for header files.
|
|
.Pp
|
|
Directories named by
|
|
.Fl I
|
|
are searched before the standard system include directories.
|
|
If the directory
|
|
.Em dir
|
|
is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated .
|
|
.Pp
|
|
.It Fl o Ar file
|
|
Write output to
|
|
.Em file .
|
|
This is the same as specifying
|
|
.Em file
|
|
as the second non-option argument to
|
|
.Nm cpp .
|
|
.Sy gcc
|
|
has a different interpretation of a second non-option argument, so you must use
|
|
.Fl o
|
|
to specify the output file.
|
|
.Pp
|
|
.It Fl Wall
|
|
Turns on all optional warnings which are desirable for normal code.
|
|
At present this is
|
|
.Fl Wcomment ,
|
|
.Fl Wtrigraphs ,
|
|
.Fl Wmultichar
|
|
and a warning about integer promotion causing a change of sign in
|
|
.Va #if
|
|
expressions.
|
|
Note that many of the preprocessor's warnings are on by default and have no options to control them.
|
|
.Pp
|
|
.It Fl Wcomment
|
|
.It Fl Wcomments
|
|
Warn whenever a comment-start sequence
|
|
.Sy /*
|
|
appears in a
|
|
.Sy /*
|
|
comment, or whenever a backslash-newline appears in a
|
|
.Sy //
|
|
comment.
|
|
(Both forms have the same effect.)
|
|
.Pp
|
|
.It Fl Wtrigraphs
|
|
@anchor{Wtrigraphs} Most trigraphs in comments cannot affect the meaning of the program.
|
|
However, a trigraph that would form an escaped newline
|
|
.Sy ( ??/
|
|
at the end of a line) can, by changing where the comment begins or ends.
|
|
Therefore, only trigraphs that would form escaped newlines produce warnings inside a comment.
|
|
.Pp
|
|
This option is implied by
|
|
.Fl Wall .
|
|
If
|
|
.Fl Wall
|
|
is not given, this option is still enabled unless trigraphs are enabled.
|
|
To get trigraph conversion without warnings, but get the other
|
|
.Fl Wall
|
|
warnings, use
|
|
.Fl trigraphs Fl Wall Fl Wno-trigraphs .
|
|
.Pp
|
|
.It Fl Wtraditional
|
|
Warn about certain constructs that behave differently in traditional and ISO C.
|
|
Also warn about ISO C constructs that have no traditional C equivalent, and problematic constructs which should be avoided.
|
|
.Pp
|
|
.It Fl Wimport
|
|
Warn the first time
|
|
.Sy #import
|
|
is used.
|
|
.Pp
|
|
.It Fl Wundef
|
|
Warn whenever an identifier which is not a macro is encountered in an
|
|
.Sy #if
|
|
directive, outside of
|
|
.Sy defined .
|
|
Such identifiers are replaced with zero.
|
|
.Pp
|
|
.It Fl Wunused-macros
|
|
Warn about macros defined in the main file that are unused.
|
|
A macro is
|
|
.Em 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.
|
|
.Pp
|
|
Built-in macros, macros defined on the command line, and macros defined in include files are not warned about.
|
|
.Pp
|
|
.Em Note:
|
|
If a macro is actually used, but only used in skipped conditional blocks, then CPP will report it as unused.
|
|
To avoid the warning in such a case, you might improve the scope of the macro's definition by, for example, moving it into the first skipped block.
|
|
Alternatively, you could provide a dummy use with something like:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
#if defined the_macro_causing_the_warning
|
|
#endif
|
|
.Ed
|
|
.It Fl Wendif-labels
|
|
Warn whenever an
|
|
.Sy #else
|
|
or an
|
|
.Sy #endif
|
|
are followed by text.
|
|
This usually happens in code of the form
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
#if FOO
|
|
\&...
|
|
#else FOO
|
|
\&...
|
|
#endif FOO
|
|
.Ed
|
|
The second and third
|
|
.Va FOO
|
|
should be in comments, but often are not in older programs.
|
|
This warning is on by default.
|
|
.Pp
|
|
.It Fl Werror
|
|
Make all warnings into hard errors.
|
|
Source code which triggers warnings will be rejected.
|
|
.Pp
|
|
.It Fl 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.
|
|
.Pp
|
|
.It Fl w
|
|
Suppress all warnings, including those which GNU CPP issues by default.
|
|
.Pp
|
|
.It Fl 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.
|
|
.Pp
|
|
.It Fl pedantic-errors
|
|
Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors.
|
|
This includes mandatory diagnostics that GCC issues without
|
|
.Fl pedantic
|
|
but treats as warnings.
|
|
.Pp
|
|
.It Fl M
|
|
Instead of outputting the result of preprocessing, output a rule suitable for
|
|
.Sy make
|
|
describing the dependencies of the main source file.
|
|
The preprocessor outputs one
|
|
.Sy 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
|
|
.Fl include
|
|
or
|
|
.Fl imacros
|
|
command line options.
|
|
.Pp
|
|
Unless specified explicitly (with
|
|
.Fl MT
|
|
or
|
|
.Fl 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
|
|
.Sy \e
|
|
-newline.
|
|
The rule has no commands.
|
|
.Pp
|
|
This option does not suppress the preprocessor's debug output, such as
|
|
.Fl dM .
|
|
To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with
|
|
.Fl MF ,
|
|
or use an environment variable like
|
|
.Sy DEPENDENCIES_OUTPUT .
|
|
Debug output will still be sent to the regular output stream as normal.
|
|
.Pp
|
|
Passing
|
|
.Fl M
|
|
to the driver implies
|
|
.Fl E ,
|
|
and suppresses warnings with an implicit
|
|
.Fl w .
|
|
.Pp
|
|
.It Fl MM
|
|
Like
|
|
.Fl M
|
|
but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header.
|
|
.Pp
|
|
This implies that the choice of angle brackets or double quotes in an
|
|
.Sy #include
|
|
directive does not in itself determine whether that header will appear in
|
|
.Fl MM
|
|
dependency output.
|
|
This is a slight change in semantics from GCC versions 3.0 and earlier.
|
|
.Pp
|
|
@anchor{dashMF}
|
|
.Pp
|
|
.It Fl MF Ar file
|
|
When used with
|
|
.Fl M
|
|
or
|
|
.Fl MM ,
|
|
specifies a file to write the dependencies to.
|
|
If no
|
|
.Fl MF
|
|
switch is given the preprocessor sends the rules to the same place it would have sent preprocessed output.
|
|
.Pp
|
|
When used with the driver options
|
|
.Fl MD
|
|
or
|
|
.Fl MMD ,
|
|
.Fl MF
|
|
overrides the default dependency output file.
|
|
.Pp
|
|
.It Fl MG
|
|
In conjunction with an option such as
|
|
.Fl M
|
|
requesting dependency generation,
|
|
.Fl MG
|
|
assumes missing header files are generated files and adds them to the dependency list without raising an error.
|
|
The dependency filename is taken directly from the
|
|
.Va #include
|
|
directive without prepending any path.
|
|
.Fl MG
|
|
also suppresses preprocessed output, as a missing header file renders this useless.
|
|
.Pp
|
|
This feature is used in automatic updating of makefiles.
|
|
.Pp
|
|
.It Fl 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
|
|
.Sy make
|
|
gives if you remove header files without updating the
|
|
.Pa Makefile
|
|
to match.
|
|
.Pp
|
|
This is typical output:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
test.o: test.c test.h
|
|
|
|
test.h:
|
|
.Ed
|
|
.It Fl MT Ar 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 suffix such as
|
|
.Sy .c ,
|
|
and appends the platform's usual object suffix.
|
|
The result is the target.
|
|
.Pp
|
|
An
|
|
.Fl 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
|
|
.Fl MT ,
|
|
or use multiple
|
|
.Fl MT
|
|
options.
|
|
.Pp
|
|
For example,
|
|
.Sy -MT '$(objpfx)foo.o'
|
|
might give
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$(objpfx)foo.o: foo.c
|
|
.Ed
|
|
.It Fl MQ Ar target
|
|
Same as
|
|
.Fl MT ,
|
|
but it quotes any characters which are special to Make.
|
|
.Sy -MQ '$(objpfx)foo.o'
|
|
gives
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$$(objpfx)foo.o: foo.c
|
|
.Ed
|
|
The default target is automatically quoted, as if it were given with
|
|
.Fl MQ .
|
|
.Pp
|
|
.It Fl MD
|
|
.Fl MD
|
|
is equivalent to
|
|
.Fl M Fl MF Ar file ,
|
|
except that
|
|
.Fl E
|
|
is not implied.
|
|
The driver determines
|
|
.Em file
|
|
based on whether an
|
|
.Fl o
|
|
option is given.
|
|
If it is, the driver uses its argument but with a suffix of
|
|
.Pa .d ,
|
|
otherwise it take the basename of the input file and applies a
|
|
.Pa .d
|
|
suffix.
|
|
.Pp
|
|
If
|
|
.Fl MD
|
|
is used in conjunction with
|
|
.Fl E ,
|
|
any
|
|
.Fl o
|
|
switch is understood to specify the dependency output file (but @pxref{dashMF,,-MF}), but if used without
|
|
.Fl E ,
|
|
each
|
|
.Fl o
|
|
is understood to specify a target object file.
|
|
.Pp
|
|
Since
|
|
.Fl E
|
|
is not implied,
|
|
.Fl MD
|
|
can be used to generate a dependency output file as a side-effect of the compilation process.
|
|
.Pp
|
|
.It Fl MMD
|
|
Like
|
|
.Fl MD
|
|
except mention only user header files, not system header files.
|
|
.Pp
|
|
.It Fl x Ar c
|
|
.It Fl x Ar c++
|
|
.It Fl x Ar objective-c
|
|
.It Fl x Ar assembler-with-cpp
|
|
Specify the source language: C, C++, Objective-C, or assembly.
|
|
This has nothing to do with standards conformance 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:
|
|
.Sy .c ,
|
|
.Sy .cc ,
|
|
.Sy .m ,
|
|
or
|
|
.Sy .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.
|
|
.Pp
|
|
.Em Note:
|
|
Previous versions of cpp accepted a
|
|
.Fl lang
|
|
option which selected both the language and the standards conformance level.
|
|
This option has been removed, because it conflicts with the
|
|
.Fl l
|
|
option.
|
|
.Pp
|
|
.It Fl std= Ns Ar standard
|
|
.It Fl 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.
|
|
.Pp
|
|
.Em standard
|
|
may be one of:
|
|
.Pp
|
|
.Bl -tag -width xx
|
|
.It Sy iso9899:1990 Ns
|
|
.It Sy c89 Ns
|
|
The ISO C standard from 1990.
|
|
.Sy c89
|
|
is the customary shorthand for this version of the standard.
|
|
.Pp
|
|
The
|
|
.Fl ansi
|
|
option is equivalent to
|
|
.Fl std=c89 .
|
|
.Pp
|
|
.It Sy iso9899:199409 Ns
|
|
The 1990 C standard, as amended in 1994.
|
|
.Pp
|
|
.It Sy iso9899:1999 Ns
|
|
.It Sy c99 Ns
|
|
.It Sy iso9899:199x Ns
|
|
.It Sy c9x Ns
|
|
The revised ISO C standard, published in December 1999.
|
|
Before publication, this was known as C9X.
|
|
.Pp
|
|
.It Sy gnu89 Ns
|
|
The 1990 C standard plus GNU extensions.
|
|
This is the default.
|
|
.Pp
|
|
.It Sy gnu99 Ns
|
|
.It Sy gnu9x Ns
|
|
The 1999 C standard plus GNU extensions.
|
|
.Pp
|
|
.It Sy c++98 Ns
|
|
The 1998 ISO C++ standard plus amendments.
|
|
.Pp
|
|
.It Sy gnu++98 Ns
|
|
The same as
|
|
.Fl std=c++98
|
|
plus GNU extensions.
|
|
This is the default for C++ code.
|
|
.Pp
|
|
.El
|
|
.It Fl I-
|
|
Split the include path.
|
|
Any directories specified with
|
|
.Fl I
|
|
options before
|
|
.Fl I-
|
|
are searched only for headers requested with
|
|
.Va .Sy #include \&"file" ;
|
|
they are not searched for
|
|
.Va .Sy #include \*[Lt]file\*[Gt] .
|
|
If additional directories are specified with
|
|
.Fl I
|
|
options after the
|
|
.Fl I- ,
|
|
those directories are searched for all
|
|
.Sy #include
|
|
directives.
|
|
.Pp
|
|
In addition,
|
|
.Fl I-
|
|
inhibits the use of the directory of the current file directory as the first search directory for
|
|
.Va .Sy #include \&"file" .
|
|
.Pp
|
|
This option has been deprecated.
|
|
.Pp
|
|
.It Fl nostdinc
|
|
Do not search the standard system directories for header files.
|
|
Only the directories you have specified with
|
|
.Fl I
|
|
options (and the directory of the current file, if appropriate) are searched.
|
|
.Pp
|
|
.It Fl 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.)
|
|
.Pp
|
|
.It Fl include Ar file
|
|
Process
|
|
.Em file
|
|
as if
|
|
.Va #include \&"file"
|
|
appeared as the first line of the primary source file.
|
|
However, the first directory searched for
|
|
.Em file
|
|
is the preprocessor's working directory
|
|
.Em instead of
|
|
the directory containing the main source file.
|
|
If not found there, it is searched for in the remainder of the
|
|
.Va #include \&"..."
|
|
search chain as normal.
|
|
.Pp
|
|
If multiple
|
|
.Fl include
|
|
options are given, the files are included in the order they appear on the command line.
|
|
.Pp
|
|
.It Fl imacros Ar file
|
|
Exactly like
|
|
.Fl include ,
|
|
except that any output produced by scanning
|
|
.Em file
|
|
is thrown away.
|
|
Macros it defines remain defined.
|
|
This allows you to acquire all the macros from a header without also processing its declarations.
|
|
.Pp
|
|
All files specified by
|
|
.Fl imacros
|
|
are processed before all files specified by
|
|
.Fl include .
|
|
.Pp
|
|
.It Fl idirafter Ar dir
|
|
Search
|
|
.Em dir
|
|
for header files, but do it
|
|
.Em after
|
|
all directories specified with
|
|
.Fl I
|
|
and the standard system directories have been exhausted.
|
|
.Em dir
|
|
is treated as a system include directory.
|
|
.Pp
|
|
.It Fl iprefix Ar prefix
|
|
Specify
|
|
.Em prefix
|
|
as the prefix for subsequent
|
|
.Fl iwithprefix
|
|
options.
|
|
If the prefix represents a directory, you should include the final
|
|
.Sy / .
|
|
.Pp
|
|
.It Fl iwithprefix Ar dir
|
|
.It Fl iwithprefixbefore Ar dir
|
|
Append
|
|
.Em dir
|
|
to the prefix specified previously with
|
|
.Fl iprefix ,
|
|
and add the resulting directory to the include search path.
|
|
.Fl iwithprefixbefore
|
|
puts it in the same place
|
|
.Fl I
|
|
would;
|
|
.Fl iwithprefix
|
|
puts it where
|
|
.Fl idirafter
|
|
would.
|
|
.Pp
|
|
.It Fl isysroot Ar dir
|
|
This option is like the
|
|
.Fl -sysroot
|
|
option, but applies only to header files.
|
|
See the
|
|
.Fl -sysroot
|
|
option for more information.
|
|
.Pp
|
|
.It Fl isystem Ar dir
|
|
Search
|
|
.Em dir
|
|
for header files, after all directories specified by
|
|
.Fl I
|
|
but before the standard system directories.
|
|
Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.
|
|
.Pp
|
|
.It Fl cxx-isystem Ar dir
|
|
Search
|
|
.Em dir
|
|
for C++ header files, after all directories specified by
|
|
.Fl I
|
|
but before the standard system directories.
|
|
Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.
|
|
.Pp
|
|
.It Fl iquote Ar dir
|
|
Search
|
|
.Em dir
|
|
only for header files requested with
|
|
.Va .Sy #include \&"file" ;
|
|
they are not searched for
|
|
.Va .Sy #include \*[Lt]file\*[Gt] ,
|
|
before all directories specified by
|
|
.Fl I
|
|
and before the standard system directories.
|
|
.Pp
|
|
.It Fl fdollars-in-identifiers
|
|
@anchor{fdollars-in-identifiers} Accept
|
|
.Sy $
|
|
in identifiers.
|
|
.Pp
|
|
.It Fl fextended-identifiers
|
|
Accept universal character names in identifiers.
|
|
This option is experimental; in a future version of GCC, it will be enabled by default for C99 and C++.
|
|
.Pp
|
|
.It Fl 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 comments, so that you can pass a file preprocessed with
|
|
.Fl C
|
|
to the compiler without problems.
|
|
In this mode the integrated preprocessor is little more than a tokenizer for the front ends.
|
|
.Pp
|
|
.Fl fpreprocessed
|
|
is implicit if the input file has one of the extensions
|
|
.Sy .i ,
|
|
.Sy .ii
|
|
or
|
|
.Sy .mi .
|
|
These are the extensions that GCC uses for preprocessed files created by
|
|
.Fl save-temps .
|
|
.Pp
|
|
.It Fl ftabstop= Ns Ar 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.
|
|
.Pp
|
|
.It Fl fexec-charset= Ns Ar charset
|
|
Set the execution character set, used for string and character constants.
|
|
The default is UTF-8.
|
|
.Em charset
|
|
can be any encoding supported by the system's
|
|
.Va iconv
|
|
library routine.
|
|
.Pp
|
|
.It Fl fwide-exec-charset= Ns Ar charset
|
|
Set the wide execution character set, used for wide string and character constants.
|
|
The default is UTF-32 or UTF-16, whichever corresponds to the width of
|
|
.Va wchar_t .
|
|
As with
|
|
.Fl fexec-charset ,
|
|
.Em charset
|
|
can be any encoding supported by the system's
|
|
.Va iconv
|
|
library routine; however, you will have problems with encodings that do not fit exactly in
|
|
.Va wchar_t .
|
|
.Pp
|
|
.It Fl finput-charset= Ns Ar charset
|
|
Set the input character set, used for translation from the character set of the input file to the source character set used by GCC.
|
|
If the locale does not specify, or GCC cannot get this information from the locale, the default is UTF-8.
|
|
This can be overridden by either the locale or this command line option.
|
|
Currently the command line option takes precedence if there's a conflict.
|
|
.Em charset
|
|
can be any encoding supported by the system's
|
|
.Va iconv
|
|
library routine.
|
|
.Pp
|
|
.It Fl fworking-directory
|
|
Enable generation of linemarkers in the preprocessor output that will let the compiler know the current working directory at the time of preprocessing.
|
|
When this option is enabled, the preprocessor will emit, after the initial linemarker, a second linemarker with the current working directory followed by two slashes.
|
|
GCC will use this directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats.
|
|
This option is implicitly enabled if debugging information is enabled, but this can be inhibited with the negated form
|
|
.Fl fno-working-directory .
|
|
If the
|
|
.Fl P
|
|
flag is present in the command line, this option has no effect, since no
|
|
.Va #line
|
|
directives are emitted whatsoever.
|
|
.Pp
|
|
.It Fl 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
|
|
.Sy dejagnu .
|
|
.Pp
|
|
.It Fl A Ar predicate Ns = Ns Ar answer
|
|
Make an assertion with the predicate
|
|
.Em predicate
|
|
and answer
|
|
.Em answer .
|
|
This form is preferred to the older form
|
|
.Fl A Ar predicate
|
|
.Sy (
|
|
.Em answer
|
|
.Sy ) ,
|
|
which is still supported, because it does not use shell special characters.
|
|
.Pp
|
|
.It Fl A Fl Ns Ar predicate Ns = Ns Ar answer
|
|
Cancel an assertion with the predicate
|
|
.Em predicate
|
|
and answer
|
|
.Em answer .
|
|
.Pp
|
|
.It Fl dCHARS
|
|
.Em CHARS
|
|
is a sequence of one or more of the following characters, and must not be preceded by a space.
|
|
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.
|
|
.Pp
|
|
.Bl -tag -width xx
|
|
.It Sy M Ns
|
|
Instead of the normal output, generate a list of
|
|
.Sy #define
|
|
directives for all the macros defined during the execution of the preprocessor, including predefined macros.
|
|
This gives you a way of finding out what is predefined in your version of the preprocessor.
|
|
Assuming you have no file
|
|
.Pa foo.h ,
|
|
the command
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
touch foo.h; cpp -dM foo.h
|
|
.Ed
|
|
will show all the predefined macros.
|
|
.Pp
|
|
.It Sy D Ns
|
|
Like
|
|
.Sy M
|
|
except in two respects: it does
|
|
.Em not
|
|
include the predefined macros, and it outputs
|
|
.Em both
|
|
the
|
|
.Sy #define
|
|
directives and the result of preprocessing.
|
|
Both kinds of output go to the standard output file.
|
|
.Pp
|
|
.It Sy N Ns
|
|
Like
|
|
.Sy D ,
|
|
but emit only the macro names, not their expansions.
|
|
.Pp
|
|
.It Sy I Ns
|
|
Output
|
|
.Sy #include
|
|
directives in addition to the result of preprocessing.
|
|
.Pp
|
|
.El
|
|
.It Fl 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.
|
|
.Pp
|
|
.It Fl 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.
|
|
.Pp
|
|
You should be prepared for side effects when using
|
|
.Fl 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
|
|
.Sy # .
|
|
.Pp
|
|
.It Fl CC
|
|
Do not discard comments, including during macro expansion.
|
|
This is like
|
|
.Fl C ,
|
|
except that comments contained within macros are also passed through to the output file where the macro is expanded.
|
|
.Pp
|
|
In addition to the side-effects of the
|
|
.Fl C
|
|
option, the
|
|
.Fl CC
|
|
option causes all C++-style comments inside a macro to be converted to C-style comments.
|
|
This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line.
|
|
.Pp
|
|
The
|
|
.Fl CC
|
|
option is generally used to support lint comments.
|
|
.Pp
|
|
.It Fl traditional-cpp
|
|
Try to imitate the behavior of old-fashioned C preprocessors, as opposed to ISO C preprocessors.
|
|
.Pp
|
|
.It Fl trigraphs
|
|
Process trigraph sequences.
|
|
.Pp
|
|
.It Fl remap
|
|
Enable special code to work around file systems which only permit very short file names, such as MS-DOS.
|
|
.Pp
|
|
.It Fl -help
|
|
.It Fl -target-help
|
|
Print text describing all the command line options instead of preprocessing anything.
|
|
.Pp
|
|
.It Fl v
|
|
Verbose mode.
|
|
Print out GNU CPP's version number at the beginning of execution, and report the final form of the include path.
|
|
.Pp
|
|
.It Fl 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
|
|
.Sy #include
|
|
stack it is.
|
|
Precompiled header files are also printed, even if they are found to be invalid; an invalid precompiled header file is printed with
|
|
.Sy ...x
|
|
and a valid one with
|
|
.Sy ...! .
|
|
.Pp
|
|
.It Fl version
|
|
.It Fl -version
|
|
Print out GNU CPP's version number.
|
|
With one dash, proceed to preprocess as normal.
|
|
With two dashes, exit immediately.
|
|
.Pp
|
|
.El
|
|
.Sh 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.
|
|
.Pp
|
|
Note that you can also specify places to search using options such as
|
|
.Fl I ,
|
|
and control dependency output with options like
|
|
.Fl M .
|
|
These take precedence over environment variables, which in turn take precedence over the configuration of GCC.
|
|
.Pp
|
|
.Bl -tag -width xx
|
|
.It Sy CPATH Ns
|
|
.It Sy C_INCLUDE_PATH Ns
|
|
.It Sy CPLUS_INCLUDE_PATH Ns
|
|
.It Sy OBJC_INCLUDE_PATH Ns
|
|
Each variable's value is a list of directories separated by a special character, much like
|
|
.Sy PATH ,
|
|
in which to look for header files.
|
|
The special character,
|
|
.Va PATH_SEPARATOR ,
|
|
is target-dependent and determined at GCC build time.
|
|
For Microsoft Windows-based targets it is a semicolon, and for almost all other targets it is a colon.
|
|
.Pp
|
|
.Sy CPATH
|
|
specifies a list of directories to be searched as if specified with
|
|
.Fl I ,
|
|
but after any paths given with
|
|
.Fl I
|
|
options on the command line.
|
|
This environment variable is used regardless of which language is being preprocessed.
|
|
.Pp
|
|
The remaining environment variables apply only when preprocessing the particular language indicated.
|
|
Each specifies a list of directories to be searched as if specified with
|
|
.Fl isystem ,
|
|
but after any paths given with
|
|
.Fl isystem
|
|
options on the command line.
|
|
.Pp
|
|
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
|
|
.Sy CPATH
|
|
is
|
|
.Va :/special/include ,
|
|
that has the same effect as
|
|
.Sy -I. -I/special/include .
|
|
.Pp
|
|
.It Sy DEPENDENCIES_OUTPUT Ns
|
|
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.
|
|
.Pp
|
|
The value of
|
|
.Sy 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
|
|
.Em file
|
|
\~
|
|
.Em target ,
|
|
in which case the rules are written to file
|
|
.Em file
|
|
using
|
|
.Em target
|
|
as the target name.
|
|
.Pp
|
|
In other words, this environment variable is equivalent to combining the options
|
|
.Fl MM
|
|
and
|
|
.Fl MF ,
|
|
with an optional
|
|
.Fl MT
|
|
switch too.
|
|
.Pp
|
|
.It Sy SUNPRO_DEPENDENCIES Ns
|
|
This variable is the same as
|
|
.Sy DEPENDENCIES_OUTPUT
|
|
(see above), except that system header files are not ignored, so it implies
|
|
.Fl M
|
|
rather than
|
|
.Fl MM .
|
|
However, the dependence on the main input file is omitted.
|
|
.Pp
|
|
.It Sy CPP_RESTRICTED Ns
|
|
If this variable is defined, cpp will skip any include file which is not a regular file, and will continue searching for the requested name (this is always done if the found file is a directory).
|
|
.Pp
|
|
.El
|
|
.Sh SEE ALSO
|
|
gpl(7), gfdl(7), fsf-funding(7), gcc(1), as(1), ld(1), and the Info entries for
|
|
.Pa cpp ,
|
|
.Pa gcc ,
|
|
and
|
|
.Pa binutils .
|
|
.Sh COPYRIGHT
|
|
Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
|
|
.Pp
|
|
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation 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).
|
|
.Pp
|
|
(a) The FSF's Front-Cover Text is:
|
|
.Pp
|
|
A GNU Manual
|
|
.Pp
|
|
(b) The FSF's Back-Cover Text is:
|
|
.Pp
|
|
You have freedom to copy and modify this GNU Manual, like GNU software.
|
|
Copies published by the Free Software Foundation raise funds for GNU development.
|