Upgrades lcov to 1.10, removes lcov-1.9

third_party/lcov/man/lcov.1

Index: third_party/lcov/man/lcov.1
diff --git a/third_party/lcov/man/lcov.1 b/third_party/lcov/man/lcov.1
index aa30fb85d89efdc597943c7a7406e27d8b3607de..092d86560bcbebfb87985d9ae7086ec399485709 100644
--- a/third_party/lcov/man/lcov.1
+++ b/third_party/lcov/man/lcov.1
@@ -1,73 +1,186 @@
-.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 ]
+.RB [ \-t | \-\-test\-name
+.IR testname ]
 .br
-.RB [ \-e | \-\-extract
-.IR tracefile ]
+.RB [ \-b | \-\-base\-directory
+.IR directory ]
+.RB [ \-i | \-\-initial ]
+.RB [ \-\-gcov\-tool
+.IR tool ]
 .br
-.RB [ \-r | \-\-remove
-.IR tracefile ]
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.RB [ \-\-no\-recursion ]
+.RB [ \-f | \-\-follow ]
 .br
-.RB [ \-l | \-\-list
-.IR tracefile ]
+.RB [ \-\-compat\-libtool ]
+.RB [ \-\-no\-compat\-libtool ]
+.RB [ \-\-ignore\-errors
+.IR errors ]
 .br
-.RB [ \-\-diff
-.IR "tracefile diff" ]
+.RB [ \-\-to\-package
+.IR package ]
+.RB [ \-\-from\-package
+.IR package ]
+.RB [ \-q | \-\-quiet ]
 .br
-.RB [ \-i | \-\-initial ]
-.RB [ \-t | \-\-test\-name
-.IR testname ]
+.RB [ \-\-no\-markers ]
+.RB [ \-\-external ]
+.RB [ \-\-no\-external ]
 .br
-.RB [ \-o | \-\-output\-file
-.IR filename ]
+.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
@@ -79,8 +192,10 @@ 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:
@@ -93,6 +208,14 @@ 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
 
 
@@ -113,8 +236,8 @@ 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
 
@@ -143,11 +266,10 @@ 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
@@ -164,8 +286,8 @@ 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
@@ -189,6 +311,73 @@ 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
@@ -209,6 +398,21 @@ 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
@@ -250,8 +454,8 @@ 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
@@ -272,6 +476,23 @@ 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
@@ -295,8 +516,8 @@ 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
@@ -307,6 +528,19 @@ at a time.
 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
@@ -393,9 +627,11 @@ 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
@@ -408,8 +644,30 @@ Note that you may specify this option more than once.
 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
@@ -458,6 +716,22 @@ 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
@@ -481,8 +755,8 @@ 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
@@ -495,6 +769,18 @@ 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
@@ -511,6 +797,46 @@ 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
@@ -529,8 +855,8 @@ 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