Import sources from 2011-03-30 iso image - sys/man

1 files changed, 167 insertions, 0 deletions

diff --git a/sys/man/1/prof b/sys/man/1/prof
new file mode 100755
index 000000000..40e4a9901
--- /dev/null
+++ b/sys/man/1/prof
@@ -0,0 +1,167 @@
+.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 2l (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 2l (1),
+.IR exec (2),
+.IR kprof (3)