This commit was generated by cvs2svn to compensate for changes in r162509,
which included commits to RCS files with non-trunk default branches.
This commit is contained in:
commit
83cc3b492f
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=162510
@ -1,8 +1,7 @@
|
||||
.\" Automatically generated by Pod::Man version 1.15
|
||||
.\" Wed Feb 5 03:13:55 2003
|
||||
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ======================================================================
|
||||
.\" ========================================================================
|
||||
.de Sh \" Subsection heading
|
||||
.br
|
||||
.if t .Sp
|
||||
@ -15,12 +14,6 @@
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Ip \" List item
|
||||
.br
|
||||
.ie \\n(.$>=3 .ne \\$3
|
||||
.el .ne 3
|
||||
.IP "\\$1" \\$2
|
||||
..
|
||||
.de Vb \" Begin verbatim text
|
||||
.ft CW
|
||||
.nf
|
||||
@ -28,15 +21,14 @@
|
||||
..
|
||||
.de Ve \" End verbatim text
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.\" Set up some character translations and predefined strings. \*(-- will
|
||||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||||
.\" double quote, and \*(R" will give a right double quote. | will give a
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
||||
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
||||
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
|
||||
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
|
||||
.\" expand to `' in nroff, nothing in troff, for use with C<>.
|
||||
.tr \(*W-|\(bv\*(Tr
|
||||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||||
.ie n \{\
|
||||
@ -56,10 +48,10 @@
|
||||
. ds R" ''
|
||||
'br\}
|
||||
.\"
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr
|
||||
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
||||
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
||||
.\" the output yourself in some meaningful fashion.
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||||
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
|
||||
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||||
.\" output yourself in some meaningful fashion.
|
||||
.if \nF \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
@ -68,14 +60,13 @@
|
||||
. rr F
|
||||
.\}
|
||||
.\"
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
||||
.\" makes way too many mistakes in technical documents.
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||||
.\" way too many mistakes in technical documents.
|
||||
.hy 0
|
||||
.if n .na
|
||||
.\"
|
||||
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||||
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||||
.bd B 3
|
||||
. \" fudge factors for nroff and troff
|
||||
.if n \{\
|
||||
. ds #H 0
|
||||
@ -135,11 +126,10 @@
|
||||
. ds Ae AE
|
||||
.\}
|
||||
.rm #[ #] #H #V #F C
|
||||
.\" ======================================================================
|
||||
.\" ========================================================================
|
||||
.\"
|
||||
.IX Title "CPP 1"
|
||||
.TH CPP 1 "gcc-3.2.2" "2003-02-05" "GNU"
|
||||
.UC
|
||||
.TH CPP 1 "2006-03-06" "gcc-3.4.6" "GNU"
|
||||
.SH "NAME"
|
||||
cpp \- The C Preprocessor
|
||||
.SH "SYNOPSIS"
|
||||
@ -147,7 +137,9 @@ cpp \- The C Preprocessor
|
||||
cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
|
||||
[\fB\-I\fR\fIdir\fR...] [\fB\-W\fR\fIwarn\fR...]
|
||||
[\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR]
|
||||
[\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...] [\fB\-MT\fR \fItarget\fR...]
|
||||
[\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...]
|
||||
[\fB\-MT\fR \fItarget\fR...]
|
||||
[\fB\-P\fR] [\fB\-fno\-working\-directory\fR]
|
||||
[\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR]
|
||||
\fIinfile\fR \fIoutfile\fR
|
||||
.PP
|
||||
@ -166,12 +158,12 @@ 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
|
||||
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. \fB\-traditional\fR
|
||||
(Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR
|
||||
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.
|
||||
@ -191,6 +183,16 @@ of a program which does not expect them. To get strict \s-1ISO\s0 Standard C,
|
||||
you should use the \fB\-std=c89\fR or \fB\-std=c99\fR options, depending
|
||||
on which version of the standard you want. To get all the mandatory
|
||||
diagnostics, you must also use \fB\-pedantic\fR.
|
||||
.PP
|
||||
This manual describes the behavior of the \s-1ISO\s0 preprocessor. To
|
||||
minimize gratuitous differences, where the \s-1ISO\s0 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 \fBTraditional
|
||||
Mode\fR.
|
||||
.PP
|
||||
For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this
|
||||
manual refer to \s-1GNU\s0 \s-1CPP\s0.
|
||||
.SH "OPTIONS"
|
||||
.IX Header "OPTIONS"
|
||||
The C preprocessor expects two file names as arguments, \fIinfile\fR and
|
||||
@ -198,10 +200,10 @@ The C preprocessor expects two file names as arguments, \fIinfile\fR and
|
||||
other files it specifies with \fB#include\fR. All the output generated
|
||||
by the combined input files is written in \fIoutfile\fR.
|
||||
.PP
|
||||
Either \fIinfile\fR or \fIoutfile\fR may be \fB-\fR, which as
|
||||
Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as
|
||||
\&\fIinfile\fR means to read from standard input and as \fIoutfile\fR
|
||||
means to write to standard output. Also, if either file is omitted, it
|
||||
means the same as if \fB-\fR had been specified for that file.
|
||||
means the same as if \fB\-\fR had been specified for that file.
|
||||
.PP
|
||||
Unless otherwise noted, or the option ends in \fB=\fR, all options
|
||||
which take an argument may have that argument appear either immediately
|
||||
@ -211,16 +213,20 @@ after the option, or with a space between option and argument:
|
||||
Many options have multi-letter names; therefore multiple single-letter
|
||||
options may \fInot\fR be grouped: \fB\-dM\fR is very different from
|
||||
\&\fB\-d\ \-M\fR.
|
||||
.Ip "\fB\-D\fR \fIname\fR" 4
|
||||
.IP "\fB\-D\fR \fIname\fR" 4
|
||||
.IX Item "-D name"
|
||||
Predefine \fIname\fR as a macro, with definition \f(CW\*(C`1\*(C'\fR.
|
||||
.Ip "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
|
||||
Predefine \fIname\fR as a macro, with definition \f(CW1\fR.
|
||||
.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
|
||||
.IX Item "-D name=definition"
|
||||
Predefine \fIname\fR as a macro, with definition \fIdefinition\fR.
|
||||
There are no restrictions on the contents of \fIdefinition\fR, 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.
|
||||
The contents of \fIdefinition\fR are tokenized and processed as if
|
||||
they appeared during translation phase three in a \fB#define\fR
|
||||
directive. In particular, the definition will be truncated by
|
||||
embedded newline characters.
|
||||
.Sp
|
||||
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.
|
||||
.Sp
|
||||
If you wish to define a function-like macro on the command line, write
|
||||
its argument list with surrounding parentheses before the equals sign
|
||||
@ -232,90 +238,132 @@ to quote the option. With \fBsh\fR and \fBcsh\fR,
|
||||
are given on the command line. All \fB\-imacros\fR \fIfile\fR and
|
||||
\&\fB\-include\fR \fIfile\fR options are processed after all
|
||||
\&\fB\-D\fR and \fB\-U\fR options.
|
||||
.Ip "\fB\-U\fR \fIname\fR" 4
|
||||
.IP "\fB\-U\fR \fIname\fR" 4
|
||||
.IX Item "-U name"
|
||||
Cancel any previous definition of \fIname\fR, either built in or
|
||||
provided with a \fB\-D\fR option.
|
||||
.Ip "\fB\-undef\fR" 4
|
||||
.IP "\fB\-undef\fR" 4
|
||||
.IX Item "-undef"
|
||||
Do not predefine any system-specific macros. The common predefined
|
||||
macros remain defined.
|
||||
.Ip "\fB\-I\fR \fIdir\fR" 4
|
||||
Do not predefine any system-specific or GCC-specific macros. The
|
||||
standard predefined macros remain defined.
|
||||
.IP "\fB\-I\fR \fIdir\fR" 4
|
||||
.IX Item "-I dir"
|
||||
Add the directory \fIdir\fR to the list of directories to be searched
|
||||
for header files.
|
||||
.Sp
|
||||
Directories named by \fB\-I\fR are searched before the standard
|
||||
system include directories.
|
||||
.Sp
|
||||
It is dangerous to specify a standard system include directory in an
|
||||
\&\fB\-I\fR option. This defeats the special treatment of system
|
||||
headers
|
||||
\&. It can also defeat the repairs to buggy system headers which \s-1GCC\s0
|
||||
makes when it is installed.
|
||||
.Ip "\fB\-o\fR \fIfile\fR" 4
|
||||
system include directories. If the directory \fIdir\fR 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
|
||||
\&.
|
||||
.IP "\fB\-o\fR \fIfile\fR" 4
|
||||
.IX Item "-o file"
|
||||
Write output to \fIfile\fR. This is the same as specifying \fIfile\fR
|
||||
as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a
|
||||
different interpretation of a second non-option argument, so you must
|
||||
use \fB\-o\fR to specify the output file.
|
||||
.Ip "\fB\-Wall\fR" 4
|
||||
.IP "\fB\-Wall\fR" 4
|
||||
.IX Item "-Wall"
|
||||
Turns on all optional warnings which are desirable for normal code. At
|
||||
present this is \fB\-Wcomment\fR and \fB\-Wtrigraphs\fR. Note that
|
||||
many of the preprocessor's warnings are on by default and have no
|
||||
options to control them.
|
||||
.Ip "\fB\-Wcomment\fR" 4
|
||||
Turns on all optional warnings which are desirable for normal code.
|
||||
At present this is \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR,
|
||||
\&\fB\-Wmultichar\fR and a warning about integer promotion causing a
|
||||
change of sign in \f(CW\*(C`#if\*(C'\fR expressions. Note that many of the
|
||||
preprocessor's warnings are on by default and have no options to
|
||||
control them.
|
||||
.IP "\fB\-Wcomment\fR" 4
|
||||
.IX Item "-Wcomment"
|
||||
.PD 0
|
||||
.Ip "\fB\-Wcomments\fR" 4
|
||||
.IP "\fB\-Wcomments\fR" 4
|
||||
.IX Item "-Wcomments"
|
||||
.PD
|
||||
Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR
|
||||
comment, or whenever a backslash-newline appears in a \fB//\fR comment.
|
||||
(Both forms have the same effect.)
|
||||
.Ip "\fB\-Wtrigraphs\fR" 4
|
||||
.IP "\fB\-Wtrigraphs\fR" 4
|
||||
.IX Item "-Wtrigraphs"
|
||||
Warn if any trigraphs are encountered. This option used to take effect
|
||||
only if \fB\-trigraphs\fR was also specified, but now works
|
||||
independently. Warnings are not given for trigraphs within comments, as
|
||||
they do not affect the meaning of the program.
|
||||
.Ip "\fB\-Wtraditional\fR" 4
|
||||
@anchor{Wtrigraphs}
|
||||
Most trigraphs in comments cannot affect the meaning of the program.
|
||||
However, a trigraph that would form an escaped newline (\fB??/\fR 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.
|
||||
.Sp
|
||||
This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not
|
||||
given, this option is still enabled unless trigraphs are enabled. To
|
||||
get trigraph conversion without warnings, but get the other
|
||||
\&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR.
|
||||
.IP "\fB\-Wtraditional\fR" 4
|
||||
.IX Item "-Wtraditional"
|
||||
Warn about certain constructs that behave differently in traditional and
|
||||
\&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C
|
||||
equivalent, and problematic constructs which should be avoided.
|
||||
.Ip "\fB\-Wimport\fR" 4
|
||||
.IP "\fB\-Wimport\fR" 4
|
||||
.IX Item "-Wimport"
|
||||
Warn the first time \fB#import\fR is used.
|
||||
.Ip "\fB\-Wundef\fR" 4
|
||||
.IP "\fB\-Wundef\fR" 4
|
||||
.IX Item "-Wundef"
|
||||
Warn whenever an identifier which is not a macro is encountered in an
|
||||
\&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are
|
||||
replaced with zero.
|
||||
.Ip "\fB\-Werror\fR" 4
|
||||
.IP "\fB\-Wunused\-macros\fR" 4
|
||||
.IX Item "-Wunused-macros"
|
||||
Warn about macros defined in the main file that are unused. A macro
|
||||
is \fIused\fR 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.
|
||||
.Sp
|
||||
Built-in macros, macros defined on the command line, and macros
|
||||
defined in include files are not warned about.
|
||||
.Sp
|
||||
\&\fBNote:\fR If a macro is actually used, but only used in skipped
|
||||
conditional blocks, then \s-1CPP\s0 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:
|
||||
.Sp
|
||||
.Vb 2
|
||||
\& #if defined the_macro_causing_the_warning
|
||||
\& #endif
|
||||
.Ve
|
||||
.IP "\fB\-Wendif\-labels\fR" 4
|
||||
.IX Item "-Wendif-labels"
|
||||
Warn whenever an \fB#else\fR or an \fB#endif\fR are followed by text.
|
||||
This usually happens in code of the form
|
||||
.Sp
|
||||
.Vb 5
|
||||
\& #if FOO
|
||||
\& ...
|
||||
\& #else FOO
|
||||
\& ...
|
||||
\& #endif FOO
|
||||
.Ve
|
||||
.Sp
|
||||
The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments, but often are not
|
||||
in older programs. This warning is on by default.
|
||||
.IP "\fB\-Werror\fR" 4
|
||||
.IX Item "-Werror"
|
||||
Make all warnings into hard errors. Source code which triggers warnings
|
||||
will be rejected.
|
||||
.Ip "\fB\-Wsystem-headers\fR" 4
|
||||
.IP "\fB\-Wsystem\-headers\fR" 4
|
||||
.IX Item "-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.
|
||||
.Ip "\fB\-w\fR" 4
|
||||
.IP "\fB\-w\fR" 4
|
||||
.IX Item "-w"
|
||||
Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default.
|
||||
.Ip "\fB\-pedantic\fR" 4
|
||||
.IP "\fB\-pedantic\fR" 4
|
||||
.IX Item "-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.
|
||||
.Ip "\fB\-pedantic-errors\fR" 4
|
||||
.IP "\fB\-pedantic\-errors\fR" 4
|
||||
.IX Item "-pedantic-errors"
|
||||
Issue all the mandatory diagnostics, and make all mandatory diagnostics
|
||||
into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues
|
||||
without \fB\-pedantic\fR but treats as warnings.
|
||||
.Ip "\fB\-M\fR" 4
|
||||
.IP "\fB\-M\fR" 4
|
||||
.IX Item "-M"
|
||||
Instead of outputting the result of preprocessing, output a rule
|
||||
suitable for \fBmake\fR describing the dependencies of the main
|
||||
@ -337,8 +385,9 @@ rules you should explicitly specify the dependency output file with
|
||||
\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output
|
||||
will still be sent to the regular output stream as normal.
|
||||
.Sp
|
||||
Passing \fB\-M\fR to the driver implies \fB\-E\fR.
|
||||
.Ip "\fB\-MM\fR" 4
|
||||
Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses
|
||||
warnings with an implicit \fB\-w\fR.
|
||||
.IP "\fB\-MM\fR" 4
|
||||
.IX Item "-MM"
|
||||
Like \fB\-M\fR but do not mention header files that are found in
|
||||
system header directories, nor header files that are included,
|
||||
@ -348,9 +397,10 @@ This implies that the choice of angle brackets or double quotes in an
|
||||
\&\fB#include\fR directive does not in itself determine whether that
|
||||
header will appear in \fB\-MM\fR dependency output. This is a
|
||||
slight change in semantics from \s-1GCC\s0 versions 3.0 and earlier.
|
||||
.Ip "\fB\-MF\fR \fIfile\fR" 4
|
||||
.Sp
|
||||
@anchor{dashMF}
|
||||
.IP "\fB\-MF\fR \fIfile\fR" 4
|
||||
.IX Item "-MF file"
|
||||
@anchor{\-MF}
|
||||
When used with \fB\-M\fR or \fB\-MM\fR, specifies a
|
||||
file to write the dependencies to. If no \fB\-MF\fR switch is given
|
||||
the preprocessor sends the rules to the same place it would have sent
|
||||
@ -358,15 +408,18 @@ preprocessed output.
|
||||
.Sp
|
||||
When used with the driver options \fB\-MD\fR or \fB\-MMD\fR,
|
||||
\&\fB\-MF\fR overrides the default dependency output file.
|
||||
.Ip "\fB\-MG\fR" 4
|
||||
.IP "\fB\-MG\fR" 4
|
||||
.IX Item "-MG"
|
||||
When used with \fB\-M\fR or \fB\-MM\fR, \fB\-MG\fR says to treat missing
|
||||
header files as generated files and assume they live in the same
|
||||
directory as the source file. It suppresses preprocessed output, as a
|
||||
missing header file is ordinarily an error.
|
||||
In conjunction with an option such as \fB\-M\fR requesting
|
||||
dependency generation, \fB\-MG\fR 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
|
||||
\&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR
|
||||
also suppresses preprocessed output, as a missing header file renders
|
||||
this useless.
|
||||
.Sp
|
||||
This feature is used in automatic updating of makefiles.
|
||||
.Ip "\fB\-MP\fR" 4
|
||||
.IP "\fB\-MP\fR" 4
|
||||
.IX Item "-MP"
|
||||
This option instructs \s-1CPP\s0 to add a phony target for each dependency
|
||||
other than the main file, causing each to depend on nothing. These
|
||||
@ -378,10 +431,11 @@ This is typical output:
|
||||
.Vb 1
|
||||
\& test.o: test.c test.h
|
||||
.Ve
|
||||
.Sp
|
||||
.Vb 1
|
||||
\& test.h:
|
||||
.Ve
|
||||
.Ip "\fB\-MT\fR \fItarget\fR" 4
|
||||
.IP "\fB\-MT\fR \fItarget\fR" 4
|
||||
.IX Item "-MT target"
|
||||
Change the target of the rule emitted by dependency generation. By
|
||||
default \s-1CPP\s0 takes the name of the main input file, including any path,
|
||||
@ -397,7 +451,7 @@ For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give
|
||||
.Vb 1
|
||||
\& $(objpfx)foo.o: foo.c
|
||||
.Ve
|
||||
.Ip "\fB\-MQ\fR \fItarget\fR" 4
|
||||
.IP "\fB\-MQ\fR \fItarget\fR" 4
|
||||
.IX Item "-MQ target"
|
||||
Same as \fB\-MT\fR, but it quotes any characters which are special to
|
||||
Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives
|
||||
@ -405,9 +459,10 @@ Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives
|
||||
.Vb 1
|
||||
\& $$(objpfx)foo.o: foo.c
|
||||
.Ve
|
||||
.Sp
|
||||
The default target is automatically quoted, as if it were given with
|
||||
\&\fB\-MQ\fR.
|
||||
.Ip "\fB\-MD\fR" 4
|
||||
.IP "\fB\-MD\fR" 4
|
||||
.IX Item "-MD"
|
||||
\&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that
|
||||
\&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on
|
||||
@ -417,26 +472,26 @@ basename of the input file and applies a \fI.d\fR suffix.
|
||||
.Sp
|
||||
If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any
|
||||
\&\fB\-o\fR switch is understood to specify the dependency output file
|
||||
(but \f(CW@pxref\fR{\-MF}), but if used without \fB\-E\fR, each \fB\-o\fR
|
||||
(but \f(CW@pxref\fR{dashMF,,\-MF}), but if used without \fB\-E\fR, each \fB\-o\fR
|
||||
is understood to specify a target object file.
|
||||
.Sp
|
||||
Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate
|
||||
a dependency output file as a side-effect of the compilation process.
|
||||
.Ip "\fB\-MMD\fR" 4
|
||||
.IP "\fB\-MMD\fR" 4
|
||||
.IX Item "-MMD"
|
||||
Like \fB\-MD\fR except mention only user header files, not system
|
||||
\&\-header files.
|
||||
.Ip "\fB\-x c\fR" 4
|
||||
.IP "\fB\-x c\fR" 4
|
||||
.IX Item "-x c"
|
||||
.PD 0
|
||||
.Ip "\fB\-x c++\fR" 4
|
||||
.IP "\fB\-x c++\fR" 4
|
||||
.IX Item "-x c++"
|
||||
.Ip "\fB\-x objective-c\fR" 4
|
||||
.IP "\fB\-x objective-c\fR" 4
|
||||
.IX Item "-x objective-c"
|
||||
.Ip "\fB\-x assembler-with-cpp\fR" 4
|
||||
.IP "\fB\-x assembler-with-cpp\fR" 4
|
||||
.IX Item "-x assembler-with-cpp"
|
||||
.PD
|
||||
Specify the source language: C, \*(C+, Objective-C, or assembly. This has
|
||||
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:
|
||||
@ -449,89 +504,97 @@ generic mode.
|
||||
which selected both the language and the standards conformance level.
|
||||
This option has been removed, because it conflicts with the \fB\-l\fR
|
||||
option.
|
||||
.Ip "\fB\-std=\fR\fIstandard\fR" 4
|
||||
.IP "\fB\-std=\fR\fIstandard\fR" 4
|
||||
.IX Item "-std=standard"
|
||||
.PD 0
|
||||
.Ip "\fB\-ansi\fR" 4
|
||||
.IP "\fB\-ansi\fR" 4
|
||||
.IX Item "-ansi"
|
||||
.PD
|
||||
Specify the standard to which the code should conform. Currently cpp
|
||||
only knows about the standards for C; other language standards will be
|
||||
added in the future.
|
||||
Specify the standard to which the code should conform. Currently \s-1CPP\s0
|
||||
knows about C and \*(C+ standards; others may be added in the future.
|
||||
.Sp
|
||||
\&\fIstandard\fR
|
||||
may be one of:
|
||||
.RS 4
|
||||
.if n .Ip "\f(CW""""iso9899:1990""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:1990\fR" 4
|
||||
.ie n .IP """iso9899:1990""" 4
|
||||
.el .IP "\f(CWiso9899:1990\fR" 4
|
||||
.IX Item "iso9899:1990"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""c89""""\fR" 4
|
||||
.el .Ip "\f(CWc89\fR" 4
|
||||
.ie n .IP """c89""" 4
|
||||
.el .IP "\f(CWc89\fR" 4
|
||||
.IX Item "c89"
|
||||
.PD
|
||||
The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for
|
||||
this version of the standard.
|
||||
.Sp
|
||||
The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR.
|
||||
.if n .Ip "\f(CW""""iso9899:199409""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:199409\fR" 4
|
||||
.ie n .IP """iso9899:199409""" 4
|
||||
.el .IP "\f(CWiso9899:199409\fR" 4
|
||||
.IX Item "iso9899:199409"
|
||||
The 1990 C standard, as amended in 1994.
|
||||
.if n .Ip "\f(CW""""iso9899:1999""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:1999\fR" 4
|
||||
.ie n .IP """iso9899:1999""" 4
|
||||
.el .IP "\f(CWiso9899:1999\fR" 4
|
||||
.IX Item "iso9899:1999"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""c99""""\fR" 4
|
||||
.el .Ip "\f(CWc99\fR" 4
|
||||
.ie n .IP """c99""" 4
|
||||
.el .IP "\f(CWc99\fR" 4
|
||||
.IX Item "c99"
|
||||
.if n .Ip "\f(CW""""iso9899:199x""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:199x\fR" 4
|
||||
.ie n .IP """iso9899:199x""" 4
|
||||
.el .IP "\f(CWiso9899:199x\fR" 4
|
||||
.IX Item "iso9899:199x"
|
||||
.if n .Ip "\f(CW""""c9x""""\fR" 4
|
||||
.el .Ip "\f(CWc9x\fR" 4
|
||||
.ie n .IP """c9x""" 4
|
||||
.el .IP "\f(CWc9x\fR" 4
|
||||
.IX Item "c9x"
|
||||
.PD
|
||||
The revised \s-1ISO\s0 C standard, published in December 1999. Before
|
||||
publication, this was known as C9X.
|
||||
.if n .Ip "\f(CW""""gnu89""""\fR" 4
|
||||
.el .Ip "\f(CWgnu89\fR" 4
|
||||
.ie n .IP """gnu89""" 4
|
||||
.el .IP "\f(CWgnu89\fR" 4
|
||||
.IX Item "gnu89"
|
||||
The 1990 C standard plus \s-1GNU\s0 extensions. This is the default.
|
||||
.if n .Ip "\f(CW""""gnu99""""\fR" 4
|
||||
.el .Ip "\f(CWgnu99\fR" 4
|
||||
.ie n .IP """gnu99""" 4
|
||||
.el .IP "\f(CWgnu99\fR" 4
|
||||
.IX Item "gnu99"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""gnu9x""""\fR" 4
|
||||
.el .Ip "\f(CWgnu9x\fR" 4
|
||||
.ie n .IP """gnu9x""" 4
|
||||
.el .IP "\f(CWgnu9x\fR" 4
|
||||
.IX Item "gnu9x"
|
||||
.PD
|
||||
The 1999 C standard plus \s-1GNU\s0 extensions.
|
||||
.ie n .IP """c++98""" 4
|
||||
.el .IP "\f(CWc++98\fR" 4
|
||||
.IX Item "c++98"
|
||||
The 1998 \s-1ISO\s0 \*(C+ standard plus amendments.
|
||||
.ie n .IP """gnu++98""" 4
|
||||
.el .IP "\f(CWgnu++98\fR" 4
|
||||
.IX Item "gnu++98"
|
||||
The same as \fB\-std=c++98\fR plus \s-1GNU\s0 extensions. This is the
|
||||
default for \*(C+ code.
|
||||
.RE
|
||||
.RS 4
|
||||
.RE
|
||||
.Ip "\fB\-I-\fR" 4
|
||||
.IP "\fB\-I\-\fR" 4
|
||||
.IX Item "-I-"
|
||||
Split the include path. Any directories specified with \fB\-I\fR
|
||||
options before \fB\-I-\fR are searched only for headers requested with
|
||||
options before \fB\-I\-\fR are searched only for headers requested with
|
||||
\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for
|
||||
\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are
|
||||
specified with \fB\-I\fR options after the \fB\-I-\fR, those
|
||||
specified with \fB\-I\fR options after the \fB\-I\-\fR, those
|
||||
directories are searched for all \fB#include\fR directives.
|
||||
.Sp
|
||||
In addition, \fB\-I-\fR inhibits the use of the directory of the current
|
||||
In addition, \fB\-I\-\fR inhibits the use of the directory of the current
|
||||
file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR.
|
||||
.Ip "\fB\-nostdinc\fR" 4
|
||||
.IP "\fB\-nostdinc\fR" 4
|
||||
.IX Item "-nostdinc"
|
||||
Do not search the standard system directories for header files.
|
||||
Only the directories you have specified with \fB\-I\fR options
|
||||
(and the directory of the current file, if appropriate) are searched.
|
||||
.Ip "\fB\-nostdinc++\fR" 4
|
||||
.IP "\fB\-nostdinc++\fR" 4
|
||||
.IX Item "-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.)
|
||||
.Ip "\fB\-include\fR \fIfile\fR" 4
|
||||
.IP "\fB\-include\fR \fIfile\fR" 4
|
||||
.IX Item "-include file"
|
||||
Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first
|
||||
line of the primary source file. However, the first directory searched
|
||||
@ -542,7 +605,7 @@ chain as normal.
|
||||
.Sp
|
||||
If multiple \fB\-include\fR options are given, the files are included
|
||||
in the order they appear on the command line.
|
||||
.Ip "\fB\-imacros\fR \fIfile\fR" 4
|
||||
.IP "\fB\-imacros\fR \fIfile\fR" 4
|
||||
.IX Item "-imacros file"
|
||||
Exactly like \fB\-include\fR, except that any output produced by
|
||||
scanning \fIfile\fR is thrown away. Macros it defines remain defined.
|
||||
@ -551,35 +614,37 @@ processing its declarations.
|
||||
.Sp
|
||||
All files specified by \fB\-imacros\fR are processed before all files
|
||||
specified by \fB\-include\fR.
|
||||
.Ip "\fB\-idirafter\fR \fIdir\fR" 4
|
||||
.IP "\fB\-idirafter\fR \fIdir\fR" 4
|
||||
.IX Item "-idirafter dir"
|
||||
Search \fIdir\fR for header files, but do it \fIafter\fR all
|
||||
directories specified with \fB\-I\fR and the standard system directories
|
||||
have been exhausted. \fIdir\fR is treated as a system include directory.
|
||||
.Ip "\fB\-iprefix\fR \fIprefix\fR" 4
|
||||
.IP "\fB\-iprefix\fR \fIprefix\fR" 4
|
||||
.IX Item "-iprefix prefix"
|
||||
Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR
|
||||
options. If the prefix represents a directory, you should include the
|
||||
final \fB/\fR.
|
||||
.Ip "\fB\-iwithprefix\fR \fIdir\fR" 4
|
||||
.IP "\fB\-iwithprefix\fR \fIdir\fR" 4
|
||||
.IX Item "-iwithprefix dir"
|
||||
.PD 0
|
||||
.Ip "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
|
||||
.IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
|
||||
.IX Item "-iwithprefixbefore dir"
|
||||
.PD
|
||||
Append \fIdir\fR to the prefix specified previously with
|
||||
\&\fB\-iprefix\fR, and add the resulting directory to the include search
|
||||
path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR
|
||||
would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would.
|
||||
.Sp
|
||||
Use of these options is discouraged.
|
||||
.Ip "\fB\-isystem\fR \fIdir\fR" 4
|
||||
.IP "\fB\-isystem\fR \fIdir\fR" 4
|
||||
.IX Item "-isystem dir"
|
||||
Search \fIdir\fR for header files, after all directories specified by
|
||||
\&\fB\-I\fR 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.
|
||||
.Ip "\fB\-fpreprocessed\fR" 4
|
||||
.IP "\fB\-fdollars\-in\-identifiers\fR" 4
|
||||
.IX Item "-fdollars-in-identifiers"
|
||||
@anchor{fdollars\-in\-identifiers}
|
||||
Accept \fB$\fR in identifiers.
|
||||
.IP "\fB\-fpreprocessed\fR" 4
|
||||
.IX Item "-fpreprocessed"
|
||||
Indicate to the preprocessor that the input file has already been
|
||||
preprocessed. This suppresses things like macro expansion, trigraph
|
||||
@ -592,35 +657,65 @@ a tokenizer for the front ends.
|
||||
\&\fB\-fpreprocessed\fR is implicit if the input file has one of the
|
||||
extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the
|
||||
extensions that \s-1GCC\s0 uses for preprocessed files created by
|
||||
\&\fB\-save-temps\fR.
|
||||
.Ip "\fB\-ftabstop=\fR\fIwidth\fR" 4
|
||||
\&\fB\-save\-temps\fR.
|
||||
.IP "\fB\-ftabstop=\fR\fIwidth\fR" 4
|
||||
.IX Item "-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.
|
||||
.Ip "\fB\-fno-show-column\fR" 4
|
||||
.IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4
|
||||
.IX Item "-fexec-charset=charset"
|
||||
Set the execution character set, used for string and character
|
||||
constants. The default is \s-1UTF\-8\s0. \fIcharset\fR can be any encoding
|
||||
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
|
||||
.IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4
|
||||
.IX Item "-fwide-exec-charset=charset"
|
||||
Set the wide execution character set, used for wide string and
|
||||
character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16\s0, whichever
|
||||
corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with
|
||||
\&\fB\-ftarget\-charset\fR, \fIcharset\fR can be any encoding supported
|
||||
by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have
|
||||
problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR.
|
||||
.IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4
|
||||
.IX Item "-finput-charset=charset"
|
||||
Set the input character set, used for translation from the character
|
||||
set of the input file to the source character set used by \s-1GCC\s0. If the
|
||||
locale does not specify, or \s-1GCC\s0 cannot get this information from the
|
||||
locale, the default is \s-1UTF\-8\s0. 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. \fIcharset\fR can be any encoding
|
||||
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
|
||||
.IP "\fB\-fworking\-directory\fR" 4
|
||||
.IX Item "-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. \s-1GCC\s0 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 \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is
|
||||
present in the command line, this option has no effect, since no
|
||||
\&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever.
|
||||
.IP "\fB\-fno\-show\-column\fR" 4
|
||||
.IX Item "-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 \fBdejagnu\fR.
|
||||
.Ip "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IX Item "-A predicate=answer"
|
||||
Make an assertion with the predicate \fIpredicate\fR and answer
|
||||
\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR
|
||||
\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because
|
||||
it does not use shell special characters.
|
||||
.Ip "\fB\-A -\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IX Item "-A -predicate=answer"
|
||||
Cancel an assertion with the predicate \fIpredicate\fR and answer
|
||||
\&\fIanswer\fR.
|
||||
.Ip "\fB\-A-\fR" 4
|
||||
.IX Item "-A-"
|
||||
Cancel all predefined assertions and all assertions preceding it on
|
||||
the command line. Also, undefine all predefined macros and all
|
||||
macros preceding it on the command line. (This is a historical wart and
|
||||
may change in the future.)
|
||||
.Ip "\fB\-dCHARS\fR" 4
|
||||
.IP "\fB\-dCHARS\fR" 4
|
||||
.IX Item "-dCHARS"
|
||||
\&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters,
|
||||
and must not be preceded by a space. Other characters are interpreted
|
||||
@ -628,7 +723,7 @@ by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so
|
||||
are silently ignored. If you specify characters whose behavior
|
||||
conflicts, the result is undefined.
|
||||
.RS 4
|
||||
.Ip "\fBM\fR" 4
|
||||
.IP "\fBM\fR" 4
|
||||
.IX Item "M"
|
||||
Instead of the normal output, generate a list of \fB#define\fR
|
||||
directives for all the macros defined during the execution of the
|
||||
@ -639,30 +734,31 @@ Assuming you have no file \fIfoo.h\fR, the command
|
||||
.Vb 1
|
||||
\& touch foo.h; cpp -dM foo.h
|
||||
.Ve
|
||||
.Sp
|
||||
will show all the predefined macros.
|
||||
.Ip "\fBD\fR" 4
|
||||
.IP "\fBD\fR" 4
|
||||
.IX Item "D"
|
||||
Like \fBM\fR except in two respects: it does \fInot\fR include the
|
||||
predefined macros, and it outputs \fIboth\fR the \fB#define\fR
|
||||
directives and the result of preprocessing. Both kinds of output go to
|
||||
the standard output file.
|
||||
.Ip "\fBN\fR" 4
|
||||
.IP "\fBN\fR" 4
|
||||
.IX Item "N"
|
||||
Like \fBD\fR, but emit only the macro names, not their expansions.
|
||||
.Ip "\fBI\fR" 4
|
||||
.IP "\fBI\fR" 4
|
||||
.IX Item "I"
|
||||
Output \fB#include\fR directives in addition to the result of
|
||||
preprocessing.
|
||||
.RE
|
||||
.RS 4
|
||||
.RE
|
||||
.Ip "\fB\-P\fR" 4
|
||||
.IP "\fB\-P\fR" 4
|
||||
.IX Item "-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.
|
||||
.Ip "\fB\-C\fR" 4
|
||||
.IP "\fB\-C\fR" 4
|
||||
.IX Item "-C"
|
||||
Do not discard comments. All comments are passed through to the output
|
||||
file, except for comments in processed directives, which are deleted
|
||||
@ -673,52 +769,54 @@ 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 \fB#\fR.
|
||||
.Ip "\fB\-gcc\fR" 4
|
||||
.IX Item "-gcc"
|
||||
Define the macros _\|_GNUC_\|_, _\|_GNUC_MINOR_\|_ and
|
||||
_\|_GNUC_PATCHLEVEL_\|_. These are defined automatically when you use
|
||||
\&\fBgcc \-E\fR; you can turn them off in that case with
|
||||
\&\fB\-no-gcc\fR.
|
||||
.Ip "\fB\-traditional\fR" 4
|
||||
.IX Item "-traditional"
|
||||
Try to imitate the behavior of old-fashioned C, as opposed to \s-1ISO\s0
|
||||
C.
|
||||
.Ip "\fB\-trigraphs\fR" 4
|
||||
.IP "\fB\-CC\fR" 4
|
||||
.IX Item "-CC"
|
||||
Do not discard comments, including during macro expansion. This is
|
||||
like \fB\-C\fR, except that comments contained within macros are
|
||||
also passed through to the output file where the macro is expanded.
|
||||
.Sp
|
||||
In addition to the side-effects of the \fB\-C\fR option, the
|
||||
\&\fB\-CC\fR 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.
|
||||
.Sp
|
||||
The \fB\-CC\fR option is generally used to support lint comments.
|
||||
.IP "\fB\-traditional\-cpp\fR" 4
|
||||
.IX Item "-traditional-cpp"
|
||||
Try to imitate the behavior of old-fashioned C preprocessors, as
|
||||
opposed to \s-1ISO\s0 C preprocessors.
|
||||
.IP "\fB\-trigraphs\fR" 4
|
||||
.IX Item "-trigraphs"
|
||||
Process trigraph sequences.
|
||||
.Ip "\fB\-remap\fR" 4
|
||||
.IP "\fB\-remap\fR" 4
|
||||
.IX Item "-remap"
|
||||
Enable special code to work around file systems which only permit very
|
||||
short file names, such as \s-1MS-DOS\s0.
|
||||
.Ip "\fB\-$\fR" 4
|
||||
.IX Item "-$"
|
||||
Forbid the use of \fB$\fR in identifiers. The C standard allows
|
||||
implementations to define extra characters that can appear in
|
||||
identifiers. By default \s-1GNU\s0 \s-1CPP\s0 permits \fB$\fR, a common extension.
|
||||
.Ip "\fB\-h\fR" 4
|
||||
.IX Item "-h"
|
||||
short file names, such as \s-1MS\-DOS\s0.
|
||||
.IP "\fB\-\-help\fR" 4
|
||||
.IX Item "--help"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--help\fR" 4
|
||||
.IX Item "help"
|
||||
.Ip "\fB\*(--target-help\fR" 4
|
||||
.IX Item "target-help"
|
||||
.IP "\fB\-\-target\-help\fR" 4
|
||||
.IX Item "--target-help"
|
||||
.PD
|
||||
Print text describing all the command line options instead of
|
||||
preprocessing anything.
|
||||
.Ip "\fB\-v\fR" 4
|
||||
.IP "\fB\-v\fR" 4
|
||||
.IX Item "-v"
|
||||
Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of
|
||||
execution, and report the final form of the include path.
|
||||
.Ip "\fB\-H\fR" 4
|
||||
.IP "\fB\-H\fR" 4
|
||||
.IX Item "-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
|
||||
\&\fB#include\fR stack it is.
|
||||
.Ip "\fB\-version\fR" 4
|
||||
\&\fB#include\fR 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 \fB...x\fR and a valid one with \fB...!\fR .
|
||||
.IP "\fB\-version\fR" 4
|
||||
.IX Item "-version"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--version\fR" 4
|
||||
.IX Item "version"
|
||||
.IP "\fB\-\-version\fR" 4
|
||||
.IX Item "--version"
|
||||
.PD
|
||||
Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to
|
||||
preprocess as normal. With two dashes, exit immediately.
|
||||
@ -733,25 +831,25 @@ Note that you can also specify places to search using options such as
|
||||
\&\fB\-M\fR. These take precedence over
|
||||
environment variables, which in turn take precedence over the
|
||||
configuration of \s-1GCC\s0.
|
||||
.Ip "\fB\s-1CPATH\s0\fR" 4
|
||||
.IP "\fB\s-1CPATH\s0\fR" 4
|
||||
.IX Item "CPATH"
|
||||
.PD 0
|
||||
.Ip "\fBC_INCLUDE_PATH\fR" 4
|
||||
.IP "\fBC_INCLUDE_PATH\fR" 4
|
||||
.IX Item "C_INCLUDE_PATH"
|
||||
.Ip "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4
|
||||
.IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4
|
||||
.IX Item "CPLUS_INCLUDE_PATH"
|
||||
.Ip "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4
|
||||
.IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4
|
||||
.IX Item "OBJC_INCLUDE_PATH"
|
||||
.PD
|
||||
Each variable's value is a list of directories separated by a special
|
||||
character, much like \fB\s-1PATH\s0\fR, in which to look for header files.
|
||||
The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and
|
||||
determined at \s-1GCC\s0 build time. For Windows-based targets it is a
|
||||
determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a
|
||||
semicolon, and for almost all other targets it is a colon.
|
||||
.Sp
|
||||
\&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if
|
||||
specified with \fB\-I\fR, but after any paths given with \fB\-I\fR
|
||||
options on the command line. The environment variable is used
|
||||
options on the command line. This environment variable is used
|
||||
regardless of which language is being preprocessed.
|
||||
.Sp
|
||||
The remaining environment variables apply only when preprocessing the
|
||||
@ -759,10 +857,13 @@ particular language indicated. Each specifies a list of directories
|
||||
to be searched as if specified with \fB\-isystem\fR, but after any
|
||||
paths given with \fB\-isystem\fR options on the command line.
|
||||
.Sp
|
||||
See also \f(CW@ref\fR{Search Path}.
|
||||
.Ip "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4
|
||||
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
|
||||
\&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same
|
||||
effect as \fB\-I.\ \-I/special/include\fR.
|
||||
.IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4
|
||||
.IX Item "DEPENDENCIES_OUTPUT"
|
||||
@anchor{\s-1DEPENDENCIES_OUTPUT\s0}
|
||||
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
|
||||
@ -777,22 +878,21 @@ file \fIfile\fR using \fItarget\fR as the target name.
|
||||
In other words, this environment variable is equivalent to combining
|
||||
the options \fB\-MM\fR and \fB\-MF\fR,
|
||||
with an optional \fB\-MT\fR switch too.
|
||||
.Ip "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4
|
||||
.IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4
|
||||
.IX Item "SUNPRO_DEPENDENCIES"
|
||||
This variable is the same as the environment variable
|
||||
\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR, except that
|
||||
system header files are not ignored, so it implies \fB\-M\fR rather
|
||||
than \fB\-MM\fR. However, the dependence on the main input file is
|
||||
omitted.
|
||||
This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above),
|
||||
except that system header files are not ignored, so it implies
|
||||
\&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the
|
||||
main input file is omitted.
|
||||
.SH "SEE ALSO"
|
||||
.IX Header "SEE ALSO"
|
||||
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf-funding\fR\|(7),
|
||||
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7),
|
||||
\&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and
|
||||
\&\fIbinutils\fR.
|
||||
.SH "COPYRIGHT"
|
||||
.IX Header "COPYRIGHT"
|
||||
Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
|
||||
1997, 1998, 1999, 2000, 2001
|
||||
1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
|
||||
Free Software Foundation, Inc.
|
||||
.PP
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
@ -808,6 +908,7 @@ This manual contains no Invariant Sections. The Front-Cover Texts are
|
||||
.Vb 1
|
||||
\& A GNU Manual
|
||||
.Ve
|
||||
.PP
|
||||
(b) The \s-1FSF\s0's Back-Cover Text is:
|
||||
.PP
|
||||
.Vb 3
|
||||
|
File diff suppressed because it is too large
Load Diff
@ -1,8 +1,7 @@
|
||||
.\" Automatically generated by Pod::Man version 1.15
|
||||
.\" Wed Feb 5 03:13:55 2003
|
||||
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ======================================================================
|
||||
.\" ========================================================================
|
||||
.de Sh \" Subsection heading
|
||||
.br
|
||||
.if t .Sp
|
||||
@ -15,12 +14,6 @@
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Ip \" List item
|
||||
.br
|
||||
.ie \\n(.$>=3 .ne \\$3
|
||||
.el .ne 3
|
||||
.IP "\\$1" \\$2
|
||||
..
|
||||
.de Vb \" Begin verbatim text
|
||||
.ft CW
|
||||
.nf
|
||||
@ -28,15 +21,14 @@
|
||||
..
|
||||
.de Ve \" End verbatim text
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.\" Set up some character translations and predefined strings. \*(-- will
|
||||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||||
.\" double quote, and \*(R" will give a right double quote. | will give a
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
||||
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
||||
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
|
||||
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
|
||||
.\" expand to `' in nroff, nothing in troff, for use with C<>.
|
||||
.tr \(*W-|\(bv\*(Tr
|
||||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||||
.ie n \{\
|
||||
@ -56,10 +48,10 @@
|
||||
. ds R" ''
|
||||
'br\}
|
||||
.\"
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr
|
||||
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
||||
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
||||
.\" the output yourself in some meaningful fashion.
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||||
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
|
||||
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||||
.\" output yourself in some meaningful fashion.
|
||||
.if \nF \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
@ -68,14 +60,13 @@
|
||||
. rr F
|
||||
.\}
|
||||
.\"
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
||||
.\" makes way too many mistakes in technical documents.
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||||
.\" way too many mistakes in technical documents.
|
||||
.hy 0
|
||||
.if n .na
|
||||
.\"
|
||||
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||||
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||||
.bd B 3
|
||||
. \" fudge factors for nroff and troff
|
||||
.if n \{\
|
||||
. ds #H 0
|
||||
@ -135,38 +126,43 @@
|
||||
. ds Ae AE
|
||||
.\}
|
||||
.rm #[ #] #H #V #F C
|
||||
.\" ======================================================================
|
||||
.\" ========================================================================
|
||||
.\"
|
||||
.IX Title "GCOV 1"
|
||||
.TH GCOV 1 "gcc-3.2.2" "2003-02-05" "GNU"
|
||||
.UC
|
||||
.TH GCOV 1 "2006-03-06" "gcc-3.4.6" "GNU"
|
||||
.SH "NAME"
|
||||
gcov \- coverage testing tool
|
||||
.SH "SYNOPSIS"
|
||||
.IX Header "SYNOPSIS"
|
||||
gcov [\fB\-v\fR|\fB\*(--version\fR] [\fB\-h\fR|\fB\*(--help\fR]
|
||||
[\fB\-b\fR|\fB\*(--branch-probabilities\fR] [\fB\-c\fR|\fB\*(--branch-counts\fR]
|
||||
[\fB\-n\fR|\fB\*(--no-output\fR] [\fB\-l\fR|\fB\*(--long-file-names\fR]
|
||||
[\fB\-f\fR|\fB\*(--function-summaries\fR]
|
||||
[\fB\-o\fR|\fB\*(--object-directory\fR \fIdirectory\fR] \fIsourcefile\fR
|
||||
gcov [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR]
|
||||
[\fB\-a\fR|\fB\-\-all\-blocks\fR]
|
||||
[\fB\-b\fR|\fB\-\-branch\-probabilities\fR]
|
||||
[\fB\-c\fR|\fB\-\-branch\-counts\fR]
|
||||
[\fB\-n\fR|\fB\-\-no\-output\fR]
|
||||
[\fB\-l\fR|\fB\-\-long\-file\-names\fR]
|
||||
[\fB\-p\fR|\fB\-\-preserve\-paths\fR]
|
||||
[\fB\-f\fR|\fB\-\-function\-summaries\fR]
|
||||
[\fB\-o\fR|\fB\-\-object\-directory\fR \fIdirectory|file\fR] \fIsourcefile\fR
|
||||
[\fB\-u\fR|\fB\-\-unconditional\-branches\fR]
|
||||
.SH "DESCRIPTION"
|
||||
.IX Header "DESCRIPTION"
|
||||
\&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0
|
||||
to analyze your programs to help create more efficient, faster
|
||||
running code. You can use \fBgcov\fR as a profiling tool to help
|
||||
discover where your optimization efforts will best affect your code. You
|
||||
can also use \fBgcov\fR along with the other profiling tool,
|
||||
\&\fBgprof\fR, to assess which parts of your code use the greatest amount
|
||||
of computing time.
|
||||
to analyze your programs to help create more efficient, faster running
|
||||
code and to discover untested parts of your program. You can use
|
||||
\&\fBgcov\fR as a profiling tool to help discover where your
|
||||
optimization efforts will best affect your code. You can also use
|
||||
\&\fBgcov\fR along with the other profiling tool, \fBgprof\fR, to
|
||||
assess which parts of your code use the greatest amount of computing
|
||||
time.
|
||||
.PP
|
||||
Profiling tools help you analyze your code's performance. Using a
|
||||
profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some
|
||||
basic performance statistics, such as:
|
||||
.Ip "\(bu" 4
|
||||
.IP "\(bu" 4
|
||||
how often each line of code executes
|
||||
.Ip "\(bu" 4
|
||||
.IP "\(bu" 4
|
||||
what lines of code are actually executed
|
||||
.Ip "\(bu" 4
|
||||
.IP "\(bu" 4
|
||||
how much computing time each section of code uses
|
||||
.PP
|
||||
Once you know these things about how your code works when compiled, you
|
||||
@ -204,84 +200,153 @@ timing information you can use along with the information you get from
|
||||
compatible with any other profiling or test coverage mechanism.
|
||||
.SH "OPTIONS"
|
||||
.IX Header "OPTIONS"
|
||||
.Ip "\fB\-h\fR" 4
|
||||
.IP "\fB\-h\fR" 4
|
||||
.IX Item "-h"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--help\fR" 4
|
||||
.IX Item "help"
|
||||
.IP "\fB\-\-help\fR" 4
|
||||
.IX Item "--help"
|
||||
.PD
|
||||
Display help about using \fBgcov\fR (on the standard output), and
|
||||
exit without doing any further processing.
|
||||
.Ip "\fB\-v\fR" 4
|
||||
.IP "\fB\-v\fR" 4
|
||||
.IX Item "-v"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--version\fR" 4
|
||||
.IX Item "version"
|
||||
.IP "\fB\-\-version\fR" 4
|
||||
.IX Item "--version"
|
||||
.PD
|
||||
Display the \fBgcov\fR version number (on the standard output),
|
||||
and exit without doing any further processing.
|
||||
.Ip "\fB\-b\fR" 4
|
||||
.IP "\fB\-a\fR" 4
|
||||
.IX Item "-a"
|
||||
.PD 0
|
||||
.IP "\fB\-\-all\-blocks\fR" 4
|
||||
.IX Item "--all-blocks"
|
||||
.PD
|
||||
Write individual execution counts for every basic block. Normally gcov
|
||||
outputs execution counts only for the main blocks of a line. With this
|
||||
option you can determine if blocks within a single line are not being
|
||||
executed.
|
||||
.IP "\fB\-b\fR" 4
|
||||
.IX Item "-b"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--branch-probabilities\fR" 4
|
||||
.IX Item "branch-probabilities"
|
||||
.IP "\fB\-\-branch\-probabilities\fR" 4
|
||||
.IX Item "--branch-probabilities"
|
||||
.PD
|
||||
Write branch frequencies to the output file, and write branch summary
|
||||
info to the standard output. This option allows you to see how often
|
||||
each branch in your program was taken.
|
||||
.Ip "\fB\-c\fR" 4
|
||||
each branch in your program was taken. Unconditional branches will not
|
||||
be shown, unless the \fB\-u\fR option is given.
|
||||
.IP "\fB\-c\fR" 4
|
||||
.IX Item "-c"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--branch-counts\fR" 4
|
||||
.IX Item "branch-counts"
|
||||
.IP "\fB\-\-branch\-counts\fR" 4
|
||||
.IX Item "--branch-counts"
|
||||
.PD
|
||||
Write branch frequencies as the number of branches taken, rather than
|
||||
the percentage of branches taken.
|
||||
.Ip "\fB\-n\fR" 4
|
||||
.IP "\fB\-n\fR" 4
|
||||
.IX Item "-n"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--no-output\fR" 4
|
||||
.IX Item "no-output"
|
||||
.IP "\fB\-\-no\-output\fR" 4
|
||||
.IX Item "--no-output"
|
||||
.PD
|
||||
Do not create the \fBgcov\fR output file.
|
||||
.Ip "\fB\-l\fR" 4
|
||||
.IP "\fB\-l\fR" 4
|
||||
.IX Item "-l"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--long-file-names\fR" 4
|
||||
.IX Item "long-file-names"
|
||||
.IP "\fB\-\-long\-file\-names\fR" 4
|
||||
.IX Item "--long-file-names"
|
||||
.PD
|
||||
Create long file names for included source files. For example, if the
|
||||
header file \fIx.h\fR contains code, and was included in the file
|
||||
\&\fIa.c\fR, then running \fBgcov\fR on the file \fIa.c\fR will produce
|
||||
an output file called \fIa.c.x.h.gcov\fR instead of \fIx.h.gcov\fR.
|
||||
This can be useful if \fIx.h\fR is included in multiple source files.
|
||||
.Ip "\fB\-f\fR" 4
|
||||
an output file called \fIa.c##x.h.gcov\fR instead of \fIx.h.gcov\fR.
|
||||
This can be useful if \fIx.h\fR is included in multiple source
|
||||
files. If you uses the \fB\-p\fR option, both the including and
|
||||
included file names will be complete path names.
|
||||
.IP "\fB\-p\fR" 4
|
||||
.IX Item "-p"
|
||||
.PD 0
|
||||
.IP "\fB\-\-preserve\-paths\fR" 4
|
||||
.IX Item "--preserve-paths"
|
||||
.PD
|
||||
Preserve complete path information in the names of generated
|
||||
\&\fI.gcov\fR files. Without this option, just the filename component is
|
||||
used. With this option, all directories are used, with '/' characters
|
||||
translated to '#' characters, '.' directory components removed and '..'
|
||||
components renamed to '^'. This is useful if sourcefiles are in several
|
||||
different directories. It also affects the \fB\-l\fR option.
|
||||
.IP "\fB\-f\fR" 4
|
||||
.IX Item "-f"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--function-summaries\fR" 4
|
||||
.IX Item "function-summaries"
|
||||
.IP "\fB\-\-function\-summaries\fR" 4
|
||||
.IX Item "--function-summaries"
|
||||
.PD
|
||||
Output summaries for each function in addition to the file level summary.
|
||||
.Ip "\fB\-o\fR \fIdirectory\fR" 4
|
||||
.IX Item "-o directory"
|
||||
.IP "\fB\-o\fR \fIdirectory|file\fR" 4
|
||||
.IX Item "-o directory|file"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--object-directory\fR \fIdirectory\fR" 4
|
||||
.IX Item "object-directory directory"
|
||||
.IP "\fB\-\-object\-directory\fR \fIdirectory\fR" 4
|
||||
.IX Item "--object-directory directory"
|
||||
.IP "\fB\-\-object\-file\fR \fIfile\fR" 4
|
||||
.IX Item "--object-file file"
|
||||
.PD
|
||||
The directory where the object files live. Gcov will search for \fI.bb\fR,
|
||||
\&\fI.bbg\fR, and \fI.da\fR files in this directory.
|
||||
Specify either the directory containing the gcov data files, or the
|
||||
object path name. The \fI.gcno\fR, and
|
||||
\&\fI.gcda\fR data files are searched for using this option. If a directory
|
||||
is specified, the data files are in that directory and named after the
|
||||
source file name, without its extension. If a file is specified here,
|
||||
the data files are named after that file, without its extension. If this
|
||||
option is not supplied, it defaults to the current directory.
|
||||
.IP "\fB\-u\fR" 4
|
||||
.IX Item "-u"
|
||||
.PD 0
|
||||
.IP "\fB\-\-unconditional\-branches\fR" 4
|
||||
.IX Item "--unconditional-branches"
|
||||
.PD
|
||||
When branch counts are given, include those of unconditional branches.
|
||||
Unconditional branches are normally not interesting.
|
||||
.PP
|
||||
\&\fBgcov\fR should be run with the current directory the same as that
|
||||
when you invoked the compiler. Otherwise it will not be able to locate
|
||||
the source files. \fBgcov\fR produces files called
|
||||
\&\fI\fImangledname\fI.gcov\fR in the current directory. These contain
|
||||
the coverage information of the source file they correspond to.
|
||||
One \fI.gcov\fR file is produced for each source file containing code,
|
||||
which was compiled to produce the data files. The \fImangledname\fR part
|
||||
of the output file name is usually simply the source file name, but can
|
||||
be something more complicated if the \fB\-l\fR or \fB\-p\fR options are
|
||||
given. Refer to those options for details.
|
||||
.PP
|
||||
The \fI.gcov\fR files contain the ':' separated fields along with
|
||||
program source code. The format is
|
||||
.PP
|
||||
.Vb 1
|
||||
\& <execution_count>:<line_number>:<source line text>
|
||||
.Ve
|
||||
.PP
|
||||
Additional block information may succeed each line, when requested by
|
||||
command line option. The \fIexecution_count\fR is \fB\-\fR for lines
|
||||
containing no code and \fB#####\fR for lines which were never
|
||||
executed. Some lines of information at the start have \fIline_number\fR
|
||||
of zero.
|
||||
.PP
|
||||
When printing percentages, 0% and 100% are only printed when the values
|
||||
are \fIexactly\fR 0% and 100% respectively. Other values which would
|
||||
conventionally be rounded to 0% or 100% are instead printed as the
|
||||
nearest non-boundary value.
|
||||
.PP
|
||||
When using \fBgcov\fR, you must first compile your program with two
|
||||
special \s-1GCC\s0 options: \fB\-fprofile-arcs \-ftest-coverage\fR.
|
||||
special \s-1GCC\s0 options: \fB\-fprofile\-arcs \-ftest\-coverage\fR.
|
||||
This tells the compiler to generate additional information needed by
|
||||
gcov (basically a flow graph of the program) and also includes
|
||||
additional code in the object files for generating the extra profiling
|
||||
information needed by gcov. These additional files are placed in the
|
||||
directory where the source code is located.
|
||||
directory where the object file is located.
|
||||
.PP
|
||||
Running the program will cause profile output to be generated. For each
|
||||
source file compiled with \fB\-fprofile-arcs\fR, an accompanying \fI.da\fR
|
||||
file will be placed in the source directory.
|
||||
source file compiled with \fB\-fprofile\-arcs\fR, an accompanying
|
||||
\&\fI.gcda\fR file will be placed in the object file directory.
|
||||
.PP
|
||||
Running \fBgcov\fR with your program's source file names as arguments
|
||||
will now produce a listing of the code along with frequency of execution
|
||||
@ -292,69 +357,133 @@ is what you see when you use the basic \fBgcov\fR facility:
|
||||
\& $ gcc -fprofile-arcs -ftest-coverage tmp.c
|
||||
\& $ a.out
|
||||
\& $ gcov tmp.c
|
||||
\& 87.50% of 8 source lines executed in file tmp.c
|
||||
\& 90.00% of 10 source lines executed in file tmp.c
|
||||
\& Creating tmp.c.gcov.
|
||||
.Ve
|
||||
.PP
|
||||
The file \fItmp.c.gcov\fR contains output from \fBgcov\fR.
|
||||
Here is a sample:
|
||||
.PP
|
||||
.Vb 3
|
||||
\& main()
|
||||
\& {
|
||||
\& 1 int i, total;
|
||||
.Vb 23
|
||||
\& -: 0:Source:tmp.c
|
||||
\& -: 0:Graph:tmp.gcno
|
||||
\& -: 0:Data:tmp.gcda
|
||||
\& -: 0:Runs:1
|
||||
\& -: 0:Programs:1
|
||||
\& -: 1:#include <stdio.h>
|
||||
\& -: 2:
|
||||
\& -: 3:int main (void)
|
||||
\& function main called 1 returned 1 blocks executed 75%
|
||||
\& 1: 4:{
|
||||
\& 1: 5: int i, total;
|
||||
\& -: 6:
|
||||
\& 1: 7: total = 0;
|
||||
\& -: 8:
|
||||
\& 11: 9: for (i = 0; i < 10; i++)
|
||||
\& 10: 10: total += i;
|
||||
\& -: 11:
|
||||
\& 1: 12: if (total != 45)
|
||||
\& #####: 13: printf ("Failure\en");
|
||||
\& -: 14: else
|
||||
\& 1: 15: printf ("Success\en");
|
||||
\& 1: 16: return 0;
|
||||
\& -: 17:}
|
||||
.Ve
|
||||
.Vb 1
|
||||
\& 1 total = 0;
|
||||
.Ve
|
||||
.Vb 2
|
||||
\& 11 for (i = 0; i < 10; i++)
|
||||
\& 10 total += i;
|
||||
.Ve
|
||||
.Vb 5
|
||||
\& 1 if (total != 45)
|
||||
\& ###### printf ("Failure\en");
|
||||
\& else
|
||||
\& 1 printf ("Success\en");
|
||||
\& 1 }
|
||||
.PP
|
||||
When you use the \fB\-a\fR option, you will get individual block
|
||||
counts, and the output looks like this:
|
||||
.PP
|
||||
.Vb 30
|
||||
\& -: 0:Source:tmp.c
|
||||
\& -: 0:Graph:tmp.gcno
|
||||
\& -: 0:Data:tmp.gcda
|
||||
\& -: 0:Runs:1
|
||||
\& -: 0:Programs:1
|
||||
\& -: 1:#include <stdio.h>
|
||||
\& -: 2:
|
||||
\& -: 3:int main (void)
|
||||
\& function main called 1 returned 1 blocks executed 75%
|
||||
\& 1: 4:{
|
||||
\& 1: 4-block 0
|
||||
\& 1: 5: int i, total;
|
||||
\& -: 6:
|
||||
\& 1: 7: total = 0;
|
||||
\& -: 8:
|
||||
\& 11: 9: for (i = 0; i < 10; i++)
|
||||
\& 11: 9-block 0
|
||||
\& 10: 10: total += i;
|
||||
\& 10: 10-block 0
|
||||
\& -: 11:
|
||||
\& 1: 12: if (total != 45)
|
||||
\& 1: 12-block 0
|
||||
\& #####: 13: printf ("Failure\en");
|
||||
\& $$$$$: 13-block 0
|
||||
\& -: 14: else
|
||||
\& 1: 15: printf ("Success\en");
|
||||
\& 1: 15-block 0
|
||||
\& 1: 16: return 0;
|
||||
\& 1: 16-block 0
|
||||
\& -: 17:}
|
||||
.Ve
|
||||
.PP
|
||||
In this mode, each basic block is only shown on one line \*(-- the last
|
||||
line of the block. A multi-line block will only contribute to the
|
||||
execution count of that last line, and other lines will not be shown
|
||||
to contain code, unless previous blocks end on those lines.
|
||||
The total execution count of a line is shown and subsequent lines show
|
||||
the execution counts for individual blocks that end on that line. After each
|
||||
block, the branch and call counts of the block will be shown, if the
|
||||
\&\fB\-b\fR option is given.
|
||||
.PP
|
||||
Because of the way \s-1GCC\s0 instruments calls, a call count can be shown
|
||||
after a line with no individual blocks.
|
||||
As you can see, line 13 contains a basic block that was not executed.
|
||||
.PP
|
||||
When you use the \fB\-b\fR option, your output looks like this:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& $ gcov -b tmp.c
|
||||
\& 87.50% of 8 source lines executed in file tmp.c
|
||||
\& 80.00% of 5 branches executed in file tmp.c
|
||||
\& 80.00% of 5 branches taken at least once in file tmp.c
|
||||
\& 50.00% of 2 calls executed in file tmp.c
|
||||
\& 90.00% of 10 source lines executed in file tmp.c
|
||||
\& 80.00% of 5 branches executed in file tmp.c
|
||||
\& 80.00% of 5 branches taken at least once in file tmp.c
|
||||
\& 50.00% of 2 calls executed in file tmp.c
|
||||
\& Creating tmp.c.gcov.
|
||||
.Ve
|
||||
.PP
|
||||
Here is a sample of a resulting \fItmp.c.gcov\fR file:
|
||||
.PP
|
||||
.Vb 3
|
||||
\& main()
|
||||
\& {
|
||||
\& 1 int i, total;
|
||||
.Ve
|
||||
.Vb 1
|
||||
\& 1 total = 0;
|
||||
.Ve
|
||||
.Vb 5
|
||||
\& 11 for (i = 0; i < 10; i++)
|
||||
\& branch 0 taken = 91%
|
||||
\& branch 1 taken = 100%
|
||||
\& branch 2 taken = 100%
|
||||
\& 10 total += i;
|
||||
.Ve
|
||||
.Vb 9
|
||||
\& 1 if (total != 45)
|
||||
\& branch 0 taken = 100%
|
||||
\& ###### printf ("Failure\en");
|
||||
\& call 0 never executed
|
||||
\& branch 1 never executed
|
||||
\& else
|
||||
\& 1 printf ("Success\en");
|
||||
\& call 0 returns = 100%
|
||||
\& 1 }
|
||||
.Vb 29
|
||||
\& -: 0:Source:tmp.c
|
||||
\& -: 0:Graph:tmp.gcno
|
||||
\& -: 0:Data:tmp.gcda
|
||||
\& -: 0:Runs:1
|
||||
\& -: 0:Programs:1
|
||||
\& -: 1:#include <stdio.h>
|
||||
\& -: 2:
|
||||
\& -: 3:int main (void)
|
||||
\& function main called 1 returned 1 blocks executed 75%
|
||||
\& 1: 4:{
|
||||
\& 1: 5: int i, total;
|
||||
\& -: 6:
|
||||
\& 1: 7: total = 0;
|
||||
\& -: 8:
|
||||
\& 11: 9: for (i = 0; i < 10; i++)
|
||||
\& branch 0 taken 91% (fallthrough)
|
||||
\& branch 1 taken 9%
|
||||
\& 10: 10: total += i;
|
||||
\& -: 11:
|
||||
\& 1: 12: if (total != 45)
|
||||
\& branch 0 taken 0% (fallthrough)
|
||||
\& branch 1 taken 100%
|
||||
\& #####: 13: printf ("Failure\en");
|
||||
\& call 0 never executed
|
||||
\& -: 14: else
|
||||
\& 1: 15: printf ("Success\en");
|
||||
\& call 0 called 1 returned 100%
|
||||
\& 1: 16: return 0;
|
||||
\& -: 17:}
|
||||
.Ve
|
||||
.PP
|
||||
For each basic block, a line is printed after the last line of the basic
|
||||
block describing the branch or call that ends the basic block. There can
|
||||
be multiple branches and calls listed for a single source line if there
|
||||
@ -376,25 +505,25 @@ of times the call was executed will be printed. This will usually be
|
||||
and thus may not return every time they are called.
|
||||
.PP
|
||||
The execution counts are cumulative. If the example program were
|
||||
executed again without removing the \fI.da\fR file, the count for the
|
||||
executed again without removing the \fI.gcda\fR file, the count for the
|
||||
number of times each line in the source was executed would be added to
|
||||
the results of the previous \fIrun\fR\|(s). This is potentially useful in
|
||||
the results of the previous run(s). This is potentially useful in
|
||||
several ways. For example, it could be used to accumulate data over a
|
||||
number of program runs as part of a test verification suite, or to
|
||||
provide more accurate long-term information over a large number of
|
||||
program runs.
|
||||
.PP
|
||||
The data in the \fI.da\fR files is saved immediately before the program
|
||||
exits. For each source file compiled with \fB\-fprofile-arcs\fR, the profiling
|
||||
code first attempts to read in an existing \fI.da\fR file; if the file
|
||||
doesn't match the executable (differing number of basic block counts) it
|
||||
will ignore the contents of the file. It then adds in the new execution
|
||||
counts and finally writes the data to the file.
|
||||
The data in the \fI.gcda\fR files is saved immediately before the program
|
||||
exits. For each source file compiled with \fB\-fprofile\-arcs\fR, the
|
||||
profiling code first attempts to read in an existing \fI.gcda\fR file; if
|
||||
the file doesn't match the executable (differing number of basic block
|
||||
counts) it will ignore the contents of the file. It then adds in the
|
||||
new execution counts and finally writes the data to the file.
|
||||
.Sh "Using \fBgcov\fP with \s-1GCC\s0 Optimization"
|
||||
.IX Subsection "Using gcov with GCC Optimization"
|
||||
If you plan to use \fBgcov\fR to help optimize your code, you must
|
||||
first compile your program with two special \s-1GCC\s0 options:
|
||||
\&\fB\-fprofile-arcs \-ftest-coverage\fR. Aside from that, you can use any
|
||||
\&\fB\-fprofile\-arcs \-ftest\-coverage\fR. Aside from that, you can use any
|
||||
other \s-1GCC\s0 options; but if you want to prove that every single line
|
||||
in your program was executed, you should not compile with optimization
|
||||
at the same time. On some machines the optimizer can eliminate some
|
||||
@ -407,6 +536,7 @@ like this:
|
||||
\& else
|
||||
\& c = 0;
|
||||
.Ve
|
||||
.PP
|
||||
can be compiled into one instruction on some machines. In this case,
|
||||
there is no way for \fBgcov\fR to calculate separate execution counts
|
||||
for each line because there isn't separate code for each line. Hence
|
||||
@ -414,25 +544,48 @@ the \fBgcov\fR output looks like this if you compiled the program with
|
||||
optimization:
|
||||
.PP
|
||||
.Vb 4
|
||||
\& 100 if (a != b)
|
||||
\& 100 c = 1;
|
||||
\& 100 else
|
||||
\& 100 c = 0;
|
||||
\& 100: 12:if (a != b)
|
||||
\& 100: 13: c = 1;
|
||||
\& 100: 14:else
|
||||
\& 100: 15: c = 0;
|
||||
.Ve
|
||||
.PP
|
||||
The output shows that this block of code, combined by optimization,
|
||||
executed 100 times. In one sense this result is correct, because there
|
||||
was only one instruction representing all four of these lines. However,
|
||||
the output does not indicate how many times the result was 0 and how
|
||||
many times the result was 1.
|
||||
.PP
|
||||
Inlineable functions can create unexpected line counts. Line counts are
|
||||
shown for the source code of the inlineable function, but what is shown
|
||||
depends on where the function is inlined, or if it is not inlined at all.
|
||||
.PP
|
||||
If the function is not inlined, the compiler must emit an out of line
|
||||
copy of the function, in any object file that needs it. If
|
||||
\&\fIfileA.o\fR and \fIfileB.o\fR both contain out of line bodies of a
|
||||
particular inlineable function, they will also both contain coverage
|
||||
counts for that function. When \fIfileA.o\fR and \fIfileB.o\fR are
|
||||
linked together, the linker will, on many systems, select one of those
|
||||
out of line bodies for all calls to that function, and remove or ignore
|
||||
the other. Unfortunately, it will not remove the coverage counters for
|
||||
the unused function body. Hence when instrumented, all but one use of
|
||||
that function will show zero counts.
|
||||
.PP
|
||||
If the function is inlined in several places, the block structure in
|
||||
each location might not be the same. For instance, a condition might
|
||||
now be calculable at compile time in some instances. Because the
|
||||
coverage of all the uses of the inline function will be shown for the
|
||||
same source lines, the line counts themselves might seem inconsistent.
|
||||
.SH "SEE ALSO"
|
||||
.IX Header "SEE ALSO"
|
||||
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR.
|
||||
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR.
|
||||
.SH "COPYRIGHT"
|
||||
.IX Header "COPYRIGHT"
|
||||
Copyright (c) 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc.
|
||||
Copyright (c) 1996, 1997, 1999, 2000, 2001, 2002, 2003
|
||||
Free Software Foundation, Inc.
|
||||
.PP
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or
|
||||
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2 or
|
||||
any later version published by the Free Software Foundation; with the
|
||||
Invariant Sections being ``\s-1GNU\s0 General Public License'' and ``Funding
|
||||
Free Software'', the Front-Cover texts being (a) (see below), and with
|
||||
@ -444,6 +597,7 @@ included in the \fIgfdl\fR\|(7) man page.
|
||||
.Vb 1
|
||||
\& A GNU Manual
|
||||
.Ve
|
||||
.PP
|
||||
(b) The \s-1FSF\s0's Back-Cover Text is:
|
||||
.PP
|
||||
.Vb 3
|
||||
|
Loading…
Reference in New Issue
Block a user