Gcov

gcov
Operating system	Unix-like
Type	Code coverage
License	GNU General Public License and other free software licenses [ which? ]
Website	gcc.gnu.org/onlinedocs/gcc/Gcov.html

Last updated October 24, 2024

Gcov is a source code coverage analysis and statement-by-statement profiling tool. Gcov generates exact counts of the number of times each statement in a program is executed and annotates source code to add instrumentation. Gcov comes as a standard utility with the GNU Compiler Collection (GCC) suite.^[1]

The gcov utility gives information on how often a program executes segments of code.^[2] It produces a copy of the source file, annotated with execution frequencies. The gcov utility does not produce any time-based data and works only on code compiled with the GCC suite. The manual claims it is not compatible with any other profiling or test coverage mechanism,^[3] but it works with llvm-generated files too.^[4]

Description

gcov produces a test coverage analysis of a specially instrumented program. The options -fprofile-arcs -ftest-coverage should be used to compile the program for coverage analysis (first option to record branch statistics and second to save line execution count); -fprofile-arcs should also be used to link the program.^[2] After running such program will create several files with ".bb" ".bbg" and ".da" extensions (suffixes), which can be analysed by gcov. It takes source files as command-line arguments and produces an annotated source listing. Each line of source code is prefixed with the number of times it has been executed; lines that have not been executed are prefixed with "#####".^[2]

gcov creates a logfile called sourcefile.gcov which indicates how many times each line of a source file sourcefile.c has executed. This annotated source file can be used with gprof, another profiling tool, to extract timing information about the program.

Example

The following program, written in C, loops over the integers 1 to 9 and tests their divisibility with the modulus (%) operator.

#include<stdio.h>intmain(void){inti;for(i=1;i<10;i++){if(i%3==0)printf("%d is divisible by 3\n",i);if(i%11==0)printf("%d is divisible by 11\n",i);}return0;}

To enable coverage testing the program must be compiled with the following options:

$ gcc-Wall-fprofile-arcs-ftest-coveragecov.c

where cov.c is the name of the program file. This creates an instrumented executable which contains additional instructions that record the number of times each line of the program is executed. The option -ftest-coverage adds instructions for counting the number of times individual lines are executed, while -fprofile-arcs incorporates instrumentation code for each branch of the program. Branch instrumentation records how frequently different paths are taken through ‘if’ statements and other conditionals.

The executable can then be run to analyze the code and create the coverage data.

$ ./a.out

The data from the run is written to several coverage data files with the extensions ‘.bb’ ‘.bbg’ and ‘.da’ respectively in the current directory.

If the program execution varies based on the input parameters or data, it can be run multiple times and the results will accumulate in the coverage data files for overall analysis.

This data can be analyzed using the gcov command and the name of a source file:

$ gcovcov.c 88.89% of 9 source lines executed in file cov.cCreating cov.c.gcov

The gcov command produces an annotated version of the original source file, with the file extension ‘.gcov’, containing counts of the number of times each line was executed:

#include<stdio.h>intmain(void){1inti;10for(i=1;i<10;i++){9if(i%3==0)3printf("%d is divisible by 3\n",i);9if(i%11==0)######        printf ("%d is divisible by 11\n", i);9}1return0;1}

The line counts can be seen in the first column of the output. Lines which were not executed are marked with hashes ‘######’.

Command-line options

Gcov command line utility supports following options while generating annotated files from profile data:^[5]^[6]

-h (--help): Display help about using gcov (on the standard output), and exit without doing any further processing.
-v (--version): Display the gcov version number (on the standard output), and exit without doing any further processing.
-a (--all-blocks): Write individual execution counts for every basic block. Normally gcov outputs execution counts only for the main blocks of a line. With this option you can determine if blocks within a single line are not being executed.
-b (--branch-probabilities): Write branch frequencies to the output file, and write branch summary info to the standard output. This option allows you to see how often each branch in your program was taken. Unconditional branches will not be shown, unless the -u option is given.
-c (--branch-counts): Write branch frequencies as the number of branches taken, rather than the percentage of branches taken.
-n (--no-output): Do not create the gcov output file.
-l (--long-file-names): Create long file names for included source files. For example, if the header file x.h contains code, and was included in the file a.c, then running gcov on the file a.c will produce an output file called a.c##x.h.gcov instead of x.h.gcov. This can be useful if x.h is included in multiple source files and you want to see the individual contributions. If you use the `-p' option, both the including and included file names will be complete path names.
-p (--preserve-paths): Preserve complete path information in the names of generated .gcov files. Without this option, just the filename component is used. With this option, all directories are used, with `/' characters translated to `#' characters, . directory components removed and unremoveable .. components renamed to `^'. This is useful if sourcefiles are in several different directories.
-r (--relative-only): Only output information about source files with a relative pathname (after source prefix elision). Absolute paths are usually system header files and coverage of any inline functions therein is normally uninteresting.
-f (--function-summaries): Output summaries for each function in addition to the file level summary.
-o directory|file (--object-directory directory or --object-file file): Specify either the directory containing the gcov data files, or the object path name. The .gcno, and .gcda data files are searched for using this option. If a directory is specified, the data files are in that directory and named after the input file name, without its extension. If a file is specified here, the data files are named after that file, without its extension.
-s directory (--source-prefix directory): A prefix for source file names to remove when generating the output coverage files. This option is useful when building in a separate directory, and the pathname to the source directory is not wanted when determining the output file names. Note that this prefix detection is applied before determining whether the source file is absolute.
-u (--unconditional-branches): When branch probabilities are given, include those of unconditional branches. Unconditional branches are normally not interesting.
-d (--display-progress): Display the progress on the standard output.

Coverage summaries

Lcov is a graphical front-end for gcov. It collects gcov data for multiple source files and creates HTML pages containing the source code annotated with coverage information. It also adds overview pages for easy navigation within the file structure. Lcov supports statement, function, and branch coverage measurement.^[7] There is also a Windows version.

Gcovr provides a utility for managing the use of gcov and generating summarized code coverage results. This command is inspired by the Python coverage.py package, which provides a similar utility in Python. Gcovr produces either compact human-readable summary reports, machine readable XML reports or a graphical HTML summary. The XML reports generated by gcovr can be used by Jenkins to provide graphical code coverage summaries. Gcovr supports statement and branch coverage measurement^[8]

SCov is a utility that processes the intermediate text format generated by gcov (using gcov -i) to generate reports on code coverage. These reports can be a simple text report, or HTML pages with more detailed reports.^[9]

Related Research Articles

The GNU Debugger (GDB) is a portable debugger that runs on many Unix-like systems and works for many programming languages, including Ada, Assembly, C, C++, D, Fortran, Haskell, Go, Objective-C, OpenCL C, Modula-2, Pascal, Rust, and partially others.

sed is a Unix utility that parses and transforms text, using a simple, compact programming language. It was developed from 1973 to 1974 by Lee E. McMahon of Bell Labs, and is available today for most operating systems. sed was based on the scripting features of the interactive editor ed and the earlier qed. It was one of the earliest tools to support regular expressions, and remains in use for text processing, most notably with the substitution command. Popular alternative tools for plaintext string manipulation and "stream editing" include AWK and Perl.

A shell script is a computer program designed to be run by a Unix shell, a command-line interpreter. The various dialects of shell scripts are considered to be command languages. Typical operations performed by shell scripts include file manipulation, program execution, and printing text. A script which sets up the environment, runs the program, and does any necessary cleanup or logging, is called a wrapper.

Lex is a computer program that generates lexical analyzers. It is commonly used with the yacc parser generator and is the standard lexical analyzer generator on many Unix and Unix-like systems. An equivalent tool is specified as part of the POSIX standard.

In software development, Make is a command-line interface software tool that performs actions ordered by configured dependencies as defined in a configuration file called a makefile. It is commonly used for build automation to build executable code from source code. But, not limited to building, Make can perform any operation available via the operating system shell.

The C preprocessor is the macro preprocessor for several computer programming languages, such as C, Objective-C, C++, and a variety of Fortran languages. The preprocessor provides inclusion of header files, macro expansions, conditional compilation, and line control.

MinGW, formerly mingw32, is a free and open source software development environment to create Microsoft Windows applications.

printf is a C standard library function that formats text and writes it to standard output.

Uncontrolled format string is a type of code injection vulnerability discovered around 1989 that can be used in security exploits. Originally thought harmless, format string exploits can be used to crash a program or to execute harmful code. The problem stems from the use of unchecked user input as the format string parameter in certain C functions that perform formatting, such as printf . A malicious user may use the %s and %x format tokens, among others, to print data from the call stack or possibly other locations in memory. One may also write arbitrary data to arbitrary locations using the %n format token, which commands printf and similar functions to write the number of bytes formatted to an address stored on the stack.

In computing, gettext is an internationalization and localization system commonly used for writing multilingual programs on Unix-like computer operating systems. One of the main benefits of gettext is that it separates programming from translating. The most commonly used implementation of gettext is GNU gettext, released by the GNU Project in 1995. The runtime library is libintl. gettext provides an option to use different strings for any number of plural forms of nouns, but this feature has no support for grammatical gender. The main filename extensions used by this system are .POT, .PO and .MO.

In computing, echo is a command that outputs the strings that are passed to it as arguments. It is a command available in various operating system shells and typically used in shell scripts and batch files to output status text to the screen or a computer file, or as a source part of a pipeline.

split is a utility on Unix, Plan 9, and Unix-like operating systems most commonly used to split a computer file into two or more smaller files.

In computing, netstat is a command-line network utility that displays open network sockets, routing tables, and a number of network interface and network protocol statistics. It is available on Unix, Plan 9, Inferno, and Unix-like operating systems including macOS, Linux, Solaris and BSD. It is also available on IBM OS/2 and on Microsoft Windows NT-based operating systems including Windows XP, Windows Vista, Windows 7, Windows 8 and Windows 10.

In computing, cmp is a command-line utility on Unix and Unix-like operating systems that compares two files of any type and writes the results to the standard output. By default, cmp is silent if the files are the same; if they differ, the byte and line number at which the first difference occurred is reported. The command is also available in the OS-9 shell.

rm is a basic command on Unix and Unix-like operating systems used to remove objects such as computer files, directories and symbolic links from file systems and also special files such as device nodes, pipes and sockets, similar to the del command in MS-DOS, OS/2, and Microsoft Windows. The command is also available in the EFI shell.

In Unix, Plan 9, and Unix-like operating systems, the strip program is a command-line utility used to remove non-essential information from executable binary programs and object files. This information, which is not required for execution, typically includes debugging data, symbol tables, relocation information, and other metadata. Its primary purpose is to reduce the file size of the binary executable and potentially increase performance. The output of this process is known as a stripped binary.

In software development, CMake is cross-platform free and open-source software for build automation, testing, packaging and installation of software by using a compiler-independent method. CMake is not a build system itself; it generates another system's build files. It supports directory hierarchies and applications that depend on multiple libraries. It can invoke native build environments such as Make, Qt Creator, Ninja, Android Studio, Apple's Xcode, and Microsoft Visual Studio. It has minimal dependencies, requiring only a C++ compiler on its own build system.

Oracle Developer Studio, formerly named Oracle Solaris Studio, Sun Studio, Sun WorkShop, Forte Developer, and SunPro Compilers, is the Oracle Corporation's flagship software development product for the Solaris and Linux operating systems. It includes optimizing C, C++, and Fortran compilers, libraries, and performance analysis and debugging tools, for Solaris on SPARC and x86 platforms, and Linux on x86/x64 platforms, including multi-core systems.

Trucov is an open source code coverage analysis tool for GCC versions 4.0 and later that aims to be a gcov replacement. Trucov improves upon gcov by providing more granular and machine readable output, such as DOT Files representing control-flow graph of the program. The use of DOT Files allows for other common tools like GraphViz to be used to produce coverage graphs. Trucov was developed as a senior design project at Washington State University.

Tcov is a source code coverage analysis and statement-by-statement profiling tool for software written in Fortran, C and C++. Tcov generates exact counts of the number of times each statement in a program is executed and annotates source code to add instrumentation. It is a standard utility, provided free of cost with Sun Studio software.

References

↑ "How Gcov works-tool part of GCC" (PDF). Archived from the original (PDF) on April 9, 2014. Retrieved February 12, 2012.{{cite journal}}: Cite journal requires |journal= (help)
1 2 3 Brian J. Gough. An Introduction to GCC - for the GNU compilers gcc and g++ - Coverage testing with gcov . Retrieved February 12, 2012.
↑ "gcov man page" . Retrieved February 12, 2012.
↑ "gcov llvm" . Retrieved November 12, 2022.
↑ gnu.org. "Gcov Command line options" . Retrieved Feb 11, 2012.
↑ linux commands. "Gcov Command line options". Archived from the original on 2012-05-23. Retrieved Feb 12, 2012.
↑ "Lcov".
↑ "Gcovr".
↑ "SCov".

This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.

[1] "How Gcov works-tool part of GCC" (PDF). Archived from the original (PDF) on April 9, 2014. Retrieved February 12, 2012.{{cite journal}}: Cite journal requires |journal= (help)

[intro81-2] 1 2 3 Brian J. Gough. An Introduction to GCC - for the GNU compilers gcc and g++ - Coverage testing with gcov . Retrieved February 12, 2012.

[3] "gcov man page" . Retrieved February 12, 2012.

[4] "gcov llvm" . Retrieved November 12, 2022.

[5] u.org. "Gcov Command line options" . Retrieved Feb 11, 2012.

[6] ux commands. "Gcov Command line options". Archived from the original on 2012-05-23. Retrieved Feb 12, 2012.

[7] "Lcov".

[8] "Gcovr".

[9] "SCov".

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]