BullseyeCoverage Up Contents Search

Running Instrumented Executables

This section describes how to run instrumented executables on Windows and Unix-like systems. This information also applies to Windows drivers and embedded systems running Linux.

This information does not apply to:

Embedded systems using the small footprint run-time configuration
Unix-like kernel mode

The Coverage File

Each instrumented program must update the same coverage file that was written when the program was built and instrumented. The COVFILE environment variable names this file. Alternatively, you can set COVFILELIST to a list of comma-separated filenames. The COVFILELIST environment variable overrides COVFILE at run-time. At build time, COVFILELIST is not used. The coverage file size does not increase due to run-time activity.

There are two alternative methods for running instrumented programs on computers other than the build system.

Copy the coverage file to each test computer and set COVFILE to the location of the copy. Merge the copies together after testing.
On each test computer, set COVFILE to the same network path of a single instance of the coverage file. If there are many test computers, this method may introduce performance degradation due to limited network bandwidth.

The run-time library saves coverage to the coverage file:

once per second (from a background thread)
when a DLL or shared library is unloaded
when the program exits normally

Error Reporting

When a run-time problem occurs, the run-time library issues an error message. If the COVERR environment variable is set, error messages are appended to the file named and no other error reporting is performed. Otherwise, error messages are reported by all the methods described below.

For programs running on Unix-like systems and Windows console mode programs, error messages are written to standard error.
For Windows GUI programs, error messages are appended to a file named %USERPROFILE%\BullseyeCoverageError.txt if USERPROFILE is set, otherwise %TMP%\BullseyeCoverageError.txt
For Windows console programs, GUI programs and drivers, error messages are written to the debugger interface via DbgPrintEx.

Environment Variables

If the run-time library does not find an environment variable in the process environment strings, it looks for settings in a file named BullseyeCoverageEnv.txt as described for Windows and Unix-like systems.

Daemon Processes

Here are several options for setting the path to the coverage file for a daemon process.

Set COVFILE in the file BullseyeCoverageEnv.txt as described for Windows and Unix-like systems.
Modify the script that launches the daemon so that it first sets the COVFILE environment variable.
Rename your daemon executable and replace it with a shell script that first sets COVFILE and then launches the real daemon.
Use the cov_file function to set the path from inside the daemon.

Updated: 9 Sep 2024