lprof(1) lprof(1)
NAME
lprof - display line-by-line execution count profile data
SYNOPSIS
lprof [-p] [-P] [-s] [-x] [-I incdir] [-r srcfile] [-c cntfile]
[-o prog] [-V] [-C]
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(1) or CC(1C++). 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 the archive 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:
Copyright 1994 Novell, Inc. Page 1
lprof(1) lprof(1)
-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.
-P Print a different form of the listing where the file
names appear in the leftmost column, followed by
function names indented one space, and indented three
spaces is a list of the line numbers of the
executable lines in the function and the
corresponding execution count. This option cannot be
used with the -s, -x, or -m options.
-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.
-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.
Copyright 1994 Novell, Inc. Page 2
lprof(1) lprof(1)
-V Print, on standard error, the version number of
lprof.
-C Decode C++ symbol table names when printing summary
information, otherwise, the encoded names will be
printed. Symbol names in C++ source listings are
printed as they appear in the source and are
therefore decoded by default.
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:
msg=[y|n]
If msg=y is specified, a message stating that profile
data are being saved is printed to stderr. If msg=n
Copyright 1994 Novell, Inc. Page 3
lprof(1) lprof(1)
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)].
NOTICES
The full pathname of prog.cnt must not exceed 60 characters.
Copyright 1994 Novell, Inc. Page 4
lprof(1) lprof(1)
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.
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.
REFERENCES
CC(1C++), cc(1), fork(2), prof(1), tmpnam(3S)
Copyright 1994 Novell, Inc. Page 5