PureCoverage(1) LICENSED SOFTWARE PureCoverage(1) NAME purecov - detect untested portions of programs SYNOPSIS purecov [-option ...] $(CC) $(CFLAGS) -o program $(OBJS) $(LIBS) purecov -view [programs.pcv] purecov -export[=ascii.data] programs.pcv purecov -merge=merged.pcv programs.pcv DESCRIPTION PureCoverage detects unused portions of your program - places where more intensive testing is necessary to exercise the code. PureCoverage tracks coverage information across multiple runs of a program, and permits analysis of coverage for shared portions of multiple programs. PureCoverage includes an interactive Viewer for analysis of the coverage information, a merging tool for manipulating coverage data files, and an export tool for converting the data into an ASCII format suitable for further processing by scripts and other programs. PureCoverage also includes a variety of scripts for performing data analysis and manipu- lation, and also as examples for users wishing to write their own scripts. Setting Up PureCoverage is typically loaded from CD-ROM, and then installed using the pure_install command. You will need a license certificate with a valid password; enter the infor- mation requested exactly as printed on the certificate. For more information, see the ``System Administrator's Guide.'' To use PureCoverage, create a symbolic link from where purecov is installed (purecovhome/purecov) to /usr/local/bin/purecov (or some other directory on each user's $PATH): example% ln -s purecovhome/purecov /usr/local/bin/purecov PureCoverage follows this symbolic link to find the other files it needs in the installation directory. Alterna- tively, add purecovhome to each user's $PATH. The PureCoverage scripts should also be made available using a similar process. The scripts normally reside in the directory purecovhome/scripts. Building Add the word purecov to the beginning of the link line in your Makefile. For example: Printed 1/6/97 15 Jan 1996 1 PureCoverage(1) LICENSED SOFTWARE PureCoverage(1) program: $(OBJS) purecov [-option ...] $(CC) $(CFLAGS) -o program \ $(OBJS) $(LIBS) PureCoverage modifies the object code at link time to pro- duce an equivalent program which has additional counting instructions built in. The -options specified on the command line are PureCoverage options to customize its operation. Running The PureCoverage-instrumented program is run exactly as the original program. When the program finishes running, a file program.pcv will be created or updated with the new coverage data. Viewing and Manipulating Data To invoke the Viewer on the resulting file, use the command: example% purecov -view [-option ...] program.pcv This displays the coverage data in the interactive Viewer. To convert a .pcv file into an ASCII format for further pro- cessing, use the command: example% purecov -export[=ascii.data] [-option ...] \ program.pcv This sends the output to a file named ascii.data; if this filename is not supplied, output will be sent to the stan- dard output, which may then be redirected to another pro- gram. To combine several example% purecov -merge=merged.pcv [-option ...] \ first.pcv second.pcv ... All three of these commands permit specification of multiple .pcv files, not just -merge. Purify and PureCoverage PureCoverage is designed to work with Purify to collect code coverage information at the same time as monitoring the code for access errors and memory leaks. To create a program instrumented by Purify and PureCoverage, use a command like: purify [-option ...] purecov [-option ...] \ $(CC) $(CFLAGS) -o program $(OBJS) $(LIBS) OPTIONS Printed 1/6/97 15 Jan 1996 % PureCo3erage(1) LICENSED SOFTWARE PureCo3erage(1) PureCoverage's operation can be customized for your program. By specifying options either at program build-time or pro- gram run-time, you can affect where PureCoverage data goes and how the program is instrumented and linked. Each option is a word or phrase that begins with a hyphen, for example -counts-file. PureCoverage ignores the case and any hyphens or underscores in the option name. The option -counts-file is equivalent to -COUNTS_FILE and -CountsFile. All options have default values. You may override these values using the assignment syntax: -option-name[=[value]] Note that no spaces are permitted on either side of the equals sign (=) if it is supplied. You may specify PureCoverage options: o on the build-time link line; or o in the environment variables $PURECOVOPTIONS or $PUREOPTIONS. Link Line Options Options may be specified on the link line, e.g.: purecov -cache-dir=$(HOME)/pcache $(CC) ... Build-time options apply to the PureCoverage build command being run. Run-time options may also be specified on the link line. These are built into the executable and become the default values at run-time when the PureCoverage- instrumented executable is run. This is a convenient way to build a program with non-standard default values for certain options, for example: purecov -counts-file=counts $(CC) ... Environment Variable Options Any option may be specified in the environment variables $PURECOVOPTIONS or $PUREOPTIONS. Note: Values in $PURECOVOPTIONS have precedence over values from $PUREOPTIONS. Build-time options specified in environment variables are applied when applications are built. Options specified explicitly on the build-time link line override environmen- tal values. Run-time options specified in environment variables are Printed 1/6/97 15 Jan 1996 % PureCo4erage(1) LICENSED SOFTWARE PureCo4erage(1) applied when PureCoverage-instrumented applications are run. The environmental values in force when the program is run override any defaults specified on the link line when the application was built. Note: If an option is specified more than once in an environment variable, the first value is used. To add an overriding value for the -log-file option, for example, without changing other options specified, use a command like: csh% setenv PURECOVOPTIONS "-log-file=new $PURECOVOPTIONS" ksh$ export PURECOVOPTIONS="-log-file=new $PURECOVOPTIONS" OPTION TYPE DEFAULT Caching Options (build-time options) -cache-dir directory purecovhome/cache This option sets the global directory where PureCoverage- instrumented versions of libraries will be cached. -always-use-cache-dir bool no This option forces all PureCoverage-instrumented versions of libraries to be written to the global cache directory. When you use the default value, PureCoverage caches to the origi- nal library's directory, if it is writable. If the direc- tory is not writable, PureCoverage caches it to the value of -cache-dir. Linker Options (build-time options) -linker program-name /bin/ld This option specifies the name of the linker that PureCoverage should invoke to produce the executable. Logfile Options -log-file filename stderr This option specifies the name of the logfile for PureCoverage messages. Normally, PureCoverage routes its report to the standard error stream. The filename may include one or more of these special keywords: o %p is replaced by the process id; o %v is replaced by the program name; and Printed 1/6/97 15 Jan 1996 % PureCo5erage(1) LICENSED SOFTWARE PureCo5erage(1) o %V is replaced by the full pathname of the program. These keywords are useful when you fork many PureCoverage- instrumented programs and want separate logfiles for each one. -append-logfile bool no This option enables PureCoverage output to be appended to the current logfile rather than replacing it. Filename Options -auto-mount-prefix directory /tmp_mnt This option is used to specify the directory prefix used by the file system auto-mounter, usually /tmp_mnt, to mount remote file systems in NFS environments. Use this option to strip the prefix, if present, to improve the readability of source filenames in PureCoverage reports. -counts-file filename program.pcv This option specifies where the resulting coverage data will be written when the program exits. The filename may include one or more of these special keywords: o %p is replaced by the process id; o %v is replaced by the program name; and o %V is replaced by the full pathname of the program. If the specified file already exists, the resulting coverage data will be combined with the coverage data already present in the file. -program-name program name argv[0] This option specifies the full pathname of the PureCoverage-instrumented program if argv[0] contains an undesirable or incorrect value. This can happen if you change argv[0] in your program, or if your program is invoked by an exec() call whose path differs from the argu- ment it passes as argv[0] to your program. In such cases, PureCoverage can not find the program file, and therefore can not interpret addresses as function names. You may need to use this option if you find little or no symbolic information in the reports from your PureCoverage- Printed 1/6/97 15 Jan 1996 % PureCo6erage(1) LICENSED SOFTWARE PureCo6erage(1) instrumented program. -user-path dir list none This option specifies a colon-separated list of directories in which to search to find programs and source code. For example, if you have a source tree in your home directory but you also link with GNU source code, you could use: -user-path=/usr/home/chris/src:/usr/local/gnu/src PureCoverage searches for the executable file from which to read the symbol table in your $PATH, and then in directories listed in -user-path. See also -program-name. Additional Options -force-merge bool no Normally, PureCoverage accumulates data for a given file across multiple executions of the programs using that file. After that file is recompiled, the old data will be disre- garded and replaced with new data when the program next runs. This ensures that coverage data is always accurate with respect to the latest version of each source file. In certain circumstances, it may be desirable to override this behavior. A typical situation is when a single source file is conditionally compiled with slight differences for use in two different programs. If you try to merge the cov- erage data for these two programs, PureCoverage will report that one of them is out of date relative to the other and discard the ``old'' data. The -force-merge=yes option will cause PureCoverage to com- bine the data regardless of the timestamps stored in the data. Care must be exercised in using this option to ensure that data may be meaningfully combined. -handle-signals signal list none -ignore-signals signal list system dependent PureCoverage installs a signal handler for many of the pos- sible software signals which may be delivered to an instru- mented process, to print an informative message and save coverage data to the .pcv file when the process crashes. The option value specifies which signals are reported and cause data to be saved. It is a comma-delimited list of signal names. The default value of -ignore-signals is sys- tem dependent. The defaults are: Printed 1/6/97 15 Jan 1996 % PureCo7erage(1) LICENSED SOFTWARE PureCo7erage(1) o SunOS 4.1.x: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT,SIGABRT, SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS,SIGPIPE, SIGTERM,SIGXCPU,SIGXFSZ,SIGLOST,SIGUSR1,SIGUSR2 o Solaris 2.x: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT,SIGABRT, SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS,SIGPIPE, SIGTERM,SIGUSR1,SIGUSR2,SIGPOLL,SIGXCPU,SIGXFSZ, SIGFREEZE,SIGTHAW,SIGRTMIN,SIGRTMAX o HP-UX: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGABRT,SIGEMT, SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS,SIGPIPE,SIGTERM, SIGUSR1,SIGUSR2,SIGLOST,SIGRESERVE,SIGDIL For instance, if you want PureCoverage to save data on the non-fatal signals SIGALRM and SIGVTALRM, use: -handle-signals=SIGALRM,SIGVTALRM If you do not want PureCoverage to save data on the fatal signal SIGSEGV because your program handles it, use: -ignore-signals=SIGSEGV Note: PureCoverage does not ever handle SIGSTOP, SIGKILL, and SIGTRAP signals, since doing so interferes with debuggers and PureCoverage's own operation. See the man pages for signal() and sigmask(), and the files /usr/include/signal.h and /usr/include/sys/signal.h for more information on signals. APPLICATION PROGRAMMING INTERFACE PureCoverage's application programming interface can be used by programs as necessary and in interactive debugging environments like dbx, gdb, and xdb. int purecov_is_running() This function returns 1 if the executable has been instru- mented with PureCoverage, 0 otherwise. This function may be used to enclose special purpose application code to execute in the PureCoverage-instrumented environment. For example: if (purecov_is_running()) { install_gui_coverage_reset_button(); } Printed 1/6/97 15 Jan 1996 % PureCo8erage(1) LICENSED SOFTWARE PureCo8erage(1) int purecov_save_data() This function causes coverage data to be saved immediately. Counts are then reset to zero, to avoid double counting. int purecov_clear_data() This function causes the coverage data to be reset to zero, discarding collected data. int purecov_set_filename(const char* filename) This function specifies that coverage counts should be saved to filename. Embedded %p, %v, and %V are turned into the program process id, the program name, and the full pathname of the program, respectively. int purecov_enable_save() int purecov_disable_save() These functions are used to enable or disable the automatic saving of coverage data at program exit. FILES *_pure_* Cached object and library files translated by PureCoverage. purecovhome/cache/... Central cache directory structure for caching translated object files and libraries when they cannot be written alongside the original files. .pure, .lock.* Locking files preventing simultaneous file access by more than one user. .purecov, .purecov.sunos4, .purecov.solaris2, .purecov.hpux Used to specify exclude directives to ignore coverage in uninteresting libraries. purecovhome/PureCoverage.purela Contains passwords and a list of regular users for use by the Pure License Advisor. purecovhome/purecov.h Include file to use with PureCoverage API. purecovhome/purecov_stubs.a Library to be included to provide dummy PureCoverage API function definitions for use when not linking under PureCoverage. Printed 1/6/97 15 Jan 1996 % PureCo9erage(1) LICENSED SOFTWARE PureCo9erage(1) purecovhome/PureCoverage.XResources Default X resource values. SEE ALSO purify(1), dbx(1), gdb(1), pc_annotate(1), pc_below(1), pc_diff(1), pc_email(1), pc_ssheet(1), pc_summary(1) CAVEATS A PureCoverage-instrumented program normally runs about 2 times slower, and takes about 10% more memory, than if not processed by PureCoverage. Occasionally the additional memory required will cause the paging behavior to degrade performance to a greater degree. In this case, running the PureCoverage-instrumented program on a machine with more memory would be advantageous. Programs instrumented on one version of Solaris may crash or generate incorrect results if run on a different version of the operating system. A PureCoverage-instrumented program can, because of its dif- ferent memory usage patterns, cause code that works by accident to behave slightly differently. For example, values read from uninitialized or unallocated locations can differ with and without PureCoverage. You can use Purify to detect such code. PureCoverage will not change the behavior of your code in any other way. If PureCoverage does change the behavior of the program (except as mentioned above), or produces incorrect coverage reports, please report such bugs to the appropriate address: Contact us in the US at: support@pure.com or (408) 720 1600 In Europe: support@europe.pure.com or (+31) 2356 94310 In Japan: support@japan.pure.com or (03) 3863 9283 Printed 1/6/97 15 Jan 1996 %