NAME

       ggcov-run - run an instrumented test program

SYNOPSIS

       ggcov-run [options] [--] program args...

DESCRIPTION

       Ggcov-run can be used to run a test program, instrumented using gcc --coverage when built,
       under certain conditions.  It's use is entirely optional, as the default behaviour of  the
       gcc instrumention is designed to be useful under most conditions.

       Ggcov-run  takes as arguments a program and it's arguments, and runs the program with some
       behavioural modifications (in the manner of strace).  If given no options, the program  is
       run without any modifications.

GCDA FILE LOCATIONS

       One  problem  with the default behaviour of the gcc instrumentation involves the locations
       of coverage data.  Instrumented test programs will read, modify and re-write  .gcda  files
       when  the  program  exits.   The  locations  of  those files are chosen by the compiler at
       compile time; the files will be placed in the build directory next to the corresponding .c
       file.   The  compiler  saves this information in the .o file.  For example, if you compile
       the  file   foo.c   in   the   directory   /home/me/software/quux,   then   the   pathname
       /home/me/software/quux/foo.gcda  is  hardcoded  in  the test program.  Of course, programs
       that examine coverage data, like ggcov, look for the .gcda files there.

       For many test applications  this  works  just  fine.   Problems  arise  however  when  the
       instrumented  program  needs  to  be  run on another machine, or as another userid, or the
       build directory is volatile, or in any other  test  scenario  where  the  build  directory
       either does not exist or is not writable by the running test program.  In these cases, you
       need to do some ad-hoc file moving before and after testing in  order  to  get  the  .gcda
       files in the right location on the right machine with the right permissions.

       A better approach is to use ggcov-run with the --gcda-prefix option.  This option takes as
       a value a directory which is prepended to the pathname of each .gcda file the test program
       accesses.  So, continuing the above example, running the test program like this:

       me$ ggcov-run --gcda-prefix=/tmp/gcda ./testprogram test-args...

       will  result  in  a  .gcda file being written to /tmp/gcda/home/me/software/quux/foo.gcda.
       The directory tree will be automatically created as the .gcda files are written,  and  the
       file and directory permissions will allow read access for all users.

       Note  that  ggcov  also  has  a --gcda-prefix option which can be used to search for .gcda
       files in locations other than the build directory.  In our example:

       me$ cd /home/me/software/quux
       me$ ggcov --gcda-prefix=/tmp/gcda -r .

OPTIONS

       -p dir, --gcda-prefix=dir
              Cause the test program, and any child processes it runs, to redirect  any  absolute
              filename ending in .gcda to a filename underneath the directory dir.

CAVEATS

       Ggcov-run  uses  a shared library shim and the LD_PRELOAD feature of the runtime linker to
       intercept certain library calls by the  instrumented  program.   For  very  good  security
       reasons,  LD_PRELOAD  is  disabled for setuid or setgid programs.  So if your test program
       relies on setuid behaviour, ggcov-run will not work.  One possible workaround  is  to  use
       sudo or su to change userid before using ggcov-run, like this:

       me$ sudo -u otheruser ggcov-run --gcda-prefix=/foo ./testprogram

AUTHOR

       Written by Greg Banks <gnb@users.sourceforge.net>.

COPYRIGHT

       ggcov is Copyright © 2001-2011 Greg Banks <gnb@users.sourceforge.net>.
       This is free software; see the COPYING file for copying conditions.  There is NO warranty;
       not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       ggcov-run(1).