Debian Codegraph @

man/lcov.1

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