sys/man/1/prof

   1 .TH PROF 1
   2 .SH NAME
   3 prof, tprof, kprof \- display profiling data
   4 .SH SYNOPSIS
   5 .B prof
   6 [
   7 .B -dr
   8 ]
   9 [
  10 .I program
  11 ]
  12 [
  13 .I profile
  14 ]
  15 .PP
  16 .B tprof
  17 .I pid
  18 .PP
  19 .B kprof
  20 .I kernel
  21 .I kpdata
  22 .SH DESCRIPTION
  23 .I Prof
  24 interprets files produced automatically by programs loaded using the
  25 .B -p
  26 option of
  27 .IR 2l (1)
  28 or other loader.
  29 The symbol table in the
  30 named program file
  31 .RL ( 2.out
  32 etc., according to
  33 .BR $objtype ,
  34 by default)
  35 is read and correlated with the
  36 profile file
  37 .RL ( prof.out
  38 by default).
  39 For each symbol, the percentage
  40 of time (in seconds) spent executing between that symbol
  41 and the next
  42 is printed (in decreasing order),
  43 together with the time spent there and
  44 the number of times that routine was called.
  45 .PP
  46 Under option
  47 .BR -d ,
  48 .I prof
  49 prints the dynamic call graph of the target program,
  50 annotating the calls with the time spent in each routine
  51 and those it calls, recursively.  The output is indented
  52 two spaces for each call, and is formatted as
  53 .IP
  54 .EX
  55 symbol:time/ncall
  56 .EE
  57 .LP
  58 where
  59 .I symbol
  60 is the entry point of the call,
  61 .I time
  62 is in milliseconds,
  63 and
  64 .I ncall
  65 is the number of times that entry point was called at that
  66 point in the call graph.  If
  67 .I ncall
  68 is one, the
  69 .B /ncall
  70 is elided.
  71 Normally recursive calls are compressed to keep the output brief;
  72 option
  73 .B -r
  74 prints the full call graph.
  75 .PP
  76 The size of the buffer
  77 in
  78 .I program
  79 used to hold the profiling
  80 data, by default 2000 entries,
  81 may be controlled by setting the environment variable
  82 .B profsize
  83 before running
  84 .IR program .
  85 If the buffer fills, subsequent function calls may not be recorded.
  86 .PP
  87 The profiling code provided by the linker initializes itself to profile the current pid,
  88 producing a file called
  89 .B prof.\f2pid\fP.
  90 If a process forks, only the parent will continue to be profiled.  Forked children
  91 can cause themselves to be profile by calling
  92 .IP
  93 .EX
  94 prof(fn, arg, entries, what)
  95 .EE
  96 .LP
  97 which causes the function \f2fn\fP(\f2arg\fP) to be profiled.  When \f2fn\fP
  98 returns
  99 .B prof.\f2pid\fP
 100 is produced for the current process pid.
 101 .PP
 102 The environment variable
 103 .B proftype
 104 can be set to one of
 105 .BR user ,
 106 .BR kernel ,
 107 .BR elapsed ,
 108 or
 109 .BR sample ,
 110 to profile time measured spent in user mode, time spent in user+kernel mode, or elapsed time,
 111 using the cycle counter, or the time in user mode using the kernel's HZ clock.  The cycle counter
 112 is currently only available on modern PCs and on the PowerPC.  Default profiling measures user
 113 time, using the cycle counter if it is available.
 114 .PP
 115 .I Tprof
 116 is similar to
 117 .IR prof ,
 118 but is intended for profiling multiprocess programs.
 119 It uses the
 120 .BI /proc/ pid /profile
 121 file to collect instruction frequency counts for the text image associated with the process,
 122 for all processes that share that text.
 123 It must be run while the program is still active, since the data is stored with the running program.
 124 To enable
 125 .I tprof
 126 profiling for a given process,
 127 .IP
 128 .EX
 129 echo profile > /proc/\f2pid\f1/ctl
 130 .EE
 131 .LP
 132 and then, after the program has run for a while, execute
 133 .IP
 134 .EX
 135 tprof \f2pid\f1
 136 .EE
 137 .LP
 138 Since the data collected for
 139 .I tprof
 140 is based on interrupt-time sampling of the program counter,
 141 .I tprof
 142 has no
 143 .B -d
 144 or
 145 .B -r
 146 options.
 147 .PP
 148 .I Kprof
 149 is similar to
 150 .IR prof ,
 151 but presents the data accumulated by the kernel
 152 profiling device,
 153 .IR kprof (3) .
 154 The symbol table file, that of the operating system kernel,
 155 and the data file, typically
 156 .BR /dev/kpdata ,
 157 must be provided.
 158 .I Kprof
 159 has no options and cannot present dynamic data.
 160 .SH SOURCE
 161 .B /sys/src/cmd/prof.c
 162 .br
 163 .B /sys/src/cmd/kprof.c
 164 .SH SEE ALSO
 165 .IR 2l (1),
 166 .IR exec (2),
 167 .IR kprof (3)