From d8a2c2edb938d0f89b2e377247296403e11051a5 Mon Sep 17 00:00:00 2001 From: dbj Date: Mon, 2 Aug 2004 17:39:51 +0000 Subject: [PATCH] fix merge botch. gcov.1 now describes gcc-3.3.3 instead of gcc-3.3.2 --- gnu/dist/gcc/gcc/doc/gcov.1 | 136 ++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 67 deletions(-) diff --git a/gnu/dist/gcc/gcc/doc/gcov.1 b/gnu/dist/gcc/gcc/doc/gcov.1 index 792405f54c0c..440b9416cf74 100644 --- a/gnu/dist/gcc/gcc/doc/gcov.1 +++ b/gnu/dist/gcc/gcc/doc/gcov.1 @@ -1,7 +1,8 @@ -.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 +.\" Automatically generated by Pod::Man version 1.15 +.\" Sat Feb 14 20:38:10 2004 .\" .\" Standard preamble: -.\" ======================================================================== +.\" ====================================================================== .de Sh \" Subsection heading .br .if t .Sp @@ -14,6 +15,12 @@ .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 @@ -21,14 +28,15 @@ .. .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 \{\ @@ -48,10 +56,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" @@ -60,13 +68,14 @@ . 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 @@ -126,22 +135,23 @@ . ds Ae AE .\} .rm #[ #] #H #V #F C -.\" ======================================================================== +.\" ====================================================================== .\" .IX Title "GCOV 1" -.TH GCOV 1 "2003-10-16" "gcc-3.3.2" "GNU" +.TH GCOV 1 "gcc-3.3.3" "2004-02-14" "GNU" +.UC .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\-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 +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\-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 .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0 @@ -156,11 +166,11 @@ time. 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 @@ -198,62 +208,62 @@ 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\-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 +.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\-p\fR" 4 +.Ip "\fB\-p\fR" 4 .IX Item "-p" .PD 0 -.IP "\fB\-\-preserve\-paths\fR" 4 -.IX Item "--preserve-paths" +.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 @@ -261,20 +271,20 @@ 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 +.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|file\fR" 4 +.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\-file\fR \fIfile\fR" 4 -.IX Item "--object-file file" +.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 Specify either the directory containing the gcov data files, or the object path name. The \fI.bb\fR, \fI.bbg\fR, and @@ -297,9 +307,8 @@ format is .Vb 1 \& :: .Ve -.PP Additional block information may succeed each line, when requested by -command line option. The \fIexecution_count\fR is \fB\-\fR for lines +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. @@ -310,7 +319,7 @@ 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 @@ -318,7 +327,7 @@ information needed by gcov. These additional files are placed in the 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 +source file compiled with \fB\-fprofile-arcs\fR, an accompanying \fI.da\fR file will be placed in the object file directory. .PP Running \fBgcov\fR with your program's source file names as arguments @@ -333,7 +342,6 @@ is what you see when you use the basic \fBgcov\fR facility: \& 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 @@ -358,7 +366,6 @@ Here is a sample: \& 1: 16: return 0; \& 1: 17:} .Ve -.PP When you use the \fB\-b\fR option, your output looks like this: .PP .Vb 6 @@ -369,7 +376,6 @@ When you use the \fB\-b\fR option, your output looks like this: \& 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 26 @@ -400,7 +406,6 @@ Here is a sample of a resulting \fItmp.c.gcov\fR file: \& 1: 16: return 0; \& 1: 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 @@ -424,14 +429,14 @@ and thus may not return every time they are called. The execution counts are cumulative. If the example program were executed again without removing the \fI.da\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 run(s). This is potentially useful in +the results of the previous \fIrun\fR\|(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 +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 @@ -440,7 +445,7 @@ new execution counts and finally writes the data to the file. .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 @@ -453,7 +458,6 @@ 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 @@ -466,7 +470,6 @@ optimization: \& 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, @@ -492,7 +495,6 @@ the Back-Cover Texts being (b) (see below). .Vb 1 \& A GNU Manual .Ve -.PP (b) The \s-1FSF\s0's Back-Cover Text is: .PP .Vb 3