gcov(1)                                                         gcov(1)

  gcov

  NAME

    gcov - GNU C coverage tool

  SYNOPSIS

    gcov [-bflnv] [-o dir] srcfile ...

  DESCRIPTION

    The gcov(1) utility produces profiling information about code coverage. It
    works on programs compiled with the gcc options -fprofile-arcs and -ftest-
    coverage. With these options, the compiler generates additional files with
    the extensions .bband .bbg in the source directory. Before running
    gcov(1), run the program to be tested, in the source directory. Running
    the program creates files with the extension .da; these files are needed
    by gcov(1). (Execution counts in the .da data files is cumulative; if the
    program is executed while there is an existing .da file in the directory,
    the new execution counts are added to the existing ones.)

    While running, gcov(1) creates a logfile (unless the -n option is given)
    which contains the results of the analysis. A description of the logfile
    format is given later.

  OPTIONS

    -b
        Branches. Writes branch frequencies into the output file and write a
        summary of branch information to standard output. This often enlarges
        the size of the output file.

    -f
        Functions. Writes summaries for each function, as well as for the
        entire file.

    -l
        Long file names. This is useful if header files containing code and
        are included in multiple files. Normally, for each object module
        srcfile gcov(1) creates a file named srcfile.gcov. With this option,
        files are named program.srcfile.gcov.

    -n
        No output. Does not create the output file srcfile.gcov.
    -o dir
        Looks for the object files and the .bb, .bbg, and .da files in dir.

    -v
        Version. Displays the version number on standard error and then exits.

    Results are less reliable if the code is compiled with the optimization
    flag. The gcov(1) program matches code on a line-by-line basis; by
    combining operations, the optimizer weakens the relationship between the
    code and the executable.

  LOGFILE FORMAT

    The logfile is a copy of the source file. Each line is prefixed by a
    frequency count, ###### if it was never executed, or two tab characters.
    For example, after running this program four times:

          #include 

              main()
              {
               4       int i, odd, even;
               4       odd = even = 0;

             404        for (i=0; i<100; i++)
                   {
             400           if (i%2)
             200             odd++;
                         else
             200             even++;
             400           if (i==100)
          ######              printf("Impossible!0);
             400        }
               4       if (i==100)
               4          printf("Certain!0);
               4       printf("there are %d odd numbers0, odd);
               4       printf("there are %d even numbers0, even);
               4       return(0);
               4    }

    The -b option changes this output:

          #include 

              main()
              {
               4       int i, odd, even;
               4       odd = even = 0;

             404       for (i=0; i<100; i++)
    branch 0 taken = 99%
    branch 1 taken = 100%
    branch 2 taken = 100%

             {
             400          if (i%2)
    branch 0 taken = 50%
             200             odd++;
    branch 0 taken = 100%
                    else
             200             even++;
             400          if (i==100)
    branch 0 taken = 100%
          ######             printf("Impossible!0);
    call 0 never executed
             400       }
               4       if (i==100)
    branch 0 taken = 0%
               4            printf("Impossible!0);
    call 0 returns = 100%
               4       printf("there are %d odd numbers0, odd);
    call 0 returns = 100%
               4       printf("there are %d even numbers0, even);
    call 0 returns = 100%
               4       return(0);
    branch 0 taken = 100%
               4    }
    call 0 returns = 0%
    call 1 returns = 100%

    A line is output after each basic block of code. If more than one block of
    code ends on a line of code, that line of code will have more than one
    output line after it.

    Each branch is numbered. In general, the left-most branch on a line gets
    numbered first, but there is no simple way to map the numbers to the
    source. If a branch is executed, the -b option causes gcov(1) to print the
    number of times it was taken divided by the number of times the branch was
    executed (as a percentage). In four executions of the program, the for
    line was executed 404 times and the branch was taken 400 times, or 99%.

    The percentage for function calls is calculated in a similar way: the
    number of times the call returned divide by the number of times the call
    was executed. (Usually only calls such as exit(3) or longjmp(3) show a
    value other than 100%.)

  DIAGNOSTICS

    The gcov(1) utility exits with status 0 for success, and >0 if an error
    occurred.

  FILES

    The gcov(1) command makes use of the following files:
    srcfile.bb
        A list of source files, header files, functions and line numbers.
        Generated by the GNU C compiler (gcc) with the -fprofile-arcs option.
    srcfile.bbg
        A list of program flow arcs use to construct the program flow.
        Generated by gcc with the -fprofile-arcs option.
    srcfile.da
        Execution counts (data) generated by a program whose modules were
        compiled with the -ftest-coverage option.
    srcfile.gcov
        A log of execution results, created by gcov(1).

  SEE ALSO

    gcc(1)