This chapter describes the cvcov commands. It contains the following two subsections:
“Common cvcov Options”, describes the command arguments that are common to more than one command
“cvcov Command Syntax and Description”, describes the specifications with descriptions for each command
A complete description of the cvcov commands, including individual arguments, is available on the cvcov man page by typing:
% man cvcov |
For examples of cvcov usage, see Appendix A, “cvcov Command Line Examples”.
This section contains descriptions of some cvcov flags and variables that are common to more than one command.
[-ver]: displays the version of cvcov. Note that there are no other arguments permitted; you enter: cvcov -ver
[-v versionnumber]: allows you to specify a version of the instrumentation or experiment directory other than the most recent, which is the default.
[-contrib]: shows the list of tests that contributed to coverage for the particular query.
[-exe exe_name]: lets you specify an executable for coverage testing. This is used when there are multiple executables involved, as in testing processes created by the fork, exec, or sproc command.
[-instr_dir instr_dir] : allows you to specify an instrumentation directory other than the current working directory, which is the default.
[-instr_file instr_file] : specifies the instrumentation file, which is an ASCII description of the instrumentation criteria you have selected.
[-list list_file]: specifies a file containing a list of test names to be made part of a test set or group. If no -list option is specified, an empty test set will be created.
[-r]: (Recursion) lets you specify tests in a hierarchy of subdirectories.
[-pretty]: displays output aligned in columns. Without -pretty, the output is in columns but more condensed.
[-sort]: sorts the output by the specified criteria, as follows:
diff: by differences in the counting information for coverage type
count: by counts for current coverage type
file: alphabetically by file name
type: alphabetically by argument type
[-pat func_pattern]: lets you enter a pattern instead of a complete function name. The pattern can be of the form func_name, dso_:func_name, or `dso:*'.
experiment | test_name: lets you specify either the experiment subdirectory or the test directory. The test directory is typically of the form test< nnnn>, where <nnnn> is a number in a sequence counting from 0000. You can specify your own name. The test directory contains all information about a test including the experiment directory. The experiment directory is typically of the form exp##<n>, where < n> is a sequential number, counting from 0.
This section contains the syntax and description for all cvcov commands in the command line interface. If you need information on command arguments that are not described in this section, please refer back to “Common cvcov Options”.
The most general command is the help command, as follows:
cvcov help command_name |
The help command prints help on the specified command. If the optional command name is not specified, it prints help for all the commands.
The rest of the commands are divided up into these categories:
General test commands, described in “General Test Commands”.
Coverage analysis commands, described in “Coverage Analysis Commands”.
Test set commands, described in “Test Set Commands”.
Test group command, described in “Test Group Commands”.
The following commands support the creation, inspection, modification, and deletion of tests:
cvcov cattest [-r] test_name
Describes the test details for a test, test set, or test group. See Example A-1, Example A-2, and Example A-3.
cvcov lsinstr [-exe] exe_name [-functions] [-v versionnumber] test_name
Displays the instrumentation information for a particular test. exe_name is the executable targeted for query. The main program is the default if no executable is specified. The -functions parameter shows the functions that are included in the coverage experiment. The versionnumber parameter allows you to specify the version of the program that was instrumented. You can specify the test directory using the test_name parameter. See Example A-4.
cvcov lstest [-r][test_name...]
Lists the test directories in the current working directory. Note that the test_name parameter will accept regular expressions for lstest.
cvcov mktest -cmd cmd_line [-des description] [-instr_dir directoryname] [-testname test] [ exe1 exe2 ...]
Creates a test directory. You specify the program and command line options for the program to be tested. This includes any redirection for stdin, stderr, or stdout as run from the Bourne shell.
The -cmd qualifier is mandatory, even if it only includes the program name. If no executables are specified, only the main program is tested. Example A-5, shows an example of mktest, followed by cattest to display the contents of the Test Description File (TDF).
cvcov rmtest [-r]test_name ...
Removes tests and test sets. Note that the test_name parameter will accept regular expressions for rmtest. It is recommended to separate the test set directory from its test subdirectories and the instrument directory. In this way, rmtest will not remove instrumentation data or subtests if you choose to remove the test set only.
cvcov runinstr [-instr_dirinstr_dir ] [-instr_file instr_file ] [-v versionnumber] executable
Adds code to the target executable to enable you to capture coverage data, according to the criteria you specify. The instrument file is an ASCII description of the instrumentation criteria for the experiment. You can also specify the version of the executable and instrument directory.
You can capture basic block counts, function pointer counts, and branch counts (at the assembly language level). You can use INCLUDE, EXCLUDE, or CONSTRAIN to modify the set of functions covered. CONSTRAIN lets you define a set of functions for the test.
cvcov runtest [ -bitcount ] [ -compress ] [-force] [-keep][-sum] [-v versionnumber] [-noarc] [-rmsub] test_name
Runs a test or a set of tests.
The -bitcount flag compresses count data file to be 1-bit-per-count. This option can decrease the database size up to 32 times, although branch count information will be lost.
The -compress flag compresses the experiment database using the standard utility compress.
The -force flag forces the test to be run again even if an experiment is present. It uses WorkShop performance tool technology to set up the instrumented process, run the process, and monitor the run, collecting counting information upon exit.
The -keep flag retains all performance data collected in the experiment. By default, the performance data is not retained, because it is not required by the coverage tool. The -sum flag accumulates (sum over) the coverage data into the existing experiment results. This allows users to run and rerun the same test and accumulate the results in one place.
The -noarc flag prevents arc information from being saved in the test database. With the -noarc flag, all arc-related queries will not work (for example, lsarc and lscall).
The -rmsub flag removes results for individual subtests for a test set or test group. There will be no data to query if you are querying a subtest. -noarc and -rmsub save disk space.
After the data has been collected from the test experiments, the user can analyze the data. There are special commands for the various types of coverage available.
cvcov lssum [-exe exe_name ] [-weight func_factor : line_factor : branch_factor : arc_factor : block_factor] experiment | test_name
Shows the overall coverage based on the user-defined weighted average over function, line, block, branch, and arc coverage. See Example A-6.
cvcov lsfun [-arg] [-bf filter_type block_filter_value] [-blocks] [-branches] [-contrib] [-exe exe_name] [-ff filter_type func_filter_value] [-pat func_pattern] [-pretty] [-rf filter_type branch_filter_value ] [-sort count | file | function] experiment |test_name
Lists coverage information for the specified functions in the program that was tested. Several sorting, matching, and filtering techniques are available. For example, you can show the list of functions that have 0 counts (were not covered) in alphabetical order. You can display arguments with the -arg flag. See Example A-7.
cvcov lsblock [-addr] [-arg] [-contrib] [-exe exe_name] [-pat func_pattern] [-pretty] [-sort count|file| function] experiment| test_name
Displays a list of blocks for one or more functions and the count information associated with each block. See Example A-8.
Blocks are identified by the line numbers in which they occur. If there are multiple blocks in a line, blocks subsequent to the first are shown in order with an index number in parentheses. Be careful before listing all blocks in the program, since this can produce a lot of data. The -addr flag show blocks with the PC range instead of the source line number range.
cvcov lsbranch [-addr] [-arg] [-exe exe_name][-pat func_pattern][-pretty][-sort function| file] experiment |test_name
Lists coverage information for branches in the program, including the line number at which the branch occurs. See Example A-9.
Branch coverage counts assembly language branch instructions that are both taken and not taken. The -addr flag show blocks with the PC range instead of the source line number range.
cvcov lsarc [-arg] [-callee callee_pattern ] [-caller caller_pattern] [-contrib][-exe exe_name] [-pretty][-sort caller| callee| count|file] experiment| test_name
Shows arc coverage, that is, the number of arcs taken out of the total possible arcs. See Example A-10.
An arc is a function caller-callee pair. Both callee_pattern and caller_pattern can be specified in the same way as func_pattern (used with the -pat option) as shown under “Common cvcov Options”.
cvcov lscall [-arg] [-exe exe_name][-node func_name] [-pretty] [-r] experiment| test_name
Lists the call graph for the executable with counts for each function. The contribution to this coverage by each test is shown in a separate column. N/A means the node is excluded. See Example A-11.
A function that has more than one parent and has children is called a subnode. Using -r will display the subnodes. Subnodes are given their own starting point in the textual call graph. They are identified by a trailing ellipsis (...). For example, see printf, exit, and malloc in Example A-11.
cvcov lsline [-arg] [-exe exe_name] [-pat func_pattern][-pretty] [-sort function|file] experiment |test_name
Lists the coverage for native source lines. Use -arg to show arguments for functions. If no executable is specified, the main program is the default. Use -pretty to provide column-aligned output. See Example A-12.
cvcov lssource [-asm] [-exe exe_name ] function experiment test_name
Displays the source annotated with line counts. The -asm switch displays the assembly level source code annotated with line counts. Lines with 0 counts are highlighted to show the absence of coverage. This is useful for mapping to the source level blocks and branches that were not covered. Lines in functions that were not included in the test appear without count annotations. See Example A-13.
Note: lssource requires the code to be compiled with the -g option. cvcov diff [-arg] [-exe exe_name] [-functions] [-pretty][-sort diff|function] experiment1 experiment2
Shows the difference in coverage for different versions of the same program. See Example A-14.
A test set is a named collection of tests and other test sets. Test sets can be hierarchical. For example, compiler_language_suite might include C++_suite, C_suite, and Fortran_suite, where Fortran_suite is a test set with subdirectories. The following commands support creation, inspection, modification, and deletion of test sets. Both addtest and deltest are also used with test groups, described in the next section.
cvcov mktset [-des description] [-list list_file][-testname test]
Makes a test set. If no test name is specified, the command assigns one automatically. See Example A-16.
cvcov addtest test_name test_set_name| test_group
cvcov deltest test_name test_set_name|test_group
Removes a test or test set from a test set or test group.
Note: Do not use UNIX commands mv and cp to rename or copy test sets because they are constructed with absolute file paths. cvcov optimize [ -blocks ] [ -branches ][ -cbb filter_type bb_filter_value ] [ -cbr filter_type br_filter_value] [ -exe exe_name] [ -pat func_pattern] [ -pretty ] [ -stat ] experiment...|test_name ...
Selects the minimum set of tests that give the same coverage or meet the given coverage criteria as the given set.
The -blocks flag shows block coverage for all the selected tests.
The -branches flag shows branch coverage for all the selected tests.
The -cbb filter_type bb_filter_value gives the basic block coverage criteria for test selection. The rules are the same as the flag -bf of the lsfun command.
The -cbr filter_type br_filter_value gives the branch coverage criteria for test selection. The rules are the same as the flag -rf of lsfun command.
The -exe exe_name option lets you specify which executable is targeted for test optimization. If no executable is specified, the main program is the default.
The -pat pattern option lets you specify DSO patterns for calculation of coverage on test selection. The -pretty flag aligns column output.
The -stat flag prints out block and branch coverage for all the selected tests. Without this option, cumulative coverages for block and branch are given.
The experiment ...| test_name ... option lets you specify names of experiments or tests to be optimized. Example A-16, demonstrates how test sets are optimized. In this case, optimizing is applied to all tests matching the expression test00*.
A test group is a collection of programs to be tested that have a common dynamically shared object (DSO). The coverage testing is limited to activity with the DSO so that the arcs and branches that terminate outside of the DSO will not be included. See descriptions of addtest and deltest in the previous section as well as the following command.
cvcov mktgroup [-des description][-list list_file][-testname test] target1 target2... |
This command creates a test group that can contain other tests or test groups. The targets are either the target libraries or DSOs.
| Note: Do not use UNIX commands mv and cp to rename or copy test groups because they are constructed with absolute files paths. |