lprof(1) UNIX System V(Enhanced Programming Utilities) lprof(1)
NAME
lprof - display line-by-line execution count profile data
SYNOPSIS
lprof [-p] [-s] [-x] [-I incdir] [-r srcfile] [-c cntfile] [-o prog] [-V]
lprof -m file1.cnt file2.cnt filen.cnt [-T] -d destfile.cnt
DESCRIPTION
lprof reports the execution characteristics of a program on a (source)
line by line basis. This is useful as a means to determine which and how
often portions of the code were executed.
lprof interprets a profile file (prog.cnt by default) produced by the
profiled program prog (a.out by default). prog creates a profile file if
it has been loaded with the -ql option of cc. The profile information is
computed for functions in a source file if the -ql option was used when
the source file was compiled.
A shared object may also be profiled by specifying -ql when the shared
object is created. When a dynamically linked executable is run, one
profile file is produced for each profiled shared object linked to the
executable. This feature is useful in building a single report covering
multiple and disparate executions of a common library. For example, if
programs prog1 and prog2 both use library libx.a, running these profiled
programs will produce two profile files, prog1.cnt and prog2.cnt, which
cannot be combined. However, if libx is built as a profiled shared
object, libx.so, and prog1 and prog2 are built as profiled dynamically
linked executables, then running these programs with the merge option
will produce three profile files; one of them, libx.so.cnt, will contain
the libx profile information from both runs.
By default, lprof prints a listing of source files (the names of which
are stored in the symbol table of the executable file), with each line
preceded by its line number (in the source file) and the number of times
the line was executed.
The following options may appear singly or be combined in any order:
-p Print listing, each line preceded by the line number and the
number of times it was executed (default). This option can be
used together with the -s option to print both the source
listing and summary information.
-s Print summary information of percentage of lines of code
executed per function.
-x Instead of printing the execution count numbers for each line,
print each line preceded by its line number and a [U] if the
line was not executed. If the line was executed, print only the
line number.
10/89 Page 1
lprof(1) UNIX System V(Enhanced Programming Utilities) lprof(1)
-I incdir
Look for source or header files in the directory incdir in
addition to the current directory and the standard place for
#include files (usually /usr/include). The user can specify
more than one directory by using multiple -I options.
-r srcfile
Instead of printing all source files, print only those files
named in -r options (to be used with the -p option only). The
user can specify multiple files with a single -r option.
-c cntfile
Use the file cntfile instead of prog.cnt as the input profile
file.
-o prog Use the name of the program prog instead of the name used when
creating the profile file. Because the program name stored in
the profile file contains the relative path, this option is
necessary if the executable file or profile file has been moved.
-V Print, on standard error, the version number of lprof.
Merging Data Files
lprof can also be used to merge profile files. The -m option must be
accompanied by the -d option:
-m file1.cnt file2.cnt filen.cnt -d destfile.cnt
Merge the data files file1.cnt through filen.cnt by summing the
execution counts per line, so that data from several runs can be
accumulated. The result is written to destfile.cnt. The data
files must contain profiling data for the same prog (see the -T
option below).
-T Time stamp override. Normally, the time stamps of the
executable files being profiled are checked, and data files will
not be merged if the time stamps do not match. If -T is
specified, this check is skipped.
CONTROLLING THE RUN-TIME PROFILING ENVIRONMENT
The environment variable PROFOPTS provides run-time control over
profiling. When a profiled program (or shared object) is about to
terminate, it examines the value of PROFOPTS to determine how the
profiling data are to be handled. A terminating shared object will honor
every PROFOPTS option except file=filename.
The environment variable PROFOPTS is a comma-separated list of options
interpreted by the program being profiled. If PROFOPTS is not defined in
the environment, then the default action is taken: The profiling data
are saved in a file (with the default name, prog.cnt) in the current
directory. If PROFOPTS is set to the null string, no profiling data are
saved. The following are the available options:
Page 2 10/89
lprof(1) UNIX System V(Enhanced Programming Utilities) lprof(1)
msg=[y|n]
If msg=y is specified, a message stating that profile data are
being saved is printed to stderr. If msg=n is specified, only
the profiling error messages are printed. The default is msg=y.
merge=[y|n]
If merge=y is specified, the data files will be merged after
successive runs. If merge=n is specified, the data files are
not merged after successive runs, and the data file is
overwritten after each execution. The merge will fail if the
program has been recompiled, and the data file will be left in
TMPDIR. The default is merge=n.
pid=[y|n]
If pid=y is specified, the name of the data file will include
the process ID of the profiled program. Inclusion of the
process ID allows for the creation of different data files for
programs calling fork. If pid=n is specified, the default name
is used. The default is pid=n. For lprof to generate its
profiling report, the -c option must be specified with lprof
otherwise the default will fail.
dir=dirname
The data file is placed in the directory dirname if this option
is specified. Otherwise, the data file is created in the
directory that is current at the end of execution.
file=filename
filename is used as the name of the data file in dir created by
the profiled program if this option is specified. Otherwise,
the default name is used. For lprof to generate its profiling
report, the -c option must be specified with lprof if the file
option has been used at execution time; otherwise the default
will fail.
FILES
prog.cnt profile data
TMPDIR usually /var/tmp but can be redefined by setting the environment
variable TMPDIR [see tempnam in tmpnam(3S)].
SEE ALSO
cc(1), prof(1), fork(2), tmpnam(3S)
The ``lprof'' chapter in the Programmer's Guide: ANSI C and Programming
Support Tools
NOTES
For the -m option, if destfile.cnt exists, its previous contents are
destroyed.
Optimized code cannot be profiled; if both optimization and line
profiling are requested, profiling has precedence.
10/89 Page 3
lprof(1) UNIX System V(Enhanced Programming Utilities) lprof(1)
Including header files that contain code (such as stat.h or utsname.h)
will cause erroneous data.
Different parts of one line of a source file may be executed different
numbers of times (for example, the for loop below); the count corresponds
to the first part of the line.
For example, in the following for loop
main()
1 [2] {
int j;
1 [5] for (j = 0; j < 5; j++)
5 [6] sub(j);
1 [8] }
sub(a)
int a;
5 [12] {
5 [13] printf("a is %d\n", a);
5 [14] }
line 5 consists of three parts. The line count listed, however, is for
the initialization part, that is, j = 0.
Page 4 10/89