test

Analyzing Program Performance With Sun WorkShop

tcov Enhanced--Statement-level Analysis

Like the original tcov, tcov Enhanced gives line-by-line information on how a program executes. It produces a copy of the source file, annotated to show which lines are used and how often. It also gives a summary of information about basic blocks. tcov Enhanced works with both C and C++ source files.

tcov Enhanced overcomes some of the shortcomings of the original tcov:

Compiling for tcov Enhanced

To use tcov Enhanced, follow the same basic steps as the original tcov:

  1. Compile a program for a tcov Enhanced experiment.

  2. Run the experiment.

  3. Analyze the results using tcov.

For the original tcov, you compile with the -xa option. To compile a program for code coverage with tcov Enhanced, you use the -xprofile=tcov option for all compilers. Using a program named index.assist as an example, you would compile for use with tcov Enhanced with this command:

% cc -xprofile=tcov -o index.assist index.assist.c

tcov Enhanced, unlike tcov, does not produce a .d file. The coverage data file is not created until the program is run. Then one coverage data file is produced as opposed to one file for each module compiled for coverage analysis.

After you compiled index.assist.c, you would run index.assist to create the profile file:

% index.assist

% ls -dF *.profile

index.assist.profile/

% ls *.profile

tcovd

By default, the name of the directory where the tcovd file is stored is derived from the name of the executable. Furthermore, that directory is created in the directory the executable was run in (the original tcov created the .d files in the directory where the modules were compiled).

The directory where the tcovd file is stored is also known as the "profile bucket." The profile bucket can be overridden by using the SUN_PROFDATA environment variable. This may be useful if the name of the executable is not the same as the value in argv[0] (for example, the invocation of the executable was through a symbolic link with a different name).

You can also override the directory where the profile bucket is created. To specify a location different from the run directory, specify the path using the SUN_PROFDATA_DIR environment variable. Absolute or relative pathnames can be specified in this variable. Relative pathnames are relative to the program's current working directory at program completion.

TCOVDIR is supported as a synonym for SUN_PROFDATA_DIR for backward compatibility. Any setting of SUN_PROFDATA_DIR causes TCOVDIR to be ignored. If both SUN_PROFDATA_DIR and TCOVDIR are set, a warning is displayed when the profile bucket is generated. SUN_PROFDATA_DIR takes precedence over TCOVDIR. The variables are used at runtime by a program compiled with -xprofile=tcov, and are used by the tcov command.

Note -

This scheme is also used by the profile feedback mechanism.

Now that some coverage data has been produced, you could generate a report that relates the raw data back to the source files:

% tcov -x index.profile index.assist.c

% ls *.tcov

index.assist.c.tcov

The output of this report is identical to the one from the previous example (for the original tcov).

Creating Profiled Shared Libraries

Creating shared libraries for use with tcov Enhanced is accomplished by using the analogous compiler options:

% cc -G -xprofile=tcov -o foo.so.1 doo.o

Locking Files

tcov Enhanced uses a simple file-locking mechanism for updating the block coverage data file. It employs a single file created in the same directory as the tcovd file. The file name is tcovd.temp.lock. If execution of the program compiled for coverage analysis is manually terminated, then the lock file must be deleted manually.

The locking scheme does an exponential back-off if there is a contention for the lock. If, after five tries, the tcov runtime cannot acquire the lock, it gives up and the data is lost for that run. In this case, the following message is displayed:

tcov_exit: temp file exists, is someone else running this executable?

tcov Directories and Environment Variables

When you compile a program for tcov and run the program, the running program generates a profile bucket. If a previous profile bucket exists, the program uses that profile bucket. If a profile bucket does not exist, it creates the profile bucket.

The profile bucket specifies the directory where the profile output is generated. The name and location of the profile output are controlled by defaults that you can modify with environment variables.

Note -

tcov uses the same defaults and environment variables that are used by the compiler options that you use to gather profile feedback: -xprofile=collect and -xprofile=use. For more information about these compiler options, see the documentation for your compiler.

The default profile bucket the program creates is named after the executable with a ".profile" extension and is created in the directory where the executable is run. Therefore, if you are in /home/joe, and run a program called /usr/bin/xyz, the default behavior is to create a profile bucket called xyz.profile in /home/joe.

The environment variables that you set to modify the defaults are:

Can be used to specify the name of the profile bucket at runtime. The value of this variable is always appended to the value of SUN_PROFDATA_DIR if both variables are set.

Can be used to specify the name of the directory containing the profile bucket. It is used at runtime and in the tcov command.

TCOVDIR is supported as a synonym for SUN_PROFDATA_DIR to maintain backward compatibility. Any setting of SUN_PROFDATA_DIR causes TCOVDIR to be ignored. If both SUN_PROFDATA_DIR and TCOVDIR are set, a warning is displayed when the profile bucket is generated.

TCOVDIR is used at runtime by a program compiled with -xprofile=tcov and it is used by the tcov command.

Overriding the Default Definitions

To override the default, use the environment variables to change the profile bucket:

  1. Change the name of the profile bucket by using the SUN_PROFDATA environment variable.

  2. Change the directory where the profile-bucket is placed by using the SUN_PROFDATA_DIR environment variable.

The environment variables override the default location and name of the profile bucket. Both can be overridden independently. For example, if you only choose to set SUN_PROFDATA_DIR, the profile bucket will go into the directory where you set SUN_PROFDATA_DIR. The default name (which is the executable name followed by a ".profile") will still be the name used for the profile bucket.

Absolute and Relative Pathnames

There are two forms of directories you can specify by using SUN_PROFDATA_DIR on the Profile Feedback compile line: absolute pathnames (which start with a `/'), and relative pathnames. If you use an absolute pathname, the profile bucket is dropped into that directory. If you specify a relative pathname, then it is relative to the current working directory where the executable is being run.

For example, if you are in /home/joe and run a program called /usr/bin/xyz with SUN_PROFDATA_DIR set to .. , then the profile bucket is called /home/joe/../xyz.profile. The value specified in the environment variable was relative, and therefore, it was relative to /home/joe. Also, the default profile bucket name is used, which is named after the executable.

TCOVDIR and SUN_PROFDATA_DIR

The previous version of tcov (enabled by compiling with the -xa or -a flag) used an environment variable called TCOVDIR. TCOVDIR specified the directory where the tcov counter files go to instead of next to the source files. To retain compatibility with this environment variable, the new SUN_PROFDATA_DIR environment variable behaves like the TCOVDIR environment variable. If both variables are set, a warning is output and SUN_PROFDATA_DIR takes precedence over TCOVDIR.

For -xprofile=tcov

By default the profile bucket is called <argv[0]>.profile in the current directory.

If you set SUN_PROFDATA, the profile bucket is called $SUN_PROFDATA, wherever it is located.

If you set SUN_PROFDATA_DIR, the profile bucket is placed in the specified directory.

SUN_PROFDATA and SUN_PROFDATA_DIR are independent. If both are specified, the profile bucket name is generated by using SUN_PROFDATA_DIR to find the profile bucket and, SUN_PROFDATA is used to name the profile bucket in that directory.

A UNIX process can change its current working directory during the execution of a program. The current working directory used to generate the profile bucket is the current working directory of the program at exit. In the rare case where a program actually does change its current working directory during execution, you can use the environment variables to control where the profile bucket is generated.

For the tcov Program

The -xprofile=bucket option specifies the name of the profile bucket to use for the tcov profile. SUN_PROFDATA_DIR or TCOVDIR are prepended to this argument, if they are set.