--- name: "kcov" section: "1" platform: "linux" package: "kcov" version: "43-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/kcov" --- # kcov(1) Code coverage analysis for compiled programs and Python scripts ## NAME kcov - Code coverage analysis for compiled programs and Python scripts ## SYNOPSIS **kcov** \[*options*\] *out-dir in-file \[args-for-executable...\]* **kcov** --merge *outdir \ \[path-to-more-coverage...\]* ## DESCRIPTION This manual page documents briefly the **kcov** command. **kcov** is a code coverage tester for ELF binaries, Python scripts and shell scripts. It allows collecting code coverage information from executables without special compiler directives, and continuously produces output from long-running applications. See the GitHub page, https://github.com/SimonKagstrom/kcov, for more documentation. ## OPTIONS - **-p**, **--pid**=*PID* Trace PID instead of executing executable (passing the executable is optional for this case). Under this mode, coverage collection for shared libraries will not work. - **-l**, **--limits**=*low,high* Setup limits for low/high coverage (default: 25,75). - **--include-path**=*P1*\[*,P2*...\] Comma-separated list of paths to include in the report. - **--exclude-path**=*P1*\[*,P2*...\] Comma-separated list of paths to exclude from the report. - **--include-pattern**=*P1*\[*,P2*...\] Comma-separated list of path patterns to include in the report. - **--exclude-pattern**=*P1*\[*,P2*...\] Comma-separated list of path patterns to exclude from the report. - **--exclude-line**=*P1*\[*,P2*...\] Comma-separated list of line patterns to exclude (mark as non-code) - **--exclude-region**=*START:END*\[*,START1:END1*...\] Comma-separated list of regions of lines patterns to exclude (mark as non-code). The region begins with START and ends with END. - **--clean** **Don't accumulate data from multiple runs.** - **--collect-only** **Only collect coverage data, don't produce HTML/Cobertura output.** - **--dump-summary** **Dump a brief coverage summary on stdout after execution** - **--report-only** **Only report HTML/Cobertura output, don't collect data.** - **--merge** **Merge the result of multiple kcov runs. Instead of a program to test, the output paths from previous runs should be given on the command line, or through a wildcard (\*)** - **--coveralls-id=***id* **Upload data to coveralls.io using secret repo\_token or Travis CI service job ID** *id***.** **The ID is taken as a repo\_token if it's longer or equal to 32 characters.** - **--strip-path=***path* **If not set, max common path will be stripped away.** ## UNCOMMON OPTIONS - **--path-strip-level=***N* **Number of path levels to show for common paths (default: 2).** - **--skip-solibs** **Skip coverage collection for shared libraries (improves performance)** - **--verify** **Verify that breakpoints are setup on instruction boundaries. This will slow down execution greatly, but can catch problems where the compiler generates bad DWARF data.** - **--exit-first-process** **exit when the first process exits, i.e., honor the behavior of daemons. The default behavior** **is to return to the console when the last process exits.** - **--cobertura-only** **Generate only cobertura output, as cov.xml, in the output directory. The intended usage is for e.g.,** **vscode coverage gutters, where the output directory can then be pointed to somewhere in the project** **directory to get coverage with little droppings.** - **--python-parser=***PARSER* **Set the python parser to use for Python programs (the default is python). Can be used to** **run with Python 3 on systems where Python 2 is the default.** - **--bash-parser=***PARSER* **Set the bash parser to use for shell scripts (the default is /bin/bash).** - **--bash-method=***METHOD* **Use collection method** *METHOD* **for bash scripts. The method can be either PS4, for use of** **the PS4 environment variable, or DEBUG for use of the DEBUG trap.** - **--bash-handle-sh-invocation** **Handle invocations of /bin/sh scripts via using a LD\_PRELOADed library that replaces execve (i.e., /bin/sh is** **executed as /bin/bash). Does not work well on some systems, so the default is not to use this.** - **--bash-dont-parse-binary-dir** **Kcov parses the directory of the binary for other scripts and add these to the report. If you don't** **want this behavior, this option turns that off.** - **--bash-parse-files-in-dir=***P1***\[***,P2***...\]** **Parse directories for bash scripts.** - **--bash-tracefd-closeexec** **Force children to not be traced by configuring the trace fd as non-cloneable with** **LD\_PRELOAD. Buggy on some systems.** - **--replace-src-path=***P1***:***P2* **Replace source file path P1 with P2, if found.** - **--system-record** **Perform full-system instrumentation on a sysroot, outputting patched binaries which collect coverage data. See doc/full-system-instrumentation.md** **for more information on full-system instrumentation.** - **--system-report** **Produce coverage output for a full-system coverage run.** - **--debug=***level* **Set the debug level, 0...31 (as a mask). Default is 0 for no debug output.** - **--output-interval=***MS* **Set the output writing interval in milliseconds. The default is 5000.** - **--configure=***KEY=VAL* **Configure key/value pairs of internal options. See --help --uncommon-options for possible configuration options.** - **--patchelf=CMD** **For system mode, set the patchelf command (default patchelf).** ## EXAMPLES **Check coverage for ./frodo and generate HTML output in /tmp/kcov and cobertura output in /tmp/kcov/frodo/cobertura.xml** **kcov /tmp/kcov ./frodo** **Check coverage for ./frodo but only include source files names with the string src/frodo** **kcov --include-pattern=src/frodo /tmp/kcov ./frodo** **Same as above but split collecting and reporting (perhaps on two different computers)** **kcov --collect-only /tmp/kcov ./frodo** **kcov --report-only --include-pattern=src/frodo /tmp/kcov ./frodo** ## HTML OUTPUT **The HTML output shows executed and non-executed lines of the source code. Some** **lines can map to multiple instrumentation points, for example for inlined functions** **(where every inlining of them will generate a separate instrumentation point).** **This is shown in the left column as 1/3 for example, which means that one of the** **three instrumentation points has been executed.** **A special output link is \[merged\], which shows the union of all covered programs.** **This can be useful for example when you have unit tests in multiple binaries which** **share a subset of source files.** ## COBERTURA OUTPUT **Kcov also outputs data in the Cobertura XML format, which allows integrating kcov** **output in Jenkins (see https://cobertura.github.io/cobertura/ and https://www.jenkins.io/).** **The Cobertura output is placed in a file named out-path/exec-filename/cobertura.xml.** ## JSON OUTPUT **Kcov generates a very generic json file which includes the overall percent covered** **for a single command and the count of lines instrumented and covered. It also includes** **a summary of each source file with a percentage and line counts. This allows easy** **integration with GitlabCI (see** **https://docs.gitlab.com/ce/user/project/pipelines/settings.html).** **The JSON output is placed in a file named out-path/exec-filename/coverage.json.** ## AUTHOR **Kcov was written by Simon Kagstrom, building upon bcov by Thomas Neumann.** **This manual page was written by Michael Tautschnig \,** **for the Debian project (but may be used by others).**