Provided by: lcov_2.1~beta2-1_all bug

NAME

       geninfo - Generate tracefiles from GCOV coverage data files

SYNOPSIS

       geninfo [-h|--help] [--version] [-q|--quiet] [-v|--verbose] [--debug]
               [--comment comment-string]
               [-i|--initial] [--all]
               [-t|--test-name test-name]
               [-o|--output-filename filename] [-f|--follow]
               [-b|--base-directory directory]
               [--build-directory directory]
               [--branch-coverage]
               [--checksum] [--no-checksum]
               [--compat-libtool] [--no-compat-libtool]
               [--gcov-tool tool]
               [--parallel|-j [integer]]
               [--memory integer_num_Mb]
               [--ignore-errors errors]
               [--keep-going]
               [--preserve]
               [--filter type]
               [--demangle-cpp[param]]
               [--no-recursion] [--external] [--no-external]
               [--config-file config-file] [--no-markers]
               [--derive-func-data] [--compat mode=on|off|auto]
               [--rc keyword=value]
               [--include glob_pattern]
               [--exclude glob_pattern]
               [--erase-functions regexp_pattern]
               [--substitute regexp_pattern]
               [--omit-lines regexp_pattern]
               [--forget-test-names]
               [--version-script script_file]
               [--tempdir dirname]
               directory

DESCRIPTION

       Use  geninfo  to  create LCOV tracefiles from GCC and LLVM/Clang coverage data files (see --gcov-tool for
       considerations when working with LLVM). You can use genhtml to create an HTML report from a tracefile.

       Note that geninfo is called by lcov --capture, so there is typically no need to call it directly.

       Unless the --output-filename option is specified geninfo  writes  its  output  to  one  file  with  .info
       filename extension per input file.

       Note  also  that  the current user needs write access to both 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.

       By  default, geninfo collects line and function coverage data.  Branch data is not collected; you can use
       the --branch-coverage option to enable branch coverage - or you can permanently enable branch coverage by
       adding the appropriate settings to your personal, group,  or  site  lcov  configuration  file.   See  man
       lcovrc(5) for details.

   File types
       A  tracefile  is  a  coverage  data  file in the format used by all LCOV tools such as geninfo, lcov, and
       genhtml.  By convention, tracefiles have a .info filename extension. See "Tracefile format" below  for  a
       description of the file format.

       A  .gcda  file  is  a compiler-specific file containing run-time coverage data. It is created and updated
       when a program compiled with GCC/LLVM's --coverage option is run  to  completion.   geninfo  reads  .gcda
       files  in  its default mode of operation. Note: earlier compiler versions used the .da filename extension
       for this file type.

       A .gcno file is a compiler-specific file containing static, compile-time coverage  data.  It  is  created
       when  source  code  is compiled with GCC/LLVM's --coverage option.  geninfo reads .gcno files when option
       --initial is specified. Note: earlier compiler versions used .bb and .bbg filename  extensions  for  this
       file type.

       A  .gcov  file  is  a  textual  or  JSON representation of the data found in .gcda and .gcno files. It is
       created by the gcov tools that is part of GCC (see  --gcov-tool  for  LLVM  considerations).   There  are
       multiple gcov file format versions, including textual, intermediate, and JSON format.  geninfo internally
       uses gcov to extract coverage data from .gcda and .gcno files using the best supported gcov file format.

       See the gcov man page for more information on .gcda, .gcno and .gcov output formats.

   Exclusion markers
       To  exclude  specific  lines  of code from a tracefile, you can add exclusion markers to the source code.
       Additionally you can exclude specific branches from branch coverage without excluding the involved  lines
       from  line  and  function  coverage. Exclusion markers are keywords which can for example be added in the
       form of a comment.  See man lcovrc(5) how to override some of them.

       The following markers are recognized by geninfo:

       LCOV_EXCL_LINE
              Lines containing this marker will be excluded.

       LCOV_EXCL_START
              Marks the beginning of an excluded section. The current line is part of this section.

       LCOV_EXCL_STOP
              Marks the end of an excluded section. The current line not part of this section.

       LCOV_EXCL_BR_LINE
              Lines containing this marker will be excluded from branch coverage.

       LCOV_EXCL_BR_START
              Marks the beginning of a section which is excluded from branch coverage. The current line is  part
              of this section.

       LCOV_EXCL_BR_STOP
              Marks  the  end  of a section which is excluded from branch coverage. The current line not part of
              this section.

       LCOV_EXCL_EXCEPTION_BR_LINE
              Lines containing this marker will be excluded from exception branch coverage:  Exception  branches
              will be ignored, but non-exception branches will not be affected.

       LCOV_EXCL_EXCEPTION_BR_START
              Marks  the  beginning  of  a section which is excluded from exception branch coverage. The current
              line is part of this section.

       LCOV_EXCL_EXCEPTION_BR_STOP
              Marks the end of a section which is excluded from exception branch coverage.  The current line not
              part of this section

OPTIONS

       -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 geninfo  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  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 use configuration file setting geninfo_auto_base=1 (see man lcovrc(5)).

       --build-directory build_dir
              Search  for .gcno data files from build_dir rather finding them only adjacent to the corresponding
              .o and/or .gcda file.

              By default, geninfo expects to find the  .gcno  and  .gcda  files  (compile-  and  run-time  data,
              respectively) in the same directory.

              When this option is used:

                     geninfo path1 --build-directory path2 ...

              then geninfo will look for .gcno file

                     path2/relative/path/to/da_base.gcno

              when it finds .gcda file

                     path1/relative/path/to/da_base.gcda.

              Use  this option when you have used the GCOV_PREFIX environment variable to direct the gcc or llvm
              runtime environment to write coverage data files to somewhere other than the directory  where  the
              code was originally compiled.  See gcc(1) and/or search for GCOV_PREFIX and GCOV_PREFIX_STRIP.

              This  option can be used several times to specify multiple alternate directories to look for .gcno
              files.  This may be useful if your application uses  code  which  is  compiled  in  many  separate
              locations - for example, common libraries that are shared between teams.

       --source-directory dirname
              Add 'dirname' to the list of places to look for source files.

              For  relative  source  file  paths found in the gcov data - possibly after substitutions have been
              applied, geninfo will first look for the path from 'cwd' (where genhtml was invoked) and then from
              each alternate directory name in the order specified.  The first  location  matching  location  is
              used.

              This option can be specified multiple times, to add more directories to the source search path.

       --branch-coverage
              Collect retain branch coverage data.

              This  is  equivalent  to using the option "--rc branch_coverage=1"; the option was added to better
              match the genhml interface.

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

              Note that this options is somewhat subsumed by the --version-script option - which does  something
              similar, but at the 'whole file' level.

       --compat mode=value[,mode=value,...]
              Set compatibility mode.

              Use  --compat to specify that geninfo 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 values are:

              on
                     Enable compatibility mode.
              off
                     Disable compatibility mode.
              auto
                     Apply  auto-detection  to  determine  if  compatibility  mode  is required. Note that auto-
                     detection is not available for all compatibility modes.

              If no value is specified, 'on' is assumed as default value.

              Valid modes are:

              libtool
                     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'.

              hammer
                     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'.

              split_crc
                     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 geninfo 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'

       --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, geninfo will assume that the source code relating to a
              .gcda 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.

       --config-file config-file
              Specify a configuration file to use.  See the lcovrc man page for details of the file  format  and
              options.

              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 geninfo with  different
              configuration file options in parallel.

              Note that this option must be specified in full - abbreviations are not supported.

       --derive-func-data
              Calculate function coverage data from line coverage data.

              Use  this option to collect function coverage data, even if the version of the gcov tool installed
              on the test system does not provide this data. lcov will instead  derive  function  coverage  data
              from line coverage data and information about which lines belong to a function.

       --external
       --no-external
              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 included by default.

       -f
       --follow
              Follow links when searching .gcda files.

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

              If  the  --gcov-tool  option  is used multiple times, then the arguments are concatenated when the
              callback is executed - similar to how the gcc -Xlinker parameter works.  This provides a  possibly
              easier way to pass arguments to your tool, without requiring a wrapper script.  In that case, your
              callback will be executed as: tool-0 'tool-1; ... 'filename'.  Note that the second and subsequent
              arguments are quoted when passed to the shell, in order to handle parameters which contain spaces.

              The --gcov-tool argument may be a split_char separated string - see man(4) lcovrc.

              A common use for this option is to enable LLVM:

                     geninfo --gcov-tool llvm-cov --gcov-tool gcov ...
                     geninfo --gcov-tool llvm-cov,gcov ...

              Note:  'llvm-cov  gcov da_file_name' will generate output in gcov-compatible format as required by
              lcov.

              If not specified, 'gcov' is used by default.

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

       --include pattern
              Include source files matching pattern.

              Use this switch if you want to include coverage data for only a particular  set  of  source  files
              matching any of the given patterns. Multiple patterns can be specified by using multiple --include
              command line switches. The patterns will be interpreted as shell wildcard patterns (note that they
              may need to be escaped accordingly to prevent the shell from expanding them first).

              See the lcov man page for details

       --exclude pattern
              Exclude source files matching pattern.

              Use  this  switch  if  you  want  to  exclude coverage data from a  particular set of source files
              matching any of the given patterns. Multiple patterns can be specified by using multiple --exclude
              command line switches. The patterns will be interpreted as shell wildcard patterns (note that they
              may need to be escaped accordingly to prevent the shell from expanding  them  first).   Note:  The
              pattern must be specified to match the absolute path of each source file.

              Can  be  combined with the --include command line switch. If a given file matches both the include
              pattern and the exclude pattern, the exclude pattern will take precedence.

              See the lcov man page for details.

       --erase-functions regexp
              Exclude coverage data from lines which fall within a function  whose  name  matches  the  supplied
              regexp.   Note  that  this is a mangled or demangled name, depending on whether the --demangle-cpp
              option is used or not.

              Note that this option requires that you use a gcc version which is new enough to support  function
              begin/end  line  reports  or  that  you  configure  the  tool to derive the required dta - see the
              derive_function_end_line discussion in the lcovrc man page.

       --substitute regexp_pattern
              Apply Perl regexp regexp_pattern to source file names found during  processing.   This  is  useful
              when  the  path name reported by gcov does not match your source layout and the file is not found.
              See the lcov man page for more details.

       --omit-lines regexp
              Exclude coverage data from lines whose content matches regexp.

              Use this switch if you want  to  exclude  line  and  branch  coverage  data  for  some  particular
              constructs in your code (e.g., some complicated macro).  See the lcov man page for details.

       --forget-test-names
              If non-zero, ignore testcase names in tracefile - i.e., treat all coverage data as if it came from
              the  same  testcase.   This may improve performance and reduce memory consumption if user does not
              need per-testcase coverage summary in coverage reports.

              This  option  can  also  be  configured  permanently   using   the   configuration   file   option
              forget_testcase_names.

       --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 geninfo should
              continue processing instead of aborting.  Note that the tool will generate a warning (rather  than
              a fatal error) unless you ignore the error two (or more) times:
                     geninfo ... --ignore-errors unused,unused

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

              branch:
                 branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence.

              callback:
                 Version script error.

              child:
                 child  process  returned  non-zero  exit  code  during  --parallel  execution.   This typically
                 indicates that the child encountered an  error:   see  the  log  file  immediately  above  this
                 message.   In  contrast:  the parallel error indicates an unexpected/unhandled exception in the
                 child process - not a 'typical' lcov error.

              corrupt:
                 corrupt/unreadable file found.

              count:
                 An excessive number of messages of some class have been reported - subsequent messages of  that
                 type  will be suppressed.  The limit can be controlled by the 'max_message_count' variable. See
                 the lcovrc man page.

              deprecated:
                 You are using a deprecated option.  This option will be removed in an upcoming release - so you
                 should change your scripts now.

              empty:
                 the .info data file is empty (e.g., because all the code was 'removed' or excluded.

              excessive:
                 your coverage data contains a suspiciously large 'hit' count which is unlikely to be correct  -
                 possibly indicating a bug in your toolchain.

                 See the excessive_count_threshold section in man lcovrc(5) for details.

              fork:
                 Unable to create child process during --parallel execution.
                 If  the  message is ignored ( --ignore-errors fork ), then genhtml will wait a brief period and
                 then retry the failed execution.
                 If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find
                 a larger server to run the task.

              format:
                 unexpected syntax found in .info file.

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

              graph:
                 the graph file could not be found or is corrupted.

              internal:
                 internal tool issue detected.  Please report this bug along with a testcase.

              mismatch:
                 Inconsistent entries found in trace file:

                 •  branch expression (3rd field in the .info file 'BRDA' entry) of merge data does  not  match,
                    or

                 •  function execution count (FNDA:...) but no function declaration (FN:...).

              missing:
                 File does not exist or is not readable.

              negative:
                 negative 'hit' count found.

                 Note that negative counts may be caused by a known GCC bug - see

                   https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080

                 and  try  compiling  with  "-fprofile-update=atomic".  You  will need to recompile, re-run your
                 tests, and re-capture coverage data.

              package:
                 a required perl package is not installed on your system.  In some  cases,  it  is  possible  to
                 ignore this message and continue - however, certain features will be disabled in that case.

              parallel:
                 various  types  of  errors related to parallelism - i.e., a child process died due to an error.
                 The corresponding error message appears in the log file immediately before the parallel error.

                 If you see an error related to parallel execution that seems invalid, it may be a good idea  to
                 remove  the  --parallel  flag and try again.  If removing the flag leads to a different result,
                 please report the issue (along with a testcase) so that the tool can be fixed.

              parent:
                 the parent process exited while child was active during  --parallel  execution.   This  happens
                 when  the  parent  has encountered a fatal error - e.g.  an error in some other child which was
                 not ignored.  This child cannot continue working without its parent - and so will exit.

              path:
                 some file paths were not resolved - e.g., .gcno file corresponding to some .gcda was not  found
                 see --build-directory option for additional information.

              range:
                 Coverage  data  refers  to a line number which is larger than the number of lines in the source
                 file.  This can be caused by a version mismatch or by an issue in the gcov data.

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

              `<

              unsupported:
                 the requested feature is not supported for this  tool  configuration.   For  example,  function
                 begin/end  line  range  exclusions  use  some GCOV features that are not available in older GCC
                 releases.

              unused:
                 the include/exclude/erase/omit/substitute pattern did not match any file pathnames.

              usage:
                 unsupported usage detected - e.g. an unsupported option combination.

              utility:
                 a tool called during processing returned an error code (e.g., 'find' encountered an  unreadable
                 directory).

              version:
                 revision control IDs of the file which we are trying to merge are not the same - line numbering
                 and other information may be incorrect.

              Also see man lcovrc(5)
               for  a discussion of the 'max_message_count' parameter which can be used to control the number of
              warnings which are emitted before all subsequent messages are suppressed.  This  can  be  used  to
              reduce log file volume.

       --keep-going
              Do not stop if error occurs: attempt to generate a result, however flawed.

              This command line option corresponds to the stop_on_error [0|1] lcovrc option.   See man lcovrc(5)
              for more details.

       --preserve
              Preserve intermediate data files (e.g., for debugging).

              By default, intermediate files are deleted.

       --filter filters
              Specify  a  list  of  coverpoint  filters  to  apply  to input data.  See the genhtml man page for
              details.

       --demangle-cpp [param]
              Demangle C++ method and function names in captured output.  See the genhtml man page for details.

       -i
       --initial
              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 and function.  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 object code files were loaded during the test.  Also see the --all flag, below.

              Note: the --initial option is not supported for gcc versions less than 6, and  does  not  generate
              branch coverage information for gcc versions less than 8.

       --all
              Capture  coverage  data  from both compile time (.gcno) data files which do not have corresponding
              runtime (.gcda) data files, as well as from those that do have corresponding runtime data.   There
              will  be  no runtime data unless some executable which links the corresponding object file has run
              to completion.

              Note that the execution count of coverpoints found only in files which do  not  have  any  runtime
              data will be zero.

              This flag is ignored if the --initial flag is set.

              Using  the  --all flag is equivalent to executing both geninfo --initial ...  and geninfo ...  and
              merging the result.

              Also see the geninfo_capture_all entry in man(5) lcovrc.

       --no-markers
              Use this option if you want to get coverage data without regard to exclusion markers in the source
              code file.

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

       -o output-filename
       --output-filename output-filename
              Write all data to 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
              .gcda file.

       --version-script script
              Use script to get a source file's version ID from revision control when extracting data. The ID is
              used for error checking when merging .info files.

              See the genhtml man page for more details on the version script.

       --resolve-script script
              Use  script to find the file path for some source or GCNO file which appears in an input data file
              if the file is not found after applying --substitute patterns and searching the --source-directory
              or --build-directory list.  This option is equivalent to the resolve_script  config  file  option.
              See man lcovrc(5) for details.

       -v
       --verbose
              Increment informational message verbosity.  This is mainly used for script and/or flow debugging -
              e.g., to figure out which data file are found, where.  Also see the --quiet flag.

              Messages  are sent to stdout unless there is no output file (i.e., if the coverage data is written
              to stdout rather than to a file) and to stderr otherwise.

       -q
       --quiet
              Decrement informational message verbosity.

              Decreased verbosity will suppress 'progress' messages  for  example  -  while  error  and  warning
              messages will continue to be printed.

       --debug
              Increment  'debug messages' verbosity.  This is useful primarily to developers who want to enhance
              the lcov tool suite.

       --comment comment_string
              Append comment_string to list of comments emitted into output result file.   This  option  may  be
              specified  multiple  times.   Comments  are printed at the top of the file, in the order they were
              specified.

              Comments can be useful to document the conditions under which the trace file was generated:  host,
              date, environment, etc.

       --parallel [ integer ]
       -j [ integer ]
              Specify parallelism to use during processing (maximum number of forked child processes).   If  the
              optional  integer  parallelism  parameter  is zero or is missing, then use to use up the number of
              cores on the machine.  Default is not to use a single process (no parallelism).

              Also see the memory, memory_percentage, max_fork_fails, fork_fail_timeout, geninfo_chunk_size  and
              geninfo_interval_update  entries  in man lcovrc(5) for a description of some options which may aid
              in parameter tuning and performance optimization.

       --memory integer
              Specify the maximum amount of memory to use during parallel processing, in Mb.   Effectively,  the
              process  will  not fork() if this limit would be exceeded.  Default is 0 (zero) - which means that
              there is no limit.

              This option may be useful if the compute  farm  environment  imposes  strict  limits  on  resource
              utilization  such  that the job will be killed if it tries to use too many parallel children - but
              the user does now know a priori what the permissible maximum is.  This option enables the tool  to
              use maximum parallelism - up to the limit imposed by the memory restriction.

              The  configuration  file  memory_percentage  option provided another way to set the maximum memory
              consumption.  See man lcovrc(5) for details.

       --rc keyword=value
              Override a configuration directive.

              Use  this  option  to  specify  a  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 man lcovrc(5) for  a  list  of  available
              keywords and their meaning.

       -t testname
       --test-name testname
              Use  test  case  name  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.

       --version
              Print version number, then exit.

       --tempdir dirname
              Write temporary and intermediate data to indicated directory.  Default is "/tmp".

TRACEFILE FORMAT

       Following is a quick description of the tracefile format as used by genhtml, geninfo and lcov.

       A tracefile is made up  of  several  human-readable  lines  of  text,  divided  into  sections.   If  the
       ---comment comment_string option is supplied, then

               #comment_string
       will appeaare at the top of the tracefile.  There is no space before or after the # character.

       If available, a tracefile begins with the testname which is stored in the following format:

              TN:<test name>

       For  each  source  file referenced in the .gcda file, there is a section containing filename and coverage
       data:

              SF:<path to the source file>

       An optional source code version ID follows:

              VER:<version ID>

       If present, the version ID is compared before file entries are merged (see lcov  --add-tracefile  ),  and
       before  the  'source  detail'  view  is  generated  by genhtml.  See the --version-script callback_script
       documentation and the sample usage in the lcov regression test examples.

       Following is a list of line numbers for each function name found in the source file:

              FN:<line number of function start>,[<line number of function end>,]<function name>

       The 'end' line number is optional, and is generated only if  the  compiler/toolchain  version  is  recent
       enough  to  generate the data (e.g., gcc 9 or newer).  This data is used to support the --erase-functions
       and --show-proportions options.  If the function end line data is not available, then these features will
       not work.

       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>

       Branch coverage information is stored which one line per branch:

              BRDA:<line_number>,[<exception>]<block>,<branch>,<taken>

       <line_number> is the line number where the branch is found - and is expected to to be a non-zero integer.
       <block> and <branch> serve to uniquely define a particular edge in the expression tree  of  a  particular
       conditional found on the associated line.
       Within  a  particular line, <block> is an integer numbered from zero with no gaps. For some languages and
       some coding styles, there will only be one block (index value zero) on any particular line.
       <branch> is a string which serves to uniquely identify a particular edge.  For some languages and tools -
       e.g., C/C++ code compiled with gcc or llvm - <branch> is an ordered integer index related  to  expression
       tree  traversal  order  of  the  associated conditional.  For others, it may be a meaningful string - see
       below.  <branch> appears in the 'tooltip' popup of the asognciated branch in  the  genhtml  output  -  so
       human-readable values are helpful to users who are trying to understand coveage results.
       <taken>  is  either  '-'  if  the  corresponding  expression  was  never evaluated (e.g., the basic block
       containing the branch was never executed) or a number indicating how often that branch was taken.
       <exception> is 'e' (single character) if this is a branch related to exception  handling  -  and  is  not
       present  if  the  branch is not related to exceptions.  Exception branch identification requires compiler
       support; note that gcc versions older than 9 do not differentiate exception branches.   Geninfo  will  be
       able to identify exception branches only if your toolchain version is new enough to support the feature.

       The following is an example branch records whose <branch> expression values are human-readable strings.

                BRDA:10,0,enable,1
                BRDA:10,0,!enable,0
       In this case, the corresponding code from line 10 is very likely similar to:
                 if (enable) {
                   ...
                 }
       such that associated testcase entered the block ('enable' evaluated to 'true').

       Arbitrarily  complicated  branch  expressions  are supported - including branch expressions which contain
       commas (e.g., in an expression containing a function call).

       Note that particular tools may or may not suppress expressions which are statically  true  or  statically
       false  -  e.g.,  expressions using template parameters.  This makes it potentially complicated to compare
       coverage data generated by two different tools.

       Branch coverage summaries are stored in two lines:

              BRF:<number of branches found>
              BRH:<number of branches 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 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
       .gcno  file  (see  gcov (1) for more information on this file type). Relative filenames are prefixed with
       the directory in which the .gcno file is found.

       Note also that symbolic links to the .gcno 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.

FILES

       /etc/lcovrc
              The system-wide configuration file.

       ~/.lcovrc
              The per-user configuration file.

       /usr/share/lcov//support-scripts/getp4version
              Sample script for use with --version-script that obtains version IDs via Perforce.

       /usr/share/lcov//support-scripts/get_signature
              Sample script for use with --version-script that uses md5hash as version IDs.

AUTHOR

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

       Henry Cox <henry.cox@mediatek.com>
              Filtering, error management, parallel execution sections.

SEE ALSO

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

       https://github.com/linux-test-project/lcov

2024-04-08                                          LCOV 2.0                                          geninfo(1)