Provided by: lcov_1.7-1_all bug

NAME

       lcov - a graphical GCOV front-end

SYNOPSIS

       lcov [-h|--help] [-v|--version] [-q|--quiet]
            [-z|--zerocounters] [-c|--capture]
            [-a|--add-tracefile tracefile]
            [-e|--extract tracefile]
            [-r|--remove tracefile]
            [-l|--list tracefile]
            [--diff tracefile diff]
            [-i|--initial] [-t|--test-name testname]
            [-o|--output-file filename]
            [-d|--directory directory]
            [-f|--follow]
            [-k|--kernel-directory directory]
            [-b|--base-directory directory]
            [--convert-filenames] [--strip depth] [--path path]
            [--checksum] [--no-checksum]
            [--compat-libtool] [--no-compat-libtool]
            [--gcov-tool tool] [--ignore-errors errors]
            [--no-recursion]

DESCRIPTION

       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.

       Use lcov to collect coverage data and 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:
              Follow  the installation instructions for the gcov-kernel patch:
              http://ltp.sourceforge.net/coverage/gcov.php

       For user space application coverage:
              Compile   the   application   with   GCC   using   the   options
              "-fprofile-arcs" and "-ftest-coverage".

       Please  note  that this man page refers to the output format of lcov as
       ".info file" or "tracefile" and that the output of GCOV is called  ".da
       file".

OPTIONS

       -a tracefile
       --add-tracefile tracefile
              Add contents of 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.

       -b directory
       --base-directory directory
              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:

                     ERROR:     could      not      read      source      file
                     /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c

              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.

       -c
       --capture
              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.

       --checksum
       --no-checksum
              Specify   whether   to   generate  checksum  data  when  writing
              tracefiles.

              Use --checksum to enable checksum generation or --no-checksum to
              disable it. Checksum generation is 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.

       --compat-libtool
       --no-compat-libtool
              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 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.

       --convert-filenames
              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.

       --diff tracefile difffile
              Convert coverage data in tracefile using source code  diff  file
              difffile.

              Use  this  option  if  you  want  to  merge  coverage  data from
              different source code levels of a program, e.g.  when  you  have
              data  taken  from  an  older version and want to combine it with
              data from a more current version.  lcov will try to  map  source
              code  lines  between those versions and adjust the coverage data
              respectively.  difffile needs to be in unified format,  i.e.  it
              has to be created using the "-u" option of the diff tool.

              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.

       -d directory
       --directory directory
              Use .da files in 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.

       -e tracefile pattern
       --extract tracefile pattern
              Extract data from 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
              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.

       -f
       --follow
              Follow links when searching for .da files.

       --gcov-tool tool
              Specify the location of the gcov tool.

       -h
       --help
              Print a short help text, then exit.

       --ignore-errors errors
              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  lcov should continue processing instead of
              aborting.

              errors can be a comma-separated list of the following keywords:

              gcov: the gcov tool returned with a non-zero return code.

              source: the source code file for a data set could not be  found.

       -i
       --initial
              Capture initial zero coverage data.

              Run  lcov  with -c and 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.

              Recommended procedure when capturing data for a test case:

              1. create baseline coverage data file
                     # lcov -c -i -d appdir -o app_base.info

              2. perform test
                     # appdir/test

              3. create test coverage data file
                     # lcov -c -d appdir -o app_test.info

              4. combine baseline and test coverage data
                     #   lcov   -a   app_base.info   -a    app_test.info    -o
                     app_total.info

       -k subdirectory
       --kernel-directory subdirectory
              Capture kernel coverage data only from subdirectory.

              Use  this  option if you don’t want to get coverage data for all
              of the kernel, but only for specific subdirectories.

              Note that you may specify this option more than once.

       -l tracefile
       --list tracefile
              List the contents of the tracefile.

              Only one of  -z, -c, -a, -e, -r, -l and --diff may be  specified
              at a time.

       --no-recursion
              Use  this  option  if  you  want  to  get  coverage data for the
              specified directory only without processing subdirectories.

       -o tracefile
       --output-file tracefile
              Write data to tracefile instead of stdout.

              Specify "-" as a filename to use the standard output.

              By convention, lcov-generated coverage  data  files  are  called
              "tracefiles" and should have the filename extension ".info".

       --path path
              Strip path from filenames when applying diff.

              Use  this  option together with --diff to tell lcov to disregard
              the specified  initial  path  component  when  matching  between
              tracefile and diff filenames.

       -q
       --quiet
              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.

       -r tracefile pattern
       --remove tracefile pattern
              Remove data from 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
              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.

       --strip depth
              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.

       -t testname
       --test-name testname
              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 ("_").

       -v
       --version
              Print version number, then exit.

       -z
       --zerocounters
              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.

FILES

       /etc/lcovrc
              The system-wide configuration file.

       ~/.lcovrc
              The per-user configuration file.

AUTHOR

       Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>

SEE ALSO

       lcovrc(5), genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)