a few missing man pages converted from info documents; work done by jmc

2 files changed, 481 insertions, 2 deletions

diff --git a/gnu/egcs/gcc/Makefile.bsd-wrapper b/gnu/egcs/gcc/Makefile.bsd-wrapper
index b3532b539cc..d59da274d7e 100644
--- a/gnu/egcs/gcc/Makefile.bsd-wrapper
+++ b/gnu/egcs/gcc/Makefile.bsd-wrapper
@@ -1,6 +1,6 @@
-#	$OpenBSD: Makefile.bsd-wrapper,v 1.13 2003/02/16 17:07:22 deraadt Exp $
+#	$OpenBSD: Makefile.bsd-wrapper,v 1.14 2003/02/16 18:28:40 deraadt Exp $
 
-MAN=		cccp.1 gcc.1 gcc-local.1 protoize.1
+MAN=		cccp.1 gcc.1 gcc-local.1 protoize.1 gcov.1
 MLINKS+=	gcc.1 cc.1
 MLINKS+=	cccp.1 cpp.1
 MLINKS+=	protoize.1 unprotoize.1
diff --git a/gnu/egcs/gcc/gcov.1 b/gnu/egcs/gcc/gcov.1
new file mode 100644
index 00000000000..8bf5a2072cc
--- /dev/null
+++ b/gnu/egcs/gcc/gcov.1
@@ -0,0 +1,479 @@
+.\" 
+.\"    Published by the Free Software Foundation 59 Temple Place - Suite 330
+.\" Boston, MA 02111-1307 USA
+.\" 
+.\"    Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+.\" 1999, 2000 Free Software Foundation, Inc.
+.\" 
+.\"    Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\" 
+.\"    Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided also
+.\" that the sections entitled "GNU General Public License" and "Funding
+.\" for Free Software" are included exactly as in the original, and
+.\" provided that the entire resulting derived work is distributed under
+.\" the terms of a permission notice identical to this one.
+.\" 
+.\"    Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for modified
+.\" versions, except that the sections entitled "GNU General Public
+.\" License" and "Funding for Free Software", and this permission notice,
+.\" may be included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.\"
+.Dd February 15, 2003
+.Dt GCOV 1
+.Os
+.Sh NAME
+.Nm gcov
+.Nd test coverage program
+.Sh SYNOPSIS
+.Nm
+.Op Fl b
+.Op Fl v
+.Op Fl n
+.Op Fl l
+.Op Fl f
+.Op Fl o Ar directory
+.Ar sourcefile
+.Sh DESCRIPTION
+The
+.Nm
+utility is a test coverage program.
+Use it in concert with
+.Xr gcc 1
+to analyze programs to help create more efficient, faster running
+code.
+.Nm
+can be used as a profiling tool to help discover where optimization efforts
+will best affect the code.
+.Nm
+can also be used along with the other profiling tool
+.Xr gprof 1 ,
+to assess which parts of the code use the greatest amount of computing time.
+.Pp
+Profiling tools help analyze the code's performance.
+Using a profiler such as
+.Nm gcov
+or
+.Xr gprof 1 ,
+basic performance statistics can be obtained, such as:
+.Pp
+.Bl -bullet -compact
+.It
+how often each line of code executes
+.It
+what lines of code are actually executed
+.It
+how much computing time each section of code uses
+.El
+.Pp
+Once you know these things about how your code works when compiled,
+you can look at each module to see which modules should be optimized.
+.Nm
+helps determine where to work on optimization.
+.Pp
+Software developers also use coverage testing in concert with
+testsuites, to make sure software is actually good enough for a release.
+Testsuites can verify that a program works as expected;
+a coverage program tests to see how much of the program is exercised by the
+testsuite.
+Developers can then determine what kinds of test cases need
+to be added to the testsuites to create both better testing and a better
+final product.
+.Pp
+Code should be compiled without optimization when using
+.Nm
+because the optimization, by combining some lines of code into
+one function,
+may not give as much information as necesary to look
+for `hot spots' where the code is using a great deal of computer time.
+Likewise, because
+.Nm
+accumulates statistics by line (at the lowest resolution),
+it works best with a programming style that places only
+one statement on each line.
+If complicated macros that expand to loops or to other control structures
+are used, the statistics are less helpful - they only report on the line
+where the macro call appears.
+If complex macros behave like functions, they can be replaced  with
+inline functions to solve this problem.
+.Pp
+.Nm
+creates a logfile called
+.Sq Ar sourcefile Ns Li .gcov
+which indicates how many times each line of a source file
+.Sq Ar sourcefile Ns Li \&.c
+has executed.
+These logfiles can then be used along with
+.Xr gprof 1
+to aid in fine-tuning the performance of the programs.
+.Xr gprof 1
+gives timing information which can be used along with the information you
+obtained from
+.Nm gcov .
+.Pp
+.Nm
+works only on code compiled with GNU CC.
+It is not compatible with any other profiling or test coverage mechanism.
+.Pp
+.Nm
+accepts the following options:
+.Pp
+.Bl -tag -width Ds
+.It Fl b
+Write branch frequencies to the output file, and write branch
+summary info to the standard output.
+This option indicates how often each branch in the program was taken.
+.It Fl v
+Display the
+.Nm
+version number (on the standard error stream).
+.It Fl n
+Do not create the
+.Nm
+output file.
+.It Fl l
+Create long file names for included source files.
+For example, if the header file
+.Pa x.h
+contains code, and was included in the file
+.Pa a.c ,
+then running
+.Nm
+on the file
+.Pa a.c
+will produce an output file called
+.Pa a.c.x.h.gcov
+instead of
+.Pa x.h.gcov .
+This can be useful if
+.Pa x.h
+is included in multiple source files.
+.It Fl f
+Output summaries for each function in addition to the file level summary.
+.It Fl o Ar directory
+The directory where the object files live.
+.Nm
+will search for
+.Pa .bb , .bbg ,
+and
+.Pa .da
+files in this directory.
+.El
+.Pp
+When using
+.Nm gcov ,
+programs must first be compiled with two special GNU CC options:
+.Fl fprofile-arcs ftest-coverage .
+This tells the compiler to generate additional information needed by
+.Nm
+(basically a flow graph of the program)
+and also includes additional code in the object files for generating the
+extra profiling information needed by
+.Nm gcov .
+These additional files are placed in the directory where the source code
+is located.
+.Pp
+Running the program will cause profile output to be generated.
+For each source file compiled with
+.Fl fprofile-arcs ,
+an accompanying
+.Pa .da
+file will be placed in the source directory.
+.Pp
+Running
+.Nm
+with the program's source file names as arguments
+will now produce a listing of the code along with frequency of execution
+for each line.
+For example, if the program is called
+.Pa tmp.c ,
+this is what is displayed when using the basic
+.Nm
+facility:
+.Pp
+     $ gcc -fprofile-arcs -ftest-coverage tmp.c
+     $ a.out
+     $ gcov tmp.c
+      87.50% of 8 source lines executed in file tmp.c
+     Creating tmp.c.gcov.
+.Pp
+The file
+.Pa tmp.c.gcov
+contains output from
+.Nm gcov .
+Here is a sample:
+.Pp
+                     main()
+                     {
+                1      int i, total;
+     
+                1      total = 0;
+     
+               11      for (i = 0; i < 10; i++)
+               10        total += i;
+     
+                1      if (total != 45)
+           ######        printf ("Failure\\n");
+                       else
+                1        printf ("Success\\n");
+                1    }
+.Pp
+When the
+.Fl b
+option is used, output looks like this:
+.Pp
+     $ 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
+     Creating tmp.c.gcov.
+.Pp
+Here is a sample of a resulting
+.Pa tmp.c.gcov
+file:
+.Pp
+                     main()
+                     {
+                1      int i, total;
+     
+                1      total = 0;
+     
+               11      for (i = 0; i < 10; i++)
+     branch 0 taken = 91%
+     branch 1 taken = 100%
+     branch 2 taken = 100%
+               10        total += i;
+     
+                1      if (total != 45)
+     branch 0 taken = 100%
+           ######        printf ("Failure\\n");
+     call 0 never executed
+     branch 1 never executed
+                       else
+                1        printf ("Success\\n");
+     call 0 returns = 100%
+                1    }
+.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 are multiple basic blocks that end on that line.
+In this case, the branches and calls are each given a number.
+There is no simple way to map these branches and calls back to source
+constructs.
+In general, though, the lowest numbered branch or call will correspond
+to the leftmost construct on the source line.
+.Pp
+For a branch, if it was executed at least once, then a percentage
+indicating the number of times the branch was taken divided by the
+number of times the branch was executed will be printed.
+Otherwise, the message "never executed" is printed.
+.Pp
+For a call, if it was executed at least once, then a percentage
+indicating the number of times the call returned divided by the number
+of times the call was executed will be printed.
+This will usually be 100%,
+but may be less for functions which call `exit' or `longjmp',
+and thus may not return everytime they are called.
+.Pp
+The execution counts are cumulative.
+If the example program were executed again without removing the
+.Pa .da
+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 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
+.Pa .da
+files is saved immediately before the program exits.
+For each source file compiled with
+.Fl fprofile-arcs ,
+the profiling code first attempts to read in an existing
+.Pa .da
+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.
+.Pp
+.Sh USING GCOV WITH GCC OPTIMIZATION
+.Pp
+If
+.Nm
+is to be used to help optimize code,
+programs must be compiled with two special GNU CC options:
+.Fl fprofile-arcs ftest-coverage .
+Aside from that, any other GNU CC options can be used;
+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 simple
+code lines by combining them with other lines.
+For example, code like this:
+.Pp
+     if (a != b)
+       c = 1;
+     else
+       c = 0;
+.Pp
+can be compiled into one instruction on some machines.
+In this case, there is no way for
+.Nm
+to calculate separate execution counts for each line because there
+isn't separate code for each line.
+Hence the
+.Nm
+output looks like this if the program is compiled with optimization:
+.Pp
+           100  if (a != b)
+           100    c = 1;
+           100  else
+           100    c = 0;
+.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
+.Sh BRIEF DESCRIPTION OF GCOV DATA FILES
+.Pp
+.Nm
+uses three files for doing profiling.
+The names of these files are derived from the original _source_ file
+by substituting the file suffix with either
+.Pa .bb , .bbg ,
+or
+.Pa .da .
+All of these files are placed in the same directory as the source file,
+and contain data stored in a platform-independent method.
+.Pp
+The
+.Pa .bb
+and
+.Pa .bbg
+files are generated when the source file is compiled with the GNU CC
+.Fl ftest-coverage
+option.
+The
+.Pa .bb
+file contains a list of source files (including headers),
+functions within those files,
+and line numbers corresponding to each basic block in the source file.
+.Pp
+The
+.Pa .bb
+file format consists of several lists of 4-byte integers
+which correspond to the line numbers of each basic block in the file.
+Each list is terminated by a line number of 0.
+A line number of -1 is used to designate that the source file name
+(padded to a 4-byte boundary and followed by another -1) follows.
+In addition, a line number of -2 is used to designate that the name of a
+function (also padded to a 4-byte boundary and followed by a -2) follows.
+.Pp
+The
+.Pa .bbg
+file is used to reconstruct the program flow graph for the source file.
+It contains a list of the program flow arcs
+(possible branches taken from one basic block to another)
+for each function which,
+in combination with the
+.Pa .bb
+file,
+enables
+.Nm
+to reconstruct the program flow.
+.Pp
+In the
+.Pa .bbg
+file, the format is:
+.Pp
+	number of basic blocks for function #0 (4-byte number)
+.br
+	total number of arcs for function #0 (4-byte number)
+.br	
+	count of arcs in basic block #0 (4-byte number)
+.br	
+	destination basic block of arc #0 (4-byte number)
+.br	
+	flag bits (4-byte number)
+.br	
+	destination basic block of arc #1 (4-byte number)
+.br	
+	flag bits (4-byte number)
+.br	
+	...
+.br	
+	destination basic block of arc #N (4-byte number)
+.br	
+	flag bits (4-byte number)
+.br	
+	count of arcs in basic block #1 (4-byte number)
+.br	
+	destination basic block of arc #0 (4-byte number)
+.br	
+	flag bits (4-byte number)
+.br	
+	...
+.Pp
+A -1 (stored as a 4-byte number) is used to separate each function's
+list of basic blocks, and to verify that the file has been read
+correctly.
+.Pp
+The
+.Pa .da
+file is generated when a program containing object files
+built with the GNU CC
+.Fl fprofile-arcs
+option is executed.
+A separate
+.Pa .da
+file is created for each source file compiled with this option,
+and the name of the
+.Pa .da
+file is stored as an absolute pathname in the resulting object file.
+This path name is derived from the source file name by substituting a
+.Pa .da
+suffix.
+.Pp
+The format of the
+.Pa .da
+file is fairly simple.
+The first 8-byte number is the number of counts in the file,
+followed by the counts
+(stored as 8-byte numbers).
+Each count corresponds to the number of
+times each arc in the program is executed.
+The counts are cumulative;
+each time the program is executed, it attemps to combine the existing
+.Pa .da
+files with the new counts for this invocation of the program.
+It ignores the contents of any
+.Pa .da
+files whose number of arcs doesn't
+correspond to the current program,
+and merely overwrites them instead.
+.Pp
+All three of these files use the functions in
+.Pa gcov-io.h
+to store integers;
+the functions in this header provide a machine-independent
+mechanism for storing and retrieving data from a stream.
+.Sh SEE ALSO
+.Xr gcc 1
+.Xr gprof 1
+.Sh HISTORY
+This man page describes version 1.5 of
+.Nm gcov .