leak 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. .TH LEAK 1
  2. .SH NAME
  3. leak, kmem, umem \- help find memory leaks
  4. .SH SYNOPSIS
  5. .B leak
  6. [
  7. .B -abcds
  8. ]
  9. [
  10. .B -f
  11. .I binary
  12. ]
  13. [
  14. .B -r
  15. .I res
  16. ]
  17. [
  18. .B -x
  19. .I width
  20. ]
  21. .I pid ...
  22. .PP
  23. .B kmem
  24. [
  25. .I kernel
  26. ]
  27. .PP
  28. .B umem
  29. .I pid
  30. [
  31. .I textfile
  32. ]
  33. .SH DESCRIPTION
  34. .I Leak
  35. examines the named processes, which
  36. should be sharing their data and bss segments,
  37. for memory leaks.
  38. It uses a mark and sweep-style algorithm to
  39. determine which allocated blocks are no longer
  40. reachable from the set of root pointers.
  41. The set of root pointers is created by looking through
  42. the shared bss segment as well as each process's registers.
  43. .PP
  44. Unless directed otherwise,
  45. .I leak
  46. prints, for each block, a line with seven space-separated fields:
  47. the string
  48. .BR block ,
  49. the address of the block,
  50. the size of the block,
  51. the first two words of the block,
  52. and the function names represented by the first two words of the block.
  53. Usually, the first two words of the block
  54. contain the malloc and realloc tags
  55. (see
  56. .IR malloc (2)),
  57. useful for finding who allocated the leaked blocks.
  58. .PP
  59. If the
  60. .B -s
  61. or the
  62. .B -c
  63. option is given,
  64. .I leak
  65. will instead present a sequence of
  66. .IR acid (1)
  67. commands that show each leaky allocation site.
  68. With
  69. .B -s
  70. a comment appears next to each command to
  71. indicate how many lost blocks were allocated
  72. at that point in the program.
  73. With
  74. .B -c
  75. the comments are extended to indicate also the total
  76. number of bytes lost at that point in the program,
  77. and an additional comment line gives the
  78. overall total number of bytes.
  79. .PP
  80. If the
  81. .B -a
  82. option is given,
  83. .I leak
  84. will print information as decribed above,
  85. but for all allocated blocks,
  86. not only leaked ones.
  87. If the
  88. .B -d
  89. option is given,
  90. .I leak
  91. will print information as decribed above,
  92. but for all free blocks,
  93. i.e. those freed,
  94. or those that are not yet
  95. in use (fragmentation?).
  96. The
  97. .B -a
  98. and
  99. .B -d
  100. options can be combined.
  101. .PP
  102. If the
  103. .B -b
  104. option is given,
  105. .I leak
  106. will print a Plan 9 image file
  107. graphically summarizing the memory arenas.
  108. In the image, each pixel represents
  109. .I res
  110. (default 8)
  111. bytes.
  112. The color code is:
  113. .TP "\w'\fIbright blue\fR 'u
  114. .I "dark blue
  115. Completely allocated.
  116. .TP
  117. .I "bright blue
  118. Contains malloc headers.
  119. .TP
  120. .I "bright red
  121. Contains malloc headers for leaked memory.
  122. .TP
  123. .I "dark red
  124. Contains leaked memory.
  125. .TP
  126. .I "yellow
  127. Completely free
  128. .TP
  129. .I "white
  130. Padding to fill out the image.
  131. .PD
  132. The bright pixels representing headers help in
  133. counting the number of blocks.
  134. Magnifying the images with
  135. .IR lens (1)
  136. is often useful.
  137. .PP
  138. If given a name rather than a list of process ids,
  139. .I leak
  140. echoes back a command-line with process ids of every process
  141. with that name.
  142. .PP
  143. The
  144. .B -f
  145. option specifies a binary to go on the
  146. .IR acid (1)
  147. command-line used to inspect the
  148. processes, and is only necessary
  149. when inspecting processes started
  150. from stripped binaries.
  151. .PP
  152. .I Umem
  153. prints a summary of all allocated blocks in the process with id
  154. .IR pid .
  155. Each line of the summary gives the count and total size of
  156. blocks allocated at an allocation point.
  157. The list is sorted by count in decreasing order.
  158. .I Umem
  159. prints summarizes all allocations, not just
  160. memory leaks, but it is faster and requires less memory than
  161. .I leak .
  162. .PP
  163. .I Kmem
  164. is like
  165. .I umem
  166. but prints a summary for the running kernel.
  167. .SH EXAMPLES
  168. List lost blocks in
  169. .IR 8.out .
  170. This depends on the fact that there is only
  171. once instance of
  172. .I 8.out
  173. running; if there were more, the output of
  174. .B "leak -s 8.out
  175. would need editing before sending to the shell.
  176. .IP
  177. .EX
  178. % leak -s 8.out
  179. leak -s 229 230
  180. % leak -s 8.out | rc
  181. src(0x0000bf1b); // 64
  182. src(0x000016f5); // 7
  183. src(0x0000a988); // 7
  184. %
  185. .EE
  186. .LP
  187. View the memory usage graphic for the window system.
  188. .IP
  189. .EX
  190. % leak -b rio | rc | page
  191. .EE
  192. .PP
  193. List the top allocation points in the kernel,
  194. first by count and then by total size:
  195. .IP
  196. .EX
  197. % kmem | sed 10q
  198. % kmem | sort -nr +1 | sed 10q
  199. .EE
  200. .SH SOURCE
  201. .B /sys/lib/acid/leak
  202. .br
  203. .B /sys/src/cmd/aux/acidleak.c
  204. .br
  205. .B /rc/bin/leak
  206. .br
  207. .B /rc/bin/kmem
  208. .br
  209. .B /rc/bin/umem
  210. .SH SEE ALSO
  211. .IR getcallerpc (2),
  212. .I setmalloctag
  213. in
  214. .IR malloc (2)
  215. .SH BUGS
  216. .I Leak
  217. and
  218. .I kmem
  219. depend on the internal structure of the
  220. libc pool memory allocator (see
  221. .IR pool (2)).
  222. Since the ANSI/POSIX environment uses a different
  223. allocator,
  224. .I leak
  225. will not work on APE programs.
  226. .PP
  227. .I Leak
  228. is not speedy, and
  229. .I acidleak
  230. can consume more memory than the process(es) being examined.