Debian Codegraph @

man/geninfo.1

raw
1 \" Define path to scripts
2 .ds scriptdir bin
3
4 \" Define project URL
5 .ds lcovurl https://github.com/linux\-test\-project/lcov
6
7 .TH geninfo 1 "LCOV 2.0" 2023\-05\-17 "User Manuals"
8 .SH NAME
9 geninfo \- Generate tracefiles from GCOV coverage data files
10 .SH SYNOPSIS
11 .B geninfo
12 .RB [ \-h | \-\-help ]
13 .RB [ \-\-version ]
14 .RB [ \-q | \-\-quiet ]
15 .RB [ \-v | \-\-verbose ]
16 .RB [ \-\-debug ]
17 .br
18 .RS 8
19 .RB [ \-\-comment
20 .IR comment-string ]
21 .br
22 .RB [ \-i | \-\-initial ]
23 .RB [ \-\-all ]
24 .br
25 .RB [ \-t | \-\-test\-name
26 .IR test\-name ]
27 .br
28 .RB [ \-o | \-\-output\-filename
29 .IR filename ]
30 .RB [ \-f | \-\-follow ]
31 .br
32 .RB [ \-b | \-\-base\-directory
33 .IR directory ]
34 .br
35 .RB [ \-\-build\-directory
36 .IR directory ]
37 .br
38 .RB [ \-\-branch\-coverage ]
39 .br
40 .RB [ \-\-mcdc\-coverage ]
41 .br
42 .RB [ \-\-checksum ]
43 .RB [ \-\-no\-checksum ]
44 .br
45 .RB [ \-\-compat\-libtool ]
46 .RB [ \-\-no\-compat\-libtool ]
47 .br
48 .RB [ \-\-gcov\-tool
49 .IR tool ]
50 .br
51 .RB [ \-\-parallel | -j
52 .IR [integer] ]
53 .br
54 .br [ \-\-large\-file
55 .IR regexp ]
56 .br
57 .RB [ \-\-memory
58 .IR integer_num_Mb ]
59 .br
60 .RB [ \-\-msg\-log
61 .IR [ log_file_name ] ]
62 .br
63 .RB [ \-\-ignore\-errors
64 .IR errors ]
65 .br
66 .RB [\-\-expect\-message\-count
67 .IR message_type=expr[,message_type=expr..]]
68 .br
69 .RB [ \-\-keep\-going ]
70 .br
71 .RB [ \-\-preserve ]
72 .br
73 .RB [ \-\-filter
74 .IR type ]
75 .br
76 .RB [ \-\-demangle\-cpp [param]]
77 .br
78 .RB [ \-\-no\-recursion ]
79 .RB [ \-\-external ]
80 .RB [ \-\-no\-external ]
81 .br
82 .RB [ \-\-sort\-input ]
83 .br
84 .RB [ \-\-config\-file
85 .IR config\-file ]
86 .RB [ \-\-no\-markers ]
87 .br
88 .RB [ \-\-profile
89 .IR [ profile\-file ] ]
90 .br
91 .RB [ \-\-derive\-func\-data ]
92 .RB [ \-\-compat
93 .IR mode =on|off|auto]
94 .br
95 .RB [ \-\-rc
96 .IR keyword = value ]
97 .br
98 .RB [ \-\-include
99 .IR glob_pattern ]
100 .br
101 .RB [ \-\-exclude
102 .IR glob_pattern ]
103 .br
104 .RB [ \-\-erase\-functions
105 .IR regexp_pattern ]
106 .br
107 .RB [ \-\-substitute
108 .IR regexp_pattern ]
109 .br
110 .RB [ \-\-omit\-lines
111 .IR regexp_pattern ]
112 .br
113 .RB [ \-\-fail\-under\-branches
114 .IR percentage ]
115 .br
116 .RB [ \-\-fail\-under\-lines
117 .IR percentage ]
118 .br
119 .RB [ \-\-forget\-test\-names ]
120 .br
121 .RB [ \-\-context\-script
122 .IR script_file ]
123 .br
124 .RB [ \-\-criteria\-script
125 .IR script_file ]
126 .br
127 .RB [ \-\-resolve\-script
128 .IR script_file ]
129 .br
130 .RB [ \-\-version\-script
131 .IR script_file ]
132 .br
133 .RB [ \-\-tempdir
134 .IR dirname ]
135 .br
136 .IR directory
137 .RE
138
139 .SH DESCRIPTION
140
141 Use
142 .B geninfo
143 to create LCOV tracefiles from GCC and LLVM/Clang coverage data files (see
144 .B --gcov-tool
145 for considerations when working with LLVM). You can use
146 .B genhtml
147 to create an HTML report from a tracefile.
148 .br
149
150 Note that
151 .B geninfo
152 is called by
153 .BR "lcov --capture" ,
154 so there is typically no need to call it directly.
155 .br
156
157 Unless the
158 .B --output-filename
159 option is specified
160 .B geninfo
161 writes its output to one file with .info filename extension per input file.
162 .br
163
164 Note also that the current user needs write access to both
165 .I directory
166 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.
167 .br
168
169 By default,
170 .B geninfo
171 collects line and function coverage data.
172 Neither branch nor MC/DC data is not collected by default; you can use the
173 .B \-\-branch\-coverage
174 and
175 .B \-\-mcdc\-coverage
176 command line options to enable them, or you can permanently enable them by adding
177 .B branch_coverage = 1
178 and/or
179 .B mcdc_coverage = 1
180 to your personal, group, or site lcov configuration file. See man
181 .B lcovrc(5)
182 for details.
183
184
185 .SS "File types"
186
187 A
188 .B tracefile
189 is a coverage data file in the format used by all LCOV tools such as
190 .BR geninfo ", " lcov ", and " genhtml .
191 By convention, tracefiles have a .info filename extension. See "Tracefile format" below for a description of the file format.
192 .br
193
194 A
195 .B .gcda file
196 is a compiler-specific file containing run-time coverage data. It is created and updated when a program compiled with GCC/LLVM's
197 .B --coverage
198 option is run to completion.
199 .B geninfo
200 reads .gcda files in its default mode of operation. Note: earlier compiler versions used the .da filename extension for this file type.
201 .br
202
203 A
204 .B .gcno file
205 is a compiler-specific file containing static, compile-time coverage data. It is created when source code is compiled with GCC/LLVM's
206 .B --coverage
207 option.
208 .B geninfo
209 reads .gcno files when option
210 .B --initial
211 is specified. Note: earlier compiler versions used .bb and .bbg filename extensions for this file type.
212 .br
213
214 A
215 .B .gcov file
216 is a textual or JSON representation of the data found in .gcda and .gcno files. It is created by the
217 .BR gcov
218 tools that is part of GCC (see
219 .B --gcov-tool
220 for LLVM considerations).
221 There are multiple gcov file format versions, including textual, intermediate, and JSON format.
222 .B geninfo
223 internally uses
224 .B gcov
225 to extract coverage data from .gcda and .gcno files using the best supported gcov file format.
226 .br
227
228 See the
229 .B gcov
230 man page for more information on .gcda, .gcno and .gcov output formats.
231 .br
232
233 .SS "Exclusion markers"
234
235 To exclude specific lines of code from a tracefile, you can add exclusion
236 markers to the source code. Additionally you can exclude specific branches from
237 branch coverage without excluding the involved lines from line and function
238 coverage. Exclusion markers are keywords which can for example be added in the
239 form of a comment.
240 See man
241 .BR lcovrc (5)
242 how to override some of them.
243
244 The following markers are recognized by geninfo:
245
246 .B LCOV_EXCL_LINE
247 .br
248 .RS
249 Lines containing this marker will be excluded.
250 .br
251 .RE
252
253 .B LCOV_EXCL_START
254 .br
255 .RS
256 Marks the beginning of an excluded section. The current line is part of this
257 section.
258 .br
259 .RE
260
261 .B LCOV_EXCL_STOP
262 .br
263 .RS
264 Marks the end of an excluded section. The current line not part of this
265 section.
266 .br
267 .RE
268
269 .B LCOV_EXCL_BR_LINE
270 .br
271 .RS
272 Lines containing this marker will be excluded from branch coverage.
273 .br
274 .RE
275
276 .B LCOV_EXCL_BR_START
277 .br
278 .RS
279 Marks the beginning of a section which is excluded from branch coverage. The
280 current line is part of this section.
281 .br
282 .RE
283
284 .B LCOV_EXCL_BR_STOP
285 .br
286 .RS
287 Marks the end of a section which is excluded from branch coverage. The current
288 line not part of this section.
289 .br
290 .RE
291
292 .B LCOV_EXCL_EXCEPTION_BR_LINE
293 .br
294 .RS
295 Lines containing this marker will be excluded from exception branch coverage:
296 Exception branches will be ignored, but non-exception branches will not be
297 affected.
298 .br
299 .RE
300
301 .B LCOV_EXCL_EXCEPTION_BR_START
302 .br
303 .RS
304 Marks the beginning of a section which is excluded from exception branch
305 coverage. The current line is part of this section.
306 .br
307 .RE
308
309 .B LCOV_EXCL_EXCEPTION_BR_STOP
310 .br
311 .RS
312 Marks the end of a section which is excluded from exception branch coverage.
313 The current line not part of this section
314 .br
315 .RE
316
317 .SH OPTIONS
318
319 In general, (almost) all
320 .B geninfo
321 options can also be specified in your personal, group, project, or site
322 configuration file - see man
323 .B lcovrc(5)
324 for details.
325
326
327 .B \-b
328 .I directory
329 .br
330 .B \-\-base\-directory
331 .I directory
332 .br
333 .RS
334 .RI "Use " directory
335 as base directory for relative paths.
336
337 Use this option to specify the base directory of a build\-environment
338 when geninfo produces error messages like:
339
340 .RS
341 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
342 .RE
343
344 In this example, use /home/user/project as base directory.
345
346 This option is required when using geninfo on projects built with libtool or
347 similar build environments that work with a base directory, i.e. environments,
348 where the current working directory when invoking the compiler is not the same
349 directory in which the source code file is located.
350
351 Note that this option will not work in environments where multiple base
352 directories are used. In that case use configuration file setting
353 .B geninfo_auto_base=1
354 (see man
355 .BR lcovrc (5)).
356 .RE
357
358 .B \-\-build\-directory
359 .I build_dir
360 .br
361 .RS
362 Search for .gcno data files from
363 .I build_dir
364 rather finding them only adjacent to the corresponding .o and/or .gcda file.
365
366 By default, geninfo expects to find the .gcno and .gcda files (compile-
367 and run-time data, respectively) in the same directory.
368 .br
369
370 When this option is used:
371 .br
372
373 .RS
374 geninfo path1 \-\-build\-directory path2 ...
375 .RE
376 .br
377
378 then geninfo will look for .gcno file
379 .br
380
381 .RS
382 path2/relative/path/to/da_base.gcno
383 .RE
384 .br
385
386 when it finds .gcda file
387 .br
388
389 .RS
390 path1/relative/path/to/da_base.gcda.
391 .RE
392
393 Use this option when you have used the
394 .I GCOV_PREFIX
395 environment variable to direct the gcc or llvm runtime environment to write
396 coverage data files to somewhere other than the directory where the code
397 was originally compiled.
398 See
399 .BR gcc (1)
400 and/or search for
401 .I GCOV_PREFIX
402 and
403 .I GCOV_PREFIX_STRIP.
404
405 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.
406
407 .RE
408 .BI "\-\-source\-directory " dirname
409 .RS
410 Add 'dirname' to the list of places to look for source files.
411 .br
412
413 For relative source file paths found in the gcov data \- possibly after substitutions have been applied,
414 .B geninfo
415 will first look for the path from 'cwd' (where genhtml was
416 invoked) and
417 then from each alternate directory name in the order specified.
418 The first location matching location is used.
419
420 This option can be specified multiple times, to add more directories to the source search path.
421 .RE
422
423 .B \-\-branch\-coverage
424 .br
425 .RS
426 Collect retain branch coverage data.
427
428 This is equivalent to using the option "\-\-rc branch_coverage=1"; the option was added to better match the genhml interface.
429
430 .RE
431
432 .B \-\-mcdc\-coverage
433 .br
434 .RS
435 Collect retain MC/DC data.
436
437 This is equivalent to using the option "\-\-rc mcdc_coverage=1".
438 MC/DC coverage capture is supported for GCC versions 14.2 and higher,
439 or LLVM versions 18.1 and higher.
440 .br
441 See
442 .I llvm2lcov \-\-help
443 for details on MC/DC data capture in LLVM.
444
445 .br
446 See the MC/DC section of man
447 .B genhtml(1)
448 for more details
449 .RE
450
451 .B \-\-checksum
452 .br
453 .B \-\-no\-checksum
454 .br
455 .RS
456 Specify whether to generate checksum data when writing tracefiles.
457
458 Use
459 .B \-\-checksum
460 to enable checksum generation or
461 .B \-\-no\-checksum
462 to disable it. Checksum generation is
463 .B disabled
464 by default.
465
466 When checksum generation is enabled, a checksum will be generated for each
467 source code line and stored along with the coverage data. This checksum will
468 be used to prevent attempts to combine coverage data from different source
469 code versions.
470
471 If you don't work with different source code versions, disable this option
472 to speed up coverage data processing and to reduce the size of tracefiles.
473
474 Note that this options is somewhat subsumed by the
475 .B \-\-version\-script
476 option - which does something similar, but at the 'whole file' level.
477
478 .RE
479
480 .B \-\-compat
481 .IR mode = value [, mode = value ,...]
482 .br
483 .RS
484 Set compatibility mode.
485
486 Use
487 .B \-\-compat
488 to specify that geninfo should enable one or more compatibility
489 modes when capturing coverage data. You can provide a comma-separated list
490 of mode=value pairs to specify the values for multiple modes.
491
492 Valid
493 .I values
494 are:
495
496 .B on
497 .RS
498 Enable compatibility mode.
499 .RE
500 .B off
501 .RS
502 Disable compatibility mode.
503 .RE
504 .B auto
505 .RS
506 Apply auto-detection to determine if compatibility mode is required. Note that
507 auto-detection is not available for all compatibility modes.
508 .RE
509
510 If no value is specified, 'on' is assumed as default value.
511
512 Valid
513 .I modes
514 are:
515
516 .B libtool
517 .RS
518 Enable this mode if you are capturing coverage data for a project that
519 was built using the libtool mechanism. See also
520 .BR \-\-compat\-libtool .
521
522 The default value for this setting is 'on'.
523
524 .RE
525 .B hammer
526 .RS
527 Enable this mode if you are capturing coverage data for a project that
528 was built using a version of GCC 3.3 that contains a modification
529 (hammer patch) of later GCC versions. You can identify a modified GCC 3.3
530 by checking the build directory of your project for files ending in the
531 extension .bbg. Unmodified versions of GCC 3.3 name these files .bb.
532
533 The default value for this setting is 'auto'.
534
535 .RE
536 .B split_crc
537 .RS
538 Enable this mode if you are capturing coverage data for a project that
539 was built using a version of GCC 4.6 that contains a modification
540 (split function checksums) of later GCC versions. Typical error messages
541 when running geninfo on coverage data produced by such GCC versions are
542 \'out of memory' and 'reached unexpected end of file'.
543
544 The default value for this setting is 'auto'
545 .RE
546
547 .RE
548
549 .B \-\-compat\-libtool
550 .br
551 .B \-\-no\-compat\-libtool
552 .br
553 .RS
554 Specify whether to enable libtool compatibility mode.
555
556 Use
557 .B \-\-compat\-libtool
558 to enable libtool compatibility mode or
559 .B \-\-no\-compat\-libtool
560 to disable it. The libtool compatibility mode is
561 .B enabled
562 by default.
563
564 When libtool compatibility mode is enabled, geninfo will assume that the source
565 code relating to a .gcda file located in a directory named ".libs" can be
566 found in its parent directory.
567
568 If you have directories named ".libs" in your build environment but don't use
569 libtool, disable this option to prevent problems when capturing coverage data.
570 .RE
571
572 .B \-\-config\-file
573 .I config\-file
574 .br
575 .RS
576 Specify a configuration file to use.
577 See man
578 .B lcovrc(5)
579 for details of the file format and options.
580 Also see the
581 .I config_file
582 entry in the same man page for details on how to include one config file into
583 another.
584
585 When this option is specified, neither the system\-wide configuration file
586 /etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.
587
588 This option may be useful when there is a need to run several
589 instances of
590 .B geninfo
591 with different configuration file options in parallel.
592
593 Note that this option must be specified in full - abbreviations are not supported.
594
595 .RE
596
597 .B \-\-profile
598 .I [ profile\-data\-file ]
599 .br
600 .RS
601 Tell the tool to keep track of performance and other configuration data.
602 If the optional
603 .I profile\-data\-file
604 is not specified, then the profile data is written to a file named with the same
605 basename as the
606 .I \-\-output\-filename, with suffix
607 .I ".json"
608 appended.
609
610 .RE
611
612
613 .B \-\-derive\-func\-data
614 .br
615 .RS
616 Calculate function coverage data from line coverage data.
617
618 Use this option to collect function coverage data, even if the version of the
619 gcov tool installed on the test system does not provide this data. lcov will
620 instead derive function coverage data from line coverage data and
621 information about which lines belong to a function.
622 .RE
623
624 .B \-\-external
625 .br
626 .B \-\-no\-external
627 .br
628 .RS
629 Specify whether to capture coverage data for external source files.
630
631 External source files are files which are not located in one of the directories
632 specified by
633 .I \-\-directory
634 or
635 .I \-\-base\-directory.
636 Use
637 .I \-\-external
638 to include
639 coverpoints in external source files while capturing coverage data or
640 .I \-\-no\-external
641 to exclude them.
642 If your
643 .I \-\-directory
644 or
645 .I \-\-base\-directory
646 path contains a soft link, then actual target directory is not considered to be
647 "internal" unless the
648 .I \-\-follow
649 option is used.
650
651 The
652 .I \-\-no\-external
653 option is somewhat of a blunt instrument; the
654 .I \-\-exclude
655 and
656 .I \-\-include
657 options provide finer grained control over which coverage data is and is not
658 included if your project structure is complex and/or
659 .I \-\-no\-external
660 does not do what you want.
661
662 Data for external source files is
663 .B included
664 by default.
665 .RE
666
667 .B \-f
668 .br
669 .B \-\-follow
670 .RS
671 Follow links when searching .gcda files, as well as to decide whether a
672 particular (symbolically linked) source directory is "internal" to the project or not - see the
673 .I \-\-no\-external
674 option, above, for more information.
675 The
676 .I \-\-follow command line option is equivalent to the
677 .I geninfo_follow_symlinks
678 config file option. See man
679 .B lcovrc(5) for more information.
680 .RE
681
682 .RE
683
684 .B \-\-sort\-input
685 .br
686 .RS
687 Specify whether to sort file names before capture and/or aggregation.
688 Sorting reduces certain types of processing order-dependent output differences.
689 See the
690 .BI sort_input
691 section in
692 man
693 .B lcovrc(5).
694
695 .RE
696
697 .B \-\-gcov\-tool
698 .I tool
699 .br
700 .RS
701 Specify the location of the gcov tool.
702
703 If the
704 .B \-\-gcov\-tool
705 option is used multiple times, then the arguments are concatenated when the callback
706 is executed - similar to how the gcc
707 .B \-Xlinker
708 parameter works. This provides a possibly easier way to pass arguments to
709 your tool, without requiring a wrapper script.
710 In that case, your callback will be executed as:
711 .I tool\-0 'tool\-1; ... 'filename'.
712 Note that the second and subsequent arguments are quoted when passed to
713 the shell, in order to handle parameters which contain spaces.
714
715 The
716 .B \-\-gcov\-tool
717 argument may be a
718 .I split_char
719 separated string - see
720 .B man(4) lcovrc.
721
722 A common use for this option is to enable LLVM:
723 .br
724
725 .RS
726 .BR "geninfo \-\-gcov-tool " "llvm-cov " "\-\-gcov-tool " "gcov ..."
727 .br
728 .BR "geninfo \-\-gcov-tool " "llvm-cov,gcov ..."
729 .RE
730 .br
731
732 Note: 'llvm-cov gcov da_file_name' will generate output in gcov-compatible format as required by lcov.
733
734 If not specified, 'gcov' is used by default.
735
736 .RE
737
738 .B \-h
739 .br
740 .B \-\-help
741 .RS
742 Print a short help text, then exit.
743 .RE
744
745 .B \-\-include
746 .I pattern
747 .br
748 .RS
749 Include source files matching
750 .IR pattern .
751
752 Use this switch if you want to include coverage data for only a particular set
753 of source files matching any of the given patterns. Multiple patterns can be
754 specified by using multiple
755 .B \-\-include
756 command line switches. The
757 .I patterns
758 will be interpreted as shell wildcard patterns (note that they may need to be
759 escaped accordingly to prevent the shell from expanding them first).
760
761 See the lcov man page for details
762
763 .RE
764
765 .B \-\-exclude
766 .I pattern
767 .br
768 .RS
769 Exclude source files matching
770 .IR pattern .
771
772 Use this switch if you want to exclude coverage data from a particular set
773 of source files matching any of the given patterns. Multiple patterns can be
774 specified by using multiple
775 .B \-\-exclude
776 command line switches. The
777 .I patterns
778 will be interpreted as shell wildcard patterns (note that they may need to be
779 escaped accordingly to prevent the shell from expanding them first).
780 Note: The pattern must be specified to match the
781 .B absolute
782 path of each source file.
783
784 Can be combined with the
785 .B \-\-include
786 command line switch. If a given file matches both the include pattern and the
787 exclude pattern, the exclude pattern will take precedence.
788
789 See the lcov man page for details.
790
791 .RE
792
793 .B \-\-erase\-functions
794 .I regexp
795 .br
796 .RS
797 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.
798
799 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
800 .BI derive_function_end_line
801 discussion in the
802 .B lcovrc
803 man page.
804
805
806 .RE
807
808 .B \-\-substitute
809 .I regexp_pattern
810 .br
811 .RS
812 Apply Perl regexp
813 .IR regexp_pattern
814 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.
815
816 .RE
817
818 .B \-\-omit\-lines
819 .I regexp
820 .br
821 .RS
822 Exclude coverage data from lines whose content matches
823 .IR regexp .
824
825 Use this switch if you want to exclude line, branch, and MC/DC coverage data for some particular constructs in your code (e.g., some complicated macro).
826 See the lcov man page for details.
827
828 .RE
829
830 .B \-\-forget\-test\-names
831 .br
832 .RS
833 If non\-zero, ignore testcase names in tracefile -
834 .I i.e.,
835 treat all coverage data as if it came from the same testcase.
836 This may improve performance and reduce memory consumption if user does
837 not need per-testcase coverage summary in coverage reports.
838
839 This option can also be configured permanently using the configuration file
840 option
841 .IR forget_testcase_names .
842 .RE
843
844 .B \-\-msg\-log
845 .I [ log_file_name ]
846 .br
847 .RS
848 Specify location to store error and warning messages (in addition to writing to STDERR).
849 If
850 .I log_file_name
851 is not specified, then default location is used.
852 .RE
853
854 .B \-\-ignore\-errors
855 .I errors
856 .br
857 .RS
858 Specify a list of errors after which to continue processing.
859
860 Use this option to specify a list of one or more classes of errors after which
861 .B geninfo
862 should continue processing instead of aborting.
863 Note that the tool will generate a warning (rather than a fatal error) unless you ignore the error two (or more) times:
864 .br
865 .RS
866 geninfo ... \-\-ignore\-errors unused,unused
867 .RE
868
869 .I errors
870 can be a comma\-separated list of the following keywords:
871
872 .IP branch: 3
873 branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence.
874 .PP
875
876 .IP callback: 3
877 Version script error.
878 .PP
879
880 .IP child: 3
881 child process returned non-zero exit code during
882 .I \-\-parallel
883 execution. This typically indicates that the child encountered an error: see the log file immediately above this message.
884 In contrast: the
885 .B parallel
886 error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error.
887 .PP
888
889 .IP corrupt: 3
890 corrupt/unreadable file found.
891 .PP
892
893 .IP count: 3
894 An excessive number of messages of some class have been reported - subsequent messages of that type will be suppressed.
895 The limit can be controlled by the 'max_message_count' variable. See the lcovrc man page.
896 .PP
897
898 .IP deprecated: 3
899 You are using a deprecated option.
900 This option will be removed in an upcoming release - so you should change your
901 scripts now.
902 .PP
903
904 .IP empty: 3
905 the .info data file is empty (e.g., because all the code was 'removed' or excluded.
906 .PP
907
908 .IP excessive: 3
909 your coverage data contains a suspiciously large 'hit' count which is unlikely
910 to be correct - possibly indicating a bug in your toolchain.
911
912 See the
913 .I excessive_count_threshold
914 section in man
915 .B lcovrc(5)
916 for details.
917 .PP
918
919 .IP fork: 3
920 Unable to create child process during
921 .I \-\-parallel
922 execution.
923 .br
924 If the message is ignored (
925 .I \-\-ignore\-errors fork
926 ), then genhtml
927 will wait a brief period and then retry the failed execution.
928 .br
929 If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task.
930 .PP
931
932 .IP format: 3
933 Unexpected syntax or value found in .info file - for example, negative number or
934 zero line number encountered.
935 .PP
936
937 .IP gcov: 3
938 the gcov tool returned with a non\-zero return code.
939 .PP
940
941 .IP graph: 3
942 the graph file could not be found or is corrupted.
943 .PP
944
945 .IP inconsistent: 3
946 your coverage data is internally inconsistent: it makes two or more mutually
947 exclusive claims. For example, some expression is marked as both an exception branch and not an exception branch. (See man
948 .B genhtml(1)
949 for more details.
950
951 .IP internal: 3
952 internal tool issue detected. Please report this bug along with a testcase.
953 .PP
954
955 .IP mismatch: 3
956 Incorrect information found in coverage data and/or source code - for example,
957 the source code contains overlapping exclusion directives.
958 .PP
959
960 .IP missing: 3
961 File does not exist or is not readable.
962 .PP
963
964 .IP negative: 3
965 negative 'hit' count found.
966
967 Note that negative counts may be caused by a known GCC bug - see
968
969 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080
970
971 and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data.
972 .PP
973
974 .IP package: 3
975 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.
976 .PP
977
978 .IP parallel: 3
979 various types of errors related to parallelism -
980 .I i.e.,
981 a child process died due to an error. The corresponding error message appears in the log file immediately before the
982 .I parallel
983 error.
984
985 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.
986 .PP
987
988 .IP parent: 3
989 the parent process exited while child was active during
990 .I \-\-parallel
991 execution. This happens when the parent has encountered a fatal error -
992 .I e.g.
993 an error in some other child which was not ignored. This child cannot continue working without its parent - and so will exit.
994
995 .PP
996
997 .IP path: 3
998 some file paths were not resolved - e.g., .gcno file corresponding to
999 some .gcda was not found see
1000 .I \-\-build\-directory
1001 option for additional information.
1002
1003 .PP
1004
1005 .IP range: 3
1006 Coverage data refers to a line number which is larger than the number of
1007 lines in the source file. This can be caused by a version mismatch or
1008 by an issue in the
1009 .I gcov
1010 data.
1011 .PP
1012
1013 .IP source: 3
1014 the source code file for a data set could not be found.
1015 .PP
1016 `<
1017 .IP unsupported: 3
1018 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.
1019 .PP
1020
1021 .IP unused: 3
1022 the include/exclude/erase/omit/substitute pattern did not match any file pathnames.
1023 .PP
1024
1025 .IP usage: 3
1026 unsupported usage detected - e.g. an unsupported option combination.
1027 .PP
1028
1029 .IP utility: 3
1030 a tool called during processing returned an error code (e.g., 'find' encountered an unreadable directory).
1031 .PP
1032
1033 .IP version: 3
1034 revision control IDs of the file which we are trying to merge are not the same - line numbering and other information may be incorrect.
1035 .PP
1036
1037 Also see the
1038 .I \-\-ignore\-errors
1039 section in man
1040 .B genhtml(1).
1041 The description there may be more complete and/or more fully explained.
1042
1043 See man
1044 .B lcovrc(5)
1045 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.
1046
1047 .RE
1048
1049 .BI "\-\-expect\-message\-count message_type:expr[,message_type:expr]"
1050 .RS
1051 Give
1052 .B geninfo
1053 a constraint on the number of messages of one or more types which are expected to
1054 be produced during execution. If the constraint is not true, then generate an
1055 error of type
1056 .I "count"
1057 (see above).
1058
1059 See man
1060 .B genhtml(1)
1061 for more details about the flag, as well as the
1062 .I "expect_message_count"
1063 section in man
1064 .B lcovrc(5)
1065 for a description of the equivalent configuration file option.
1066 .RE
1067
1068 .BI "\-\-keep\-going "
1069 .RS
1070 Do not stop if error occurs: attempt to generate a result, however flawed.
1071
1072 This command line option corresponds to the
1073 .I stop_on_error [0|1]
1074 lcovrc option. See man
1075 .B lcovrc(5) for more details.
1076
1077 .RE
1078
1079 .BI "\-\-fail-under-lines "
1080 .I percentage
1081 .br
1082 .RS
1083 Use this option to tell geninfo to exit with a status of 1 if the total
1084 line coverage is less than
1085 .I percentage.
1086 See
1087 .B man lcov(1)
1088 for more details.
1089 .RE
1090
1091 .BI "\-\-preserve "
1092 .RS
1093 Preserve intermediate data files (e.g., for debugging).
1094
1095 By default, intermediate files are deleted.
1096
1097 .RE
1098 .BI "\-\-filter "
1099 .I filters
1100 .RS
1101 Specify a list of coverpoint filters to apply to input data.
1102 See the genhtml man page for details.
1103
1104 .RE
1105 .BI "\-\-demangle\-cpp " [param]
1106 .RS
1107 Demangle C++ method and function names in captured output.
1108 See the genhtml man page for details.
1109
1110 .RE
1111 .B \-i
1112 .br
1113 .B \-\-initial
1114 .RS
1115 Capture initial zero coverage data.
1116
1117 Run geninfo with this option on the directories containing .bb, .bbg or .gcno
1118 files before running any test case. The result is a "baseline" coverage data
1119 file that contains zero coverage for every instrumented line and function.
1120 Combine this data file (using lcov \-a) with coverage data files captured
1121 after a test run to ensure that the percentage of total lines covered is
1122 correct even when not all object code files were loaded during the test.
1123 Also see the
1124 .I \-\-all
1125 flag, below.
1126
1127 Note: the
1128 .B \-\-initial
1129 option is not supported for gcc versions less than 6, and does not generate branch coverage information for gcc versions less than 8.
1130 .RE
1131
1132 .B \-\-all
1133 .RS
1134 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
1135 .I do
1136 have corresponding runtime data.
1137 There will be no runtime data unless some executable which links the corresponding object file has run to completion.
1138
1139 Note that the execution count of coverpoints found only in files which do not have any runtime data will be zero.
1140
1141 This flag is ignored if the
1142 .I \-\-initial
1143 flag is set.
1144
1145 Using the
1146 .B \-\-all
1147 flag is equivalent to executing both
1148 .I geninfo --initial ...
1149 and
1150 .I geninfo ...
1151 and merging the result.
1152
1153 Also see the
1154 .I geninfo_capture_all
1155 entry in
1156 .B man(5) lcovrc.
1157
1158 .RE
1159
1160
1161 .B \-\-no\-markers
1162 .br
1163 .RS
1164 Unless the
1165 .I \-\-no\-markers
1166 option is used,
1167 .BR geninfo
1168 will apply both
1169 .I region
1170 and
1171 .I branch_region
1172 filters to the captured coverae data.
1173 Use this option if you want to get coverage data without regard to exclusion
1174 markers in the source code file.
1175
1176 If any
1177 .I \-\-filter
1178 options are applied, then the default region filters are not used.
1179
1180 .I \-\-no\-markers should not be specified along with
1181 .I \-\-filter.
1182 .RE
1183
1184 .B \-\-no\-recursion
1185 .br
1186 .RS
1187 Use this option if you want to get coverage data for the specified directory
1188 only without processing subdirectories.
1189 .RE
1190
1191 .BI "\-o " output\-filename
1192 .br
1193 .BI "\-\-output\-filename " output\-filename
1194 .RS
1195 Write all data to
1196 .IR output\-filename .
1197
1198 If you want to have all data written to a single file (for easier
1199 handling), use this option to specify the respective filename. By default,
1200 one tracefile will be created for each processed .gcda file.
1201 .RE
1202
1203 .RE
1204 .B \-\-context\-script
1205 .I script
1206 .br
1207 .RS
1208
1209 Use
1210 .I script
1211 to collect additional tool execution context information - to aid in
1212 infrastructure debugging and/or tracking.
1213
1214 See the genhtml man page for more details on the context script.
1215
1216 .br
1217
1218 .RE
1219 .B \-\-criteria\-script
1220 .I script
1221 .br
1222 .RS
1223
1224 Use
1225 .I script
1226 to test for coverage acceptance criteria.
1227
1228 See the genhtml man page for more details on the criteria script.
1229 Note that geninfo does not keep track of date and owner information (see the
1230 .I \-\-annotate\-script
1231 entry in the genhtml man page) - so this information is not passed to the geninfo callback.
1232
1233 .br
1234
1235 .RE
1236 .B \-\-resolve\-script
1237 .I script
1238 .br
1239 .RS
1240 Use
1241 .I script
1242 to find the file path for some source or GCNO file which appears in
1243 an input data file if the file is not found after applying
1244 .I \-\-substitute
1245 patterns and searching the
1246 .I \-\-source\-directory
1247 or
1248 .I \-\-build\-directory
1249 list.
1250
1251 This option is equivalent to the
1252 .B resolve_script
1253 config file option.
1254 .br
1255 In addition, the
1256 .I geninfo_follow_path_links
1257 config file option can be used to resolve source paths to their actual
1258 target.
1259
1260 See man
1261 .B lcovrc(5)
1262 for details.
1263 .RE
1264
1265 .RE
1266 .B \-\-version\-script
1267 .I script
1268 .br
1269 .RS
1270 Use
1271 .I script
1272 to get a source file's version ID from revision control when
1273 extracting data. The ID is used for error checking when merging .info files.
1274 .br
1275
1276 See the genhtml man page for more details on the version script.
1277
1278
1279 .B \-v
1280 .br
1281 .B \-\-verbose
1282 .RS
1283 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.
1284 Also see the
1285 .B \-\-quiet
1286 flag.
1287
1288 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.
1289
1290 .RE
1291 .B \-q
1292 .br
1293 .B \-\-quiet
1294 .RS
1295 Decrement informational message verbosity.
1296
1297 Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed.
1298
1299 .RE
1300 .B \-\-debug
1301 .RS
1302 Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite.
1303
1304 .RE
1305 .B \-\-comment comment_string
1306 .RS
1307 Append
1308 .I comment_string
1309 to list of comments emitted into output result file.
1310 This option may be specified multiple times.
1311 Comments are printed at the top of the file, in the order they were specified.
1312
1313 Comments can be useful to document the conditions under which the trace file was
1314 generated: host, date, environment,
1315 .I etc.
1316
1317
1318 .RE
1319
1320 .BI "\-\-parallel "
1321 .I [ integer ]
1322 .br
1323 .BI "\-j "
1324 .I [ integer ]
1325 .RS
1326 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 to use a single process (no parallelism).
1327
1328 The
1329 .I \-\large\-file
1330 option described below may be necessary to enable parallelism to succeed
1331 in the presence of data files which consume excessive memory in
1332 .B gcov.
1333
1334
1335 Also see the
1336 .I memory, memory_percentage, max_fork_fails, fork_fail_timeout, geninfo_chunk_size
1337 and
1338 .I geninfo_interval_update
1339 entries in man
1340 .B lcovrc(5)
1341 for a description of some options which may aid in parameter tuning and performance optimization.
1342
1343 .RE
1344 .BI "\-\-large\-file "
1345 .I regexp
1346 .RS
1347
1348 GCDA files whose name matches a
1349 .I \-\-large\-file
1350 regexp are processed serially - not in parallel with other files - so that
1351 their
1352 .B gcov
1353 process can use all available system memory.
1354 .br
1355 Use this option is you see errors related to memory allocation from gcov.
1356 .br
1357 This feature is exactly as if you had moved the matching GCDA files to another location and processed them serially, then processed remaining GDCA files in parallel and merged the results.
1358
1359 This option may be used multiple times to specify more than one regexp.
1360
1361 .RE
1362 .BI "\-\-memory "
1363 .I integer
1364 .RS
1365 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.
1366
1367 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.
1368
1369 The configuration file
1370 .I memory_percentage
1371 option provided another way to set the maximum memory consumption.
1372 See man
1373 .B lcovrc(5)
1374 for details.
1375
1376 .RE
1377
1378 .B \-\-rc
1379 .IR keyword = value
1380 .br
1381 .RS
1382 Override a configuration directive.
1383
1384 Use this option to specify a
1385 .IR keyword = value
1386 statement which overrides the corresponding configuration statement in
1387 the lcovrc configuration file. You can specify this option more than once
1388 to override multiple configuration statements.
1389 See man
1390 .BR lcovrc (5)
1391 for a list of available keywords and their meaning.
1392 .RE
1393
1394 .BI "\-t " testname
1395 .br
1396 .BI "\-\-test\-name " testname
1397 .RS
1398 Use test case name
1399 .I testname
1400 for resulting data. Valid test case names can consist of letters, decimal
1401 digits and the underscore character ('_').
1402
1403 This proves useful when data from several test cases is merged (i.e. by
1404 simply concatenating the respective tracefiles) in which case a test
1405 name can be used to differentiate between data from each test case.
1406 .RE
1407
1408 .B \-\-version
1409 .RS
1410 Print version number, then exit.
1411 .RE
1412
1413 .B \-\-tempdir
1414 .I dirname
1415 .br
1416 .RS
1417 Write temporary and intermediate data to indicated directory. Default is "/tmp".
1418 .RE
1419
1420
1421 .SH "TRACEFILE FORMAT"
1422
1423 Following is a quick description of the tracefile format as used by
1424 .BR genhtml ", " geninfo " and " lcov .
1425
1426 A tracefile is made up of several human\-readable lines of text,
1427 divided into sections. If the
1428 .BI "--\-comment\ comment_string"
1429 option is supplied, then
1430
1431 .RS
1432 #comment_string
1433 .RE
1434 will appear at the top of the tracefile. There is no space before or after the
1435 .I #
1436 character.
1437
1438
1439 If available, a tracefile begins with the
1440 .I testname
1441 which is stored in the following format:
1442
1443 .RS
1444 TN:<test name>
1445 .RE
1446
1447 For each source file referenced in the .gcda file, there is a section containing
1448 filename and coverage data:
1449
1450 .RS
1451 SF:<path to the source file>
1452 .RE
1453
1454 An optional source code version ID follows:
1455 .br
1456
1457 .RS
1458 VER:<version ID>
1459 .RE
1460
1461 If present, the version ID is compared before file entries are merged (see
1462 .B "lcov \-\-add\-tracefile"
1463 ), and before the 'source detail' view is generated by genhtml.
1464 See the
1465 .BI "\-\-version\-script " callback_script
1466 documentation and the sample usage in the lcov regression test examples.
1467
1468 Function coverage data follows.
1469 Note that the format of the function coverage data has changed from LCOV 2.2 onward.
1470 The tool continues to be able to read the old format but now writes only the
1471 new format.
1472 This change was made so that
1473 .B function
1474 filter outcome is persistent in the generated tracefile.
1475
1476 Functions and their aliases are recorded contiguously:
1477
1478 First, the leader:
1479
1480 .RS
1481 FNL:<index>,<line number of function start>[,line number of function end>]
1482 .RE
1483
1484 Then the aliases of the function; there will be at least one alias. All aliases of a particular function share the same index.
1485
1486 .RS
1487 FNA:<index>,<execution count>,<name>
1488 .RE
1489
1490
1491 The now-obsolete function data format is:
1492
1493 .RS
1494
1495 .RS
1496 FN:<line number of function start>,[<line number of function end>,]<function name>
1497 .RE
1498
1499 The 'end' line number is optional, and is generated only if the compiler/toolchain
1500 version is recent enough to generate the data (e.g., gcc 9 or newer).
1501 This data is used to support the
1502 .B \-\-erase\-functions
1503 and
1504 .B \-\-show\-proportions
1505 options. If the function end line data is not available, then these features will not work.
1506
1507 Next, there is a list of execution counts for each instrumented function:
1508
1509 .RS
1510 FNDA:<execution count>,<function name>
1511 .RE
1512 .RE
1513
1514 This list is followed by two lines containing the number of functions found
1515 and hit:
1516
1517 .RS
1518 FNF:<number of functions found>
1519 .br
1520 FNH:<number of function hit>
1521 .RE
1522
1523 Note that, as of LCOV 2.2, these numbers count function groups - not the individual aliases.
1524
1525 Branch coverage information is stored one line per branch:
1526
1527 .RS
1528 BRDA:<line_number>,[<exception>]<block>,<branch>,<taken>
1529 .RE
1530
1531 .I <line_number>
1532 is the line number where the branch is found - and is expected to be a non-zero integer.
1533 .br
1534 .I <block>
1535 and
1536 .I <branch>
1537 serve to uniquely define a particular edge in the expression tree of a particular conditional found on the associated line.
1538 .br
1539 Within a particular line,
1540 .I <block>
1541 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.
1542 .br
1543 .I <branch>
1544 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 -
1545 .I <branch>
1546 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.
1547 .I <branch>
1548 appears in the 'tooltip' popup of the associated branch in the
1549 .B genhtml
1550 output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage.
1551 .br
1552 .I <taken>
1553 is either '-' if the corresponding expression was never evaluated (e.g., the basic block containing the branch was never executed) or
1554 a number indicating how often that branch was taken.
1555 .br
1556 .I <exception>
1557 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.
1558 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.
1559
1560 The following are example branch records whose
1561 .I <branch>
1562 expression values are human-readable strings.
1563
1564 .RS
1565 BRDA:10,0,enable,1
1566 .br
1567 BRDA:10,0,!enable,0
1568 .RE
1569 In this case, the corresponding code from line 10 is very likely similar to:
1570 .br
1571 .RS
1572 if (enable) {
1573 .br
1574 ...
1575 .br
1576 }
1577 .br
1578 .RE
1579 such that the associated testcase entered the block ('enable' evaluated to 'true').
1580
1581 Arbitrarily complicated branch expressions are supported - including branch expressions which contain commas (
1582 .I e.g.,
1583 in an expression containing a function call).
1584
1585 Note that particular tools may or may not suppress expressions which are statically true or statically false -
1586 .I e.g.,
1587 expressions using template parameters.
1588 This makes it potentially complicated to compare coverage data generated by two different tools.
1589
1590
1591 Branch coverage summaries are stored in two lines:
1592
1593 .RS
1594 BRF:<number of branches found>
1595 .br
1596 BRH:<number of branches hit>
1597 .RE
1598
1599 MC/DC information is stored one line per expression:
1600
1601 .RS
1602 MCDC:<line_number>,<groupSize>,<sense>,<taken>,<index>,<expression>
1603 .RE
1604 where:
1605
1606 .I <line_number>
1607 is the line number where the condition is found - and is expected to be a non-zero integer.
1608 .br
1609 .I <groupSize>
1610 and
1611 .I <index>
1612 serve to uniquely define a particular element in the expression tree of a particular conditional found on the associated line.
1613 .br
1614 Within a particular line and group,
1615 .I <index>
1616 is an integer numbered from zero to
1617 .I <groupSize> - 1
1618 with no gaps. For some languages and some coding styles, there will only be one group on any particular line.
1619
1620 .I <sense>
1621 is either
1622 .I "f"
1623 or
1624 .I "t",
1625 indicating whether the condition is sensitive to the indicated change - that is, does the condition outcome change if the corresponding changes from 'false' to 'true' or from 'tru' to 'false, respectively.
1626
1627
1628 .I <taken>
1629 is a count - 0 (zero) if the expression was not senstized, non-zero if it was senstized.
1630 Note that tome tools may treat
1631 .I <taken>
1632 as the number of times that the expression was sensitized where others may treat it
1633 as a boolean - 1:sensitized or 0: not sensitized.
1634
1635 .I <expression>
1636 is an arbitrary string, intended to be a meaningful string which will help the user to understand the condition context - see below.
1637 .I <expression>
1638 appears in the 'tooltip' popup of the associated MC/DC condition in the
1639 .B genhtml
1640 output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage.
1641 .br
1642 For a given <groupSize> and <index>, the <expression> should be identical for both
1643 "t" and "f" senses.
1644
1645
1646 The following are example MC/DC records whose
1647 .I <expression>
1648 values are human-readable strings.
1649
1650 .RS
1651 MCDC:10,2,f,0,0,enable
1652 .br
1653 MCDC:10,2,t,1,0,enable
1654 .br
1655 ...
1656 .RE
1657 In this case, the corresponding code from line 10 is very likely similar to:
1658 .br
1659 .RS
1660 if (enable ...) {
1661 .br
1662 ...
1663 .br
1664 }
1665 .br
1666 .RE
1667 such that the associated testcase was sensitive to a change of 'enable' from true to false (but not the converse).
1668
1669 Arbitrarily complicated expressions are supported - including expressions which contain commas (
1670 .I e.g.,
1671 in an expression containing a function call).
1672
1673 Note that particular tools may or may not suppress expressions which are statically true or statically false -
1674 .I e.g.,
1675 expressions using template parameters.
1676 This makes it potentially complicated to compare coverage data generated by two different tools.
1677
1678
1679 MCDC coverage summaries are stored in two lines:
1680
1681 .RS
1682 MRF:<number of conditions found>
1683 .br
1684 MRH:<number of condition hit>
1685 .RE
1686
1687
1688 Then there is a list of execution counts for each instrumented line
1689 (i.e. a line which resulted in executable code):
1690
1691 .RS
1692 DA:<line number>,<execution count>[,<checksum>]
1693 .RE
1694
1695 Note that there may be an optional checksum present for each instrumented
1696 line. The current
1697 .B geninfo
1698 implementation uses an MD5 hash as checksumming algorithm.
1699
1700 At the end of a section, there is a summary about how many lines
1701 were found and how many were actually instrumented:
1702
1703 .RS
1704 LH:<number of lines with a non\-zero execution count>
1705 .br
1706 LF:<number of instrumented lines>
1707 .RE
1708
1709 Each sections ends with:
1710
1711 .RS
1712 end_of_record
1713 .RE
1714
1715 In addition to the main source code file there are sections for all
1716 #included files which also contain executable code.
1717
1718 Note that the absolute path of a source file is generated by interpreting
1719 the contents of the respective .gcno file (see
1720 .BR "gcov " (1)
1721 for more information on this file type). Relative filenames are prefixed
1722 with the directory in which the .gcno file is found.
1723
1724 Note also that symbolic links to the .gcno file will be resolved so that the
1725 actual file path is used instead of the path to a link. This approach is
1726 necessary for the mechanism to work with the /proc/gcov files.
1727
1728
1729 .SH FILES
1730
1731 .I /etc/lcovrc
1732 .RS
1733 The system\-wide configuration file.
1734 .RE
1735
1736 .I ~/.lcovrc
1737 .RS
1738 The per\-user configuration file.
1739 .RE
1740
1741 .I \*[scriptdir]/getp4version
1742 .RS
1743 Sample script for use with
1744 .B --version-script
1745 that obtains version IDs via Perforce.
1746 .br
1747 .RE
1748
1749 .I \*[scriptdir]/get_signature
1750 .RS
1751 Sample script for use with
1752 .B --version-script
1753 that uses md5hash as version IDs.
1754 .br
1755 .RE
1756
1757
1758 .SH AUTHOR
1759 Peter Oberparleiter <[email protected]>
1760
1761 Henry Cox <[email protected]>
1762 .RS
1763 Filtering, error management, parallel execution sections.
1764 .RE
1765
1766 .SH SEE ALSO
1767 .BR lcov (1),
1768 .BR lcovrc (5),
1769 .BR genhtml (1),
1770 .BR genpng (1),
1771 .BR gendesc (1),
1772 .BR gcov (1)
1773 .br
1774
1775 .I \*[lcovurl]
1776 .br