Subversion Repositories planix.SVN

.TH PROF 1

.SH NAME

prof, tprof, kprof \- display profiling data

.SH SYNOPSIS

.B prof

[

.B -dr

]

[

.I program

]

[

.I profile

]

.PP

.B tprof

.I pid

.PP

.B kprof

.I kernel

.I kpdata

.SH DESCRIPTION

.I Prof

interprets files produced automatically by programs loaded using the

.B -p

option of

.IR 8l (1)

or other loader.

The symbol table in the

named program file

.RL ( 2.out

etc., according to

.BR $objtype ,

by default)

is read and correlated with the

profile file

.RL ( prof.out

by default).

For each symbol, the percentage

of time (in seconds) spent executing between that symbol

and the next

is printed (in decreasing order),

together with the time spent there and

the number of times that routine was called.

.PP

Under option

.BR -d ,

.I prof

prints the dynamic call graph of the target program,

annotating the calls with the time spent in each routine

and those it calls, recursively.  The output is indented

two spaces for each call, and is formatted as

.IP

.EX

symbol:time/ncall

.EE

.LP

where

.I symbol

is the entry point of the call,

.I time

is in milliseconds,

and

.I ncall

is the number of times that entry point was called at that

point in the call graph.  If

.I ncall

is one, the

.B /ncall

is elided.

Normally recursive calls are compressed to keep the output brief;

option

.B -r

prints the full call graph.

.PP

The size of the buffer

in

.I program

used to hold the profiling

data, by default 2000 entries,

may be controlled by setting the environment variable

.B profsize

before running

.IR program .

If the buffer fills, subsequent function calls may not be recorded.

.PP

The profiling code provided by the linker initializes itself to profile the current pid,

producing a file called

.B prof.\f2pid\fP.

If a process forks, only the parent will continue to be profiled.  Forked children

can cause themselves to be profile by calling

.IP

.EX

prof(fn, arg, entries, what)

.EE

.LP

which causes the function \f2fn\fP(\f2arg\fP) to be profiled.  When \f2fn\fP

returns 

.B prof.\f2pid\fP

is produced for the current process pid.

.PP

The environment variable

.B proftype

can be set to one of

.BR user ,

.BR kernel ,

.BR elapsed ,

or

.BR sample ,

to profile time measured spent in user mode, time spent in user+kernel mode, or elapsed time,

using the cycle counter, or the time in user mode using the kernel's HZ clock.  The cycle counter

is currently only available on modern PCs and on the PowerPC.  Default profiling measures user

time, using the cycle counter if it is available.

.PP

.I Tprof

is similar to

.IR prof ,

but is intended for profiling multiprocess programs.

It uses the

.BI /proc/ pid /profile

file to collect instruction frequency counts for the text image associated with the process,

for all processes that share that text.

It must be run while the program is still active, since the data is stored with the running program.

To enable

.I tprof

profiling for a given process,

.IP

.EX

echo profile > /proc/\f2pid\f1/ctl

.EE

.LP

and then, after the program has run for a while, execute

.IP

.EX

tprof \f2pid\f1

.EE

.LP

Since the data collected for

.I tprof

is based on interrupt-time sampling of the program counter,

.I tprof

has no

.B -d

or

.B -r

options.

.PP

.I Kprof

is similar to

.IR prof ,

but presents the data accumulated by the kernel

profiling device,

.IR kprof (3) .

The symbol table file, that of the operating system kernel,

and the data file, typically

.BR /dev/kpdata ,

must be provided.

.I Kprof

has no options and cannot present dynamic data.

.SH SOURCE

.B /sys/src/cmd/prof.c

.br

.B /sys/src/cmd/kprof.c

.SH SEE ALSO

.IR 8l (1),

.IR exec (2),

.IR kprof (3)