prof 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  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)