lcov-1.7 into third_party for code coverage on POSIX systems....

third_party/lcov/man/geninfo.1

Index: third_party/lcov/man/geninfo.1
===================================================================
--- third_party/lcov/man/geninfo.1	(revision 0)
+++ third_party/lcov/man/geninfo.1	(revision 0)
@@ -0,0 +1,323 @@
+.TH geninfo 1 "LCOV 1.7" 2008\-11\-17 "User Manuals"
+.SH NAME
+geninfo \- Generate tracefiles from .da files
+.SH SYNOPSIS
+.B geninfo
+.RB [ \-h | \-\-help ]
+.RB [ \-v | \-\-version ]
+.RB [ \-q | \-\-quiet ]
+.br
+.RS 8
+.RB [ \-i | \-\-initial ]
+.RB [ \-t | \-\-test\-name
+.IR test\-name ]
+.br
+.RB [ \-o | \-\-output\-filename
+.IR filename ]
+.RB [ \-f | \-\-follow ]
+.br
+.RB [ \-b | \-\-base\-directory
+.IR directory ]
+.br
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.br
+.RB [ \-\-compat\-libtool ]
+.RB [ \-\-no\-compat\-libtool ]
+.br
+.RB [ \-\-gcov\-tool
+.IR tool  ]
+.RB [ \-\-ignore\-errors
+.IR errors  ]
+.br
+.RB [ \-\-no\-recursion ]
+.I directory
+.RE
+.SH DESCRIPTION
+.B geninfo 
+converts all GCOV coverage data files found in 
+.I directory
+into tracefiles, which the
+.B genhtml
+tool can convert to HTML output.
+
+Unless the \-\-output\-filename option is specified,
+.B geninfo
+writes its
+output to one file per .da file, the name of which is generated by simply
+appending ".info" to the respective .da file name.
+
+Note that the current user needs write access to both
+.I directory
+as well as to the original source code location. This is necessary because
+some temporary files have to be created there during the conversion process.
+
+Note also that
+.B geninfo
+is called from within
+.BR lcov ,
+so that there is usually no need to call it directly.
+.SH OPTIONS
+
+.B \-b
+.I directory
+.br
+.B \-\-base\-directory
+.I directory
+.br
+.RS
+.RI "Use " directory
+as base directory for relative paths.
+
+Use this option to specify the base directory of a build\-environment
+when geninfo produces error messages like:
+
+.RS
+ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
+.RE
+
+In this example, use /home/user/project as base directory.
+
+This option is required when using geninfo on projects built with libtool or
+similar build environments that work with a base directory, i.e. environments,
+where the current working directory when invoking the compiler is not the same
+directory in which the source code file is located.
+
+Note that this option will not work in environments where multiple base
+directories are used. In that case repeat the geninfo call for each base
+directory while using the \-\-ignore\-errors option to prevent geninfo from
+exiting when the first source code file could not be found. This way you can
+get partial coverage information for each base directory which can then be
+combined using the \-a option.
+.RE
+
+.B \-\-checksum
+.br
+.B \-\-no\-checksum
+.br
+.RS
+Specify whether to generate checksum data when writing tracefiles.
+
+Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
+disable it. Checksum generation is
+.B disabled
+by default.
+
+When checksum generation is enabled, a checksum will be generated for each
+source code line and stored along with the coverage data. This checksum will
+be used to prevent attempts to combine coverage data from different source
+code versions.
+
+If you don't work with different source code versions, disable this option
+to speed up coverage data processing and to reduce the size of tracefiles.
+.RE
+
+.B \-\-compat\-libtool
+.br
+.B \-\-no\-compat\-libtool
+.br
+.RS
+Specify whether to enable libtool compatibility mode.
+
+Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
+to disable it. The libtool compatibility mode is
+.B enabled
+by default.
+
+When libtool compatibility mode is enabled, geninfo will assume that the source
+code relating to a .da file located in a directory named ".libs" can be
+found in its parent directory.
+
+If you have directories named ".libs" in your build environment but don't use
+libtool, disable this option to prevent problems when capturing coverage data.
+.RE
+
+.B \-f
+.br
+.B \-\-follow
+.RS
+Follow links when searching .da files.
+.RE
+
+.B \-\-gcov\-tool
+.I tool
+.br
+.RS
+Specify the location of the gcov tool.
+.RE
+
+.B \-h
+.br
+.B \-\-help
+.RS
+Print a short help text, then exit.
+.RE
+
+.B \-\-ignore\-errors
+.I errors
+.br
+.RS
+Specify a list of errors after which to continue processing.
+
+Use this option to specify a list of one or more classes of errors after which
+geninfo should continue processing instead of aborting.
+
+.I errors
+can be a comma\-separated list of the following keywords:
+
+.B gcov:
+the gcov tool returned with a non\-zero return code.
+
+.B source:
+the source code file for a data set could not be found.
+.RE
+
+.B \-i
+.br
+.B \-\-initial
+.RS
+Capture initial zero coverage data.
+
+Run geninfo with this option on the directories containing .bb, .bbg or .gcno
+files before running any test case. The result is a "baseline" coverage data
+file that contains zero coverage for every instrumented line. Combine this
+data file (using lcov \-a) with coverage data files captured after a test
+run to ensure that the percentage of total lines covered is correct even
+when not all source code files were loaded during the test.
+.RE
+
+.B \-\-no\-recursion
+.br
+.RS
+Use this option if you want to get coverage data for the specified directory
+only without processing subdirectories.
+.RE
+
+.BI "\-o " output\-filename
+.br
+.BI "\-\-output\-filename " output\-filename
+.RS
+Write all data to
+.IR output\-filename .
+
+If you want to have all data written to a single file (for easier
+handling), use this option to specify the respective filename. By default,
+one tracefile will be created for each processed .da file.
+.RE
+
+.B \-q
+.br
+.B \-\-quiet
+.RS
+Do not print progress messages.
+
+Suppresses all informational progress output. When this switch is enabled,
+only error or warning messages are printed.
+.RE
+
+.BI "\-t " testname
+.br
+.BI "\-\-test\-name " testname
+.RS
+Use test case name 
+.I testname
+for resulting data. Valid test case names can consist of letters, decimal
+digits and the underscore character ('_').
+
+This proves useful when data from several test cases is merged (i.e. by
+simply concatenating the respective tracefiles) in which case a test
+name can be used to differentiate between data from each test case.
+.RE
+
+.B \-v
+.br
+.B \-\-version
+.RS
+Print version number, then exit.
+.RE
+
+
+.SH FILES
+
+.I /etc/lcovrc
+.RS
+The system\-wide configuration file.
+.RE
+
+.I ~/.lcovrc
+.RS
+The per\-user configuration file.
+.RE
+
+Following is a quick description of the tracefile format as used by
+.BR genhtml ", " geninfo " and " lcov .
+
+A tracefile is made up of several human\-readable lines of text,
+divided into sections. If available, a tracefile begins with the
+.I testname
+which is stored in the following format:
+
+  TN:<test name>
+
+For each source file referenced in the .da file, there is a section containing
+filename and coverage data:
+
+  SF:<absolute path to the source file>
+
+Following is a list of line numbers for each function name found in the
+source file:
+
+  FN:<line number of function start>,<function name>
+
+Next, there is a list of execution counts for each instrumented function:
+
+  FNDA:<execution count>,<function name>
+
+This list is followed by two lines containing the number of functions found
+and hit:
+
+  FNF:<number of functions found>
+  FNH:<number of function hit>
+
+Then there is a list of execution counts for each instrumented line
+(i.e. a line which resulted in executable code):
+
+  DA:<line number>,<execution count>[,<checksum>]
+
+Note that there may be an optional checksum present for each instrumented
+line. The current
+.B geninfo
+implementation uses an MD5 hash as checksumming algorithm.
+
+At the end of a section, there is a summary about how many lines
+were found and how many were actually instrumented:
+
+  LH:<number of lines with a non\-zero execution count>
+  LF:<number of instrumented lines>
+
+Each sections ends with:
+
+  end_of_record
+
+In addition to the main source code file there are sections for all
+#included files which also contain executable code.
+
+Note that the absolute path of a source file is generated by interpreting
+the contents of the respective .bb file (see
+.BR "gcov " (1)
+for more information on this file type). Relative filenames are prefixed
+with the directory in which the .bb file is found.
+
+Note also that symbolic links to the .bb file will be resolved so that the
+actual file path is used instead of the path to a link. This approach is
+necessary for the mechanism to work with the /proc/gcov files.
+
+.SH AUTHOR
+Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
+
+.SH SEE ALSO
+.BR lcov (1),
+.BR genhtml (1),
+.BR genpng (1),
+.BR gendesc (1),
+.BR gcov (1)