cvcov Command Syntax and Description
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.
| cvcov help command_name | |
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:
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. Example 7-1 shows the ASCII display for a single test.
Example 7-1. cattest Example
% cvcov cattest test0000
Test Info Settings
-------------------------------------------------------------
Test /disk2/tutorial/tutorial/test0000
Type single
Description
Command Line copyn alphabet targetfile 20
Number of Exes 1
Exe List copyn
Instrument Directory /disk2/tutorial/tutorial/
Experiment List
exp##0
exp##1 |
|
Example 7-2 shows the ASCII report for a test set without recursion.
Example 7-2. cattest Example without -r
% cvcov cattest tut_testset
Test Info Settings
----------------------------------------------------------
Test /disk2/tutorial/tutorial/tut_testset
Type set
Description full coverage testset
Number of Exes 1
Exe List copyn
Number of Subtests 9
Subtest List
[0] /disk2/tutorial/tutorial/test0000
[1] /disk2/tutorial/tutorial/test0001
[2] /disk2/tutorial/tutorial/test0002
[3] /disk2/tutorial/tutorial/test0003
[4] /disk2/tutorial/tutorial/test0004
[5] /disk2/tutorial/tutorial/test0005
[6] /disk2/tutorial/tutorial/test0006
[7] /disk2/tutorial/tutorial/test0007
[8] /disk2/tutorial/tutorial/test0008
Experiment List
exp##0 |
Example 7-3 shows the ASCII report for a nested test set.
Example 7-3. cattest Example with -r
% cvcov cattest -r tut_testset
Test Info Settings
---------------------------------------------------------
Test /disk2/tutorial/tutorial/tut_testset
Type set
Description full coverage testset
Number of Exes 1
Exe List copyn
Number of Subtests 9
Subtest List
/disk2/tutorial/tutorial/test0000
/disk2/tutorial/tutorial/test0001
/disk2/tutorial/tutorial/test0002
/disk2/tutorial/tutorial/test0003
/disk2/tutorial/tutorial/test0004
/disk2/tutorial/tutorial/test0005
/disk2/tutorial/tutorial/test0006
/disk2/tutorial/tutorial/test0007
/disk2/tutorial/tutorial/test0008
Experiment List
exp##0 |
| 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 7-4.
Example 7-4. lsinstr Example
% cvcov lsinstr test0000
Instrumentation Info
---------------------------------------------------------
Executable copyn
Version 0
Instrument Directory /x/tmp/carol/
Instrument File tut_instr_file
Criteria RBPA
Instrumented Objects copyn_Instr(2.57X)
libc.so.1_RBP_Instr(1.07X)
Argument Tracing copy_file(size[bounds]) [copyn.c] |
|
| 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 7-5 shows an example of mktest, followed by cattest to display the contents of the Test Description File (TDF).
Example 7-5. Test Description File Examples
% cvcov mktest -cmd "copyn tut_instr_file targetfile"
cvcov: Made test directory: /d/Tester/tutorial/test0002
% cvcov cattest test0002
Test Info Settings
---------------------------------------------------------
Test /d/Tester/tutorial/test0002
Type single
Description
Command Line copyn tut_instr_file targetfile
Number of Exes 1
Exe List copyn
Instrument Directory /d/Tester/tutorial
Experiment List |
|
| 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_dir instr_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 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.
|
Coverage Analysis Commands
Once 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. Example 7-6 shows a typical lssum report.
Example 7-6. lssum Example
% cvcov lssum test0000
Coverages Covered Total % Coverage Weight
-------------------------------------------------------------
Function 2 2 100.00% 0.400
Source Line 17 35 48.57% 0.200
Branch 0 10 0.00% 0.200
Arc 8 18 44.44% 0.200
Block 19 42 45.24% 0.000
Weighted Sum 58.60% 1.000
|
|
| 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.
Example 7-7 shows a typical lsfun ASCII report.
Example 7-7. lsfun Example
% cvcov lsfun -pretty -sort function test0000
Functions Files Counts
-------------------------------------
copy_file copyn.c 1
main copyn.c 1 |
|
 | Note: C++ in-line functions are not counted as functions.
|
| 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. 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. Example 7-8 shows a typical lsblock ASCII report.
Example 7-8. lsblock Example
% cvcov lsblock -pat main -pretty test0000
Blocks Functions Files Counts
-------------------------------------------------
13~16 main copyn.c 1
17~17 main copyn.c 0
18~18 main copyn.c 0
19~19 main copyn.c 0
21~21 main copyn.c 1
22~22 main copyn.c 0
23~23 main copyn.c 0
24~24 main copyn.c 0
26~26 main copyn.c 1
26~27 main copyn.c 1
27~27 main copyn.c 1
28~28 main copyn.c 0
28~28(2) main copyn.c 0
28~28(3) main copyn.c 0
28~28(4) main copyn.c 0
30~30 main copyn.c 0
31~31 main copyn.c 0
33~33 main copyn.c 0
34~34 main copyn.c 0
36~36 main copyn.c 0
37~37 main copyn.c 0
39~39 main copyn.c 0
41~41 main copyn.c 0
43~43 main copyn.c 1
43~43(2) main copyn.c 0
43~43(3) main copyn.c 1
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.
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. |
|
Example 7-9 shows a typical branch coverage ASCII report. Note that branches with incomplete or null coverage are highlighted (boldfaced).
Example 7-9. lsbranch Example
% cvcov lsbranch -pretty -sort function test0000
Line Functions Files Taken Not Taken
-------------------------------------------------------------
50 copy_file copyn.c 1 0
54 copy_file copyn.c 1 0
57 copy_file copyn.c 1 0
60 copy_file copyn.c 1 0
16 main copyn.c 1 0
21 main copyn.c 1 0
27 main copyn.c 1 0
28 main copyn.c 0 0
28(2) main copyn.c 0 0
28(3) main copyn.c 0 0 |
| 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. 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".
|
Example 7-10 shows a typical lsarc ASCII report.
Example 7-10. lsarc Example
% cvcov lsarc -callee printf -pretty test0001
Callers Callees Line Files Counts
---------------------------------------------------------
main printf 17 copyn.c 1
main printf 18 copyn.c 1
main printf 22 copyn.c 0
main printf 23 copyn.c 0
main printf 30 copyn.c 0
main printf 33 copyn.c 0
main printf 36 copyn.c 0 |
| 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. Example 7-11 shows a typical lscall ASCII report. N/A means the node is excluded.
Example 7-11. lscall Example
% cvcov lscall -pretty test0000
Graph Counts
---------------------------------
main 1
copy_file 1
_open N/A
_stat... N/A
_creat N/A
_malloc... N/A
_read N/A
_write N/A
printf... N/A
exit... N/A
atoi N/A |
|
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 7-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 7-12.
Example 7-12. lsline Example
% cvcov lsline -pretty -pat main test0000
Functions Files Covered Total % Coverage
---------------------------------------------------------
main copyn.c 6 20 30.00% |
|
| cvcov lssource [-asm] [-exe exe_name] functionexperiment | |
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.
Example 7-13 shows a segment of a typical lssource ASCII report.
| Note: lssource requires the code to be compiled with the -g option.
|
Example 7-13. lssource Example
% cvcov lssource main test0000
Counts Source
-------------------------------------------------------------
#include <stdio.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <fcntl.h>
#define OPEN_ERR 1
#define NOT_ENOUGH_BYTES 2
#define SIZE_0 3
int copy_file();
main (int argc, char *argv[])
1 {
int bytes, status;
1 if( argc < 4){
0 printf("copyn: Insufficient arguments.\n");
0 printf("Usage: copyn f1 f2 bytes\n");
0 exit(1);
}
1 if( argc > 4 ) {
0 printf("Error: Too many arguments\n");
0 printf("Usage: copyn f1 f2 bytes\n");
0 exit(1);
}
1 bytes = atoi(argv[3]); |
|
| cvcov lstrace [-exe exe_name] [-pat func_pattern] [-pretty] | |
[-sort function | type]
experiment | test_name
shows the argument tracing information. Example 7-14 shows a typical lstrace ASCII report. The Range column shows upper and lower bounds. A dash (-) means that side of the bound has not been counted.
Example 7-14. lstrace Example
% cvcov lstrace -pretty testtrace
Arguments Type Range
---------------------------------
main(argc) int -, 4
copy_file(size) int 1, 20 |
|
| Note: lstrace 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. Example 7-15 shows an example of the diff command applied to two tests (although you should make sure that the comparison is relevant). Example 7-16 shows diff applied to different instrumentations of the same test.
Example 7-15. diff between Two Tests
% cvcov diff test0000/exp##0 test0001/exp##0
Experiment 1: test0000/exp##0
Experiment 2: test0001/exp##0
Coverages Exp 1 Exp 2 Differences
----------------------------------------------------------
Function Coverage 2(100.00%) 1(50.00%) 1(50.00%)
Source Line Coverage 17(48.57%) 5(14.29%) 12(34.29%)
Branch Coverage 0(0.00%) 0(0.00%) 0(0.00%)
Arc Coverage 8(44.44%) 3(16.67%) 5(27.78%)
Block Coverage 19(45.24%) 4(9.52%) 15(35.71%) |
Example 7-16. diff between Different Instrumentations of the Same Test
% cvcov diff test0000/exp##0 test0000/exp##1Experiment 1: test0000/exp##0
Experiment 2: test0000/exp##1
Coverages Exp 1 Exp 2 Differences
----------------------------------------------------------
Function Coverage 2(100.00%) 2(100.00%) 0(0.00%)
Source Line Coverage 17(48.57%) 17(47.22%) 0(1.35%)
Branch Coverage 0(0.00%) 0(0.00%) 0(0.00%)
Arc Coverage 8(44.44%) 8(44.44%) 0(0.00%)
Block Coverage 19(45.24%) 19(44.19%) 0(-1.05%) |
|
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.
|
| cvcov addtest test_nametest_set_name | test_group | |
adds a test or test set to a test set or 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: Don't use UNIX commands mv and cp to rename or copy test sets because they are constructed with absolute files 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 -cbbfilter_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 -exeexe_name option lets you specify which executable is targeted for test optimization. If no executable is specified, the main program is the default. The -patpattern 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 7-17 demonstrates how test sets are optimized. In this case, optimizing is applied to all tests matching the expression test00*.
Example 7-17. Optimizing Test Sets
% cvcov optimize -pretty -blocks -branches test00*
Test Block Coverage Branch Coverage
---------------------------------------------------------
test0000 41.54% 0.00%
test0001 7.69% 10.00%
test0002 7.69% 10.00%
test0003 9.23% 20.00%
test0004 9.23% 20.00%
test0005 6.15% 20.00%
test0006 1.54% 10.00%
Total Coverage 83.08% 90.00% |
|
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 ...
creates a test group that can contain other tests or test groups. The targets are either the target libraries or DSOs.
| Note: Don't use UNIX commands mv and cp to rename or copy test groups because they are constructed with absolute files paths.
|
|