duma.3 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383
  1. .TH DUMA 3 10-September-2005
  2. .SH NAME
  3. DUMA \- DUMA Malloc Debugger
  4. .SH SYNOPSIS
  5. .nf
  6. .ft B
  7. #include <stdlib.h>
  8. .ft
  9. .fi
  10. .LP
  11. .nf
  12. .ft B
  13. void * malloc (size_t size);
  14. .ft
  15. .fi
  16. .LP
  17. .nf
  18. .ft B
  19. void free (void *ptr);
  20. .ft
  21. .fi
  22. .LP
  23. .nf
  24. .ft B
  25. void * realloc (void *ptr, size_t size);
  26. .ft
  27. .fi
  28. .LP
  29. .nf
  30. .ft B
  31. void * calloc (size_t nelem, size_t elsize);
  32. .ft
  33. .fi
  34. .LP
  35. .nf
  36. .ft B
  37. void * memalign (size_t alignment, size_t size);
  38. .ft
  39. .fi
  40. .LP
  41. .nf
  42. .ft B
  43. void * valloc (size_t size);
  44. .ft
  45. .fi
  46. .LP
  47. .nf
  48. .ft B
  49. extern int DUMA_ALIGNMENT;
  50. .ft
  51. .fi
  52. .LP
  53. .nf
  54. .ft B
  55. extern int DUMA_PROTECT_BELOW;
  56. .ft
  57. .fi
  58. .LP
  59. .nf
  60. .ft B
  61. extern int DUMA_PROTECT_FREE;
  62. .ft
  63. .fi
  64. .LP
  65. .nf
  66. .ft B
  67. extern int DUMA_ALLOW_MALLOC_0;
  68. .ft
  69. .fi
  70. .LP
  71. .nf
  72. .ft B
  73. extern int DUMA_FILL;
  74. .ft
  75. .fi
  76. .SH DESCRIPTION
  77. .I DUMA
  78. helps you detect two common programming bugs:
  79. software that overruns the boundaries of a malloc() memory
  80. allocation, and software that touches a memory allocation that has been
  81. released by free(). Unlike other malloc() debuggers, DUMA will
  82. detect
  83. .I read
  84. accesses as well as writes, and it will pinpoint the exact instruction that
  85. causes an error. It has been in use at Pixar since 1987, and at many other
  86. sites for years.
  87. .LP
  88. DUMA uses the virtual memory hardware of your computer to place an
  89. inaccessible memory page immediately after (or before, at the user's option)
  90. each memory allocation. When software reads or writes this inaccessible page,
  91. the
  92. hardware issues a segmentation fault, stopping the program at the offending
  93. instruction. It is then trivial to find the erroneous statement using your
  94. favorite debugger. In a similar manner, memory that has been released by
  95. free() is made inaccessible, and any code that touches it will get a
  96. segmentation fault.
  97. .LP
  98. Simply linking your application with libduma.a will allow you to detect
  99. most, but not all, malloc buffer overruns and accesses of free memory.
  100. If you want to be reasonably sure that you've found
  101. .I all
  102. bugs of this type, you'll have to read and understand the rest of this
  103. man page.
  104. .SH USAGE
  105. Link your program with the library
  106. .B libduma.a .
  107. Make sure you are
  108. .I not
  109. linking with
  110. .B -lmalloc,
  111. .B -lmallocdebug,
  112. or with other malloc-debugger or malloc-enhancer libraries.
  113. You can only use one at a time.
  114. If your system administrator
  115. has installed DUMA for public use, you'll be able to use the
  116. .B -lduma
  117. argument to the linker, otherwise you'll have to put the path-name for
  118. .B libduma.a
  119. in the linker's command line.
  120. You can also use dynamic linking. If you're using a Bourne shell, the
  121. statement
  122. .B export LD_PRELOAD=libduma.so.0.0
  123. will cause DUMA to be loaded to run all dynamic executables.
  124. The command
  125. .B duma
  126. .I command
  127. runs a single command under DUMA.
  128. .LP
  129. Some systems will require special arguments to the linker to assure that
  130. you are using the DUMA malloc() and not the one from your C library.
  131. .LP
  132. Run your program
  133. .I using a debugger.
  134. It's easier to work this way than to create a
  135. .B core
  136. file and post-mortem debug it. DUMA can create
  137. .I huge
  138. core files, and some operating systems will thus take minutes simply to dump
  139. core! Some operating systems will not create usable core files from programs
  140. that are linked with DUMA.
  141. If your program has one of the errors detected by DUMA, it will
  142. get a segmentation fault (SIGSEGV) at the offending instruction. Use the
  143. debugger to locate the erroneous statement, and repair it.
  144. .SH GLOBAL AND ENVIRONMENT VARIABLES
  145. DUMA has four configuration switches that can be enabled via
  146. the shell environment, or by setting the value of global integer variables
  147. using a debugger. These switches change what bugs DUMA will detect,
  148. so it's important that you know how to use them.
  149. .TP
  150. DUMA_ALIGNMENT
  151. This is an integer that specifies the alignment for any memory allocations
  152. that will be returned by malloc(), calloc(), and realloc().
  153. The value is specified in
  154. bytes, thus a value of 4 will cause memory to be aligned to 32-bit boundaries
  155. unless your system doesn't have a 8-bit characters. DUMA_ALIGNMENT is set to
  156. sizeof(int) by default, since that is generally the word-size of your CPU.
  157. If your program requires that allocations be aligned to 64-bit
  158. boundaries and you have a 32-bit
  159. .B int
  160. you'll have to set this value to 8. This is the case when compiling with the
  161. .B -mips2
  162. flag on MIPS-based systems such as those from SGI.
  163. The memory allocation that is returned by DUMA malloc() is aligned
  164. using the value in DUMA_ALIGNMENT, and
  165. .I its size the multiple of
  166. .I that value
  167. that is greater than or equal to the requested size.
  168. For this reason, you will sometimes want to set DUMA_ALIGNMENT to 0 (no
  169. alignment), so that
  170. you can detect overruns of less than your CPU's word size. Be sure to read
  171. the section
  172. .I WORD-ALIGNMENT AND OVERRUN DETECTION
  173. in this manual page before you try this.
  174. To change this value, set DUMA_ALIGNMENT in the shell environment to an
  175. integer value, or assign
  176. to the global integer variable DUMA_ALIGNMENT using a debugger.
  177. .TP
  178. DUMA_PROTECT_BELOW
  179. DUMA usually places an inaccessible page immediately after each
  180. memory allocation, so that software that runs past the end of the allocation
  181. will be detected. Setting DUMA_PROTECT_BELOW to 1 causes DUMA
  182. to place the inaccessible page
  183. .I before
  184. the allocation in the address space, so that under-runs will be detected
  185. instead of over-runs.
  186. When DUMA_PROTECT_BELOW is set, the DUMA_ALIGNMENT parameter is ignored.
  187. All allocations will be aligned to virtual-memory-page boundaries, and
  188. their size will be the exact size that was requested.
  189. To change this value, set DUMA_PROTECT_BELOW in the shell environment to an
  190. integer value, or assign to the global integer variable DUMA_PROTECT_BELOW using
  191. a debugger.
  192. .TP
  193. DUMA_PROTECT_FREE
  194. DUMA usually returns free memory to a pool from which it may be
  195. re-allocated. If you suspect that a program may be touching free memory,
  196. set DUMA_PROTECT_FREE to 1. This will cause DUMA to never re-allocate
  197. memory once it has been freed, so that any access to free memory will be
  198. detected. Some programs will use tremendous amounts of memory when this
  199. parameter is set.
  200. To change this value, set DUMA_PROTECT_FREE in the shell environment to an
  201. integer value, or assign to the global integer variable DUMA_PROTECT_FREE using
  202. a debugger.
  203. .TP
  204. DUMA_ALLOW_MALLOC_0
  205. By default, DUMA traps calls to malloc() with a size of zero, because
  206. they are often the result of a software bug. If DUMA_ALLOW_MALLOC_0 is non-zero,
  207. the software will not trap calls to malloc() with a size of zero.
  208. To change this value, set DUMA_ALLOC_MALLOC_0 in the shell environment to an
  209. integer value, or assign to the global integer variable DUMA_ALLOC_MALLOC_0 using
  210. a debugger.
  211. .TP
  212. DUMA_FILL
  213. When set to a value between 0 and 255, every byte of allocated memory is
  214. initialized to that value. This can help detect reads of uninitialized memory.
  215. When set to -1, some memory is filled with zeroes
  216. (the operating system default on most systems) and some memory will retain
  217. the values written to it during its last use.
  218. .TP
  219. DUMA_MEMCPY_OVERLAP
  220. Setting this variable to 1 will make DUMA to ignore memcpy region overlapping when
  221. the destination address is less than source address. It was added as a workaround
  222. for ARM port where memmove implementation calls memcpy if the overlapping
  223. destination is safe and produces in false aborts.
  224. .SH WORD-ALIGNMENT AND OVERRUN DETECTION
  225. There is a conflict between the alignment restrictions that malloc() operates
  226. under and the debugging strategy used by DUMA. When detecting
  227. overruns, DUMA malloc() allocates two or more virtual memory
  228. pages for each allocation. The last page is made inaccessible in such a way
  229. that any read, write, or execute access will cause a segmentation fault.
  230. Then, DUMA malloc() will return an address such that the first
  231. byte after
  232. the end of the allocation is on the inaccessible page.
  233. Thus, any overrun
  234. of the allocation will cause a segmentation fault.
  235. .LP
  236. It follows that the
  237. address returned by malloc() is the address of the inaccessible page minus
  238. the size of the memory allocation.
  239. Unfortunately, malloc() is required to return
  240. .I word-aligned
  241. allocations, since many CPUs can only access a word when its address is aligned.
  242. The conflict happens when software makes a memory allocation using a size that
  243. is not a multiple of the word size, and expects to do word accesses to that
  244. allocation. The location of the inaccessible page is fixed by hardware at
  245. a word-aligned address. If DUMA malloc() is to return an aligned
  246. address, it must increase the size of the allocation to a multiple of the
  247. word size.
  248. In addition, the functions memalign() and valloc() must honor explicit
  249. specifications on the alignment of the memory allocation, and this, as well
  250. can only be implemented by increasing the size of the allocation.
  251. Thus, there will be situations in which the end of a memory allocation
  252. contains some padding space, and accesses of that padding space will not
  253. be detected, even if they are overruns.
  254. .LP
  255. DUMA provides the variable DUMA_ALIGNMENT so that the user can
  256. control the default alignment used by malloc(), calloc(), and realloc().
  257. To debug overruns as small as a single byte, you can set DUMA_ALIGNMENT to
  258. zero. This will result in DUMA malloc() returning unaligned
  259. addresses for allocations with sizes that are not a multiple of the word
  260. size. This is not a problem in most cases, because compilers must pad the
  261. size of objects so that alignment restrictions are honored when storing
  262. those objects in arrays. The problem surfaces when software allocates
  263. odd-sized buffers for objects that must be word-aligned. One case of this
  264. is software that allocates a buffer to contain a structure and a
  265. string, and the string has an odd size (this example was in a popular TIFF
  266. library). If word references are made to un-aligned buffers, you will see
  267. a bus error (SIGBUS) instead of a segmentation fault. The only way to fix
  268. this is to re-write the offending code to make byte references or not make
  269. odd-sized allocations, or to set DUMA_ALIGNMENT to the word size.
  270. .LP
  271. Another example of software incompatible with
  272. DUMA_ALIGNMENT < word-size
  273. is the strcmp() function and other string functions on SunOS (and probably
  274. Solaris), which make word-sized accesses to character strings, and may
  275. attempt to access up to three bytes beyond the end of a string. These
  276. result in a segmentation fault (SIGSEGV). The only way around this is to
  277. use versions of the string functions that perform byte references instead
  278. of word references.
  279. .SH INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM
  280. .TP
  281. 1.
  282. Link with libduma.a as explained above.
  283. .TP
  284. 2.
  285. Run your program in a debugger and fix any overruns or accesses to free memory.
  286. .TP
  287. 3.
  288. Quit the debugger.
  289. .TP
  290. 4.
  291. Set DUMA_PROTECT_BELOW = 1 in the shell environment.
  292. .TP
  293. 5.
  294. Repeat step 2, this time repairing underruns if they occur.
  295. .TP
  296. 6.
  297. Quit the debugger.
  298. .TP
  299. 7.
  300. Read the restrictions in the section on
  301. .I WORD-ALIGNMENT AND OVERRUN DETECTION.
  302. See if you can
  303. set DUMA_ALIGNMENT to 0 and repeat step 2. Sometimes this will be too much work,
  304. or there will be problems with library routines for which you don't have the
  305. source, that will prevent you from doing this.
  306. .SH MEMORY USAGE AND EXECUTION SPEED
  307. Since DUMA uses at least two virtual memory pages for each of its
  308. allocations, it's a terrible memory hog. I've sometimes found it necessary to
  309. add a swap file using swapon(8) so that the system would have enough virtual
  310. memory to debug my program. Also, the way we manipulate memory results in
  311. various cache and translation buffer entries being flushed with each call
  312. to malloc or free. The end result is that your program will be much slower
  313. and use more resources while you are debugging it with DUMA.
  314. .LP
  315. Don't leave libduma.a linked into production software! Use it only
  316. for debugging.
  317. .SH AUTHOR
  318. Hayati Ayguen
  319. .SH WARNINGS
  320. I have tried to do as good a job as I can on this software, but I doubt
  321. that it is even theoretically possible to make it bug-free.
  322. This software has no warranty. It will not detect some bugs that you might
  323. expect it to detect, and will indicate that some non-bugs are bugs.
  324. .SH LICENSE
  325. Copyright 1987-1999 Bruce Perens. All rights reserved.
  326. .br
  327. This program is free software; you can redistribute it and/or modify
  328. it under the terms of the GNU General Public License, Version 2,
  329. as published by the Free Software Foundation. A copy of this license is
  330. distributed with this software in the file "COPYING".
  331. This program is distributed in the hope that it will be useful,
  332. but WITHOUT ANY WARRANTY; without even the implied warranty of
  333. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Read the
  334. file "COPYING" for more details.
  335. .SH CONTACTING THE AUTHOR
  336. .nf
  337. Bruce Perens
  338. 1563 Solano Ave. #349
  339. Berkeley, CA 94707
  340. Telephone: 510-526-1165
  341. Internet: bruce@perens.com
  342. .fi
  343. .ft
  344. .SH FILES
  345. /dev/zero: Source of memory pages (via mmap(2)).
  346. .SH SEE ALSO
  347. malloc(3), mmap(2), mprotect(2), swapon(8)
  348. .SH DIAGNOSTICS
  349. Segmentation Fault: Examine the offending statement for violation of the
  350. boundaries of a memory allocation.
  351. .br
  352. Bus Error: See the section on
  353. .I WORD-ALIGNMENT AND OVERRUN DETECTION.
  354. in this manual page.
  355. .SH BUGS
  356. My explanation of the alignment issue could be improved.
  357. .LP
  358. Some Sun systems running SunOS 4.1 were reported to signal an access to a
  359. protected page with
  360. .B SIGBUS
  361. rather than
  362. .B SIGSEGV,
  363. I suspect this is an undocumented feature of a particular Sun hardware
  364. version, not just the operating system.
  365. On these systems, dumatest will fail with a bus error until you modify the
  366. Makefile to define
  367. .B PAGE_PROTECTION_VIOLATED_SIGNAL
  368. as
  369. .B SIGBUS.
  370. .LP
  371. There are, without doubt, other bugs and porting issues. Please contact me via
  372. e-mail if you have any bug reports, ideas, etc.
  373. .SH WHAT'S BETTER
  374. .I Purify
  375. does a much more thorough job than DUMA, and does not have
  376. the huge memory overhead.
  377. .I Checkergcc,
  378. a modified version of the GNU C Compiler that instruments all memory
  379. references,
  380. is available on Linux systems and where GCC is used. It performs some of the
  381. same tasks as Purify, but only on code that it has compiled.