lprof(CP)

lprof -- display line-by-line execution count profile data

Syntax

lprof [-pPsVx] [-b elf] [-I incdir] [-r srcfile] [-c cntfile] [-o prog]

lprof -m file1.cnt file2.cnt [... filen.cnt] [-T] -d destfile.cnt

Description

lprof is a tool for dynamic analysis; that is, the analysis of a program at run time. Specifically, lprof reports the execution characteristics of a program on a line by line (source code) basis, identifies the most frequently executed parts of source code and parts of code that are never executed.

lprof interprets a profile file (prog.cnt by default) produced by the profiled program prog (a.out by default) that has been compiled with the -ql option of cc(CP). This cc command option arranges for code to be inserted to record run-time behavior and for data to be written to a file at the end of execution of prog.

By default, lprof prints a listing of source files, the names of which are stored in the symbol table of the executable file. Each line preceded by its line number (in the source file) and the number of times it was executed.

A shared object may also be profiled by specifying -belf -ql to cc 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.

Options

The following options may appear singly or be combined in any order:

-b [elf|coff|ibcs2]

Specify the file format of the object file. Normally, lprof scans the profiled program prog to determine its file format and invokes the appropriate tool to process the profile file (prog.cnt.) With this option, lprof does not scan the program and the file format that lprof assumes is that requested through the option:

-b coff or -b ibcs2: Invoke /usr/ccs/bin/coff/lprof to process the profile file generated by a COFF binary.
-b elf: Invoke /usr/ccs/bin/elf/lprof to process the profile file generated by an ELF binary.

-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 must be used with -b elf. 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). You can specify more than one directory with -I on the command line.

-r srcfile

Instead of printing all source files, print only those files named in -r options (to be used with the -p option only). You can specify multiple files with -r on one command line.

-c cntfile

Use the file cntfile instead of prog.cnt as the input profile file.

-o prog

Profile 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. This option must be used with -b elf.

Merging data files

lprof can also be used to merge profile data files. The -m option must be accompanied by the -d option:

-m file1.cnt file2.cnt [filen.cnt] -ddestfile.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

lprof uses the environment variable PATH to locate the correct full pathname of the profiled program. If the profiled program is in a directory not pointed to by PATH, lprof reports ``Unable to open file prog.'' and exits. To profile the program, give an explicit pathname of prog to lprof. For example, ../../prog has an explicit pathname, but prog does not.

The environment variable PROFOPTS provides run-time control over profiling. When a profiled program is about to terminate, it examines the value of PROFOPTS to determine how the profiling data is 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 is 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 is saved. The following are the available options:

msg=[yn]: If msg=y is specified, a message stating that profile data is being saved is printed to standard error. If msg=n is specified, print only profiling error messages. The default is msg=y.
merge=[yn]: If merge=n is specified, do not merge data files after successive runs. The data file is overwritten after each execution. If merge=y is specified, the data will be merged. The merge will fail if the program has been recompiled; the data file will be left in TMPDIR. The default is merge=n.
pid=[yn]: If pid=y is specified, the name of the data file will include the process ID of the profiled program. This allows the creation of different data files for programs calling fork(S). 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: Place the data file 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: Use filename 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.

Warning

For the -m option, if destfile.cnt exists, its previous contents are destroyed.

Optimizing functions may result in the loss of some line number information and may cause the order of generated code to be different from that in the source file, both of which may make lprof information unreliable. If both optimization and line profiling are requested, profiling has precedence.

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, line 5 consists of three parts:

                   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]    }

The line count listed, however, is for the initialization part, that is, j=0.

Files

/bin/lprof
/usr/ccs/bin/coff/lprof
/usr/ccs/bin/elf/lprof
prog.cnt: For profile data.
TMPDIR/*: Temporary files.
TMPDIR is usually /usr/tmp, but can be redefined by setting the environment variable TMPDIR (see tempnam() in tmpnam(S)).