sys/man/1/leak

   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 .IR 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 one 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.
 231 .PP
 232 These commands require
 233 .B /sys/src/libc/port/pool.acid
 234 to be present and generated from
 235 .BR pool.c .