Upgrades lcov to 1.10, removes lcov-1.9

third_party/lcov/man/lcov.1

-.TH lcov 1 "LCOV 1.7" 2008\-11\-17 "User Manuals"
+.TH lcov 1 "LCOV 1.10" 2012\-10\-10 "User Manuals"
 .SH NAME
 lcov \- a graphical GCOV front\-end
 .SH SYNOPSIS
 .B lcov
-.RB [ \-h | \-\-help ]
-.RB [ \-v | \-\-version ]
-.RB [ \-q | \-\-quiet ]
+.BR \-c | \-\-capture
 .RS 5
 .br
-.RB [ \-z | \-\-zerocounters ]
-.RB [ \-c | \-\-capture ]
+.RB [ \-d | \-\-directory
+.IR directory ]
+.RB [ \-k | \-\-kernel\-directory
+.IR directory ]
 .br
-.RB [ \-a | \-\-add\-tracefile
+.RB [ \-o | \-\-output\-file
 .IR tracefile ]
-.br
-.RB [ \-e | \-\-extract
-.IR tracefile ]
-.br
-.RB [ \-r | \-\-remove
-.IR tracefile ]
-.br
-.RB [ \-l | \-\-list
-.IR tracefile ]
-.br
-.RB [ \-\-diff
-.IR "tracefile diff" ]
-.br
-.RB [ \-i | \-\-initial ]
 .RB [ \-t | \-\-test\-name
 .IR testname ]
 .br
-.RB [ \-o | \-\-output\-file
-.IR filename ]
+.RB [ \-b | \-\-base\-directory
+.IR directory ]
+.RB [ \-i | \-\-initial ]
+.RB [ \-\-gcov\-tool
+.IR tool ]
+.br
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.RB [ \-\-no\-recursion ]
+.RB [ \-f | \-\-follow ]
+.br
+.RB [ \-\-compat\-libtool ]
+.RB [ \-\-no\-compat\-libtool ]
+.RB [ \-\-ignore\-errors
+.IR errors ]
+.br
+.RB [ \-\-to\-package
+.IR package ]
+.RB [ \-\-from\-package
+.IR package ]
+.RB [ \-q | \-\-quiet ]
+.br
+.RB [ \-\-no\-markers ]
+.RB [ \-\-external ]
+.RB [ \-\-no\-external ]
+.br
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
+.br
+.RB [ \-\-compat
+.IR  mode =on|off|auto]
+.br
+.RE
+
+.B lcov
+.BR \-z | \-\-zerocounters
+.RS 5
 .br
 .RB [ \-d | \-\-directory
 .IR directory ]
-.br
+.RB [ \-\-no\-recursion ]
 .RB [ \-f | \-\-follow ]
 .br
-.RB [ \-k | \-\-kernel\-directory
-.IR directory ]
+.RB [ \-q | \-\-quiet ]
 .br
-.RB [ \-b | \-\-base\-directory
-.IR directory ]
+.RE
+
+.B lcov
+.BR \-l | \-\-list
+.I tracefile
+.RS 5
+.br
+.RB [ \-q | \-\-quiet ]
+.RB [ \-\-list\-full\-path ]
+.RB [ \-\-no\-list\-full\-path ]
+.br
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
+.br
+.RE
+
+.B lcov
+.BR \-a | \-\-add\-tracefile
+.I tracefile
+.RS 5
+.br
+.RB [ \-o | \-\-output\-file
+.IR tracefile ]
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.br
+.RB [ \-q | \-\-quiet ]
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
+.br
+.RE
+
+.B lcov
+.BR \-e | \-\-extract
+.I tracefile pattern
+.RS 5
+.br
+.RB [ \-o | \-\-output\-file
+.IR tracefile ]
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.br
+.RB [ \-q | \-\-quiet ]
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
+.br
+.RE
+
+.B lcov
+.BR \-r | \-\-remove
+.I tracefile pattern
+.RS 5
+.br
+.RB [ \-o | \-\-output\-file
+.IR tracefile ]
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.br
+.RB [ \-q | \-\-quiet ]
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
+.br
+.RE
+
+.B lcov
+.BR \-\-diff
+.IR "tracefile diff"
+.RS 5
+.br
+.RB [ \-o | \-\-output\-file
+.IR tracefile ]
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
 .br
 .RB [ \-\-convert\-filenames ]
 .RB [ \-\-strip
 .IR depth ]
 .RB [ \-\-path
 .IR path ]
+.RB [ \-q | \-\-quiet ]
 .br
-.RB [ \-\-checksum ]
-.RB [ \-\-no\-checksum ]
+.RB [ \-\-config\-file
+.IR config\-file ]
+.RB [ \-\-rc
+.IR keyword = value ]
 .br
-.RB [ \-\-compat\-libtool ]
-.RB [ \-\-no\-compat\-libtool ]
+.RE
+
+.B lcov
+.BR \-\-summary
+.I tracefile
+.RS 5
 .br
-.RB [ \-\-gcov\-tool
-.IR tool ]
-.RB [ \-\-ignore\-errors
-.IR errors ]
+.RB [ \-q | \-\-quiet ]
 .br
-.RB [ \-\-no\-recursion ]
+.RE
+
+.B lcov
+.RB [ \-h | \-\-help ]
+.RB [ \-v | \-\-version ]
+.RS 5
+.br
+.RE
+
 .SH DESCRIPTION
 .B lcov
 is a graphical front\-end for GCC's coverage testing tool gcov. It collects
-gcov data for multiple source files and creates HTML pages containing the
-source code annotated with coverage information. It also adds overview pages
-for easy navigation within the file structure.
+line, function and branch coverage data for multiple source files and creates
+HTML pages containing the source code annotated with coverage information.
+It also adds overview pages for easy navigation within the file structure.
 
 Use
 .B lcov
 to collect coverage data and
 .B genhtml
 to create HTML pages. Coverage data can either be collected from the
 currently running Linux kernel or from a user space application. To do this,
 you have to complete the following preparation steps:
 
 For Linux kernel coverage:
 .RS
-Follow the installation instructions for the gcov\-kernel patch:
+Follow the setup instructions for the gcov\-kernel infrastructure:
 .I http://ltp.sourceforge.net/coverage/gcov.php
+.br
+
 
 .RE
 For user space application coverage:
 .RS
 Compile the application with GCC using the options
 "\-fprofile\-arcs" and "\-ftest\-coverage".
 .RE
 
 Please note that this man page refers to the output format of
 .B lcov
 as ".info file" or "tracefile" and that the output of GCOV
 is called ".da file".
+
+Also note that when printing percentages, 0% and 100% are only printed when
+the values are exactly 0% and 100% respectively. Other values which would
+conventionally be rounded to 0% or 100% are instead printed as nearest
+non-boundary value. This behavior is in accordance with that of the
+.BR gcov (1)
+tool.
+
 .SH OPTIONS
 
 
 .B \-a
 .I tracefile
 .br
 .B \-\-add\-tracefile
 .I tracefile
 .br
 .RS
 Add contents of
 .IR tracefile .
 
 Specify several tracefiles using the \-a switch to combine the coverage data
 contained in these files by adding up execution counts for matching test and
 filename combinations.
 
 The result of the add operation will be written to stdout or the tracefile
 specified with \-o.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 
 .RE
 
 .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 lcov 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 lcov 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 lcov call for each base directory
-while using the \-\-ignore\-errors option to prevent lcov 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.
+directories are used. In that case use configuration file setting
+.B geninfo_auto_base=1
+(see
+.BR lcovrc (5)).
 .RE
 
 .B \-c
 .br
 .B \-\-capture
 .br
 .RS
 Capture coverage data.
 
 By default captures the current kernel execution counts and writes the
 resulting coverage data to the standard output. Use the \-\-directory
 option to capture counts for a user space program.
 
 The result of the capture operation will be written to stdout or the tracefile
 specified with \-o.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 .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
+.IR mode = value [, mode = value ,...]
+.br
+.RS
+Set compatibility mode.
+
+Use \-\-compat to specify that lcov should enable one or more compatibility
+modes when capturing coverage data. You can provide a comma-separated list
+of mode=value pairs to specify the values for multiple modes.
+
+Valid
+.I values
+are:
+
+.B on
+.RS
+Enable compatibility mode.
+.RE
+.B off
+.RS
+Disable compatibility mode.
+.RE
+.B auto
+.RS
+Apply auto-detection to determine if compatibility mode is required. Note that
+auto-detection is not available for all compatibility modes.
+.RE
+
+If no value is specified, 'on' is assumed as default value.
+
+Valid
+.I modes
+are:
+
+.B libtool
+.RS
+Enable this mode if you are capturing coverage data for a project that
+was built using the libtool mechanism. See also
+\-\-compat\-libtool.
+
+The default value for this setting is 'on'.
+
+.RE
+.B hammer
+.RS
+Enable this mode if you are capturing coverage data for a project that
+was built using a version of GCC 3.3 that contains a modification
+(hammer patch) of later GCC versions. You can identify a modified GCC 3.3
+by checking the build directory of your project for files ending in the
+extension '.bbg'. Unmodified versions of GCC 3.3 name these files '.bb'.
+
+The default value for this setting is 'auto'.
+
+.RE
+.B split_crc
+.RS
+Enable this mode if you are capturing coverage data for a project that
+was built using a version of GCC 4.6 that contains a modification
+(split function checksums) of later GCC versions. Typical error messages
+when running lcov on coverage data produced by such GCC versions are
+\'out of memory' and 'reached unexpected end of file'.
+
+The default value for this setting is 'auto'
+.RE
+
+.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, lcov 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 \-\-config\-file
+.I config\-file
+.br
+.RS
+Specify a configuration file to use.
+
+When this option is specified, neither the system\-wide configuration file
+/etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.
+
+This option may be useful when there is a need to run several
+instances of
+.B lcov
+with different configuration file options in parallel.
+.RE
+
 .B \-\-convert\-filenames
 .br
 .RS
 Convert filenames when applying diff.
 
 Use this option together with \-\-diff to rename the file names of processed
 data sets according to the data provided by the diff.
 .RE
 
 .B \-\-diff
@@ skipping 21 matching lines @@
 Note that lines which are not present in the old version will not be counted
 as instrumented, therefore tracefiles resulting from this operation should
 not be interpreted individually but together with other tracefiles taken
 from the newer version. Also keep in mind that converted coverage data should
 only be used for overview purposes as the process itself introduces a loss
 of accuracy.
 
 The result of the diff operation will be written to stdout or the tracefile
 specified with \-o.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 .RE
 
 .B \-d
 .I directory
 .br
 .B \-\-directory
 .I  directory
 .br
 .RS
 Use .da files in
 .I directory
 instead of kernel.
 
 If you want to work on coverage data for a user space program, use this
 option to specify the location where the program was compiled (that's
 where the counter files ending with .da will be stored).
 
 Note that you may specify this option more than once.
 .RE
 
+.B \-\-external
+.br
+.B \-\-no\-external
+.br
+.RS
+Specify whether to capture coverage data for external source files.
+
+External source files are files which are not located in one of the directories
+specified by \-\-directory or \-\-base\-directory. Use \-\-external to include
+external source files while capturing coverage data or \-\-no\-external to
+ignore this data.
+
+Data for external source files is
+.B included
+by default.
+.RE
+
 .B \-e
 .I tracefile
 .I pattern
 .br
 .B \-\-extract
 .I tracefile
 .I pattern
 .br
 .RS
 Extract data from
 .IR tracefile .
 
 Use this switch if you want to extract coverage data for only a particular
 set of files from a tracefile. Additional command line parameters will be
 interpreted as shell wildcard patterns (note that they may need to be
 escaped accordingly to prevent the shell from expanding them first).
 Every file entry in
 .I tracefile
 which matches at least one of those patterns will be extracted.
 
 The result of the extract operation will be written to stdout or the tracefile
 specified with \-o.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 .RE
 
 .B \-f
 .br
 .B \-\-follow
 .br
 .RS
 Follow links when searching for .da files.
 .RE
 
+.B \-\-from\-package
+.I package
+.br
+.RS
+Use .da files in
+.I package
+instead of kernel or directory.
+
+Use this option if you have separate machines for build and test and
+want to perform the .info file creation on the build machine. See
+\-\-to\-package for more information.
+.RE
+
 .B \-\-gcov\-tool
 .I tool
 .br
 .RS
 Specify the location of the gcov tool.
 .RE
 
 .B \-h
 .br
 .B \-\-help
@@ skipping 66 matching lines @@
 .I subdirectory
 .br
 .B \-\-kernel\-directory
 .I subdirectory
 .br
 .RS
 Capture kernel coverage data only from
 .IR subdirectory .
 
 Use this option if you don't want to get coverage data for all of the
-kernel, but only for specific subdirectories.
+kernel, but only for specific subdirectories. This option may be specified
+more than once.
 
-Note that you may specify this option more than once.
+Note that you may need to specify the full path to the kernel subdirectory
+depending on the version of the kernel gcov support.
 .RE
 
 .B \-l
 .I tracefile
 .br
 .B \-\-list
 .I tracefile
 .br
 .RS
 List the contents of the
 .IR tracefile .
 
-Only one of  \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
+.RE
+
+.B \-\-list\-full\-path
+.br
+.B \-\-no\-list\-full\-path
+.br
+.RS
+Specify whether to show full paths during list operation.
+
+Use \-\-list\-full\-path to show full paths during list operation
+or \-\-no\-list\-full\-path to show shortened paths. Paths are
+.B shortened
+by default.
+.RE
+
+.B \-\-no\-markers
+.br
+.RS
+Use this option if you want to get coverage data without regard to exclusion
+markers in the source code file. See
+.BR "geninfo " (1)
+for details on exclusion markers.
 .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
 
 .B \-o
@@ skipping 28 matching lines @@
 .B \-\-quiet
 .br
 .RS
 Do not print progress messages.
 
 This option is implied when no output filename is specified to prevent
 progress messages to mess with coverage data which is also printed to
 the standard output.
 .RE
 
+.B \-\-rc
+.IR keyword = value
+.br
+.RS
+Override a configuration directive.
+
+Use this option to specify a
+.IR keyword = value
+statement which overrides the corresponding configuration statement in
+the lcovrc configuration file. You can specify this option more than once
+to override multiple configuration statements.
+See
+.BR lcovrc (5)
+for a list of available keywords and their meaning.
+.RE
+
 .B \-r
 .I tracefile
 .I pattern
 .br
 .B \-\-remove
 .I tracefile
 .I pattern
 .br
 .RS
 Remove data from
 .IR tracefile .
 
 Use this switch if you want to remove coverage data for a particular
 set of files from a tracefile. Additional command line parameters will be
 interpreted as shell wildcard patterns (note that they may need to be
 escaped accordingly to prevent the shell from expanding them first).
 Every file entry in
 .I tracefile
 which matches at least one of those patterns will be removed.
 
 The result of the remove operation will be written to stdout or the tracefile
 specified with \-o.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 .RE
 
 .B \-\-strip
 .I depth
 .br
 .RS
 Strip path components when applying diff.
 
 Use this option together with \-\-diff to tell lcov to disregard the specified
 number of initial directories when matching tracefile and diff filenames.
 .RE
 
+.B \-\-summary
+.I tracefile
+.br
+.RS
+Show summary coverage information for the specified tracefile.
+
+Note that you may specify this option more than once.
+
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
+.RE
+
 .B \-t
 .I testname
 .br
 .B \-\-test\-name
 .I testname
 .br
 .RS
 Specify test name to be stored in the tracefile.
 
 This name identifies a coverage data set when more than one data set is merged
 into a combined tracefile (see option \-a).
 
 Valid test names can consist of letters, decimal digits and the underscore
 character ("_").
 .RE
 
+.B \-\-to\-package
+.I package
+.br
+.RS
+Store .da files for later processing.
+
+Use this option if you have separate machines for build and test and
+want to perform the .info file creation on the build machine. To do this,
+follow these steps:
+
+On the test machine:
+.RS
+.br
+\- run the test
+.br
+\- run lcov \-c [\-d directory] \-\-to-package
+.I file
+.br
+\- copy
+.I file
+to the build machine
+.RE
+.br
+
+On the build machine:
+.RS
+.br
+\- run lcov \-c \-\-from-package
+.I file
+[\-o and other options]
+.RE
+.br
+
+This works for both kernel and user space coverage data. Note that you might
+have to specify the path to the build directory using \-b with
+either \-\-to\-package or \-\-from-package. Note also that the package data
+must be converted to a .info file before recompiling the program or it will
+become invalid.
+.RE
+
 .B \-v
 .br
 .B \-\-version
 .br
 .RS
 Print version number, then exit.
 .RE
 
 .B \-z
 .br
 .B \-\-zerocounters
 .br
 .RS
 Reset all execution counts to zero.
 
 By default tries to reset kernel execution counts. Use the \-\-directory
 option to reset all counters of a user space program.
 
-Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
-at a time.
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be
+specified at a time.
 .RE
 
 .SH FILES
 
 .I /etc/lcovrc
 .RS
 The system\-wide configuration file.
 .RE
 
 .I ~/.lcovrc
 .RS
 The per\-user configuration file.
 .RE
 
 .SH AUTHOR
 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
 
 .SH SEE ALSO
 .BR lcovrc (5),
 .BR genhtml (1),
 .BR geninfo (1),
 .BR genpng (1),
 .BR gendesc (1),
 .BR gcov (1)