Debian Codegraph @

docs/dmalloc.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
2 <html>
3 <!-- Created on May, 14 2007 by texi2html 1.76 -->
4 <!--
5 Written by: Lionel Cons <[email protected]> (original author)
6 Karl Berry <[email protected]>
7 Olaf Bachmann <[email protected]>
8 and many others.
9 Maintained by: Many creative people <[email protected]>
10 Send bugs and suggestions to <[email protected]>
11
12 -->
13 <head>
14 <title>Dmalloc Tutorial: Debug Malloc Library</title>
15
16 <meta name="description" content="Dmalloc Tutorial: Debug Malloc Library">
17 <meta name="keywords" content="Dmalloc Tutorial: Debug Malloc Library">
18 <meta name="resource-type" content="document">
19 <meta name="distribution" content="global">
20 <meta name="Generator" content="texi2html 1.76">
21 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
22 <style type="text/css">
23 <!--
24 a.summary-letter {text-decoration: none}
25 pre.display {font-family: serif}
26 pre.format {font-family: serif}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 pre.smalldisplay {font-family: serif; font-size: smaller}
30 pre.smallexample {font-size: smaller}
31 pre.smallformat {font-family: serif; font-size: smaller}
32 pre.smalllisp {font-size: smaller}
33 span.sansserif {font-family:sans-serif; font-weight:normal;}
34 ul.toc {list-style: none}
35 -->
36 </style>
37
38
39 </head>
40
41 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
42
43 <a name="Top"></a>
44 <a name="SEC_Top"></a>
45 <table cellpadding="1" cellspacing="1" border="0">
46 <tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
47 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
48 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
49 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
50 </tr></table>
51 <h1 class="settitle">Debug Malloc Library</h1>
52
53
54
55 <p>The debug memory allocation or <em>dmalloc</em> library has been designed
56 as a drop in replacement for the system's <code>malloc</code>, <code>realloc</code>,
57 <code>calloc</code>, <code>free</code> and other memory management routines while
58 providing powerful debugging facilities configurable at runtime. These
59 facilities include such things as memory-leak tracking, fence-post write
60 detection, file/line number reporting, and general logging of
61 statistics.
62 </p>
63 <p>The library is reasonably portable having been run successfully on at
64 least the following operating systems: AIX, DGUX, Free/Net/OpenBSD,
65 GNU/Hurd, HPUX, Irix, Linux, Mac OSX, NeXT, OSF/DUX, SCO, Solaris,
66 Ultrix, Unixware, MS Windows, and Unicos on a Cray T3E. It also
67 provides support for the debugging of threaded programs. See section <a href="#SEC24">Using the Library with a Thread Package</a>.
68 </p>
69 <p>The package includes the library, configuration scripts, debug utility
70 application, test program, and documentation. Online documentation as
71 well as the full source is available at URL <a href="http://dmalloc.com/">http://dmalloc.com/</a>.
72 Details on the library's mailing list are available there as well.
73 </p>
74 <p>Please use the forums at URL <a href="http://dmalloc.com/">http://dmalloc.com/</a> to discuss any
75 problems or to request features. If you are still having problems,
76 the author can be reached via his home page at URL
77 <a href="http://256.com/gray/">http://256.com/gray/</a> with questions or feedback. Please
78 include the version number of the library that you are using, your
79 machine and operating system types, and the value of the
80 DMALLOC_OPTIONS environment variable.
81 </p>
82 <p>Gray Watson.
83 </p>
84 <table class="menu" border="0" cellspacing="0">
85 <tr><td align="left" valign="top"><a href="#SEC1">1. Library Copying and Licensing Conditions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Library copying and licensing conditions.
86 </td></tr>
87 <tr><td align="left" valign="top"><a href="#SEC2">2. Description of Features and How to Get Started</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Description of features and how to get started.
88 </td></tr>
89 <tr><td align="left" valign="top"><a href="#SEC10">3. How to Program with the Library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How to program with the library.
90 </td></tr>
91 <tr><td align="left" valign="top"><a href="#SEC29">4. Dmalloc Utility Program</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How to use the library's utility.
92 </td></tr>
93 <tr><td align="left" valign="top"><a href="#SEC35">5. Information on the Source Code</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Information on the source code.
94 </td></tr>
95 <tr><td align="left" valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Some solutions to common problems.
96 </td></tr>
97 <tr><td align="left" valign="top"><a href="#SEC40">Index of Concepts</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Index of concepts in the manual.
98 </td></tr>
99 </table>
100
101
102 <hr size="1">
103 <a name="Copying"></a>
104 <a name="SEC1"></a>
105 <table cellpadding="1" cellspacing="1" border="0">
106 <tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Previous section in reading order"> &lt; </a>]</td>
107 <td valign="middle" align="left">[<a href="#SEC2" title="Next section in reading order"> &gt; </a>]</td>
108 <td valign="middle" align="left"> &nbsp; </td>
109 <td valign="middle" align="left">[ &lt;&lt; ]</td>
110 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
111 <td valign="middle" align="left">[<a href="#SEC2" title="Next chapter"> &gt;&gt; </a>]</td>
112 <td valign="middle" align="left"> &nbsp; </td>
113 <td valign="middle" align="left"> &nbsp; </td>
114 <td valign="middle" align="left"> &nbsp; </td>
115 <td valign="middle" align="left"> &nbsp; </td>
116 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
117 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
118 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
119 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
120 </tr></table>
121 <h1 class="chapter"> 1. Library Copying and Licensing Conditions </h1>
122
123
124 <p>Copyright 1992 to 2007 by Gray Watson.
125 </p>
126 <p>Permission to use, copy, modify, and distribute this software for any
127 purpose and without fee is hereby granted, provided that the above
128 copyright notice and this permission notice appear in all copies, and
129 that the name of Gray Watson not be used in advertising or publicity
130 pertaining to distribution of the document or software without specific,
131 written prior permission.
132 </p>
133 <p>Gray Watson makes no representations about the suitability of the
134 software described herein for any purpose. It is provided &quot;as is&quot;
135 without express or implied warranty.
136 </p>
137
138 <hr size="6">
139 <a name="Overview"></a>
140 <a name="SEC2"></a>
141 <table cellpadding="1" cellspacing="1" border="0">
142 <tr><td valign="middle" align="left">[<a href="#SEC1" title="Previous section in reading order"> &lt; </a>]</td>
143 <td valign="middle" align="left">[<a href="#SEC3" title="Next section in reading order"> &gt; </a>]</td>
144 <td valign="middle" align="left"> &nbsp; </td>
145 <td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
146 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
147 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
148 <td valign="middle" align="left"> &nbsp; </td>
149 <td valign="middle" align="left"> &nbsp; </td>
150 <td valign="middle" align="left"> &nbsp; </td>
151 <td valign="middle" align="left"> &nbsp; </td>
152 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
153 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
154 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
155 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
156 </tr></table>
157 <h1 class="chapter"> 2. Description of Features and How to Get Started </h1>
158
159
160 <table class="menu" border="0" cellspacing="0">
161 <tr><td align="left" valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How to install the library.
162 </td></tr>
163 <tr><td align="left" valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Getting started with the library.
164 </td></tr>
165 <tr><td align="left" valign="top"><a href="#SEC5">2.3 Basic Description of Terms and Functions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Basic description of terms and functions.
166 </td></tr>
167 <tr><td align="left" valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> General features of the library.
168 </td></tr>
169 <tr><td align="left" valign="top"><a href="#SEC9">2.5 How the Library Checks Your Program</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How the library checks your program.
170 </td></tr>
171 </table>
172
173
174 <hr size="6">
175 <a name="Installation"></a>
176 <a name="SEC3"></a>
177 <table cellpadding="1" cellspacing="1" border="0">
178 <tr><td valign="middle" align="left">[<a href="#SEC2" title="Previous section in reading order"> &lt; </a>]</td>
179 <td valign="middle" align="left">[<a href="#SEC4" title="Next section in reading order"> &gt; </a>]</td>
180 <td valign="middle" align="left"> &nbsp; </td>
181 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
182 <td valign="middle" align="left">[<a href="#SEC2" title="Up section"> Up </a>]</td>
183 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
184 <td valign="middle" align="left"> &nbsp; </td>
185 <td valign="middle" align="left"> &nbsp; </td>
186 <td valign="middle" align="left"> &nbsp; </td>
187 <td valign="middle" align="left"> &nbsp; </td>
188 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
189 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
190 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
191 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
192 </tr></table>
193 <h2 class="section"> 2.1 How to Install the Library </h2>
194
195
196 <p>To configure, compile, and install the library, follow these steps
197 carefully.
198 </p>
199 <ol>
200 <li> Make sure you have downloaded the latest version of the library
201 available from the home page at URL <a href="http://dmalloc.com/">http://dmalloc.com/</a>.
202
203 </li><li> The release files have a <tt>`.tgz'</tt> file extension which means
204 that they are a tar'd gzip'd directory of files. You will need to
205 ungzip and then untar the release file into your source work
206 directory. You may have to rename the file to <tt>`.tar.gz'</tt> to get
207 some old zip programs to handle the file correctly.
208
209 <a name="IDX1"></a>
210
211 </li><li> You may want to edit or at least review the settings in
212 <tt>`settings.dist'</tt> to tune specific features of the library. The
213 <tt>`configure'</tt> script will copy this file to <tt>`settings.h'</tt> which
214 is where you should be adding per-architecture settings.
215
216 <a name="IDX2"></a>
217 <a name="IDX3"></a>
218 <a name="IDX4"></a>
219 <a name="IDX5"></a>
220 <a name="IDX6"></a>
221
222 </li><li> Type <kbd>sh ./configure</kbd> to configure the library. You may want
223 to first examine the <tt>`config.help'</tt> file for some information about
224 configure. You may want to use the <kbd>--disable-cxx</kbd> option if you do
225 not want the Makefile to build the C++ version of dmalloc. You may want
226 to use the <kbd>--enable-threads</kbd> option to build the threaded version
227 of dmalloc. You may want to use the <kbd>--enable-shlib</kbd> option to
228 build the shared versions of the dmalloc libraries. <kbd>sh ./configure
229 --help</kbd> lists the available options to configure. Configure should
230 generate the <tt>`Makefile'</tt> and configuration files automatically.
231
232 </li><li> You may want to examine the <tt>`Makefile'</tt> and <tt>`conf.h'</tt> files
233 created by configure to make sure it did its job correctly.
234
235 <a name="IDX7"></a>
236
237 </li><li> You might want to tune the settings in <tt>`settings.h'</tt> file to
238 tune the library to the local architecture. This file contains relevant
239 settings if you are using pthreads or another thread library.
240 See section <a href="#SEC24">Using the Library with a Thread Package</a>. The <tt>`configure'</tt> script created this
241 file from the <tt>`settings.dist'</tt> file. Any permanent changes to these
242 settings should made to the <tt>`settings.dist'</tt> file. You then can run
243 <tt>`config.status'</tt> to re-create the <tt>`settings.h'</tt> file.
244
245 <a name="IDX8"></a>
246
247 </li><li> The <code>DMALLOC_SIZE</code> variable gets auto-configured in
248 <tt>`dmalloc.h.2'</tt> but it may not generate correct settings for all
249 systems. You may have to alter the definitions in this file to get
250 things to stop complaining when you go to compile about the size
251 arguments to malloc routines. Comments on this please.
252
253 </li><li> Typing <kbd>make</kbd> should be enough to build <tt>`libdmalloc.a'</tt>,
254 and <tt>`dmalloc'</tt> program. If it does not work, please see if there
255 are any notes in the contrib directory about your system-type. If not
256 and you figure your problem out, please send me some notes so future
257 users can profit from your experiences.
258
259 <a name="IDX9"></a>
260
261 <p><em>NOTE</em>: You may experience some errors compiling some of the
262 <tt>`return.h'</tt> assembly macros which attempt to determine the callers
263 address for logging purposes. See section <a href="#SEC38">Issues Important for Porting the Library</a>. You may want to
264 first try disabling any compiler optimization flags. If this doesn't
265 work then you may need to disable the <samp>`USE_RETURN_MACROS'</samp>
266 variable in the <tt>`settings.h'</tt> file.
267 </p>
268 <a name="IDX10"></a>
269
270 <p><em>NOTE</em>: The code is dependent on an ANSI-C compiler. If the
271 configure script gives the <samp>`WARNING'</samp> that you do not have an ANSI-C
272 compiler, you may still be able to add some sort of option to your
273 compiler to make it ANSI. If there such is an option, please send it to
274 the author so it can be added to the configure script.
275 </p>
276 </li><li> If you use threads and did not add the <kbd>--enable-threads</kbd>
277 argument to configure, typing <kbd>make threads</kbd> should be enough to
278 build <tt>`libdmallocth.a'</tt> which is the threaded version of the
279 library. This may or may not work depending on the configuration
280 scripts ability to detect your local thread functionality. Feel free to
281 send me mail with improvements.
282
283 <p>See the section of the manual on threads for more information about
284 the operation of the library with your threaded program. See section <a href="#SEC24">Using the Library with a Thread Package</a>.
285 </p>
286 </li><li> If you have a C++ compiler installed, the library should have
287 automatically built <tt>`libdmallocxx.a'</tt> which is the C++ version of
288 the library. If it was not done automatically, you can build it by
289 typing <kbd>make cxx</kbd>. You should link this library into your C++
290 programs instead of <tt>`libdmalloc.a'</tt>. See the <tt>`dmallocc.cc'</tt> C++
291 file which contains basic code to overload the <code>new</code>, <code>new[]</code>,
292 <code>delete</code>, and <code>delete[]</code> C++ operators. My apologies on the
293 minimal C++ support. I am still living in a mostly C world. Any help
294 improving this interface without sacrificing portability would be
295 appreciated.
296
297 <a name="IDX11"></a>
298 <a name="IDX12"></a>
299
300 </li><li> Typing <kbd>make light</kbd> should build and run the <tt>`dmalloc_t'</tt> test
301 program through a set of light trials. By default this will execute
302 <tt>`dmalloc_t'</tt> 5 times - each time will execute 10,000 malloc
303 operations in a very random manner. Anal folks can type <kbd>make
304 heavy</kbd> to up the ante. Use <kbd>dmalloc_t --usage</kbd> for the list of all
305 <tt>`dmalloc_t'</tt> options.
306
307 </li><li> Typing <kbd>make install</kbd> should install the <tt>`libdmalloc.a'</tt>
308 library in <tt>`/usr/local/lib'</tt>, the <tt>`dmalloc.h'</tt> include file in
309 <tt>`/usr/local/include'</tt>, and the <tt>`dmalloc'</tt> utility in
310 <tt>`/usr/local/bin'</tt>. You may also want to type <kbd>make installth</kbd>
311 to install the thread library into place and/or <kbd>make installcc</kbd> to
312 install the C++ library into place.
313
314 <p>You may have specified a <samp>`--prefix=PATH'</samp> option to configure in
315 which case <samp>`/usr/local'</samp> will have been replaced with <samp>`PATH'</samp>.
316 </p>
317 </li></ol>
318
319 <p>See the &quot;Getting Started&quot; section to get up and running with the
320 library. See section <a href="#SEC4">Getting Started with the Library</a>.
321 </p>
322
323 <hr size="6">
324 <a name="Getting-Started"></a>
325 <a name="SEC4"></a>
326 <table cellpadding="1" cellspacing="1" border="0">
327 <tr><td valign="middle" align="left">[<a href="#SEC3" title="Previous section in reading order"> &lt; </a>]</td>
328 <td valign="middle" align="left">[<a href="#SEC5" title="Next section in reading order"> &gt; </a>]</td>
329 <td valign="middle" align="left"> &nbsp; </td>
330 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
331 <td valign="middle" align="left">[<a href="#SEC2" title="Up section"> Up </a>]</td>
332 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
333 <td valign="middle" align="left"> &nbsp; </td>
334 <td valign="middle" align="left"> &nbsp; </td>
335 <td valign="middle" align="left"> &nbsp; </td>
336 <td valign="middle" align="left"> &nbsp; </td>
337 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
338 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
339 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
340 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
341 </tr></table>
342 <h2 class="section"> 2.2 Getting Started with the Library </h2>
343
344
345 <p>This section should give you a quick idea on how to get going.
346 Basically, you need to do the following things to make use of the
347 library:
348 </p>
349 <ol>
350 <li> Make sure you have downloaded the latest version of the library
351 available from the home page at URL <a href="http://dmalloc.com/">http://dmalloc.com/</a>.
352
353 </li><li> Follow the installation instructions on how to configure,
354 make, and install the library (i.e. type: <kbd>make install</kbd>).
355 See section <a href="#SEC3">How to Install the Library</a>.
356
357 <a name="IDX13"></a>
358 <a name="IDX14"></a>
359 <a name="IDX15"></a>
360 <a name="IDX16"></a>
361 <a name="IDX17"></a>
362
363 </li><li> You need to make sure that the library configuration and
364 build process above was able to locate one of the <code>on_exit</code>
365 function, <code>atexit</code> function, or had compiler destructor support.
366 If one of these functions or support is available then the dmalloc
367 library should be able to automatically shut itself down when the
368 program exits. This causes the memory statistics and unfreed
369 information to be dumped to the log file. However, if your system has
370 none of the above, then you will need to call <code>dmalloc_shutdown</code>
371 yourself before your program exits.
372
373 <a name="IDX18"></a>
374 <a name="IDX19"></a>
375 <a name="IDX20"></a>
376 <a name="IDX21"></a>
377
378 </li><li> To get the dmalloc utility to work you need to add an alias for
379 dmalloc to your shell's runtime configuration file if supported. The
380 idea is to have the shell capture the dmalloc program's output and
381 adjust the environment.
382
383 <p>After you add the alias to the shell config file you need to log out
384 and log back in to have it take effect, or you can execute the
385 appropriate command below on the command line directly. After you
386 setup the alias, if you enter <kbd>dmalloc runtime</kbd> and see any output
387 with DMALLOC_OPTIONS in it then the alias did not take effect.
388 </p>
389 <p>Bash, ksh, and zsh (<a href="http://www.zsh.org/">http://www.zsh.org/</a>) users should add the
390 following to their <tt>`.bashrc'</tt>, <tt>`.profile'</tt>, or <tt>`.zshrc'</tt>
391 file respectively (notice the <kbd>-b</kbd> option for bourne shell
392 output):
393 </p>
394 <table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `command dmalloc -b $*`; }
395 </pre></td></tr></table>
396 <p>If your shell does not support the <code>command</code> function then try:
397 </p>
398 <table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `\dmalloc -b $*`; }
399 </pre></td></tr></table><p>or
400 </p><table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
401 </pre></td></tr></table>
402 <a name="IDX22"></a>
403 <a name="IDX23"></a>
404
405 <p>If you are still using csh or tcsh, you should add the following to
406 your <tt>`.cshrc'</tt> file (notice the <kbd>-C</kbd> option for c-shell
407 output):
408 </p>
409 <table><tr><td>&nbsp;</td><td><pre class="example">alias dmalloc 'eval `\dmalloc -C \!*`'
410 </pre></td></tr></table>
411 <a name="IDX24"></a>
412
413 <p>If you are using rc shell, you should add the following to your
414 <tt>`.rcrc'</tt> file (notice the <kbd>-R</kbd> option for rc-shell output):
415 </p>
416 <table><tr><td>&nbsp;</td><td><pre class="example">fn dmalloc {eval `{/usr/local/bin/dmalloc $*}}
417 </pre></td></tr></table>
418 </li><li> Although not necessary, you may want to include <tt>`dmalloc.h'</tt>
419 in your C files and recompile. This will allow the library to report
420 the file/line numbers of calls that generate problems. See section <a href="#SEC11">Macros Providing File and Line Information</a>. It should be inserted at the <em>bottom</em> of your include
421 files as to not conflict with wother includes. You may want to ifdef it
422 as well and compile with <kbd>cc -DDMALLOC &hellip;</kbd>:
423
424 <table><tr><td>&nbsp;</td><td><pre class="example">/* other includes above ^^^ */
425
426 #ifdef DMALLOC
427 #include &quot;dmalloc.h&quot;
428 #endif
429 </pre></td></tr></table>
430 <a name="IDX25"></a>
431 </li><li> Another optional task is to compile all of your source with the
432 <tt>`dmalloc.h'</tt> with the <code>DMALLOC_FUNC_CHECK</code> compilation flag.
433 This willallow the library to check all of the arguments of a number
434 of common string and utility routines. See section <a href="#SEC13">Checking of Function Arguments</a>.
435
436 <table><tr><td>&nbsp;</td><td><pre class="example">cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
437 </pre></td></tr></table>
438 </li><li> Link the dmalloc library into your program. The dmalloc library
439 should probably be placed at or near the end of the library list.
440
441 </li><li> Enable the debugging features by typing <kbd>dmalloc -l logfile
442 -i 100 low</kbd> (for example). You should not see any messages printed by
443 the dmalloc utility (see NOTE below). This will:
444
445 <ul>
446 <li> Set the malloc logfile name to <tt>`logfile'</tt> (<kbd>-l logfile</kbd>).
447 For programs which change directories, you may want to specify the
448 full path to your logfile.
449
450 </li><li> Have the library check itself every 100 iterations (<kbd>-i 100</kbd>).
451 This controls how fast your program will run. Larger numbers check
452 the heap less and so it will run faster. Lower numbers will be more
453 likely to catch memory problems.
454
455 </li><li> Enable a number of debug features (<kbd>low</kbd>). You can
456 also try <kbd>runtime</kbd> for minimal checking or <kbd>medium</kbd> or
457 <kbd>high</kbd> for more extensive heap verification.
458
459 </li><li> By default, the low, medium, and high values enable the
460 <code>error-abort</code> token which will cause the library to abort and
461 usually dump core immediately upon seeing an error. See section <a href="#SEC14">Generating a Core File on Errors</a>. You can disable this feature by entering <kbd>dmalloc -m
462 error-abort</kbd> (-m for minus) to remove the <code>error-abort</code> token and
463 your program will just log errors and continue.
464
465 </li></ul>
466
467 <p><kbd>dmalloc --usage</kbd> will provide verbose usage info for the dmalloc
468 program. See section <a href="#SEC29">Dmalloc Utility Program</a>.
469 </p>
470 <p>You may also want to install the <tt>`dmallocrc'</tt> file in your home
471 directory as <tt>`.dmallocrc'</tt>. This allows you to add your own
472 combination of debug tokens. See section <a href="#SEC34">Format of the Runtime Configuration File</a>.
473 </p>
474 <p><em>NOTE</em>: The output from the dmalloc utility should be captured by
475 your shell. If you see a bunch of stuff which includes the string
476 <code>DMALLOC_OPTIONS</code> then the alias you should have created above is
477 not working and he environmental variables are not being set. Make
478 sure you've logged out and back in to have the alias take effect.
479 </p>
480 </li><li> Run your program, examine the logfile that should have been
481 created by <code>dmalloc_shutdown</code>, and use its information to help
482 debug your program.
483
484 </li></ol>
485
486
487 <hr size="6">
488 <a name="Allocation-Basics"></a>
489 <a name="SEC5"></a>
490 <table cellpadding="1" cellspacing="1" border="0">
491 <tr><td valign="middle" align="left">[<a href="#SEC4" title="Previous section in reading order"> &lt; </a>]</td>
492 <td valign="middle" align="left">[<a href="#SEC6" title="Next section in reading order"> &gt; </a>]</td>
493 <td valign="middle" align="left"> &nbsp; </td>
494 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
495 <td valign="middle" align="left">[<a href="#SEC2" title="Up section"> Up </a>]</td>
496 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
497 <td valign="middle" align="left"> &nbsp; </td>
498 <td valign="middle" align="left"> &nbsp; </td>
499 <td valign="middle" align="left"> &nbsp; </td>
500 <td valign="middle" align="left"> &nbsp; </td>
501 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
502 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
503 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
504 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
505 </tr></table>
506 <h2 class="section"> 2.3 Basic Description of Terms and Functions </h2>
507
508
509 <table class="menu" border="0" cellspacing="0">
510 <tr><td align="left" valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> General memory terms and concepts.
511 </td></tr>
512 <tr><td align="left" valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Functionality supported by all malloc libs.
513 </td></tr>
514 </table>
515
516
517 <hr size="6">
518 <a name="Basic-Definitions"></a>
519 <a name="SEC6"></a>
520 <table cellpadding="1" cellspacing="1" border="0">
521 <tr><td valign="middle" align="left">[<a href="#SEC5" title="Previous section in reading order"> &lt; </a>]</td>
522 <td valign="middle" align="left">[<a href="#SEC7" title="Next section in reading order"> &gt; </a>]</td>
523 <td valign="middle" align="left"> &nbsp; </td>
524 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
525 <td valign="middle" align="left">[<a href="#SEC5" title="Up section"> Up </a>]</td>
526 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
527 <td valign="middle" align="left"> &nbsp; </td>
528 <td valign="middle" align="left"> &nbsp; </td>
529 <td valign="middle" align="left"> &nbsp; </td>
530 <td valign="middle" align="left"> &nbsp; </td>
531 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
532 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
533 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
534 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
535 </tr></table>
536 <h3 class="subsection"> 2.3.1 General Memory Terms and Concepts </h3>
537
538
539 <p>Any program can be divided into 2 logical parts: text and data. Text is
540 the actual program code in machine-readable format and data is the
541 information that the text operates on when it is executing. The data,
542 in turn, can be divided into 3 logical parts according to where it is
543 stored: <em>static</em>, <em>stack</em>, and <em>heap</em>.
544 </p>
545 <a name="IDX26"></a>
546
547 <p>Static data is the information whose storage space is compiled into the
548 program.
549 </p>
550 <table><tr><td>&nbsp;</td><td><pre class="example">/* global variables are allocated as static data */
551 int numbers[10];
552
553 main()
554 {
555 &hellip;
556 }
557 </pre></td></tr></table>
558 <a name="IDX27"></a>
559
560 <p>Stack data is data allocated at runtime to hold information used inside
561 of functions. This data is managed by the system in the space called
562 stack space.
563 </p>
564 <table><tr><td>&nbsp;</td><td><pre class="example">void foo()
565 {
566 /* this local variable is stored on the stack */
567 float total;
568 &hellip;
569 }
570
571 main()
572 {
573 foo();
574 }
575 </pre></td></tr></table>
576 <a name="IDX28"></a>
577
578 <p>Heap data is also allocated at runtime and provides a programmer with
579 dynamic memory capabilities.
580 </p>
581 <table><tr><td>&nbsp;</td><td><pre class="example">main()
582 {
583 /* the address is stored on the stack */
584 char * string;
585 &hellip;
586
587 /*
588 * Allocate a string of 10 bytes on the heap. Store the
589 * address in string which is on the stack.
590 */
591 string = (char *)malloc(10);
592 &hellip;
593
594 /* de-allocate the heap memory now that we're done with it */
595 (void)free(string);
596 &hellip;
597 }
598 </pre></td></tr></table>
599 <p>It is the heap data that is managed by this library.
600 </p>
601 <p>Although the above is an example of how to use the malloc and free
602 commands, it is not a good example of why using the heap for runtime
603 storage is useful.
604 </p>
605 <p>Consider this: You write a program that reads a file into memory,
606 processes it, and displays results. You would like to handle files with
607 arbitrary size (from 10 bytes to 1.2 megabytes and more). One problem,
608 however, is that the entire file must be in memory at one time to do the
609 calculations. You don't want to have to allocate 1.2 megabytes when you
610 might only be reading in a 10 byte file because it is wasteful of system
611 resources. Also, you are worried that your program might have to handle
612 files of more than 1.2 megabytes.
613 </p>
614 <p>A solution: first check out the file's size and then, using the
615 heap-allocation routines, get enough storage to read the entire file
616 into memory. The program will only be using the system resources
617 necessary for the job and you will be guaranteed that your program can
618 handle any sized file.
619 </p>
620
621 <hr size="6">
622 <a name="Malloc-Functions"></a>
623 <a name="SEC7"></a>
624 <table cellpadding="1" cellspacing="1" border="0">
625 <tr><td valign="middle" align="left">[<a href="#SEC6" title="Previous section in reading order"> &lt; </a>]</td>
626 <td valign="middle" align="left">[<a href="#SEC8" title="Next section in reading order"> &gt; </a>]</td>
627 <td valign="middle" align="left"> &nbsp; </td>
628 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
629 <td valign="middle" align="left">[<a href="#SEC5" title="Up section"> Up </a>]</td>
630 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
631 <td valign="middle" align="left"> &nbsp; </td>
632 <td valign="middle" align="left"> &nbsp; </td>
633 <td valign="middle" align="left"> &nbsp; </td>
634 <td valign="middle" align="left"> &nbsp; </td>
635 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
636 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
637 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
638 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
639 </tr></table>
640 <h3 class="subsection"> 2.3.2 Functionality Supported by All Malloc Libraries </h3>
641
642
643 <p>All malloc libraries support 4 basic memory allocation commands. These
644 include <em>malloc</em>, <em>calloc</em>, <em>realloc</em>, and <em>free</em>. For
645 more information about their capabilities, check your system's manual
646 pages - in unix, do a <code>man 3 malloc</code>.
647 </p>
648 <a name="IDX29"></a>
649 <dl>
650 <dt><u>Function:</u> void <b>*malloc</b><i> ( unsigned int <var>size</var> )</i>
651 <a name="IDX30"></a>
652 </dt>
653 <dd><p>Usage: <code>pnt = (type *)malloc(size)</code>
654 </p>
655 <p>The malloc routine is the basic memory allocation routine. It allocates
656 an area of <code>size</code> bytes. It will return a pointer to the space
657 requested.
658 </p>
659 </dd></dl>
660 <dl>
661 <dt><u>Function:</u> void <b>*calloc</b><i> ( unsigned int <var>number</var>, unsigned int<var>size</var> )</i>
662 <a name="IDX31"></a>
663 </dt>
664 <dd><a name="IDX32"></a>
665 <a name="IDX33"></a>
666 <a name="IDX34"></a>
667
668 <p>Usage: <code>pnt = (type *)calloc(number, size)</code>
669 </p>
670 <p>The calloc routine allocates a certain <code>number</code> of items, each of
671 <code>size</code> bytes, and returns a pointer to the space. It is
672 appropriate to pass in a <code>sizeof(type)</code> value as the size argument.
673 </p>
674 <p>Also, calloc nulls the space that it returns, assuring that the memory
675 is all zeros.
676 </p>
677 </dd></dl>
678 <dl>
679 <dt><u>Function:</u> void <b>*realloc</b><i> ( void *<var>old_pnt</var>, unsigned int <var>new_size</var> )</i>
680 <a name="IDX35"></a>
681 </dt>
682 <dd><a name="IDX36"></a>
683
684 <p>Usage: <code>new_pnt = (type *)realloc(old_pnt, new_size)</code>
685 </p>
686 <p>The realloc function expands or shrinks the memory allocation in
687 <code>old_pnt</code> to <code>new_size</code> number of bytes. Realloc copies as
688 much of the information from <code>old_pnt</code> as it can into the
689 <code>new_pnt</code> space it returns, up to <code>new_size</code> bytes. If there
690 is a problem allocating this memory, 0L will be returned.
691 </p>
692 <p>If the <code>old_pnt</code> is 0L then realloc will do the equivalent of a
693 <code>malloc(new_size)</code>. If <code>new_size</code> is 0 and <code>old_pnt</code> is
694 not 0L, then it will do the equivalent of <code>free(old_pnt)</code> and will
695 return 0L.
696 </p>
697 </dd></dl>
698 <dl>
699 <dt><u>Function:</u> void <b>free</b><i> ( void *<var>pnt</var> )</i>
700 <a name="IDX37"></a>
701 </dt>
702 <dd><a name="IDX38"></a>
703
704 <p>Usage: <code>free(pnt)</code>
705 </p>
706 <p>The free routine releases allocation in <code>pnt</code> which was returned by
707 malloc, calloc, or realloc back to the heap. This allows other parts of
708 the program to re-use memory that is not needed anymore. It guarantees
709 that the process does not grow too big and swallow a large portion of
710 the system resources.
711 </p>
712 </dd></dl>
713
714 <p><em>WARNING</em>: there is a quite common myth that all of the space that
715 is returned by malloc libraries has already been cleared. <em>Only</em>
716 the <code>calloc</code> routine will zero the memory space it returns.
717 </p>
718
719 <hr size="6">
720 <a name="Features"></a>
721 <a name="SEC8"></a>
722 <table cellpadding="1" cellspacing="1" border="0">
723 <tr><td valign="middle" align="left">[<a href="#SEC7" title="Previous section in reading order"> &lt; </a>]</td>
724 <td valign="middle" align="left">[<a href="#SEC9" title="Next section in reading order"> &gt; </a>]</td>
725 <td valign="middle" align="left"> &nbsp; </td>
726 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
727 <td valign="middle" align="left">[<a href="#SEC2" title="Up section"> Up </a>]</td>
728 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
729 <td valign="middle" align="left"> &nbsp; </td>
730 <td valign="middle" align="left"> &nbsp; </td>
731 <td valign="middle" align="left"> &nbsp; </td>
732 <td valign="middle" align="left"> &nbsp; </td>
733 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
734 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
735 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
736 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
737 </tr></table>
738 <h2 class="section"> 2.4 General Features of the Library </h2>
739
740
741 <p>The debugging features that are available in this debug malloc library
742 can be divided into a couple basic classifications:
743 </p>
744 <dl compact="compact">
745 <dt> file and line number information</dt>
746 <dd><a name="IDX39"></a>
747 <a name="IDX40"></a>
748 <p>One of the nice things about a good debugger is its ability to provide
749 the file and line number of an offending piece of code. This library
750 attempts to give this functionality with the help of <em>cpp</em>, the C
751 preprocessor. See section <a href="#SEC11">Macros Providing File and Line Information</a>.
752 </p>
753 </dd>
754 <dt> return-address information</dt>
755 <dd><a name="IDX41"></a>
756 <p>To debug calls to the library from external sources (i.e. those files
757 that could not use the allocation macros), some facilities have been
758 provided to supply the caller's address. This address, with the help of
759 a debugger, can help you locate the source of a problem. See section <a href="#SEC12">Getting Caller Address Information</a>.
760 </p>
761 </dd>
762 <dt> fence-post (i.e. bounds) checking</dt>
763 <dd><a name="IDX42"></a>
764 <a name="IDX43"></a>
765 <a name="IDX44"></a>
766 <p><em>Fence-post</em> memory is the area immediately above or below memory
767 allocations. It is all too easy to write code that accesses above or
768 below an allocation - especially when dealing with arrays or strings.
769 The library can write special values in the areas around every
770 allocation so it will notice when these areas have been overwritten.
771 See section <a href="#SEC22">Diagnosing Fence-Post Overwritten Memory</a>.
772 </p>
773 <p><em>NOTE</em>: The library cannot notice when the program <em>reads</em>
774 from these areas, only when it writes values. Also, fence-post checking
775 will increase the amount of memory the program allocates.
776 </p>
777 </dd>
778 <dt> heap-constancy verification</dt>
779 <dd><a name="IDX45"></a>
780 <p>The administration of the library is reasonably complex. If any of the
781 heap-maintenance information is corrupted, the program will either crash
782 or give unpredictable results.
783 </p>
784 <p>By enabling heap-consistency checking, the library will run through its
785 administrative structures to make sure all is in order. This will mean
786 that problems will be caught faster and diagnosed better.
787 </p>
788 <p>The drawback of this is, of course, that the library often takes quite a
789 long time to do this. It is suitable to enable this only during
790 development and debugging sessions.
791 </p>
792 <p><em>NOTE</em>: the heap checking routines cannot guarantee that the tests
793 will not cause a segmentation-fault if the heap administration
794 structures are properly (or improperly if you will) overwritten. In
795 other words, the tests will verify that everything is okay but may not
796 inform the user of problems in a graceful manner.
797 </p>
798 </dd>
799 <dt> logging statistics</dt>
800 <dd><a name="IDX46"></a>
801 <a name="IDX47"></a>
802 <a name="IDX48"></a>
803 <a name="IDX49"></a>
804 <p>One of the reasons why the debug malloc library was initially developed
805 was to track programs' memory usage - specifically to locate
806 <em>memory leaks</em> which are places where allocated memory is never
807 getting freed. See section <a href="#SEC21">Tracking Down Non-Freed Memory</a>.
808 </p>
809 <p>The library has a number of logging capabilities that can track un-freed
810 memory pointers as well as runtime memory usage, memory transactions,
811 administrative actions, and final statistics.
812 </p>
813 </dd>
814 <dt> examining freed memory</dt>
815 <dd><a name="IDX50"></a>
816 <a name="IDX51"></a>
817 <p>Another common problem happens when a program frees a memory pointer but
818 goes on to use it again by mistake. This can lead to mysterious crashes
819 and unexplained problems.
820 </p>
821 <p>To combat this, the library can write special values into a block of
822 memory after it has been freed. This serves two purposes: it will make
823 sure that the program will get garbage data if it trying to access the
824 area again, and it will allow the library to verify the area later for
825 signs of overwriting.
826 </p></dd>
827 </dl>
828
829 <p>If any of the above debugging features detect an error, the library will
830 try to recover. If logging is enabled then an error will be logged with
831 as much information as possible.
832 </p>
833 <p>The error messages that the library displays are designed to give the
834 most information for developers. If the error message is not
835 understood, then it is most likely just trying to indicate that a part
836 of the heap has been corrupted.
837 </p>
838 <a name="IDX52"></a>
839 <a name="IDX53"></a>
840 <p>The library can be configured to quit immediately when an error is
841 detected and to dump a core file or memory-image. This can be
842 examined with a debugger to determine the source of the problem. The
843 library can either stop after dumping core or continue running.
844 See section <a href="#SEC14">Generating a Core File on Errors</a>.
845 </p>
846 <a name="IDX54"></a>
847 <a name="IDX55"></a>
848 <p><em>NOTE</em>: do not be surprised if the library catches problems with
849 your system's routines. It took me hours to finally come to the
850 conclusion that the localtime call, included in SunOS release 4.1,
851 overwrites one of its fence-post markers.
852 </p>
853
854 <hr size="6">
855 <a name="How-It-Works"></a>
856 <a name="SEC9"></a>
857 <table cellpadding="1" cellspacing="1" border="0">
858 <tr><td valign="middle" align="left">[<a href="#SEC8" title="Previous section in reading order"> &lt; </a>]</td>
859 <td valign="middle" align="left">[<a href="#SEC10" title="Next section in reading order"> &gt; </a>]</td>
860 <td valign="middle" align="left"> &nbsp; </td>
861 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
862 <td valign="middle" align="left">[<a href="#SEC2" title="Up section"> Up </a>]</td>
863 <td valign="middle" align="left">[<a href="#SEC10" title="Next chapter"> &gt;&gt; </a>]</td>
864 <td valign="middle" align="left"> &nbsp; </td>
865 <td valign="middle" align="left"> &nbsp; </td>
866 <td valign="middle" align="left"> &nbsp; </td>
867 <td valign="middle" align="left"> &nbsp; </td>
868 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
869 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
870 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
871 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
872 </tr></table>
873 <h2 class="section"> 2.5 How the Library Checks Your Program </h2>
874
875 <p>This is one of the newer sections of the library implying that it is
876 incomplete. If you have any questions or issues that you'd like to see
877 handled here, please let me know.
878 </p>
879 <p>The dmalloc library replaces the heap library calls normally found in
880 your system libraries with its own versions. When you make a call to
881 malloc (for example), you are calling dmalloc's version of the memory
882 allocation function. When you allocate memory with these functions, the
883 dmalloc library keeps track of a number of pieces of debugging
884 information about your pointer including: where it was allocated,
885 exactly how much memory was requested, when the call was made, etc..
886 This information can then be verified when the pointer is freed or
887 reallocated and the details can be logged on any errors.
888 </p>
889 <p>Whenever you reallocate or free a memory address, the dmalloc library
890 always performs a number of checks on the pointer to make sure that it
891 is valid and has not been corrupted. You can configure the library to
892 perform additional checks such as detected fence-post writing. The
893 library can also be configured to overwrite memory with non-zeros (only
894 if calloc is not called) when it is allocated and erase the memory when
895 the pointers are freed.
896 </p>
897 <a name="IDX56"></a>
898 <p>In addition to per-pointer checks, you can configure the library to
899 perform complete heap checks. These complete checks verify all
900 internal heap structures and include walking all of the known
901 allocated pointers to verify each one in turn. You need this level of
902 checking to find random pointers in your program which got corrupted
903 but that won't be freed for a while. To turn on these checks, you
904 will need to enable the <code>check-heap</code> debug token. See section <a href="#SEC33">Description of the Debugging Tokens</a>. By default this will cause the heap to be fully checked each
905 and every time dmalloc is called whether it is a malloc, free,
906 realloc, or another dmalloc overloaded function.
907 </p>
908 <p>Performing a full heap check can take a good bit of CPU and it may be
909 that you will want to run it sporadically. This can be accomplished in
910 a couple different ways including the '-i' interval argument to the
911 dmalloc utility. See section <a href="#SEC29">Dmalloc Utility Program</a>. This will cause the check to
912 be run every N-th time. For instance, 'dmalloc -i 3' will cause the
913 heap to be checked before every 3rd call to a memory function. Values
914 of 100 or even 1000 for high memory usage programs are more useful than
915 smaller ones.
916 </p>
917 <a name="IDX57"></a>
918 <a name="IDX58"></a>
919 <a name="IDX59"></a>
920 <p>You can also cause the program to start doing detailed heap checking
921 after a certain point. For instance, with 'dmalloc -s 1000' option, you
922 can tell the dmalloc library to enable the heap checks after the 1000th
923 memory call. Examine the dmalloc log file produced and use the
924 iteration count if you have <code>LOG_ITERATION_COUNT</code> enabled in your
925 <tt>`settings.h'</tt> file.
926 </p>
927 <p>The start option can also have the format <samp>`file:line'</samp>. For
928 instance, if it is set to <samp>`dmalloc_t.c:126'</samp>, dmalloc will start
929 checking the heap after it sees a dmalloc call from the
930 <tt>`dmalloc_t.c'</tt> file, line number 126. If you use
931 <samp>`dmalloc_t.c:0'</samp>, with a 0 line number, then dmalloc will start
932 checking the heap after it sees a call from anywhere in the
933 <tt>`dmalloc_t.c'</tt> file.
934 </p>
935
936 <hr size="6">
937 <a name="Programming"></a>
938 <a name="SEC10"></a>
939 <table cellpadding="1" cellspacing="1" border="0">
940 <tr><td valign="middle" align="left">[<a href="#SEC9" title="Previous section in reading order"> &lt; </a>]</td>
941 <td valign="middle" align="left">[<a href="#SEC11" title="Next section in reading order"> &gt; </a>]</td>
942 <td valign="middle" align="left"> &nbsp; </td>
943 <td valign="middle" align="left">[<a href="#SEC2" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
944 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
945 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
946 <td valign="middle" align="left"> &nbsp; </td>
947 <td valign="middle" align="left"> &nbsp; </td>
948 <td valign="middle" align="left"> &nbsp; </td>
949 <td valign="middle" align="left"> &nbsp; </td>
950 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
951 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
952 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
953 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
954 </tr></table>
955 <h1 class="chapter"> 3. How to Program with the Library </h1>
956
957
958 <table class="menu" border="0" cellspacing="0">
959 <tr><td align="left" valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Macros providing file and line information.
960 </td></tr>
961 <tr><td align="left" valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Getting caller address information.
962 </td></tr>
963 <tr><td align="left" valign="top"><a href="#SEC13">3.3 Checking of Function Arguments</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Checking of function arguments.
964 </td></tr>
965 <tr><td align="left" valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Generating a core file on errors for debugging.
966 </td></tr>
967 <tr><td align="left" valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Additional non-standard routines.
968 </td></tr>
969 <tr><td align="left" valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Description of the internal error numbers.
970 </td></tr>
971 <tr><td align="left" valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How to disable the library.
972 </td></tr>
973 <tr><td align="left" valign="top"><a href="#SEC18">3.8 Using the Library with C++</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Using the library with C++.
974 </td></tr>
975 <tr><td align="left" valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Using a debugger with the library.
976 </td></tr>
977 <tr><td align="left" valign="top"><a href="#SEC24">3.10 Using the Library with a Thread Package</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Using the library with a thread package.
978 </td></tr>
979 <tr><td align="left" valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"></td></tr>
980 <tr><td align="left" valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Debugging memory in a server or cgi-bin process.
981 </td></tr>
982 <tr><td align="left" valign="top"><a href="#SEC27">3.13 Explanation of the Logfile Output</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"></td></tr>
983 <tr><td align="left" valign="top"><a href="#SEC28">3.14 Various Other Hints That May Help</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Various other hints that may help.
984 </td></tr>
985 </table>
986
987
988 <hr size="6">
989 <a name="Allocation-Macros"></a>
990 <a name="SEC11"></a>
991 <table cellpadding="1" cellspacing="1" border="0">
992 <tr><td valign="middle" align="left">[<a href="#SEC10" title="Previous section in reading order"> &lt; </a>]</td>
993 <td valign="middle" align="left">[<a href="#SEC12" title="Next section in reading order"> &gt; </a>]</td>
994 <td valign="middle" align="left"> &nbsp; </td>
995 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
996 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
997 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
998 <td valign="middle" align="left"> &nbsp; </td>
999 <td valign="middle" align="left"> &nbsp; </td>
1000 <td valign="middle" align="left"> &nbsp; </td>
1001 <td valign="middle" align="left"> &nbsp; </td>
1002 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1003 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1004 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1005 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1006 </tr></table>
1007 <h2 class="section"> 3.1 Macros Providing File and Line Information </h2>
1008
1009
1010 <p>By including <tt>`dmalloc.h'</tt> in your C files, your calls to malloc,
1011 calloc, realloc, recalloc, memalign, valloc, strdup, and free are
1012 replaced with calls to _dmalloc_malloc, _dmalloc_realloc, and
1013 _dmalloc_free with various flags. Additionally the library replaces
1014 calls to xmalloc, xcalloc, xrealloc, xrecalloc, xmemalign, xvalloc,
1015 xstrdup, and xfree with associated calls.
1016 </p>
1017 <p>These macros use the c-preprocessor <code>__FILE__</code> and <code>__LINE__</code>
1018 macros which get replaced at compilation time with the current file and
1019 line-number of the source code in question. The routines use this
1020 information to produce verbose reports on memory problems.
1021 </p>
1022 <table><tr><td>&nbsp;</td><td><pre class="example">not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
1023 </pre></td></tr></table>
1024 <p>This line from a log file shows that memory was not freed from file
1025 <tt>`dmalloc_t.c'</tt> line 92. See section <a href="#SEC21">Tracking Down Non-Freed Memory</a>.
1026 </p>
1027 <a name="IDX60"></a>
1028 <a name="IDX61"></a>
1029 <a name="IDX62"></a>
1030 <a name="IDX63"></a>
1031
1032 <p>You may notice some non standard memory allocation functions in the
1033 above list. Recalloc is a routine like realloc that reallocates
1034 previously allocated memory to a new size. If the new memory size is
1035 larger than the old, recalloc initializes the new space to all zeros.
1036 This may or may not be supported natively by your operating system.
1037 Memalign is like malloc but should insure that the returned pointer is
1038 aligned to a certain number of specified bytes. Currently, the memalign
1039 function is not supported by the library. It defaults to returning
1040 possibly non-aligned memory for alignment values less than a block-size.
1041 Valloc is like malloc but insures that the returned pointer will be
1042 aligned to a page boundary. This may or may not be supported natively
1043 by your operating system but is fully supported by the library. Strdup
1044 is a string duplicating routine which takes in a null terminated string
1045 pointer and returns an allocated copy of the string that will need to be
1046 passed to free later to deallocate.
1047 </p>
1048 <p>The X versions of the standard memory functions (xmalloc, xfree, etc.)
1049 will print out an error message to standard error and will stop if the
1050 library is unable to allocate any additional memory. It is useful to
1051 use these routines instead of checking everywhere in your program for
1052 allocation routines returning NULL pointers.
1053 </p>
1054 <p><em>WARNING</em>: If you are including the <tt>`dmalloc.h'</tt> file in your
1055 sources, it is recommended that it be at the end of your include file
1056 list because dmalloc uses macros and may try to change declarations of
1057 the malloc functions if they come after it.
1058 </p>
1059
1060 <hr size="6">
1061 <a name="Return-Address"></a>
1062 <a name="SEC12"></a>
1063 <table cellpadding="1" cellspacing="1" border="0">
1064 <tr><td valign="middle" align="left">[<a href="#SEC11" title="Previous section in reading order"> &lt; </a>]</td>
1065 <td valign="middle" align="left">[<a href="#SEC13" title="Next section in reading order"> &gt; </a>]</td>
1066 <td valign="middle" align="left"> &nbsp; </td>
1067 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1068 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
1069 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
1070 <td valign="middle" align="left"> &nbsp; </td>
1071 <td valign="middle" align="left"> &nbsp; </td>
1072 <td valign="middle" align="left"> &nbsp; </td>
1073 <td valign="middle" align="left"> &nbsp; </td>
1074 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1075 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1076 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1077 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1078 </tr></table>
1079 <h2 class="section"> 3.2 Getting Caller Address Information </h2>
1080
1081
1082 <p>Even though the allocation macros can provide file/line information for
1083 some of your code, there are still modules which either you can't
1084 include <tt>`dmalloc.h'</tt> (such as library routines) or you just don't
1085 want to. You can still get information about the routines that call
1086 dmalloc function from the return-address information. To accomplish
1087 this, you must be using this library on one of the supported
1088 architecture/compilers. See section <a href="#SEC38">Issues Important for Porting the Library</a>.
1089 </p>
1090 <a name="IDX64"></a>
1091
1092 <p>The library attempts to use some assembly hacks to get the
1093 return-address or the address of the line that called the dmalloc
1094 function. If you have unfreed memory that does not have associated file
1095 and line information, you might see the following non-freed memory
1096 messages.
1097 </p>
1098 <table><tr><td>&nbsp;</td><td><pre class="example">not freed: '0x38410' (22 bytes) from 'ra=0xdd2c'
1099 not freed: '0x38600' (10232 bytes) from 'ra=0x10234d'
1100 not freed: '0x38220' (137 bytes) from 'ra=0x82cc'
1101 </pre></td></tr></table>
1102 <a name="IDX65"></a>
1103 <p>With the help of a debugger, these return-addresses (or ra) can then be
1104 identified. I've provided a <tt>`ra_info.pl'</tt> perl script in the
1105 <tt>`contrib/'</tt> directory with the dmalloc sources which seems to work
1106 well with gdb. You can also use manual methods for gdb to find the
1107 return-address location. See section <a href="#SEC23">Translating Return Addresses into Code Locations</a>.
1108 </p>
1109
1110 <hr size="6">
1111 <a name="Argument-Checking"></a>
1112 <a name="SEC13"></a>
1113 <table cellpadding="1" cellspacing="1" border="0">
1114 <tr><td valign="middle" align="left">[<a href="#SEC12" title="Previous section in reading order"> &lt; </a>]</td>
1115 <td valign="middle" align="left">[<a href="#SEC14" title="Next section in reading order"> &gt; </a>]</td>
1116 <td valign="middle" align="left"> &nbsp; </td>
1117 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1118 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
1119 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
1120 <td valign="middle" align="left"> &nbsp; </td>
1121 <td valign="middle" align="left"> &nbsp; </td>
1122 <td valign="middle" align="left"> &nbsp; </td>
1123 <td valign="middle" align="left"> &nbsp; </td>
1124 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1125 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1126 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1127 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1128 </tr></table>
1129 <h2 class="section"> 3.3 Checking of Function Arguments </h2>
1130
1131
1132 <p>One potential problem with the library and its multitude of checks and
1133 diagnoses is that they only get performed when a dmalloc function is
1134 called. One solution this is to include <tt>`dmalloc.h'</tt> and compile
1135 your source code with the <code>DMALLOC_FUNC_CHECK</code> flag defined and
1136 enable the <code>check-funcs</code> token. See section <a href="#SEC33">Description of the Debugging Tokens</a>.
1137 </p>
1138 <table><tr><td>&nbsp;</td><td><pre class="example">cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
1139 </pre></td></tr></table>
1140 <p><em>NOTE</em>: Once you have compiled your source with DMALLOC_FUNC_CHECK
1141 enabled, you will have to recompile with it off to disconnect the
1142 library. See section <a href="#SEC17">How to Disable the library</a>.
1143 </p>
1144 <p><em>WARNING</em>: You should be sure to have <tt>`dmalloc.h'</tt> included at
1145 the end of your include file list because dmalloc uses macros and may
1146 try to change declarations of the checked functions if they come after
1147 it.
1148 </p>
1149 <p>When this is defined dmalloc will override a number of functions and
1150 will insert a routine which knows how to check its own arguments and
1151 then call the real function. Dmalloc can check such functions as
1152 <code>bcopy</code>, <code>index</code>, <code>strcat</code>, and <code>strcasecmp</code>. For
1153 the full list see the end of <tt>`dmalloc.h'</tt>.
1154 </p>
1155 <p>When you call <code>strlen</code>, for instance, dmalloc will make sure the
1156 string argument's fence-post areas have not been overwritten, its file
1157 and line number locations are good, etc. With <code>bcopy</code>, dmalloc
1158 will make sure that the destination string has enough space to store the
1159 number of bytes specified.
1160 </p>
1161 <p>For all of the arguments checked, if the pointer is not in the heap then
1162 it is ignored since dmalloc does not know anything about it.
1163 </p>
1164
1165 <hr size="6">
1166 <a name="Dumping-Core"></a>
1167 <a name="SEC14"></a>
1168 <table cellpadding="1" cellspacing="1" border="0">
1169 <tr><td valign="middle" align="left">[<a href="#SEC13" title="Previous section in reading order"> &lt; </a>]</td>
1170 <td valign="middle" align="left">[<a href="#SEC15" title="Next section in reading order"> &gt; </a>]</td>
1171 <td valign="middle" align="left"> &nbsp; </td>
1172 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1173 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
1174 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
1175 <td valign="middle" align="left"> &nbsp; </td>
1176 <td valign="middle" align="left"> &nbsp; </td>
1177 <td valign="middle" align="left"> &nbsp; </td>
1178 <td valign="middle" align="left"> &nbsp; </td>
1179 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1180 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1181 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1182 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1183 </tr></table>
1184 <h2 class="section"> 3.4 Generating a Core File on Errors </h2>
1185
1186
1187 <p>If the <code>error-abort</code> debug token has been enabled, when the
1188 library detects any problems with the heap memory, it will immediately
1189 attempt to dump a core file. See section <a href="#SEC33">Description of the Debugging Tokens</a>. Core files are a
1190 complete copy of the program and it's state and can be used by a
1191 debugger to see specifically what is going on when the error occurred.
1192 See section <a href="#SEC19">Using Dmalloc With a Debugger</a>. By default, the low, medium, and high
1193 arguments to the library utility enable the <code>error-abort</code> token.
1194 You can disable this feature by entering <kbd>dmalloc -m error-abort</kbd>
1195 (-m for minus) to remove the <code>error-abort</code> token and your program
1196 will just log errors and continue. You can also use the
1197 <code>error-dump</code> token which tries to dump core when it sees an error
1198 but still continue running. See section <a href="#SEC33">Description of the Debugging Tokens</a>.
1199 </p>
1200 <a name="IDX66"></a>
1201 <a name="IDX67"></a>
1202 <a name="IDX68"></a>
1203 <a name="IDX69"></a>
1204 <a name="IDX70"></a>
1205
1206 <p>When a program dumps core, the system writes the program and all of
1207 its memory to a file on disk usually named <tt>`core'</tt>. If your
1208 program is called <tt>`foo'</tt> then your system may dump core as
1209 <tt>`foo.core'</tt>. If you are not getting a <tt>`core'</tt> file, make sure
1210 that your program has not changed to a new directory meaning that it
1211 may have written the core file in a different location. Also insure
1212 that your program has write privileges over the directory that it is
1213 in otherwise it will not be able to dump a core file. Core dumps are
1214 often security problems since they contain all program memory so
1215 systems often block their being produced. You will want to check your
1216 user and system's core dump size ulimit settings.
1217 </p>
1218 <a name="IDX71"></a>
1219 <a name="IDX72"></a>
1220 <a name="IDX73"></a>
1221
1222 <p>The library by default uses the <code>abort</code> function to dump core
1223 which may or may not work depending on your operating system. If the
1224 following program does not dump core then this may be the problem.
1225 See <code>KILL_PROCESS</code> definition in <tt>`settings.dist'</tt>.
1226 </p>
1227 <table><tr><td>&nbsp;</td><td><pre class="example">main()
1228 {
1229 abort();
1230 }
1231 </pre></td></tr></table>
1232 <p>If <code>abort</code> does work then you may want to try the following
1233 setting in <tt>`settings.dist'</tt>. This code tries to generate a
1234 segmentation fault by dereferencing a <code>NULL</code> pointer.
1235 </p>
1236 <table><tr><td>&nbsp;</td><td><pre class="example">#define KILL_PROCESS { int *_int_p = 0L; *_int_p = 1; }
1237 </pre></td></tr></table>
1238
1239 <hr size="6">
1240 <a name="Extensions"></a>
1241 <a name="SEC15"></a>
1242 <table cellpadding="1" cellspacing="1" border="0">
1243 <tr><td valign="middle" align="left">[<a href="#SEC14" title="Previous section in reading order"> &lt; </a>]</td>
1244 <td valign="middle" align="left">[<a href="#SEC16" title="Next section in reading order"> &gt; </a>]</td>
1245 <td valign="middle" align="left"> &nbsp; </td>
1246 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1247 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
1248 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
1249 <td valign="middle" align="left"> &nbsp; </td>
1250 <td valign="middle" align="left"> &nbsp; </td>
1251 <td valign="middle" align="left"> &nbsp; </td>
1252 <td valign="middle" align="left"> &nbsp; </td>
1253 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1254 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1255 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1256 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1257 </tr></table>
1258 <h2 class="section"> 3.5 Additional Non-standard Routines </h2>
1259
1260
1261 <p>The library has a number of variables that are not a standard part of
1262 most malloc libraries:
1263 </p>
1264
1265 <a name="IDX74"></a>
1266 <a name="IDX75"></a>
1267 <a name="IDX76"></a>
1268
1269 <dl>
1270 <dt><u>Variable:</u> int <b>dmalloc_errno</b>
1271 <a name="IDX77"></a>
1272 </dt>
1273 <dd><p>This variable stores the internal dmalloc library error number like errno
1274 does for the system calls. It can be passed to <code>dmalloc_strerror()</code>
1275 (see below) to get a string version of the error. It will have a value
1276 of zero if the library has not detected any problems.
1277 </p>
1278 </dd></dl>
1279
1280
1281 <a name="IDX78"></a>
1282 <a name="IDX79"></a>
1283
1284 <dl>
1285 <dt><u>Variable:</u> char* <b>dmalloc_logpath</b>
1286 <a name="IDX80"></a>
1287 </dt>
1288 <dd><p>This variable can be used to set the dmalloc log filename. The env
1289 variable <code>DMALLOC_LOGFILE</code> overrides this variable.
1290 </p>
1291
1292 </dd></dl>
1293
1294 <p>Additionally the library provides a number of non-standard malloc
1295 routines:
1296 </p>
1297
1298 <a name="IDX81"></a>
1299 <a name="IDX82"></a>
1300
1301 <dl>
1302 <dt><u>Function:</u> void <b>dmalloc_shutdown</b><i> ( void )</i>
1303 <a name="IDX83"></a>
1304 </dt>
1305 <dd><a name="IDX84"></a>
1306 <a name="IDX85"></a>
1307
1308 <p>This function shuts the library down and logs the final statistics and
1309 information especially the non-freed memory pointers. The library has
1310 code to support auto-shutdown if your system has the <code>on_exit()</code>
1311 call, <code>atexit()</code> call, or compiler destructor support (see
1312 <tt>`conf.h'</tt>). If you do not have these, then <code>dmalloc_shutdown</code>
1313 should be called right before <code>exit()</code> or as the last function in
1314 <code>main()</code>.
1315 </p>
1316 <table><tr><td>&nbsp;</td><td><pre class="example">main()
1317 {
1318 &hellip;
1319 dmalloc_shutdown();
1320 exit(0);
1321 }
1322 </pre></td></tr></table></dd></dl>
1323
1324
1325 <a name="IDX86"></a>
1326 <a name="IDX87"></a>
1327 <a name="IDX88"></a>
1328
1329 <dl>
1330 <dt><u>Function:</u> int <b>dmalloc_verify</b><i> ( char * <var>pnt</var> )</i>
1331 <a name="IDX89"></a>
1332 </dt>
1333 <dd><p>This function verifies individual memory pointers that are suspect of
1334 memory problems. To check the entire heap pass in a NULL or 0 pointer.
1335 The routine returns DMALLOC_VERIFY_ERROR or DMALLOC_VERIFY_NOERROR.
1336 </p>
1337 <p><em>NOTE</em>: <samp>`dmalloc_verify()'</samp> can only check the heap with the
1338 functions that have been enabled. For example, if fence-post checking
1339 is not enabled, <samp>`dmalloc_verify()'</samp> cannot check the fence-post
1340 areas in the heap.
1341 </p></dd></dl>
1342
1343
1344 <a name="IDX90"></a>
1345 <a name="IDX91"></a>
1346 <a name="IDX92"></a>
1347
1348 <dl>
1349 <dt><u>Function:</u> unsigned-int <b>dmalloc_debug</b><i> ( const unsigned int <var>flags</var> )</i>
1350 <a name="IDX93"></a>
1351 </dt>
1352 <dd><p>This routine sets the debug functionality flags and returns the
1353 previous flag value. It is helpful in server or cgi-bin programs
1354 where environmental variables cannot be used. See section <a href="#SEC26">Debugging Memory in a Server or Cgi-Bin Process</a>. For instance, if debugging should never be enabled for a
1355 program, a call to <code>dmalloc_debug(0)</code> as the first call in
1356 <code>main()</code> will disable all the memory debugging from that point
1357 on.
1358 </p>
1359 <p><em>NOTE</em>: you cannot add or remove certain flags such as signal
1360 handlers since they are setup at initialization time only.
1361 </p>
1362 <p><em>NOTE</em>: you can also use <code>dmalloc_debug_setup</code> below.
1363 </p>
1364 </dd></dl>
1365
1366
1367 <a name="IDX94"></a>
1368 <a name="IDX95"></a>
1369
1370 <dl>
1371 <dt><u>Function:</u> unsigned-int <b>dmalloc_debug_current</b><i> ( void )</i>
1372 <a name="IDX96"></a>
1373 </dt>
1374 <dd><p>This routine returns the current debug functionality value value. This
1375 allows you to save a copy of the debug dmalloc settings to be changed
1376 and then restored later.
1377 </p>
1378 </dd></dl>
1379
1380
1381 <a name="IDX97"></a>
1382 <a name="IDX98"></a>
1383 <a name="IDX99"></a>
1384 <a name="IDX100"></a>
1385 <a name="IDX101"></a>
1386
1387 <dl>
1388 <dt><u>Function:</u> void <b>dmalloc_debug_setup</b><i> ( const char * <var>options_str</var> )</i>
1389 <a name="IDX102"></a>
1390 </dt>
1391 <dd><p>This routine sets the global debugging functionality as an option
1392 string. Normally this would be passed in in the DMALLOC_OPTIONS
1393 environmental variable. This is here to override the env or for
1394 circumstances where modifying the environment is not possible or does
1395 not apply such as servers or cgi-bin programs. See section <a href="#SEC26">Debugging Memory in a Server or Cgi-Bin Process</a>.
1396 </p>
1397 <p>Some examples:
1398 </p>
1399 <table><tr><td>&nbsp;</td><td><pre class="example">/*
1400 * debug tokens high, threaded lock-on at 20,
1401 * log to dmalloc.%p (pid)
1402 */
1403 dmalloc_debug_setup(&quot;debug=0x4f46d03,lockon=20,log=dmalloc.%p&quot;);
1404
1405 /*
1406 * turn on some debug tokens directly and log to the
1407 * file 'logfile'
1408 */
1409 dmalloc_debug_setup(
1410 &quot;log-stats,log-non-free,check-fence,log=logfile&quot;);
1411 </pre></td></tr></table>
1412 </dd></dl>
1413
1414
1415 <a name="IDX103"></a>
1416 <a name="IDX104"></a>
1417 <a name="IDX105"></a>
1418
1419 <dl>
1420 <dt><u>Function:</u> int <b>dmalloc_examine</b><i> ( const DMALLOC_PNT <var>pnt</var>, DMALLOC_SIZE * <var>user_size_p</var>, DMALLOC_SIZE * <var>total_size_p</var>, char ** <var>file_p</var>, int * <var>line_p</var>, DMALLOC_PNT * <var>ret_addr_p</var>, unsigned long * <var>user_mark_p</var>, unsigned long * <var>seen_p</var> )</i>
1421 <a name="IDX106"></a>
1422 </dt>
1423 <dd><a name="IDX107"></a>
1424 <p>This function returns the size of a pointer's allocation as well as the
1425 total size given including administrative overhead, file and line or the
1426 return-address from where it was allocated, the last pointer when the
1427 pointer was &quot;used&quot;, and the number of times the pointer has been &quot;seen&quot;.
1428 It will return DMALLOC_NOERROR or DMALLOC_ERROR depending on whether pnt
1429 is good or not.
1430 </p>
1431 <p><em>NOTE</em>: This function is <em>certainly</em> not provided by most if
1432 not all other malloc libraries.
1433 </p>
1434 </dd></dl>
1435
1436
1437 <a name="IDX108"></a>
1438 <a name="IDX109"></a>
1439
1440 <dl>
1441 <dt><u>Function:</u> void <b>dmalloc_track</b><i> ( const dmalloc_track_t <var>track_func</var> )</i>
1442 <a name="IDX110"></a>
1443 </dt>
1444 <dd><p>Register an allocation tracking function which will be called each time
1445 an allocation occurs. Pass in NULL to disable. To take a look at what
1446 information is provided, see the dmalloc_track_t function typedef in
1447 dmalloc.h.
1448 </p>
1449 </dd></dl>
1450
1451
1452 <a name="IDX111"></a>
1453 <a name="IDX112"></a>
1454 <a name="IDX113"></a>
1455 <a name="IDX114"></a>
1456 <a name="IDX115"></a>
1457 <a name="IDX116"></a>
1458
1459 <dl>
1460 <dt><u>Function:</u> unsigned-long <b>dmalloc_mark</b><i> ( void )</i>
1461 <a name="IDX117"></a>
1462 </dt>
1463 <dd><p>Return to the caller the current &quot;mark&quot; which can be used later to log
1464 the pointers which have changed since this mark with the
1465 <code>dmalloc_log_changed</code> function. Multiple marks can be saved and
1466 used.
1467 </p>
1468 <p>This is very useful when using the library with a server which does
1469 not exit. You can then save a mark before a transaction or event
1470 happens and then check to see what has changed using the
1471 <code>dmalloc_log_changed</code> function below. See section <a href="#SEC26">Debugging Memory in a Server or Cgi-Bin Process</a>.
1472 </p>
1473 <p>If you <code>LOG_ITERATION</code> enabled in your <tt>`settings.h'</tt> file then
1474 the entries in the log file will be prepended with the number of memory
1475 transactions that the library has handled so far. You can also enable
1476 <code>LOG_PNT_ITERATION</code> in <tt>`settings.h'</tt> to store the memory
1477 transaction number with each pointer.
1478 </p>
1479 </dd></dl>
1480
1481
1482 <a name="IDX118"></a>
1483 <a name="IDX119"></a>
1484 <a name="IDX120"></a>
1485
1486 <dl>
1487 <dt><u>Function:</u> unsigned-long <b>dmalloc_memory_allocated</b><i> ( void )</i>
1488 <a name="IDX121"></a>
1489 </dt>
1490 <dd><p>Return to the caller the total number of bytes that have been allocated
1491 by the library. This is not the current in use but the total number of
1492 bytes returned by allocation functions.
1493 </p>
1494 </dd></dl>
1495
1496
1497 <a name="IDX122"></a>
1498 <a name="IDX123"></a>
1499
1500 <dl>
1501 <dt><u>Function:</u> unsigned-int <b>dmalloc_page_size</b><i> ( void )</i>
1502 <a name="IDX124"></a>
1503 </dt>
1504 <dd><p>Return to the caller the memory page-size being used by the library.
1505 This should be the same value as the one returned by the
1506 <code>getpagesize()</code> function, if available.
1507 </p>
1508 </dd></dl>
1509
1510
1511 <a name="IDX125"></a>
1512 <a name="IDX126"></a>
1513 <a name="IDX127"></a>
1514
1515 <dl>
1516 <dt><u>Function:</u> unsigned-long <b>dmalloc_count_changed</b><i> ( const unsigned long <var>mark</var>, const int <var>not_freed_b</var>, const int <var>free_b</var> )</i>
1517 <a name="IDX128"></a>
1518 </dt>
1519 <dd><p>Count the pointers that have changed since the mark which was returned by
1520 <code>dmalloc_mark</code>. If <code>not_freed_b</code> is set to non-0 then count the
1521 pointers that have not been freed. If <code>free_b</code> is set to non-0
1522 then count the pointers that have been freed.
1523 </p>
1524 <p>This can be used in conjunction with the <code>dmalloc_mark()</code>
1525 function to help servers which never exit ensure that transactions or
1526 events are not leaking memory. See section <a href="#SEC26">Debugging Memory in a Server or Cgi-Bin Process</a>.
1527 </p>
1528 <table><tr><td>&nbsp;</td><td><pre class="example">unsigned long mark = dmalloc_mark() ;
1529 &hellip;
1530 assert(dmalloc_count_changed(mark, 1, 0) == 0) ;
1531 </pre></td></tr></table>
1532 </dd></dl>
1533
1534
1535 <a name="IDX129"></a>
1536 <a name="IDX130"></a>
1537 <a name="IDX131"></a>
1538
1539 <dl>
1540 <dt><u>Function:</u> void <b>dmalloc_log_stats</b><i> ( void )</i>
1541 <a name="IDX132"></a>
1542 </dt>
1543 <dd><p>This routine outputs the current dmalloc statistics to the log file.
1544 </p></dd></dl>
1545
1546
1547 <a name="IDX133"></a>
1548 <a name="IDX134"></a>
1549 <a name="IDX135"></a>
1550
1551 <dl>
1552 <dt><u>Function:</u> void <b>dmalloc_log_unfreed</b><i> ( void )</i>
1553 <a name="IDX136"></a>
1554 </dt>
1555 <dd><p>This function logs the unfreed-memory information to the log file.
1556 This is also useful to log the currently allocated points to the log
1557 file to be compared against another dump later on.
1558 </p>
1559 </dd></dl>
1560
1561
1562 <a name="IDX137"></a>
1563 <a name="IDX138"></a>
1564 <a name="IDX139"></a>
1565 <a name="IDX140"></a>
1566
1567 <dl>
1568 <dt><u>Function:</u> void <b>dmalloc_log_changed</b><i> ( const unsigned long <var>mark</var>, const int <var>not_freed_b</var>, const int <var>freed_b</var>, const int <var>details_b</var> )</i>
1569 <a name="IDX141"></a>
1570 </dt>
1571 <dd><p>Log the pointers that have changed since the mark which was returned by
1572 <code>dmalloc_mark</code>. If <code>not_freed_b</code> is set to non-0 then log the
1573 pointers that have not been freed. If <code>free_b</code> is set to non-0
1574 then log the pointers that have been freed. If <code>details_b</code> set to
1575 non-0 then log the individual pointers that have changed otherwise just
1576 log the summaries.
1577 </p>
1578 <p>This can be used in conjunction with the <code>dmalloc_mark()</code>
1579 function to help servers which never exit find transactions or events
1580 which are leaking memory. See section <a href="#SEC26">Debugging Memory in a Server or Cgi-Bin Process</a>.
1581 </p>
1582 </dd></dl>
1583
1584
1585 <a name="IDX142"></a>
1586 <a name="IDX143"></a>
1587 <a name="IDX144"></a>
1588
1589 <dl>
1590 <dt><u>Function:</u> void <b>dmalloc_vmessage</b><i> ( const char * <var>format</var>, va_list <var>args</var> )</i>
1591 <a name="IDX145"></a>
1592 </dt>
1593 <dd><p>Write a message into the dmalloc logfile using vprintf-like arguments.
1594 </p>
1595 </dd></dl>
1596
1597
1598 <a name="IDX146"></a>
1599 <a name="IDX147"></a>
1600 <a name="IDX148"></a>
1601
1602 <dl>
1603 <dt><u>Function:</u> void <b>dmalloc_message</b><i> ( const char * <var>format</var>, <var>...</var> )</i>
1604 <a name="IDX149"></a>
1605 </dt>
1606 <dd><p>Write a message into the dmalloc logfile using printf-like arguments.
1607 </p>
1608 </dd></dl>
1609
1610
1611 <a name="IDX150"></a>
1612 <a name="IDX151"></a>
1613 <a name="IDX152"></a>
1614 <a name="IDX153"></a>
1615
1616 <dl>
1617 <dt><u>Function:</u> void <b>dmalloc_get_stats</b><i> ( DMALLOC_PNT * <var>heap_low_p</var>, DMALLOC_PNT * <var>heap_high_p</var>, unsigned long * <var>total_space_p</var>, unsigned long * <var>user_space_p</var>, unsigned long * <var>current_allocated_p</var>, unsigned long * <var>current_pnt_np</var>, unsigned long * <var>max_allocated_p</var>, unsigned long * <var>max_pnt_np</var>, unsigned long * <var>max_one_p</var>)</i>
1618 <a name="IDX154"></a>
1619 </dt>
1620 <dd><p>This function return a number of statistics about the current heap.
1621 The pointers <code>heap_low_p</code> and <code>heap_high_p</code> will be set to
1622 the low and high spots in the heap. <code>total_space_p</code> will be set
1623 to the total space in the heap including user space, administrative
1624 space, and overhead. <code>user_space_p</code> will be set to the space
1625 given to the user process (allocated and free space).
1626 <code>current_allocated_p</code> will be set to the current allocated space
1627 given to the user process. <code>current_pnt_np</code> will be set to the
1628 current number of pointers allocated by the user process.
1629 <code>max_allocated_p</code> will be set to the maximum allocated space
1630 given to the user process. <code>max_pnt_np</code> will be set to the
1631 maximum number of pointers allocated by the user process.
1632 <code>max_on_p</code> will be set to the maximum space allocated with one
1633 call by the user process.
1634 </p>
1635 </dd></dl>
1636
1637
1638 <a name="IDX155"></a>
1639 <a name="IDX156"></a>
1640 <a name="IDX157"></a>
1641
1642 <dl>
1643 <dt><u>Function:</u> const-char* <b>dmalloc_strerror</b><i> ( const int <var>error_number</var> )</i>
1644 <a name="IDX158"></a>
1645 </dt>
1646 <dd><p>This function returns the string representation of the error value in
1647 <code>error_number</code> (which probably should be dmalloc_errno). This
1648 allows the logging of more verbose memory error messages.
1649 </p>
1650 <p>You can also display the string representation of an error value by a
1651 call to the <tt>`dmalloc'</tt> program with a <samp>`-e #'</samp> option.
1652 See section <a href="#SEC29">Dmalloc Utility Program</a>.
1653 </p>
1654 </dd></dl>
1655
1656
1657 <hr size="6">
1658 <a name="Error-Codes"></a>
1659 <a name="SEC16"></a>
1660 <table cellpadding="1" cellspacing="1" border="0">
1661 <tr><td valign="middle" align="left">[<a href="#SEC15" title="Previous section in reading order"> &lt; </a>]</td>
1662 <td valign="middle" align="left">[<a href="#SEC17" title="Next section in reading order"> &gt; </a>]</td>
1663 <td valign="middle" align="left"> &nbsp; </td>
1664 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1665 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
1666 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
1667 <td valign="middle" align="left"> &nbsp; </td>
1668 <td valign="middle" align="left"> &nbsp; </td>
1669 <td valign="middle" align="left"> &nbsp; </td>
1670 <td valign="middle" align="left"> &nbsp; </td>
1671 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1672 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
1673 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
1674 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
1675 </tr></table>
1676 <h2 class="section"> 3.6 Description of the Internal Error Codes </h2>
1677
1678
1679 <p>The following error codes are defined in <tt>`error_val.h'</tt>. They are
1680 used by the library to indicate a detected problem. They can be caused
1681 by the user (<samp>`ERROR_TOO_BIG'</samp>) or can indicate an internal library
1682 problem (<samp>`ERROR_SLOT_CORRUPT'</samp>). The <tt>`dmalloc'</tt> utility can
1683 give you the string version of the error with the <code>-e</code> argument:
1684 </p>
1685 <table><tr><td>&nbsp;</td><td><pre class="example">$ dmalloc -e 60
1686 dmalloc: dmalloc_errno value '60' =
1687 'pointer is not on block boundary'
1688 </pre></td></tr></table>
1689 <p>Here are the error codes set by the library. They are non contiguous on
1690 purpose because I add and delete codes all of the time and there are
1691 sections for various error-code types.
1692 </p>
1693 <dl compact="compact">
1694 <dd>
1695
1696 <a name="IDX159"></a>
1697 <a name="IDX160"></a>
1698 <a name="IDX161"></a>
1699 <a name="IDX162"></a>
1700
1701 </dd>
1702 <dt> <code>1 (ERROR_NONE) no error</code></dt>
1703 <dd><p>No error. It is good coding practice to set the no-error code to be
1704 non-0 value because it forces you to set it explicitly.
1705 </p>
1706
1707 <a name="IDX163"></a>
1708 <a name="IDX164"></a>
1709 <a name="IDX165"></a>
1710 <a name="IDX166"></a>
1711 <a name="IDX167"></a>
1712
1713 </dd>
1714 <dt> <code>2 (INVALID_ERROR)</code></dt>
1715 <dd><p>Invalid error number. If the library outputs this error then your
1716 dmalloc utility may be out of date with the library you linked
1717 against. This will be returned with all error codes not listed here.
1718 </p>
1719
1720 <a name="IDX168"></a>
1721 <a name="IDX169"></a>
1722 <a name="IDX170"></a>
1723 <a name="IDX171"></a>
1724 <a name="IDX172"></a>
1725
1726 </dd>
1727 <dt> <code>10 (ERROR_BAD_SETUP) initialization and setup failed</code></dt>
1728 <dd><p>Bad setup value. This is currently unused but it is intended to report
1729 on invalid setup configuration information.
1730 </p>
1731
1732 <a name="IDX173"></a>
1733 <a name="IDX174"></a>
1734 <a name="IDX175"></a>
1735 <a name="IDX176"></a>
1736 <a name="IDX177"></a>
1737 <a name="IDX178"></a>
1738 <a name="IDX179"></a>
1739
1740 </dd>
1741 <dt> <code>11 (ERROR_IN_TWICE) malloc library has gone recursive</code></dt>
1742 <dd><p>Library went recursive. This usually indicates that you are not using
1743 the threaded version of the library. Or if you are then you are not
1744 using the <samp>`-o'</samp> &quot;lock-on&quot; option. See section <a href="#SEC24">Using the Library with a Thread Package</a>.
1745 </p>
1746
1747 <a name="IDX180"></a>
1748 <a name="IDX181"></a>
1749 <a name="IDX182"></a>
1750 <a name="IDX183"></a>
1751 <a name="IDX184"></a>
1752
1753 </dd>
1754 <dt> <code>13 (ERROR_LOCK_NOT_CONFIG) thread locking has not been configured</code></dt>
1755 <dd><p>Thread locking has not been configured. This indicates that you
1756 attempted to use the <samp>`-o'</samp> &quot;lock-on&quot; option without linking with
1757 the thread version of the library. You should probably be using
1758 <code>-ldmallocth</code> <em>not</em> <code>-ldmalloc</code> when you are linking.
1759 Or you should include <code>&hellip;/lib/libdmallocth.a</code> on your
1760 compilation line.
1761 </p>
1762
1763 <a name="IDX185"></a>
1764 <a name="IDX186"></a>
1765 <a name="IDX187"></a>
1766 <a name="IDX188"></a>
1767 <a name="IDX189"></a>
1768 <a name="IDX190"></a>
1769 <a name="IDX191"></a>
1770
1771 </dd>
1772 <dt> <code>20 (ERROR_IS_NULL) pointer is null</code></dt>
1773 <dd><p>Pointer is null. The program passed a NULL (0L) pointer to <code>free</code>
1774 and you have the <code>error-free-null</code> token enabled.
1775 </p>
1776
1777 <a name="IDX192"></a>
1778 <a name="IDX193"></a>
1779 <a name="IDX194"></a>
1780 <a name="IDX195"></a>
1781 <a name="IDX196"></a>
1782 <a name="IDX197"></a>
1783
1784 </dd>
1785 <dt> <code>21 (ERROR_NOT_IN_HEAP) pointer is not pointing to heap data space</code></dt>
1786 <dd><p>Pointer is not pointing to heap data space. This means that the program
1787 passed an out-of-bounds pointer to <code>free</code> or <code>realloc</code>. This
1788 could be someone trying to work with a wild pointer or trying to free a
1789 pointer from a different source than <code>malloc</code>.
1790 </p>
1791
1792 <a name="IDX198"></a>
1793 <a name="IDX199"></a>
1794 <a name="IDX200"></a>
1795 <a name="IDX201"></a>
1796 <a name="IDX202"></a>
1797 <a name="IDX203"></a>
1798 <a name="IDX204"></a>
1799 <a name="IDX205"></a>
1800
1801 </dd>
1802 <dt> <code>22 (ERROR_NOT_FOUND) cannot locate pointer in heap</code></dt>
1803 <dd><p>Cannot locate pointer in heap. The user passed in a pointer which the
1804 heap did not know about. Either this pointer was allocated by some
1805 other mechanism (like <code>mmap</code> or <code>sbrk</code> directly) or it is a
1806 random invalid pointer.
1807 </p>
1808 <p>In some rare circumstances, sometimes seen with shared libraries, there
1809 can be two separate copies of the dmalloc library in a program. Each
1810 one does not know about the pointers allocated by the other.
1811 </p>
1812
1813 <a name="IDX206"></a>
1814 <a name="IDX207"></a>
1815 <a name="IDX208"></a>
1816 <a name="IDX209"></a>
1817 <a name="IDX210"></a>
1818
1819 </dd>
1820 <dt> <code>23 (ERROR_IS_FOUND) found pointer the user was looking for</code></dt>
1821 <dd><p>This indicates that the pointer specified in the address part of the
1822 environmental variable was discovered by the library. See section <a href="#SEC32">Environment Variable Name and Features</a>. This error is useful so you can put a breakpoint in a
1823 debugger to find where a particular address was allocated. See section <a href="#SEC19">Using Dmalloc With a Debugger</a>.
1824 </p>
1825
1826 <a name="IDX211"></a>
1827 <a name="IDX212"></a>
1828 <a name="IDX213"></a>
1829 <a name="IDX214"></a>
1830 <a name="IDX215"></a>
1831
1832 </dd>
1833 <dt> <code>24 (ERROR_BAD_FILE) possibly bad .c filename pointer</code></dt>
1834 <dd><p>A possibly invalid filename was discovered in the dmalloc administrative
1835 sections. This could indicate some corruption of the internal tables.
1836 It also could mean that you have a source file whose name is longer than
1837 100 characters. See <code>MAX_FILE_LENGTH</code> in the <tt>`settings.dist'</tt>
1838 file.
1839 </p>
1840
1841 <a name="IDX216"></a>
1842 <a name="IDX217"></a>
1843 <a name="IDX218"></a>
1844 <a name="IDX219"></a>
1845 <a name="IDX220"></a>
1846
1847 </dd>
1848 <dt> <code>25 (ERROR_BAD_LINE) possibly bad .c file line-number</code></dt>
1849 <dd><p>A line-number was out-of-bounds in the dmalloc administrative sections.
1850 This could indicate some corruption of the internal tables. It also
1851 could mean that you have a source file containing more than <code>30000</code>
1852 lines of code. See <code>MAX_LINE_NUMBER</code> in the <tt>`settings.dist'</tt>
1853 file.
1854 </p>
1855
1856 <a name="IDX221"></a>
1857 <a name="IDX222"></a>
1858 <a name="IDX223"></a>
1859 <a name="IDX224"></a>
1860 <a name="IDX225"></a>
1861
1862 </dd>
1863 <dt> <code>26 (ERROR_UNDER_FENCE) failed UNDER picket-fence magic-number check</code></dt>
1864 <dd><p>This indicates that a pointer had its lower bound picket-fence magic
1865 number overwritten. If the <code>check-fence</code> token is enabled, the
1866 library writes magic values above and below allocations to protect
1867 against overflow. Most likely this is because a pointer below it went
1868 past its allocate and wrote into the next pointer's space.
1869 </p>
1870
1871 <a name="IDX226"></a>
1872 <a name="IDX227"></a>
1873 <a name="IDX228"></a>
1874 <a name="IDX229"></a>
1875 <a name="IDX230"></a>
1876
1877 </dd>
1878 <dt> <code>27 (ERROR_OVER_FENCE) failed OVER picket-fence magic-number check</code></dt>
1879 <dd><p>This indicates that a pointer had its upper bound picket-fence magic
1880 space overwritten. If the <code>check-fence</code> token is enabled, the
1881 library writes magic values above and below allocations to protect
1882 against overflow. Most likely this is because an array or string
1883 allocation wrote past the end of the allocation.
1884 </p>
1885 <p>Check for improper usage of <code>strcat</code>, <code>sprintf</code>,
1886 <code>strcpy</code>, and any other functions which work with strings and do
1887 not protect themselves by tracking the size of the string. These
1888 functions should <em>always</em> be replaced with: <code>strncat</code>,
1889 <code>snprintf</code>, <code>strncpy</code>, and others.
1890 </p>
1891
1892 <a name="IDX231"></a>
1893 <a name="IDX232"></a>
1894 <a name="IDX233"></a>
1895 <a name="IDX234"></a>
1896 <a name="IDX235"></a>
1897
1898 </dd>
1899 <dt> <code>28 (ERROR_WOULD_OVERWRITE) use of pointer would exceed allocation</code></dt>
1900 <dd><p>This error is generated by the function pointer checking code usually
1901 enabled with the <code>check-funcs</code> token. Dmalloc overloads a number of
1902 string and memory copying functions and verifies that the buffers (if
1903 allocated in the heap) would not be overwritten by the function.
1904 </p>
1905
1906 <a name="IDX236"></a>
1907 <a name="IDX237"></a>
1908 <a name="IDX238"></a>
1909 <a name="IDX239"></a>
1910 <a name="IDX240"></a>
1911
1912 </dd>
1913 <dt> <code>30 (ERROR_NOT_START_BLOCK) pointer is not to start of memory block</code></dt>
1914 <dd><p>This indicates that the user passed in a pointer to be freed or
1915 reallocated that was not at the start of the allocation. You would get
1916 this error, for example, if you allocate and get pointer <code>X</code> but
1917 then try to free <code>X+1</code>.
1918 </p>
1919
1920 <a name="IDX241"></a>
1921 <a name="IDX242"></a>
1922 <a name="IDX243"></a>
1923 <a name="IDX244"></a>
1924 <a name="IDX245"></a>
1925
1926 </dd>
1927 <dt> <code>40 (ERROR_BAD_SIZE) invalid allocation size</code></dt>
1928 <dd><p>This error indicates that a size value in the internal structures of the
1929 library were corrupted. This could be a random pointer problem, pointer
1930 overflow, or some other corruption.
1931 </p>
1932
1933 <a name="IDX246"></a>
1934 <a name="IDX247"></a>
1935 <a name="IDX248"></a>
1936 <a name="IDX249"></a>
1937 <a name="IDX250"></a>
1938
1939 </dd>
1940 <dt> <code>41 (ERROR_TOO_BIG) largest maximum allocation size exceeded</code></dt>
1941 <dd><p>An allocation asked for memory larger than the configured maximum. This
1942 is a user configured setting. See <code>LARGEST_ALLOCATION</code> in the
1943 <tt>`settings.dist'</tt> file. It is used to protect against wild
1944 allocation sizes. If you have super large allocation sizes then you
1945 should tune the <code>LARGEST_ALLOCATION</code> value appropriately.
1946 </p>
1947
1948 <a name="IDX251"></a>
1949 <a name="IDX252"></a>
1950 <a name="IDX253"></a>
1951 <a name="IDX254"></a>
1952 <a name="IDX255"></a>
1953
1954 </dd>
1955 <dt> <code>43 (ERROR_ALLOC_FAILED) could not grow heap by allocating memory</code></dt>
1956 <dd><p>The library could not allocate more heap space and the program has run
1957 out of memory. This could indicate that you've overflowed some system
1958 imposed limit. On many operation systems, the <code>ulimit</code> call can
1959 tune system defaults. The library uses a lot more memory compared to
1960 the system malloc library because it stores a lot more information
1961 about the allocated pointers.
1962 </p>
1963 <a name="IDX256"></a>
1964 <a name="IDX257"></a>
1965
1966 <p><em>NOTE</em>: This also may be due to an inability of your operating
1967 system to use the <code>mmap</code> system call to allocate memory. You may
1968 need to force the <code>USE_MMAP</code> setting to be 0. Please use the
1969 forums at URL <a href="http://dmalloc.com/">http://dmalloc.com/</a> to report issues with this.
1970 </p>
1971
1972 <a name="IDX258"></a>
1973 <a name="IDX259"></a>
1974 <a name="IDX260"></a>
1975 <a name="IDX261"></a>
1976 <a name="IDX262"></a>
1977 <a name="IDX263"></a>
1978
1979 </dd>
1980 <dt> <code>45 (ERROR_OVER_LIMIT) over user specified allocation limit</code></dt>
1981 <dd><p>The library has allocated more memory than was specified in the
1982 memory-limit environmental variable. See section <a href="#SEC32">Environment Variable Name and Features</a>.
1983 </p>
1984
1985 <a name="IDX264"></a>
1986 <a name="IDX265"></a>
1987 <a name="IDX266"></a>
1988 <a name="IDX267"></a>
1989 <a name="IDX268"></a>
1990
1991 </dd>
1992 <dt> <code>60 (ERROR_NOT_ON_BLOCK) pointer is not on block boundary</code></dt>
1993 <dd><p>The user tried to free or realloc a pointer that was not pointing to a
1994 block boundary. You would get this error, for example, if you allocate
1995 and get pointer <code>X</code> but then try to free <code>X+1</code>.
1996 </p>
1997
1998 <a name="IDX269"></a>
1999 <a name="IDX270"></a>
2000 <a name="IDX271"></a>
2001 <a name="IDX272"></a>
2002 <a name="IDX273"></a>
2003
2004 </dd>
2005 <dt> <code>61 (ERROR_ALREADY_FREE) tried to free previously freed pointer</code></dt>
2006 <dd><p>The user tried to free a pointer than has already been freed. This is a
2007 very common mistake and can lead to serious problems. It can be because
2008 a destructor is being called twice for some reason. Although tracking
2009 down the specific source is highly recommended, it is good to set
2010 pointers to NULL (0L) after you free them as a rule.
2011 </p>
2012
2013 <a name="IDX274"></a>
2014 <a name="IDX275"></a>
2015 <a name="IDX276"></a>
2016 <a name="IDX277"></a>
2017 <a name="IDX278"></a>
2018 <a name="IDX279"></a>
2019 <a name="IDX280"></a>
2020
2021 </dd>
2022 <dt> <code>67 (ERROR_FREE_OVERWRITTEN) free space has been overwritten</code></dt>
2023 <dd><p>If either the <code>free-blank</code> or <code>check-blank</code> tokens are enabled
2024 then the library will overwrite memory when it is freed with the
2025 &quot;dmalloc-free&quot; byte (hex 0xdf, octal 0337, decimal 223). If the
2026 program writes into this space, then the library will detect the write
2027 and trigger this error. This could indicate that the program is using a
2028 pointer after it has been freed.
2029 </p>
2030
2031 <a name="IDX281"></a>
2032 <a name="IDX282"></a>
2033 <a name="IDX283"></a>
2034 <a name="IDX284"></a>
2035 <a name="IDX285"></a>
2036
2037 </dd>
2038 <dt> <code>70 (ERROR_ADMIN_LIST) bad admin structure list</code></dt>
2039 <dd><p>An internal corruption in the library's administrative structures has
2040 been detected. This could be a random pointer problem, pointer
2041 overflow, or some other corruption.
2042 </p>
2043
2044 <a name="IDX286"></a>
2045 <a name="IDX287"></a>
2046 <a name="IDX288"></a>
2047 <a name="IDX289"></a>
2048 <a name="IDX290"></a>
2049
2050 </dd>
2051 <dt> <code>72 (ERROR_ADDRESS_LIST) internal address list corruption</code></dt>
2052 <dd><p>An internal corruption in the library's administrative structures has
2053 been detected. This could be a random pointer problem, pointer
2054 overflow, or some other corruption.
2055 </p>
2056
2057 <a name="IDX291"></a>
2058 <a name="IDX292"></a>
2059 <a name="IDX293"></a>
2060 <a name="IDX294"></a>
2061 <a name="IDX295"></a>
2062
2063 </dd>
2064 <dt> <code>73 (ERROR_SLOT_CORRUPT) internal memory slot corruption</code></dt>
2065 <dd><p>An internal corruption in the library's administrative structures has
2066 been detected. This could be a random pointer problem, pointer
2067 overflow, or some other corruption.
2068 </p>
2069 </dd>
2070 </dl>
2071
2072
2073 <hr size="6">
2074 <a name="Disabling-the-Library"></a>
2075 <a name="SEC17"></a>
2076 <table cellpadding="1" cellspacing="1" border="0">
2077 <tr><td valign="middle" align="left">[<a href="#SEC16" title="Previous section in reading order"> &lt; </a>]</td>
2078 <td valign="middle" align="left">[<a href="#SEC18" title="Next section in reading order"> &gt; </a>]</td>
2079 <td valign="middle" align="left"> &nbsp; </td>
2080 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2081 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2082 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2083 <td valign="middle" align="left"> &nbsp; </td>
2084 <td valign="middle" align="left"> &nbsp; </td>
2085 <td valign="middle" align="left"> &nbsp; </td>
2086 <td valign="middle" align="left"> &nbsp; </td>
2087 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2088 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2089 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2090 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2091 </tr></table>
2092 <h2 class="section"> 3.7 How to Disable the library </h2>
2093
2094
2095 <p>If you would like to disable the library's detailed checking features
2096 during a particularly allocation intensive section of code, you can do
2097 something like the following:
2098 </p>
2099 <table><tr><td>&nbsp;</td><td><pre class="example"> unsigned int dmalloc_flags;
2100 &hellip;
2101 /* turn off all debug flags and save a copy of old value */
2102 dmalloc_flags = dmalloc_debug(0);
2103
2104 /* section of a lot of allocations */
2105 &hellip;
2106 /* end of section */
2107
2108 /* restore the dmalloc flag setting */
2109 dmalloc_debug(dmalloc_flags);
2110 </pre></td></tr></table>
2111 <p>When you are finished with the development and debugging sessions, you
2112 may want to disable the dmalloc library and put in its place either the
2113 system's memory-allocation routines, gnu-malloc, or maybe your own.
2114 Attempts have been made to make this a reasonably painless process. The
2115 ease of the extraction depends heavily on how many of the library's
2116 features your made use of during your coding.
2117 </p>
2118 <p>Reasonable suggestions are welcome as to how to improve this process
2119 while maintaining the effectiveness of the debugging.
2120 </p>
2121 <ul>
2122 <li>
2123 If you want to <em>totally</em> disable the dmalloc library then you will
2124 need to recompile all the C files that include <tt>`dmalloc.h'</tt> while
2125 defining <code>DMALLOC_DISABLE</code>. This will cause the dmalloc macros to
2126 not be applied. See section <a href="#SEC11">Macros Providing File and Line Information</a>.
2127
2128 <table><tr><td>&nbsp;</td><td><pre class="example">cc -g -DDMALLOC_DISABLE file.c
2129 </pre></td></tr></table>
2130 <p>An alternative is to surround the <code>dmalloc.h</code> inclusion or any
2131 direct dmalloc references with an <code>#ifdef DMALLOC</code> and then just
2132 remove the -DDMALLOC.
2133 </p>
2134 <table><tr><td>&nbsp;</td><td><pre class="example">#ifdef DMALLOC
2135 #include &quot;dmalloc.h&quot;
2136 #endif
2137
2138 main()
2139 {
2140 &hellip;
2141
2142 #ifdef DMALLOC
2143 dmalloc_verify(0L);
2144 #endif
2145 return 0;
2146 }
2147 </pre></td></tr></table>
2148 <table><tr><td>&nbsp;</td><td><pre class="example">// to get dmalloc information
2149 $ cc -DDMALLOC main.c
2150
2151 // without dmalloc information
2152 $ cc main.c
2153 </pre></td></tr></table>
2154 </li><li>
2155 If you compiled any of your source modules with <code>DMALLOC_FUNC_CHECK</code>
2156 defined then you must first recompile all those modules without the flag
2157 enabled.
2158
2159 <p>If you have disabled dmalloc with the <code>DMALLOC_DISABLED</code> flag or
2160 never included <tt>`dmalloc.h'</tt> in any of your C files, then you will
2161 not need to recompile your sources when you need to disable the library.
2162 </p>
2163 <p>If you get unresolved references like <code>_dmalloc_malloc</code> or
2164 <code>_dmalloc_bcopy</code> then something was not disabled as it should have
2165 been.
2166 </p></li></ul>
2167
2168
2169 <hr size="6">
2170 <a name="Using-With-C_002b_002b"></a>
2171 <a name="SEC18"></a>
2172 <table cellpadding="1" cellspacing="1" border="0">
2173 <tr><td valign="middle" align="left">[<a href="#SEC17" title="Previous section in reading order"> &lt; </a>]</td>
2174 <td valign="middle" align="left">[<a href="#SEC19" title="Next section in reading order"> &gt; </a>]</td>
2175 <td valign="middle" align="left"> &nbsp; </td>
2176 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2177 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2178 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2179 <td valign="middle" align="left"> &nbsp; </td>
2180 <td valign="middle" align="left"> &nbsp; </td>
2181 <td valign="middle" align="left"> &nbsp; </td>
2182 <td valign="middle" align="left"> &nbsp; </td>
2183 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2184 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2185 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2186 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2187 </tr></table>
2188 <h2 class="section"> 3.8 Using the Library with C++ </h2>
2189
2190
2191 <p>For those people using the C++ language, the library tries to configure
2192 and build <tt>`libdmallocxx.a'</tt> library. This library should be linked
2193 into your C++ programs instead of <tt>`libdmalloc.a'</tt>.
2194 </p>
2195 <a name="IDX296"></a>
2196 <p>Dmalloc is not as good with C++ as C because the dynamic memory routines
2197 in C++ are <code>new()</code> and <code>delete()</code> as opposed to
2198 <code>malloc()</code> and <code>free()</code>. Since new and delete are usually not
2199 used as functions but rather as <code>x = new type</code>, there is no easy
2200 way for dmalloc to pass in file and line information unfortunately. The
2201 <tt>`libdmallocxx.a'</tt> library provides the file <tt>`dmallocc.cc'</tt> which
2202 effectively redirects <code>new</code> to the more familiar <code>malloc</code> and
2203 <code>delete</code> to the more familiar <code>free</code>.
2204 </p>
2205 <p><em>NOTE</em>: The author is not a C++ hacker so feedback in the form of
2206 other hints and ideas for C++ users would be much appreciated.
2207 </p>
2208
2209 <hr size="6">
2210 <a name="Using-With-a-Debugger"></a>
2211 <a name="SEC19"></a>
2212 <table cellpadding="1" cellspacing="1" border="0">
2213 <tr><td valign="middle" align="left">[<a href="#SEC18" title="Previous section in reading order"> &lt; </a>]</td>
2214 <td valign="middle" align="left">[<a href="#SEC20" title="Next section in reading order"> &gt; </a>]</td>
2215 <td valign="middle" align="left"> &nbsp; </td>
2216 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2217 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2218 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2219 <td valign="middle" align="left"> &nbsp; </td>
2220 <td valign="middle" align="left"> &nbsp; </td>
2221 <td valign="middle" align="left"> &nbsp; </td>
2222 <td valign="middle" align="left"> &nbsp; </td>
2223 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2224 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2225 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2226 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2227 </tr></table>
2228 <h2 class="section"> 3.9 Using Dmalloc With a Debugger </h2>
2229
2230
2231 <p>Here are a number of possible scenarios for using the dmalloc library to
2232 track down problems with your program.
2233 </p>
2234 <p>You should first enable a logfile filename and turn on a set of debug
2235 features. You can use <kbd>dmalloc -l logfile low</kbd> to accomplish this.
2236 If you are interested in having the error messages printed to your
2237 terminal as well, enable the <code>print-messages</code> token by typing
2238 <kbd>dmalloc -p print-messages</kbd> afterwards. See section <a href="#SEC29">Dmalloc Utility Program</a>.
2239 </p>
2240 <a name="IDX297"></a>
2241 <a name="IDX298"></a>
2242 <p>Now you can enter your debugger (I use the <em>excellent</em> GNU debugger
2243 gdb), and put a break-point in <code>dmalloc_error()</code> which is the
2244 internal error routine for the library. When your program is run, it
2245 will stop there if a memory problem is detected.
2246 </p>
2247 <p>If you are using GDB, I would recommend adding the contents of
2248 <tt>`dmalloc.gdb'</tt> in the <tt>`contrib'</tt> subdirectory to your
2249 <tt>`.gdbinit'</tt> file in your home directory. This enables the
2250 <code>dmalloc</code> command which will prompt you for the arguments to the
2251 dmalloc command and will set a break point in <code>dmalloc_error()</code>
2252 automatically.
2253 </p>
2254 <a name="IDX299"></a>
2255 <a name="IDX300"></a>
2256 <p>If you are using shared libraries, you may want to execute the following
2257 commands initially to load in dmalloc and other library symbols:
2258 </p>
2259 <table><tr><td>&nbsp;</td><td><pre class="example">(gdb) sharedlibrary
2260 (gdb) add-shared-symbol-files
2261 </pre></td></tr></table>
2262 <table class="menu" border="0" cellspacing="0">
2263 <tr><td align="left" valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Diagnosing general problems with a debugger.
2264 </td></tr>
2265 <tr><td align="left" valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Tracking down non-freed memory.
2266 </td></tr>
2267 <tr><td align="left" valign="top"><a href="#SEC22">3.9.3 Diagnosing Fence-Post Overwritten Memory</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Diagnosing fence-post overwritten memory.
2268 </td></tr>
2269 <tr><td align="left" valign="top"><a href="#SEC23">3.9.4 Translating Return Addresses into Code Locations</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Convert ra return-addresses into a location.
2270 </td></tr>
2271 </table>
2272
2273
2274 <hr size="6">
2275 <a name="General-Errors"></a>
2276 <a name="SEC20"></a>
2277 <table cellpadding="1" cellspacing="1" border="0">
2278 <tr><td valign="middle" align="left">[<a href="#SEC19" title="Previous section in reading order"> &lt; </a>]</td>
2279 <td valign="middle" align="left">[<a href="#SEC21" title="Next section in reading order"> &gt; </a>]</td>
2280 <td valign="middle" align="left"> &nbsp; </td>
2281 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2282 <td valign="middle" align="left">[<a href="#SEC19" title="Up section"> Up </a>]</td>
2283 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2284 <td valign="middle" align="left"> &nbsp; </td>
2285 <td valign="middle" align="left"> &nbsp; </td>
2286 <td valign="middle" align="left"> &nbsp; </td>
2287 <td valign="middle" align="left"> &nbsp; </td>
2288 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2289 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2290 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2291 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2292 </tr></table>
2293 <h3 class="subsection"> 3.9.1 Diagnosing General Problems with a Debugger </h3>
2294
2295
2296 <p>If your program stops at the <code>dmalloc_error()</code> routine then one
2297 of a number of problems could be happening. Incorrect arguments could
2298 have been passed to a malloc call: asking for negative number of
2299 bytes, trying to realloc a non-heap pointer, etc.. There also could
2300 be a problem with the system's allocations: you've run out of memory,
2301 some other function in your program is using the heap allocation
2302 functions <code>mmap</code> or <code>sbrk</code>, etc.. However, it is most
2303 likely that some code that has been executed was naughty.
2304 </p>
2305 <p>To get more information about the problem, first print via the debugger
2306 the dmalloc_errno variable to get the library's internal error code.
2307 You can suspend your debugger and run <kbd>dmalloc -e
2308 value-returned-from-print</kbd> to get an English translation of the error.
2309 A number of the error messages are designed to indicate specific
2310 problems with the library administrative structures and may not be
2311 user-friendly.
2312 </p>
2313 <p>If the problem was due to the arguments or system allocations then the
2314 source of the problem has been found. However, if some code did
2315 something wrong, you may have some more work to do to locate the actual
2316 problem. The <code>check-heap</code> token should be enabled and the interval
2317 setting disabled or set to a low value so that the library can find the
2318 problem as close as possible to its source. The code that was execute
2319 right before the library halted, can then be examined closely for
2320 irregularities. See section <a href="#SEC33">Description of the Debugging Tokens</a>, See section <a href="#SEC29">Dmalloc Utility Program</a>.
2321 </p>
2322 <a name="IDX301"></a>
2323
2324 <p>You may also want to put calls to <code>dmalloc_verify(0)</code> in your code
2325 before the section which generated the error. This should locate the
2326 problem faster by checking the library's structures at that point.
2327 See section <a href="#SEC15">Additional Non-standard Routines</a>.
2328 </p>
2329
2330 <hr size="6">
2331 <a name="Memory-Leaks"></a>
2332 <a name="SEC21"></a>
2333 <table cellpadding="1" cellspacing="1" border="0">
2334 <tr><td valign="middle" align="left">[<a href="#SEC20" title="Previous section in reading order"> &lt; </a>]</td>
2335 <td valign="middle" align="left">[<a href="#SEC22" title="Next section in reading order"> &gt; </a>]</td>
2336 <td valign="middle" align="left"> &nbsp; </td>
2337 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2338 <td valign="middle" align="left">[<a href="#SEC19" title="Up section"> Up </a>]</td>
2339 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2340 <td valign="middle" align="left"> &nbsp; </td>
2341 <td valign="middle" align="left"> &nbsp; </td>
2342 <td valign="middle" align="left"> &nbsp; </td>
2343 <td valign="middle" align="left"> &nbsp; </td>
2344 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2345 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2346 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2347 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2348 </tr></table>
2349 <h3 class="subsection"> 3.9.2 Tracking Down Non-Freed Memory </h3>
2350
2351
2352 <p>So you've run your program, examined the log-file and discovered (to
2353 your horror) some un-freed memory. Memory leaks can become large
2354 problems since even the smallest and most insignificant leak can starve
2355 the program given the right circumstances.
2356 </p>
2357 <table><tr><td>&nbsp;</td><td><pre class="example">not freed: '0x45008' (12 bytes) from 'ra=0x1f8f4'
2358 not freed: '0x45028' (12 bytes) from 'unknown'
2359 not freed: '0x45048' (10 bytes) from 'argv.c:1077'
2360 known memory not freed: 1 pointer, 10 bytes
2361 unknown memory not freed: 2 pointers, 24 bytes
2362 </pre></td></tr></table>
2363 <p>Above you will see a sample of some non-freed memory messages from the
2364 logfile. In the first line the <samp>`0x45008'</samp> is the pointer that was
2365 not freed, the <samp>`12 bytes'</samp> is the size of the unfreed block, and the
2366 <samp>`ra=0x1f8f4'</samp> or return-address shows where the allocation
2367 originated from. See section <a href="#SEC23">Translating Return Addresses into Code Locations</a>.
2368 </p>
2369 <p>The systems which cannot provide return-address information show
2370 <samp>`unknown'</samp> instead, as in the 2nd line in the sample above.
2371 </p>
2372 <p>The <samp>`argv.c:1077'</samp> information from the 3rd line shows the file and
2373 line number which allocated the memory which was not freed. This
2374 information comes from the calls from C files which included
2375 <tt>`dmalloc.h'</tt>. See section <a href="#SEC11">Macros Providing File and Line Information</a>.
2376 </p>
2377 <p>At the bottom of the sample it totals the memory for you and breaks it
2378 down to known memory (those calls which supplied the file/line
2379 information) and unknown (the rest).
2380 </p>
2381 <p>Often, you may allocate memory in via <code>strdup()</code> or another
2382 routine, so the logfile listing where in the <code>strdup</code> routine the
2383 memory was allocated does not help locate the true source of the memory
2384 leak - the routine that called <code>strdup</code>. Without a mechanism to
2385 trace the calling stack, there is no way for the library to see who the
2386 caller of the caller (so to speak) was.
2387 </p>
2388 <a name="IDX302"></a>
2389 <a name="IDX303"></a>
2390 <a name="IDX304"></a>
2391
2392 <p>However, there is a way to track down unfreed memory in this
2393 circumstance. You need to compile the library with
2394 <code>STORE_SEEN_COUNT</code> defined in <tt>`conf.h'</tt>. The library will then
2395 record how many times a pointer has been allocated or freed. It will
2396 display the unfreed memory as:
2397 </p>
2398 <table><tr><td>&nbsp;</td><td><pre class="example">not freed: '0x45008|s3' (12 bytes) from 'ra=0x1f8f4'
2399 </pre></td></tr></table>
2400 <p>The <code>STORE_SEEN_COUNT</code> option adds a <samp>`|s#'</samp> qualifier to the
2401 address. This means that the address in question was seen <samp>`#'</samp> many
2402 times. In the above example, the address <samp>`0x45008'</samp> was seen
2403 <samp>`3'</samp> times. The last time it was allocated, it was not freed.
2404 </p>
2405 <p>How can a pointer be &quot;seen&quot; 3 times? Let say you <code>strdup</code> a
2406 string of 12 characters and get address <samp>`0x45008'</samp> - this is #1
2407 time the pointer is seen. You then free the pointer (seen #2) but later
2408 <code>strdup</code> another 12 character string and it gets the <samp>`0x45008'</samp>
2409 address from the free list (seen #3).
2410 </p>
2411 <p>So to find out who is allocating this particular 12 bytes the 3rd time,
2412 try <kbd>dmalloc -a 0x45008:3</kbd>. The library will stop the program the
2413 third time it sees the <samp>`0x45008'</samp> address. You then enter a
2414 debugger and put a break point at <code>dmalloc_error</code>. Run the program
2415 and when the breakpoint is reached you can examine the stack frame to
2416 determine who called <code>strdup</code> to allocate the pointer.
2417 </p>
2418 <p>To not bother with the <code>STORE_SEEN_COUNT</code> feature, you can also run
2419 your program with the <code>never-reuse</code> token enabled. This token will
2420 cause the library to never reuse memory that has been freed. Unique
2421 addresses are always generated. This should be used with caution since
2422 it may cause your program to run out of memory.
2423 </p>
2424
2425 <hr size="6">
2426 <a name="Fence_002dPost-Overruns"></a>
2427 <a name="SEC22"></a>
2428 <table cellpadding="1" cellspacing="1" border="0">
2429 <tr><td valign="middle" align="left">[<a href="#SEC21" title="Previous section in reading order"> &lt; </a>]</td>
2430 <td valign="middle" align="left">[<a href="#SEC23" title="Next section in reading order"> &gt; </a>]</td>
2431 <td valign="middle" align="left"> &nbsp; </td>
2432 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2433 <td valign="middle" align="left">[<a href="#SEC19" title="Up section"> Up </a>]</td>
2434 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2435 <td valign="middle" align="left"> &nbsp; </td>
2436 <td valign="middle" align="left"> &nbsp; </td>
2437 <td valign="middle" align="left"> &nbsp; </td>
2438 <td valign="middle" align="left"> &nbsp; </td>
2439 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2440 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2441 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2442 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2443 </tr></table>
2444 <h3 class="subsection"> 3.9.3 Diagnosing Fence-Post Overwritten Memory </h3>
2445
2446
2447 <p>For a definition of fence-posts please see the &quot;Features&quot; section.
2448 See section <a href="#SEC8">General Features of the Library</a>.
2449 </p>
2450 <p>To detect fence-post overruns, you need to enable the <samp>`check-fence'</samp>
2451 token. See section <a href="#SEC33">Description of the Debugging Tokens</a>. This pads your allocations with some extra
2452 bytes at the front and the end and watches the space to make sure that
2453 they don't get overwritten. <em>NOTE:</em> The library cannot detect if
2454 this space gets read, only written.
2455 </p>
2456 <p>If you have encountered a fence-post memory error, the logfile should be
2457 able to tell you the offending address.
2458 </p>
2459 <table><tr><td>&nbsp;</td><td><pre class="example">free: failed UNDER picket-fence magic-number checking:
2460 pointer '0x1d008' from 'dmalloc_t.c:427'
2461 Dump of proper fence-bottom bytes: '\e\253\300\300\e\253\300\300'
2462 Dump of '0x1d008'-8: '\e\253\300\300WOW!\003\001pforger\023\001\123'
2463 </pre></td></tr></table>
2464 <p>The above sample shows that the pointer <samp>`0x1d008'</samp> has had its lower
2465 fence-post area overwritten. This means that the code wrote below the
2466 bottom of the address or above the address right below this one. In the
2467 sample, the string that did it was <samp>`WOW!'</samp>.
2468 </p>
2469 <p>The library first shows you what the proper fence-post information
2470 should look like, and then shows what the pointer's bad information was.
2471 If it cannot print the character, it will display the value as
2472 <samp>`\ddd'</samp> where ddd are three octal digits.
2473 </p>
2474 <p>By enabling the <code>check-heap</code> debugging token and assigning the
2475 interval setting to a low number, you should be able to locate
2476 approximately when this problem happened. See section <a href="#SEC33">Description of the Debugging Tokens</a>,
2477 See section <a href="#SEC29">Dmalloc Utility Program</a>.
2478 </p>
2479
2480 <hr size="6">
2481 <a name="Translate-Return-Addresses"></a>
2482 <a name="SEC23"></a>
2483 <table cellpadding="1" cellspacing="1" border="0">
2484 <tr><td valign="middle" align="left">[<a href="#SEC22" title="Previous section in reading order"> &lt; </a>]</td>
2485 <td valign="middle" align="left">[<a href="#SEC24" title="Next section in reading order"> &gt; </a>]</td>
2486 <td valign="middle" align="left"> &nbsp; </td>
2487 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2488 <td valign="middle" align="left">[<a href="#SEC19" title="Up section"> Up </a>]</td>
2489 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2490 <td valign="middle" align="left"> &nbsp; </td>
2491 <td valign="middle" align="left"> &nbsp; </td>
2492 <td valign="middle" align="left"> &nbsp; </td>
2493 <td valign="middle" align="left"> &nbsp; </td>
2494 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2495 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2496 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2497 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2498 </tr></table>
2499 <h3 class="subsection"> 3.9.4 Translating Return Addresses into Code Locations </h3>
2500
2501
2502 <p>The following gdb commands help you translate the return-addresses (ra=)
2503 entries in the logfile into locations in your code. I've provided a
2504 <tt>`ra_info.pl'</tt> perl script in the <tt>`contrib/'</tt> directory with the
2505 dmalloc sources which seems to work well with gdb. But, if you need to
2506 do it manually, here are the commands in gdb to use.
2507 </p>
2508 <a name="IDX305"></a>
2509 <a name="IDX306"></a>
2510
2511 <table><tr><td>&nbsp;</td><td><pre class="example"># you may need to add the following commands to load in shared libraries
2512 (gdb) sharedlibrary
2513 (gdb) add-shared-symbol-files
2514
2515 (gdb) x 0x10234d
2516 0x10234d &lt;_findbuf+132&gt;: 0x7fffceb7
2517
2518 (gdb) info line *(0x82cc)
2519 Line 1092 of argv.c starts at pc 0x7540 and ends at 0x7550.
2520 </pre></td></tr></table>
2521 <p>In the above example, gdb was used to find that the two non-freed memory
2522 pointers were allocated in <code>_findbuf()</code> and in file argv.c line
2523 1092 respectively. The <samp>`x address'</samp> (for examine) can always be
2524 used on the return-addresses but the <samp>`info line *(address)'</samp> will
2525 only work if that file was compiled using the <kbd>-g</kbd> option and has
2526 not been stripped. This limitation may not be true in later versions of
2527 gdb.
2528 </p>
2529
2530 <hr size="6">
2531 <a name="Using-With-Threads"></a>
2532 <a name="SEC24"></a>
2533 <table cellpadding="1" cellspacing="1" border="0">
2534 <tr><td valign="middle" align="left">[<a href="#SEC23" title="Previous section in reading order"> &lt; </a>]</td>
2535 <td valign="middle" align="left">[<a href="#SEC25" title="Next section in reading order"> &gt; </a>]</td>
2536 <td valign="middle" align="left"> &nbsp; </td>
2537 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2538 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2539 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2540 <td valign="middle" align="left"> &nbsp; </td>
2541 <td valign="middle" align="left"> &nbsp; </td>
2542 <td valign="middle" align="left"> &nbsp; </td>
2543 <td valign="middle" align="left"> &nbsp; </td>
2544 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2545 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2546 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2547 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2548 </tr></table>
2549 <h2 class="section"> 3.10 Using the Library with a Thread Package </h2>
2550
2551
2552 <p>Threads are special operating system facilities which allow your
2553 programs to have multiple threads of execution (hence the name). In
2554 effect your program can be doing a number of things &quot;at the same
2555 time&quot;. This allows you to take full advantage of modern operating
2556 system scheduling and multi-processor hardware. If I've already lost
2557 you or if any of the terminology below does not make sense, see manuals
2558 about POSIX threads (pthreads) before going any further. O'Reilly
2559 publishes a pretty good pthreads manual for example.
2560 </p>
2561 <p>To use dmalloc with your threaded program, you will first need to make
2562 sure that you are linking with <tt>`libdmallocth.a'</tt> which is the
2563 threaded version of the library. The support for threads in dmalloc
2564 should be adequate for most if not all testing scenarios. It provides
2565 support for mutex locking itself to protect against race conditions that
2566 result in multiple simultaneous execution. One of the major problems is
2567 that most thread libraries uses malloc themselves. Since all of
2568 dmalloc's initialization happens when a call to malloc is made, we may
2569 be attempting to initialize or lock the mutex while the thread library
2570 is booting up. A very bad thing since thread libraries don't expect to
2571 recurse.
2572 </p>
2573 <a name="IDX307"></a>
2574
2575 <p>The solution to this problem is to have the library not initialize or
2576 lock its mutex variable until after a certain number of allocation calls
2577 have been completed. If the library does not wait before initializing
2578 the locks, the thread library will probably core dump. If it waits too
2579 long then it can't protect itself from multiple execution and it will
2580 abort or other bad things might happen. You adjust the number of times
2581 to wait at runtime with the <samp>`lock-on'</samp> option to the dmalloc program
2582 (for example <kbd>dmalloc -o 20</kbd>). See section <a href="#SEC29">Dmalloc Utility Program</a>. Times
2583 values between 5 and 30 are probably good although operating systems
2584 will vary significantly. You know its too low if your program
2585 immediately core dumps and too high if the dmalloc library says its gone
2586 recursive although with low values, you might get either problem.
2587 </p>
2588 <p>An additional complexity is when we are initializing the lock before
2589 mutex locking around the library. As mentioned, the initialization
2590 itself may generate a malloc call causing the library to go recursive
2591 and the pthread library to possibly core dump. With the THREAD_INIT_LOCK
2592 setting defined in <tt>`settings.h'</tt>, you can tune how many times before
2593 we start locking to try and initialize the mutex lock. It defaults to 2
2594 which seems to work for me. If people need to have this runtime
2595 configurable or would like to present an alternative default, please let
2596 me know.
2597 </p>
2598 <p>So to use dmalloc with a threaded program, follow the following steps
2599 carefully.
2600 </p>
2601 <ol>
2602 <li> Follow the installation instructions on how to configure,
2603 make, and install the library but make sure to add the
2604 <kbd>--enable-threads</kbd> argument to configure. See section <a href="#SEC3">How to Install the Library</a>.
2605
2606 </li><li> Typing <kbd>make</kbd> should be enough to build the threaded versions
2607 of the libraries including <tt>`libdmallocth.a'</tt>.
2608
2609 </li><li> Link the dmalloc threaded library into your program. The dmalloc
2610 library should probably be placed at or near the end of the library
2611 list.
2612
2613 </li><li> Enable the debugging options that you need by typing
2614 <kbd>dmalloc -l logfile -i 100 low</kbd> (for example). <kbd>dmalloc
2615 --usage</kbd> will provide verbose usage info for the dmalloc program.
2616 See section <a href="#SEC29">Dmalloc Utility Program</a>.
2617
2618 </li><li> Enable the &quot;lock-on&quot; option (for example <kbd>dmalloc -o 20</kbd>).
2619 As explained above, you may have to try different values before getting
2620 it right. Values between 5 and 30 are probably good.
2621
2622 </li><li> If you get a dmalloc error #13 <samp>`thread locking has not
2623 been configured'</samp> then you have not compiled you program with the
2624 threaded version of dmalloc or there was a problem building it.
2625
2626 </li><li> If everything works, you should be able to run your program, have
2627 it not immediately crash, and the dmalloc library should not complain
2628 about recursion.
2629
2630 </li></ol>
2631
2632 <p>If you have any specific questions or would like addition information
2633 posted in this section, please let me know. Experienced thread
2634 programmers only please.
2635 </p>
2636
2637 <hr size="6">
2638 <a name="Using-With-Cygwin"></a>
2639 <a name="SEC25"></a>
2640 <table cellpadding="1" cellspacing="1" border="0">
2641 <tr><td valign="middle" align="left">[<a href="#SEC24" title="Previous section in reading order"> &lt; </a>]</td>
2642 <td valign="middle" align="left">[<a href="#SEC26" title="Next section in reading order"> &gt; </a>]</td>
2643 <td valign="middle" align="left"> &nbsp; </td>
2644 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2645 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2646 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2647 <td valign="middle" align="left"> &nbsp; </td>
2648 <td valign="middle" align="left"> &nbsp; </td>
2649 <td valign="middle" align="left"> &nbsp; </td>
2650 <td valign="middle" align="left"> &nbsp; </td>
2651 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2652 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2653 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2654 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2655 </tr></table>
2656 <h2 class="section"> 3.11 Using the library with Cygwin environment. </h2>
2657
2658
2659 <p>The Cygwin environment is a Linux-like environment for Windows. It
2660 provides Linux look and feel as well as a programming environment. See
2661 URL <a href="http://www.cygwin.com/">http://www.cygwin.com/</a> for more details.
2662 </p>
2663 <a name="IDX308"></a>
2664 <a name="IDX309"></a>
2665 <a name="IDX310"></a>
2666
2667 <p>Cygwin uses the <code>GetEnvironmentVariableA</code> function to read in
2668 environmental variables instead of <code>getenv</code>. This functions are
2669 used to get the value of the <samp>`DMALLOC_OPTIONS'</samp> variable which
2670 sets the debugging options. See section <a href="#SEC32">Environment Variable Name and Features</a>.
2671 </p>
2672 <a name="IDX311"></a>
2673 <a name="IDX312"></a>
2674
2675 <p>As of right now, dmalloc is not detecting the
2676 <code>GetEnvironmentVariableA</code> function correctly so you may need to
2677 tune the <tt>`conf.h'</tt> file to get it to work. See the sections on
2678 <code>HAVE_GETENVIRONMENTVARIABLEA</code> and <code>GETENV_SAVE</code> settings.
2679 Feedback is welcome here.
2680 </p>
2681 <p>If you still have problems reading in the environmental variables, you
2682 can work around this issue. You can add some code into the
2683 <code>main</code> function in your program to initialize the dmalloc flags
2684 yourself. Here is a code sample:
2685 </p>
2686 <a name="IDX313"></a>
2687
2688 <table><tr><td>&nbsp;</td><td><pre class="example">main(int argc, char **argv)
2689 {
2690 #ifdef DMALLOC
2691 /*
2692 * Get environ variable DMALLOC_OPTIONS and pass the settings string
2693 * on to dmalloc_debug_setup to setup the dmalloc debugging flags.
2694 */
2695 dmalloc_debug_setup(getenv(&quot;DMALLOC_OPTIONS&quot;));
2696 #endif
2697
2698 /* rest of code in main starts here */
2699 &hellip;
2700 }
2701 </pre></td></tr></table>
2702 <p>The <code>#ifdef</code> is just a good idea. I means that when debugging with
2703 dmalloc you need to compile your code with <code>-DDMALLOC</code>. When you
2704 are done debugging you can remove the flag and the call to
2705 <code>dmalloc_debug_setup</code> will be removed.
2706 </p>
2707 <p>Please let me know if there is a better way to do this.
2708 </p>
2709
2710 <hr size="6">
2711 <a name="Debugging-A-Server"></a>
2712 <a name="SEC26"></a>
2713 <table cellpadding="1" cellspacing="1" border="0">
2714 <tr><td valign="middle" align="left">[<a href="#SEC25" title="Previous section in reading order"> &lt; </a>]</td>
2715 <td valign="middle" align="left">[<a href="#SEC27" title="Next section in reading order"> &gt; </a>]</td>
2716 <td valign="middle" align="left"> &nbsp; </td>
2717 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2718 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2719 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2720 <td valign="middle" align="left"> &nbsp; </td>
2721 <td valign="middle" align="left"> &nbsp; </td>
2722 <td valign="middle" align="left"> &nbsp; </td>
2723 <td valign="middle" align="left"> &nbsp; </td>
2724 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2725 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2726 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2727 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2728 </tr></table>
2729 <h2 class="section"> 3.12 Debugging Memory in a Server or Cgi-Bin Process </h2>
2730
2731
2732 <p>There are some specified challenges when trying to debug allocations
2733 in processes which do not startup, run, and then shutdown. Server
2734 processes (often called daemons) are those that are started (often at
2735 system boot time) and run perpetually. Other processes which are
2736 difficult to debug are CGI programs which are spawned by web servers
2737 or when you want to start debugging inside of a child process.
2738 </p>
2739 <ol>
2740 <li> Build your server or cgi-bin program with the dmalloc library
2741 like any other program. See section <a href="#SEC4">Getting Started with the Library</a>.
2742
2743 </li><li> Add code into your program to enable the library flags to
2744 perform the memory checks that you require. Since these programs
2745 often do not run from the command line, you cannot use the dmalloc
2746 utility program and modify the process environment. See section <a href="#SEC29">Dmalloc Utility Program</a>. The library provides a couple of functions to set the
2747 debugging flags when a program is running.
2748
2749 <a name="IDX314"></a>
2750
2751 </li><li> To set the memory debugging flags, use the
2752 <code>dmalloc_debug_setup</code> function which takes a string in the same
2753 format of the <samp>`DMALLOC_OPTIONS'</samp> environmental variable.
2754 See section <a href="#SEC32">Environment Variable Name and Features</a>. Use the dmalloc utility with the
2755 <code>-n</code> no-changes argument to see the appropriate settings for the
2756 <samp>`DMALLOC_OPTIONS'</samp> environmental variable.
2757
2758 <table><tr><td>&nbsp;</td><td><pre class="example">&gt; dmalloc -n -l logfile high
2759 Outputed:
2760 DMALLOC_OPTIONS=debug=0x4f4ed03,log=logfile
2761 export DMALLOC_OPTIONS
2762 </pre></td></tr></table>
2763 <p>So if you want to turn on <kbd>high</kbd> debugging and log to the file
2764 <tt>`logfile'</tt> then you would copy the above <samp>`DMALLOC_OPTIONS'</samp>
2765 value into a call to <code>dmalloc_debug_setup</code>. Notice that I have
2766 surrounded the dmalloc code with an <code>#ifdef DMALLOC</code> so you'll
2767 have to compile using the <code>-DDMALLOC</code> flag.
2768 </p>
2769 <table><tr><td>&nbsp;</td><td><pre class="example">main()
2770 {
2771 #ifdef DMALLOC
2772 /* set the 'high' flags */
2773 dmalloc_debug_setup(&quot;debug=0x4f47d03,log=logfile&quot;);
2774 #endif
2775 &hellip;
2776 }
2777 </pre></td></tr></table>
2778 <p><em>Please note</em> that the <code>dmalloc_debug_setup</code> function does
2779 not know about <code>high</code>, <code>low</code>, or other debug tokens but
2780 needs the actual flag values.
2781 </p>
2782 </li><li> For earlier versions of the library (before 5.0.0) without
2783 <code>dmalloc_debug_setup</code>, the <code>dmalloc_debug</code> function is
2784 available to set the flags directly, but it cannot adjust the logfile
2785 name and the other environment settings. You can use the dmalloc
2786 utility program to see what the numerical equivalent of the <kbd>high</kbd>
2787 token.
2788
2789 <table><tr><td>&nbsp;</td><td><pre class="example">&gt; dmalloc -n high
2790 Outputed:
2791 DMALLOC_OPTIONS=debug=0x4f4ed03
2792 export DMALLOC_OPTIONS
2793 </pre></td></tr></table>
2794 <p>You can then take the <code>0x4f4ed03</code> hexadecimal number and call
2795 <code>dmalloc_debug</code> with that number.
2796 </p>
2797 <table><tr><td>&nbsp;</td><td><pre class="example">main()
2798 {
2799 #ifdef DMALLOC
2800 /* set the 'high' flags */
2801 dmalloc_debug(0x4f4ed03);
2802 #endif
2803 &hellip;
2804 }
2805 </pre></td></tr></table>
2806 </li><li> Even with the settings enabled, you may have problems getting
2807 the logfile to be written if your program is running as <samp>`nobody'</samp>
2808 or another user without permissions for security reasons. This is
2809 especially true for cgi-bin programs. In this case you should specify
2810 a full path to your malloc logfile in a world writable directory
2811 (ex. <code>dmalloc_debug_setup(&quot;debug=0x4f47d03,log=/var/tmp/malloc&quot;);</code>).
2812 Watch for programs which change into other directories and which may
2813 cause logfiles specified as relative or local paths to be dropped in
2814 other locations. You may always want to use a full path logfile.
2815
2816 </li><li> Once you have your settings enabled and your log is being
2817 generated, you may now want to check out how your process is doing in
2818 terms of unfreed memory. Since it is not shutting down, the automatic
2819 unfreed log entries are not being dropped to the logfile. By using
2820 the <code>dmalloc_mark</code> and <code>dmalloc_log_changed</code> functions, you
2821 can set a mark point at a certain place inside of your program, and
2822 then later see whether there are any unfreed pointers since the mark.
2823
2824 <table><tr><td>&nbsp;</td><td><pre class="example">main()
2825 {
2826 #ifdef DMALLOC
2827 /* set the 'high' flags */
2828 dmalloc_debug_setup(&quot;debug=0x4f47d03,log=logfile&quot;);
2829 #endif
2830
2831 while (1) {
2832 /* accept a connection from a client */
2833 accept_connection();
2834
2835 while (1) {
2836 #ifdef DMALLOC
2837 unsigned long mark;
2838 /* get the current dmalloc position */
2839 mark = dmalloc_mark() ;
2840 #endif
2841 /* process the connection */
2842 if (process_connection() != PROCESS_OK) {
2843 break;
2844 }
2845 #ifdef DMALLOC
2846 /*
2847 * log unfreed pointers that have been added to
2848 * the heap since mark
2849 */
2850 dmalloc_log_changed(mark,
2851 1 /* log unfreed pointers */,
2852 0 /* do not log freed pointers */,
2853 1 /* log each pnt otherwise summary */);
2854 #endif
2855 }
2856 /* close the connection with the client */
2857 close_connection();
2858 }
2859 &hellip;
2860 }
2861 </pre></td></tr></table>
2862 <p>Usually you would set the mark after the initializations and before
2863 each transaction is processed. Then for each transaction you can use
2864 <code>dmalloc_log_changed</code> to show the unfreed memory.
2865 See section <a href="#SEC15">Additional Non-standard Routines</a>.
2866 </p>
2867 </li><li> You can also use the <code>dmalloc_log_stats</code> function to dump
2868 general information about the heap. Also, remember that you can use
2869 the <code>dmalloc_message</code> and <code>dmalloc_vmessage</code> routines to
2870 annotate the dmalloc logfile with details to help you debug memory
2871 problems. See section <a href="#SEC15">Additional Non-standard Routines</a>.
2872
2873 </li></ol>
2874
2875
2876 <hr size="6">
2877 <a name="Logfile-Details"></a>
2878 <a name="SEC27"></a>
2879 <table cellpadding="1" cellspacing="1" border="0">
2880 <tr><td valign="middle" align="left">[<a href="#SEC26" title="Previous section in reading order"> &lt; </a>]</td>
2881 <td valign="middle" align="left">[<a href="#SEC28" title="Next section in reading order"> &gt; </a>]</td>
2882 <td valign="middle" align="left"> &nbsp; </td>
2883 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2884 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2885 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2886 <td valign="middle" align="left"> &nbsp; </td>
2887 <td valign="middle" align="left"> &nbsp; </td>
2888 <td valign="middle" align="left"> &nbsp; </td>
2889 <td valign="middle" align="left"> &nbsp; </td>
2890 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2891 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2892 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2893 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2894 </tr></table>
2895 <h2 class="section"> 3.13 Explanation of the Logfile Output </h2>
2896
2897
2898 <p>Most of time you will be using the logfile output from library as the
2899 sole information source for diagnosing problems in and getting
2900 statistics for your program.
2901 </p>
2902 <table><tr><td>&nbsp;</td><td><pre class="example">1098918225: 3: Dmalloc version 'Version 5.5.2'
2903 1098918225: 3: flags = 0x4f4e503, logfile '/tmp/dmalloc.log'
2904 1098918225: 3: interval = 500, addr = 0, seen # = 0, limit = 0
2905 1098918225: 3: starting time = 1098918225
2906 1098918225: 3: process pid = 32406
2907 1098918226: 4: WARNING: tried to free(0) from foo.c:708'
2908 1098918228: 20: *** free: at 'unknown' pnt '0xed310080|s2': \
2909 size 12, alloced at 'bar.c:102'
2910 1098918230: 50: ERROR: heap_check: free space was overwritten (err 67)
2911 1098918230: 50: error details: checking free pointer
2912 1098918230: 50: pointer '0x291c5' from 'unknown' prev access 'foo.c:787'
2913 </pre></td></tr></table>
2914 <p>Here is a short example of some logfile information. Each of the
2915 lines are prefixed by the time (in epoch seconds since 1/1/1970) and
2916 the iteration or call count which is the number of times the library
2917 has been called from malloc, free, verify, etc.. In the above
2918 example, the first 5 log entries where written at epoch 1098918225 or
2919 <samp>`Wed Oct 27 19:03:45 2004 EST'</samp> and they were generated by the 3rd
2920 call to the library. See the <tt>`settings.dist'</tt> file entries to
2921 tune what elements appear on each line: LOG_TIME_NUMBER,
2922 LOG_ITERATION, LOG_PID, etc.. You can convert the epoch seconds to a
2923 date from the command line with the following perl code: <code>perl -e
2924 'print localtime($ARGV[0]).&quot;\n&quot;;' epoch-seconds-number</code>
2925 </p>
2926 <a name="IDX315"></a>
2927 <p>The first 5 lines of the sample logfile contain header information for
2928 all logfiles. They show the version number and URL for the library as
2929 well as all of the settings that the library is currently using.
2930 These settings are tuned using the dmalloc utility program.
2931 See section <a href="#SEC29">Dmalloc Utility Program</a>. The 5th line of is the process-id that
2932 generated the logfile.
2933 </p>
2934 <a name="IDX316"></a>
2935 <p>The 6th line in the above example is what causes the logfile to be
2936 opened and the header to be written. It is a warning that tells you
2937 that you tried to free a 0L pointer at a certain location. You can
2938 disable these warnings by setting <samp>`ALLOW_FREE_NULL_MESSAGE'</samp> to 0
2939 in <tt>`settings.dist'</tt>.
2940 </p>
2941 <a name="IDX317"></a>
2942 <p>Line 7 is an example of a transaction log that you get when you enable
2943 the <code>log-trans</code> debug token. See section <a href="#SEC33">Description of the Debugging Tokens</a>. This line
2944 shows that a call to free was made from an unknown location. It is
2945 unknown because the file in question did not include <tt>`dmalloc.h'</tt>
2946 to get file/line-number information. The call to free was freeing the
2947 pointer address <code>0xed310080</code> which we have &quot;seen&quot; 2 times (s2).
2948 We saw the pointer when it was allocated and then we are seeing it
2949 again when it was freed. Because the library is reusing pointers
2950 (reclaiming freed memory) the seen count helps to track how many times
2951 a pointer was used. The last part of the line shows that the pointer
2952 to be freed was allocated by <tt>`bar.c'</tt> line 102.
2953 </p>
2954 <p>Lines 8-10 is the next problem that the library caught and this one is
2955 an error. It happened 5 seconds from the start of the log
2956 (1098918230) and at the 50th call into the library. It shows that an
2957 allocation that had been freed then was overwritten. This may imply
2958 that someone tried to use memory after it was freed or that there was
2959 a loose pointer reference. The last two lines give more details about
2960 when the error was discovered, the address of the offending pointer,
2961 and when the pointer was previous accessed, in this case freed. To
2962 discover where this problem is happening, you can use a debugger.
2963 See section <a href="#SEC19">Using Dmalloc With a Debugger</a>.
2964 </p>
2965
2966 <hr size="6">
2967 <a name="Other-Hints"></a>
2968 <a name="SEC28"></a>
2969 <table cellpadding="1" cellspacing="1" border="0">
2970 <tr><td valign="middle" align="left">[<a href="#SEC27" title="Previous section in reading order"> &lt; </a>]</td>
2971 <td valign="middle" align="left">[<a href="#SEC29" title="Next section in reading order"> &gt; </a>]</td>
2972 <td valign="middle" align="left"> &nbsp; </td>
2973 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
2974 <td valign="middle" align="left">[<a href="#SEC10" title="Up section"> Up </a>]</td>
2975 <td valign="middle" align="left">[<a href="#SEC29" title="Next chapter"> &gt;&gt; </a>]</td>
2976 <td valign="middle" align="left"> &nbsp; </td>
2977 <td valign="middle" align="left"> &nbsp; </td>
2978 <td valign="middle" align="left"> &nbsp; </td>
2979 <td valign="middle" align="left"> &nbsp; </td>
2980 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
2981 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
2982 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
2983 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
2984 </tr></table>
2985 <h2 class="section"> 3.14 Various Other Hints That May Help </h2>
2986
2987
2988 <p>One of the problems that is often seen is that a program crashes in
2989 the <code>libc</code> memory code and you suspect a heap memory problem but
2990 both dmalloc and maybe valgrind don't show any problems. One of the
2991 big problems with debugging is that it is very difficult to do it
2992 without effecting how the program is run. Sometimes errors are due to
2993 subtle race conditions that are only seen when the program is running
2994 at full speed - not slowed down by debugging code.
2995 </p>
2996 <p>This is especially true with threaded code which is often heavily
2997 affected when used with dmalloc and valgrind. Older versions of
2998 valgrid (maybe current) forced all threads into a single virtual
2999 system by design, which often masks reentrance bugs.
3000 </p>
3001 <p>One way to work through these issues is to run with the library with
3002 very few debugging flags enabled. Many memory problems are fence-post
3003 areas so start with dmalloc checking just the fence post and error
3004 logging enabled:
3005 </p>
3006 <table><tr><td>&nbsp;</td><td><pre class="example">dmalloc -d 0 -l dmalloc.log -p log-stats -p log-non-free -p check-fence -p check-funcs
3007 </pre></td></tr></table>
3008 <p>This enabled a small number of checks and should cause your program to
3009 run at close to full speed. The library has never been optimized for
3010 speed so some performance penalties will be felt.
3011 </p>
3012
3013 <hr size="6">
3014 <a name="Dmalloc-Program"></a>
3015 <a name="SEC29"></a>
3016 <table cellpadding="1" cellspacing="1" border="0">
3017 <tr><td valign="middle" align="left">[<a href="#SEC28" title="Previous section in reading order"> &lt; </a>]</td>
3018 <td valign="middle" align="left">[<a href="#SEC30" title="Next section in reading order"> &gt; </a>]</td>
3019 <td valign="middle" align="left"> &nbsp; </td>
3020 <td valign="middle" align="left">[<a href="#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3021 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
3022 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3023 <td valign="middle" align="left"> &nbsp; </td>
3024 <td valign="middle" align="left"> &nbsp; </td>
3025 <td valign="middle" align="left"> &nbsp; </td>
3026 <td valign="middle" align="left"> &nbsp; </td>
3027 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3028 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3029 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3030 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3031 </tr></table>
3032 <h1 class="chapter"> 4. Dmalloc Utility Program </h1>
3033
3034
3035 <p>The dmalloc program is designed to assist in the setting of the
3036 environment variable <samp>`DMALLOC_OPTIONS'</samp>. See section <a href="#SEC32">Environment Variable Name and Features</a>. It is designed to print the shell commands necessary to make
3037 the appropriate changes to the environment. Unfortunately, it cannot
3038 make the changes on its own so the output from dmalloc should be sent
3039 through the <code>eval</code> shell command which will do the commands.
3040 </p>
3041 <table class="menu" border="0" cellspacing="0">
3042 <tr><td align="left" valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Using a shell alias with the utility.
3043 </td></tr>
3044 <tr><td align="left" valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> How to use the dmalloc program.
3045 </td></tr>
3046 <tr><td align="left" valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Environment variable name and features.
3047 </td></tr>
3048 <tr><td align="left" valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Description of the debugging tokens.
3049 </td></tr>
3050 <tr><td align="left" valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Format of the runtime configuration file.
3051 </td></tr>
3052 </table>
3053
3054
3055 <hr size="6">
3056 <a name="Shell-Alias"></a>
3057 <a name="SEC30"></a>
3058 <table cellpadding="1" cellspacing="1" border="0">
3059 <tr><td valign="middle" align="left">[<a href="#SEC29" title="Previous section in reading order"> &lt; </a>]</td>
3060 <td valign="middle" align="left">[<a href="#SEC31" title="Next section in reading order"> &gt; </a>]</td>
3061 <td valign="middle" align="left"> &nbsp; </td>
3062 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3063 <td valign="middle" align="left">[<a href="#SEC29" title="Up section"> Up </a>]</td>
3064 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3065 <td valign="middle" align="left"> &nbsp; </td>
3066 <td valign="middle" align="left"> &nbsp; </td>
3067 <td valign="middle" align="left"> &nbsp; </td>
3068 <td valign="middle" align="left"> &nbsp; </td>
3069 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3070 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3071 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3072 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3073 </tr></table>
3074 <h2 class="section"> 4.1 Using a Shell Alias with the Utility </h2>
3075
3076 <p>The dmalloc program is designed to assist in the setting of the
3077 environment variable <samp>`DMALLOC_OPTIONS'</samp>. See section <a href="#SEC32">Environment Variable Name and Features</a>. It is designed to print the shell commands necessary to make
3078 the appropriate changes to the environment. Unfortunately, it cannot
3079 make the changes on its own so the output from dmalloc should be sent
3080 through the <code>eval</code> shell command which will do the commands.
3081 </p>
3082 <a name="IDX318"></a>
3083 <a name="IDX319"></a>
3084 <a name="IDX320"></a>
3085 <a name="IDX321"></a>
3086
3087 <p>With shells that have aliasing or macro capabilities: csh, bash, ksh,
3088 tcsh, zsh, etc., setting up an alias to dmalloc to do the eval call is
3089 recommended. Bash, ksh, and zsh users should add the following to their
3090 <tt>`.bashrc'</tt>, <tt>`.profile'</tt>, or <tt>`.zshrc'</tt> file respectively
3091 (notice the <kbd>-b</kbd> option for bourne shell output):
3092 </p>
3093 <table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `command dmalloc -b $*`; }
3094 </pre></td></tr></table>
3095 <p>If your shell does not support the <code>command</code> function then try:
3096 </p>
3097 <table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `\dmalloc -b $*`; }
3098 </pre></td></tr></table><p>or
3099 </p><table><tr><td>&nbsp;</td><td><pre class="example">function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
3100 </pre></td></tr></table>
3101 <a name="IDX322"></a>
3102 <a name="IDX323"></a>
3103
3104 <p>If you are <em>still</em> using csh or tcsh, you should add the following
3105 to your <tt>`.cshrc'</tt> file (notice the <kbd>-C</kbd> option for c-shell
3106 output):
3107 </p>
3108 <table><tr><td>&nbsp;</td><td><pre class="example">alias dmalloc 'eval `\dmalloc -C \!*`'
3109 </pre></td></tr></table>
3110 <p>This allows the user to execute the dmalloc command as <samp>`dmalloc
3111 arguments'</samp>.
3112 </p>
3113 <p>Users of versions of the Bourne shell (usually known as /bin/sh) that
3114 don't have command functions will need to send the output to a temporary
3115 file and the read it back in with the &quot;.&quot; command:
3116 </p>
3117 <table><tr><td>&nbsp;</td><td><pre class="example">$ dmalloc -b arguments &hellip; &gt; /tmp/out
3118 $ . /tmp/out
3119 </pre></td></tr></table>
3120 <p>By the way, if you are looking for a shell, I heartily recommend trying
3121 out zsh. It is a bourne shell written from scratch with much the same
3122 features as tcsh without the csh crap.
3123 </p>
3124 <p><em>NOTE</em>: After you add the alias to the file you need to log out and
3125 log back in to have it take effect, or you can execute the above
3126 appropriate command on the command line. If you enter <kbd>dmalloc
3127 runtime</kbd> and see any output with DMALLOC_OPTIONS in it then the alias
3128 did not work.
3129 </p>
3130
3131 <hr size="6">
3132 <a name="Utility-Usage"></a>
3133 <a name="SEC31"></a>
3134 <table cellpadding="1" cellspacing="1" border="0">
3135 <tr><td valign="middle" align="left">[<a href="#SEC30" title="Previous section in reading order"> &lt; </a>]</td>
3136 <td valign="middle" align="left">[<a href="#SEC32" title="Next section in reading order"> &gt; </a>]</td>
3137 <td valign="middle" align="left"> &nbsp; </td>
3138 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3139 <td valign="middle" align="left">[<a href="#SEC29" title="Up section"> Up </a>]</td>
3140 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3141 <td valign="middle" align="left"> &nbsp; </td>
3142 <td valign="middle" align="left"> &nbsp; </td>
3143 <td valign="middle" align="left"> &nbsp; </td>
3144 <td valign="middle" align="left"> &nbsp; </td>
3145 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3146 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3147 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3148 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3149 </tr></table>
3150 <h2 class="section"> 4.2 How to Use the Dmalloc Program </h2>
3151
3152
3153 <p>The most basic usage for the program is <samp>`dmalloc [-bC] tag'</samp>. The
3154 <samp>`-b'</samp> or <samp>`-C'</samp> (either but not both flags used at a time) are
3155 for generating Bourne or C shell type commands respectively. dmalloc
3156 will try and use the <code>SHELL</code> environment variable to determine
3157 whether bourne or C shell commands should be generated but you may want
3158 to explicitly specify the correct flag.
3159 </p>
3160 <p>The <samp>`tag'</samp> argument to dmalloc should match a line from the user's
3161 runtime configuration file or should be one of the built-in tags.
3162 See section <a href="#SEC34">Format of the Runtime Configuration File</a>. If no tag is specified and no other option-commands
3163 used, dmalloc will display the current settings of the environment
3164 variable. It is useful to specify one of the verbose options when doing
3165 this.
3166 </p>
3167 <p>To find out the usage for the debug malloc program try <samp>`dmalloc
3168 --usage-long'</samp>. The standardized usage message that will be displayed is
3169 one of the many features of the argv library included with this package.
3170 </p>
3171 <p>It is available on the web at URL <a href="http://256.com/sources/argv/">http://256.com/sources/argv/</a>.
3172 See the documentation there for more information.
3173 </p>
3174 <p>Here is a detailed list of the flags that can passed to dmalloc:
3175 </p>
3176 <dl compact="compact">
3177 <dt> <code>-a address</code></dt>
3178 <dd><p>Set the <samp>`addr'</samp> part of the <samp>`DMALLOC_OPTIONS'</samp> variable to
3179 address (or alternatively address:number).
3180 </p>
3181 </dd>
3182 <dt> <code>-b</code></dt>
3183 <dd><p>Output Bourne shell type commands. Usually handled automagically.
3184 </p>
3185 </dd>
3186 <dt> <code>-C</code></dt>
3187 <dd><p>Output C shell type commands. Usually handled automagically.
3188 </p>
3189 </dd>
3190 <dt> <code>-c</code></dt>
3191 <dd><p>Clear/unset all of the settings not specified with other arguments. You
3192 can do this automatically when you set to a new tag with the <kbd>-r</kbd>
3193 option.
3194 </p>
3195 <p><em>NOTE</em>: clear will never unset the <samp>`debug'</samp> setting. Use
3196 <kbd>-d 0</kbd> or a tag to <samp>`none'</samp> to achieve this.
3197 </p>
3198 </dd>
3199 <dt> <code>-d bitmask</code></dt>
3200 <dd><p>Set the <samp>`debug'</samp> part of the <samp>`DMALLOC_OPTIONS'</samp> env variable to
3201 the bitmask value which should be in hex. This is overridden (and
3202 unnecessary) if a tag is specified.
3203 </p>
3204 </dd>
3205 <dt> <code>-D</code></dt>
3206 <dd><p>List all of the debug-tokens. Useful for finding a token to be used
3207 with the <kbd>-p</kbd> or <kbd>-m</kbd> options. Use with <kbd>-v</kbd> or <kbd>-V</kbd>
3208 verbose options.
3209 </p>
3210 </dd>
3211 <dt> <code>-e errno</code></dt>
3212 <dd><p>Print the dmalloc error string that corresponds to the error number
3213 errno.
3214 </p>
3215 </dd>
3216 <dt> <code>-f filename</code></dt>
3217 <dd><p>Use this configuration file instead of the RC file
3218 <tt>`$HOME/.dmallocrc'</tt>.
3219 </p>
3220 </dd>
3221 <dt> <code>-g</code></dt>
3222 <dd><p>Output gdb type commands for using inside of the gdb debugger.
3223 </p>
3224 </dd>
3225 <dt> <code>-h (or --help)</code></dt>
3226 <dd><p>Output a help message for the utility.
3227 </p>
3228 </dd>
3229 <dt> <code>-i number</code></dt>
3230 <dd><a name="IDX324"></a>
3231 <p>Set the checking interval to number. If the <code>check-heap</code> token is
3232 enabled, this causes the library to only check the heap every Nth time
3233 which can <em>significantly</em> increase the running speed of your
3234 program. If a problem is found, however, this limits your ability to
3235 determine when the problem occurred. Try values of 50 or 100 initially.
3236 </p>
3237 </dd>
3238 <dt> <code>-k</code></dt>
3239 <dd><p>Do not reset all of the settings when a tag is specified. This
3240 specifically overrides the <kbd>-r</kbd> option and is provided here to
3241 override <kbd>-r</kbd> if it has been added to the dmalloc alias.
3242 </p>
3243 </dd>
3244 <dt> <code>-l filename</code></dt>
3245 <dd><p>Write the debugging output and other log-file information to the
3246 filename. Filename can include some of the following patterns which get
3247 expanded into strings:
3248 </p>
3249 <dl compact="compact">
3250 <dd>
3251 <a name="IDX325"></a>
3252 <a name="IDX326"></a>
3253 <a name="IDX327"></a>
3254 <a name="IDX328"></a>
3255 </dd>
3256 <dt> <code>%h</code></dt>
3257 <dd><p>Gets expanded into the hostname if the <code>gethostname()</code> function is
3258 available.
3259 </p>
3260 <a name="IDX329"></a>
3261 <a name="IDX330"></a>
3262 </dd>
3263 <dt> <code>%i</code></dt>
3264 <dd><p>Gets expanded into the thread-id if the library has been configure to be
3265 used with threads. See section <a href="#SEC24">Using the Library with a Thread Package</a>. See the end of the
3266 <tt>`settings.dist'</tt> file for settings which return the thread-id and
3267 convert it into a string.
3268 </p>
3269 <a name="IDX331"></a>
3270 <a name="IDX332"></a>
3271 <a name="IDX333"></a>
3272 <a name="IDX334"></a>
3273 </dd>
3274 <dt> <code>%p</code></dt>
3275 <dd><p>Gets expanded into the process-id if the <code>getpid()</code> function is
3276 available.
3277 </p>
3278 <a name="IDX335"></a>
3279 <a name="IDX336"></a>
3280 <a name="IDX337"></a>
3281 </dd>
3282 <dt> <code>%t</code></dt>
3283 <dd><p>Gets expanded into the time value in seconds if the <code>time()</code>
3284 function is available.
3285 </p>
3286 <a name="IDX338"></a>
3287 <a name="IDX339"></a>
3288 <a name="IDX340"></a>
3289 <a name="IDX341"></a>
3290 </dd>
3291 <dt> <code>%u</code></dt>
3292 <dd><p>Gets expanded into the user-id number if the <code>getuid()</code> function is
3293 available.
3294 </p>
3295 </dd>
3296 </dl>
3297
3298 <p>Some examples:
3299 </p>
3300 <table><tr><td>&nbsp;</td><td><pre class="example"># logfile produced with pid extension:
3301 # logfile.8412 or logfile.31451
3302 dmalloc -l logfile.%p
3303
3304 # hostname and time extensions:
3305 # dmalloc-box1.foo.com-1055213240
3306 dmalloc -l dmalloc-%h-%t
3307
3308 # if threads enabled, have thread-id extension: log.thread32
3309 dmalloc -l log.thread%i
3310 </pre></td></tr></table>
3311 </dd>
3312 <dt> <code>-L</code></dt>
3313 <dd><p>Write the debug-value into the environment not in hex but by
3314 individual debug-tokens in long form.
3315 </p>
3316 </dd>
3317 <dt> <code>-m token(s)</code></dt>
3318 <dd><p>Remove (minus) the debug capabilities of token(s) from the current debug
3319 setting or from the selected tag (or <kbd>-d</kbd> value). Multiple <kbd>-m</kbd>
3320 options can be specified.
3321 </p>
3322 <a name="IDX342"></a>
3323 <a name="IDX343"></a>
3324 </dd>
3325 <dt> <code>-M limit</code></dt>
3326 <dd><p>Set the memory allocation limit which will abort the program if the
3327 total memory allocations exceed this number of bytes. The limit can
3328 be a number with a k, m, or g at the end to indicate kilobyte,
3329 megabyte, and gigabyte respectively. Ex: 100k, 200m, 1g. If the
3330 limit is exceeded, this will generate an <code>ERROR_OVER_LIMIT</code>
3331 error. See section <a href="#SEC16">Description of the Internal Error Codes</a>.
3332 </p>
3333 </dd>
3334 <dt> <code>-n</code></dt>
3335 <dd><p>Without changing the environment, output the commands resulting from the
3336 supplied options.
3337 </p>
3338 <a name="IDX344"></a>
3339 </dd>
3340 <dt> <code>-o times</code></dt>
3341 <dd><p>Set the &quot;lock-on&quot; period which dictates to the threaded version of
3342 the library to not initialize or lock the mutex lock around the library
3343 until after a certain number of allocation calls have been made. Some
3344 number between 2 and 30 is probably good. See the &quot;Using With
3345 Threads&quot; section for more information about the operation of the
3346 library with threads. See section <a href="#SEC24">Using the Library with a Thread Package</a>.
3347 </p>
3348 </dd>
3349 <dt> <code>-p token(s)</code></dt>
3350 <dd><p>Add (plus) the debug capabilities of token(s) to the current debug
3351 setting or to the selected tag (or <kbd>-d</kbd> value). Multiple <kbd>-p</kbd>
3352 options can be specified.
3353 </p>
3354 </dd>
3355 <dt> <code>-r</code></dt>
3356 <dd><p>Remove (unset) all settings when using a tag. This is useful when you
3357 are returning to a standard development tag and want the logfile,
3358 address, and interval settings to be cleared automatically. If you want
3359 this behavior by default, this can be put into the dmalloc alias.
3360 </p>
3361 </dd>
3362 <dt> <code>-R</code></dt>
3363 <dd><p>Output rc shell type commands. This is not for the runtime
3364 configuration file but for the rc shell program.
3365 </p>
3366 <a name="IDX345"></a>
3367 <a name="IDX346"></a>
3368 </dd>
3369 <dt> <code>-s file:line</code></dt>
3370 <dd><p>Set the <samp>`start'</samp> part of the <samp>`DMALLOC_OPTIONS'</samp> env variable to
3371 a file-name and line-number location in the source where the library
3372 should begin more extensive heap checking. The file and line numbers
3373 for heap transactions must be working for this option to be obeyed.
3374 This is used if you are trying to locate a problem and you want the
3375 extensive checking to not happen initially because it's too slow.
3376 </p>
3377 <a name="IDX347"></a>
3378 <a name="IDX348"></a>
3379 <a name="IDX349"></a>
3380 <a name="IDX350"></a>
3381 <a name="IDX351"></a>
3382 <a name="IDX352"></a>
3383 <a name="IDX353"></a>
3384 </dd>
3385 <dt> <code>-S number</code></dt>
3386 <dd><p>Set the <samp>`start'</samp> part of the <samp>`DMALLOC_OPTIONS'</samp> env variable to
3387 an dmalloc mark number. The library will begin more extensive heap
3388 checking after this number of memory transactions. If you
3389 <code>LOG_ITERATION</code> enabled in your <tt>`settings.h'</tt> file then
3390 the entries in the log file will be prepended with the number of memory
3391 transactions that the library has handled so far. This number can be
3392 used to delay the start of the fine grained heap checking which can be
3393 very slow.
3394 </p>
3395 <a name="IDX354"></a>
3396 <a name="IDX355"></a>
3397 </dd>
3398 <dt> <code>--start-size size</code></dt>
3399 <dd><p>Set the <samp>`start'</samp> part of the <samp>`DMALLOC_OPTIONS'</samp> env variable to
3400 a number of bytes. The library will begin more extensive heap checking
3401 after this amount of memory has been allocated by the library. This
3402 allows you to start the slow and detailed checking of the library later
3403 in the program execution. You can use patterns like 250m, 1g, or 102k
3404 to mean 250 megabytes, 1 gigabyte, and 102 kilobytes respectively.
3405 </p>
3406 </dd>
3407 <dt> <code>-t</code></dt>
3408 <dd><p>List all of the tags in the rc-file. Use with <kbd>-v</kbd> or <kbd>-V</kbd>
3409 verbose options.
3410 </p>
3411 </dd>
3412 <dt> <code>-u (or --usage)</code></dt>
3413 <dd><p>Output the usage information for the utility.
3414 </p>
3415 </dd>
3416 <dt> <code>-v</code></dt>
3417 <dd><p>Give verbose output. Especially useful when dumping current settings or
3418 listing all of the tags.
3419 </p>
3420 </dd>
3421 <dt> <code>-V</code></dt>
3422 <dd><p>Give very verbose output for outputting even more details about
3423 settings.
3424 </p>
3425 <a name="IDX356"></a>
3426 <a name="IDX357"></a>
3427 <a name="IDX358"></a>
3428 </dd>
3429 <dt> <code>--version</code></dt>
3430 <dd><p>Output the version string for the utility. <em>Please note</em> that
3431 the version of the library that is installed or has been linked into
3432 your application may be different from the utility version.
3433 </p>
3434 </dd>
3435 </dl>
3436
3437 <p>If no arguments are specified, dmalloc dumps out the current settings
3438 that you have for the environment variable. For example:
3439 </p>
3440 <table><tr><td>&nbsp;</td><td><pre class="example">Debug-Flags '0x40005c7' (runtime)
3441 Address 0x1f008, count = 3
3442 Interval 100
3443 Logpath 'malloc'
3444 Start-File not-set
3445 </pre></td></tr></table>
3446 <p>With a -v option and no arguments, dmalloc dumps out the current
3447 settings in a verbose manner. For example:
3448 </p>
3449 <table><tr><td>&nbsp;</td><td><pre class="example">Debug-Flags '0x40005c7' (runtime)
3450 log-stats, log-non-free, log-bad-space, check-fence, catch-null
3451 Address 0x1f008, count = 10
3452 Interval 100
3453 Logpath 'malloc'
3454 Start-File not-set
3455 </pre></td></tr></table>
3456 <p>Here are some examples of dmalloc usage:
3457 </p>
3458 <table><tr><td>&nbsp;</td><td><pre class="example"># start tough debugging, check the heap every 100 times,
3459 # send the log information to file 'logfile'
3460 dmalloc high -i 100 -l logfile
3461
3462 # find out what error code 20 is (from the logfile)
3463 dmalloc -e 20
3464
3465 # cause the library to halt itself when it sees the address 0x34238
3466 # for the 6th time.
3467 dmalloc -a 0x34238:6
3468
3469 # send the log information to file 'logfile' with the time in seconds
3470 # as an extension.
3471 dmalloc -l logfile.%t
3472
3473 # return to the normal 'runtime' settings and clear out all
3474 # other settings
3475 dmalloc -c runtime
3476
3477 # enable basic 'low' settings plus (-p) the logging of
3478 # transactions (log-trans) to file 'logfile'
3479 dmalloc low -p log-trans -l logfile
3480
3481 # print out the current settings with Very-verbose output
3482 dmalloc -V
3483
3484 # list the available debug malloc tokens with Very-verbose output
3485 dmalloc -DV
3486
3487 # list the available tags from the rc file with verbose output
3488 dmalloc -tv
3489 </pre></td></tr></table>
3490
3491 <hr size="6">
3492 <a name="Environment-Variable"></a>
3493 <a name="SEC32"></a>
3494 <table cellpadding="1" cellspacing="1" border="0">
3495 <tr><td valign="middle" align="left">[<a href="#SEC31" title="Previous section in reading order"> &lt; </a>]</td>
3496 <td valign="middle" align="left">[<a href="#SEC33" title="Next section in reading order"> &gt; </a>]</td>
3497 <td valign="middle" align="left"> &nbsp; </td>
3498 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3499 <td valign="middle" align="left">[<a href="#SEC29" title="Up section"> Up </a>]</td>
3500 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3501 <td valign="middle" align="left"> &nbsp; </td>
3502 <td valign="middle" align="left"> &nbsp; </td>
3503 <td valign="middle" align="left"> &nbsp; </td>
3504 <td valign="middle" align="left"> &nbsp; </td>
3505 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3506 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3507 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3508 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3509 </tr></table>
3510 <h2 class="section"> 4.3 Environment Variable Name and Features </h2>
3511
3512
3513 <p>An <em>environment variable</em> is a variable that is part of the user's
3514 working environment and is shared by all the programs. The
3515 <samp>`DMALLOC_OPTIONS'</samp> variable is used by the dmalloc library to
3516 enable or disable the memory debugging features, at runtime.
3517 <em>NOTE:</em> you can also use the <code>dmalloc_debug_setup</code> function
3518 to set the option string. It can be set either by hand or with the
3519 help of the dmalloc program. See section <a href="#SEC29">Dmalloc Utility Program</a>.
3520 </p>
3521 <a name="IDX359"></a>
3522
3523 <a name="IDX360"></a>
3524 <a name="IDX361"></a>
3525 <a name="IDX362"></a>
3526 <a name="IDX363"></a>
3527 <a name="IDX364"></a>
3528 <p>To set it by hand, Bourne shell (sh, bash, ksh, or zsh) users should use:
3529 </p>
3530 <table><tr><td>&nbsp;</td><td><pre class="example">DMALLOC_OPTIONS=value
3531 export DMALLOC_OPTIONS
3532 </pre></td></tr></table>
3533 <a name="IDX365"></a>
3534 <a name="IDX366"></a>
3535 <a name="IDX367"></a>
3536 <p>C shell (csh or tcsh) users need to invoke:
3537 </p>
3538 <table><tr><td>&nbsp;</td><td><pre class="example">setenv DMALLOC_OPTIONS value
3539 </pre></td></tr></table>
3540 <p>The value in the above examples is a comma separated list of tokens each
3541 having a corresponding value. The tokens are described below:
3542 </p>
3543 <dl compact="compact">
3544 <dt> <code>debug</code></dt>
3545 <dd><a name="IDX368"></a>
3546 <p>This should be set to a value in hexadecimal which corresponds to the
3547 functionality token values added together. See section <a href="#SEC33">Description of the Debugging Tokens</a>. For
3548 instance, if the user wanted to enable the logging of memory
3549 transactions (value <samp>`0x008'</samp>) and wanted to check fence-post memory
3550 (value <samp>`0x400'</samp>) then <samp>`debug'</samp> should be set to <samp>`0x408'</samp>
3551 (<samp>`0x008'</samp> + <samp>`0x400'</samp>).
3552 </p>
3553 <p><em>NOTE</em>: You don't have to worry about remembering all the hex
3554 values of the tokens because the dmalloc program automates the setting
3555 of this variable especially.
3556 </p>
3557 <a name="IDX369"></a>
3558
3559 <p><em>NOTE</em>: You can also specify the debug tokens directly, separated
3560 by commas. See section <a href="#SEC33">Description of the Debugging Tokens</a>. If <samp>`debug'</samp> and the tokens are
3561 both used, the token values will be added to the debug value.
3562 </p>
3563 </dd>
3564 <dt> <code>lockon</code></dt>
3565 <dd><a name="IDX370"></a>
3566 <p>Set this to a number which is the &quot;lock-on&quot; period. This dictates
3567 to the threaded version of the library to not initialize or lock the
3568 mutex lock around the library until after a certain number of allocation
3569 calls have been made. See the &quot;Using With Threads&quot; section for more
3570 information about the operation of the library with threads.
3571 See section <a href="#SEC24">Using the Library with a Thread Package</a>.
3572 </p>
3573 </dd>
3574 <dt> <code>log</code></dt>
3575 <dd><a name="IDX371"></a>
3576 <a name="IDX372"></a>
3577 <p>Set this to a filename so that if <samp>`debug'</samp> has logging enabled, the
3578 library can log transactions, administration information, and/or errors
3579 to the file so memory problems and usage can be tracked.
3580 </p>
3581 <p>To get different logfiles for different processes, you can assign
3582 <samp>`log'</samp> to a string with <code>%d</code> in it (for instance
3583 <samp>`logfile.%d'</samp>). This will be replaced with the pid of the running
3584 process (for instance <samp>`logfile.2451'</samp>).
3585 </p>
3586 <p><em>WARNING</em>: it is easy to core dump any program with dmalloc, if
3587 you send in a format with arguments other than the one <code>%d</code>.
3588 </p>
3589 </dd>
3590 <dt> <code>addr</code></dt>
3591 <dd><a name="IDX373"></a>
3592 <a name="IDX374"></a>
3593 <a name="IDX375"></a>
3594 <p>When this is set to a hex address (taken from the dmalloc log-file for
3595 instance) dmalloc will abort when it finds itself either allocating or
3596 freeing that address.
3597 </p>
3598 <p>The address can also have an <samp>`:number'</samp> argument. For instance, if
3599 it was set it to <samp>`0x3e45:10'</samp>, the library will kill itself the 10th
3600 time it sees address <samp>`0x3e45'</samp>. By setting the number argument to
3601 0, the program will never stop when it sees the address. This is useful
3602 for logging all activity on the address and makes it easier to track
3603 down specific addresses not being freed.
3604 </p>
3605 <p>This works well in conjunction with the <code>STORE_SEEN_COUNT</code> option.
3606 See section <a href="#SEC21">Tracking Down Non-Freed Memory</a>.
3607 </p>
3608 <p><em>NOTE</em>: dmalloc will also log all activity on this address along
3609 with a count.
3610 </p>
3611 </dd>
3612 <dt> <code>inter</code></dt>
3613 <dd><a name="IDX376"></a>
3614 <p>By setting this to a number X, dmalloc will only check the heap every X
3615 times. This means a number of debugging features can be enabled while
3616 still running the program within a finite amount of time.
3617 </p>
3618 <p>A setting of <samp>`100'</samp> works well with reasonably memory intensive
3619 programs. This of course means that the library will not catch errors
3620 exactly when they happen but possibly 100 library calls later.
3621 </p>
3622 </dd>
3623 <dt> <code>start</code></dt>
3624 <dd><a name="IDX377"></a>
3625 <p>Set this to a number X and dmalloc will begin checking the heap after X
3626 times. This means the intensive debugging can be started after a
3627 certain point in a program.
3628 </p>
3629 <p><samp>`start'</samp> also has the format <samp>`file:line'</samp>. For instance, if it
3630 is set to <samp>`dmalloc_t.c:126'</samp> dmalloc will start checking the heap
3631 after it sees a dmalloc call from the <tt>`dmalloc_t.c'</tt> file, line
3632 number 126. If you use <samp>`dmalloc_t.c:0'</samp>, with a 0 line number, then
3633 dmalloc will start checking the heap after it sees a call from anywhere
3634 in the <tt>`dmalloc_t.c'</tt> file.
3635 </p>
3636 <p>This allows the intensive debugging to be started after a certain
3637 routine or file has been reached in the program.
3638 </p></dd>
3639 </dl>
3640
3641 <p>Some examples are:
3642 </p>
3643 <table><tr><td>&nbsp;</td><td><pre class="example"># turn on transaction and stats logging and set
3644 # 'logfile' as the log-file
3645 setenv DMALLOC_OPTIONS log-trans,log-stats,log=logfile
3646
3647 # enable debug flags 0x1f as well as heap-checking and
3648 # set the interval to be 100
3649 setenv DMALLOC_OPTIONS debug=0x1f,check-heap,inter=100
3650
3651 # enable 'logfile' as the log-file, watch for
3652 # address '0x1234', and start checking when we see
3653 # file.c line 123
3654 setenv DMALLOC_OPTIONS log=logfile,addr=0x1234,start=file.c:123
3655 </pre></td></tr></table>
3656
3657 <hr size="6">
3658 <a name="Debug-Tokens"></a>
3659 <a name="SEC33"></a>
3660 <table cellpadding="1" cellspacing="1" border="0">
3661 <tr><td valign="middle" align="left">[<a href="#SEC32" title="Previous section in reading order"> &lt; </a>]</td>
3662 <td valign="middle" align="left">[<a href="#SEC34" title="Next section in reading order"> &gt; </a>]</td>
3663 <td valign="middle" align="left"> &nbsp; </td>
3664 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3665 <td valign="middle" align="left">[<a href="#SEC29" title="Up section"> Up </a>]</td>
3666 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3667 <td valign="middle" align="left"> &nbsp; </td>
3668 <td valign="middle" align="left"> &nbsp; </td>
3669 <td valign="middle" align="left"> &nbsp; </td>
3670 <td valign="middle" align="left"> &nbsp; </td>
3671 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3672 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3673 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3674 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3675 </tr></table>
3676 <h2 class="section"> 4.4 Description of the Debugging Tokens </h2>
3677
3678
3679 <p>The below tokens and their corresponding descriptions are for the
3680 setting of the debug library setting in the environment variable.
3681 See section <a href="#SEC32">Environment Variable Name and Features</a>. They should be specified in the user's
3682 <tt>`.dmallocrc'</tt> file. See section <a href="#SEC34">Format of the Runtime Configuration File</a>.
3683 </p>
3684 <p>Each token, when specified, enables a specific debugging feature. For
3685 instance, if you have the <code>log-stats</code> token enabled, the library
3686 will log general statistics to the logfile.
3687 </p>
3688 <p>To get this information on the fly, use <kbd>dmalloc -DV</kbd>. This will
3689 print out the Debug tokens in Very-verbose mode. See section <a href="#SEC29">Dmalloc Utility Program</a>.
3690 </p>
3691 <dl compact="compact">
3692 <dd><a name="IDX378"></a>
3693 </dd>
3694 <dt> <code>none</code></dt>
3695 <dd><p>No debugging functionality
3696 </p>
3697 <a name="IDX379"></a>
3698 </dd>
3699 <dt> <code>log-stats</code></dt>
3700 <dd><p>Log general statistics when dmalloc_shutdown or dmalloc_log_stats is
3701 called.
3702 </p>
3703 <a name="IDX380"></a>
3704 </dd>
3705 <dt> <code>log-non-free</code></dt>
3706 <dd><p>Log non-freed memory pointers when dmalloc_shutdown or dmalloc_log_unfreed
3707 is called.
3708 </p>
3709 <a name="IDX381"></a>
3710 </dd>
3711 <dt> <code>log-known</code></dt>
3712 <dd><p>Log only known memory pointers that have not been freed. Pointers which
3713 do not have file/line or return-address information will not be logged.
3714 </p>
3715 <a name="IDX382"></a>
3716 </dd>
3717 <dt> <code>log-trans</code></dt>
3718 <dd><p>Log general memory transactions (quite verbose).
3719 </p>
3720 <a name="IDX383"></a>
3721 </dd>
3722 <dt> <code>log-admin</code></dt>
3723 <dd><p>Log administrative information (quite verbose).
3724 </p>
3725 <a name="IDX384"></a>
3726 </dd>
3727 <dt> <code>log-bad-space</code></dt>
3728 <dd><p>Log actual bytes in and around bad pointers.
3729 </p>
3730 <a name="IDX385"></a>
3731 </dd>
3732 <dt> <code>log-nonfree-space</code></dt>
3733 <dd><p>Log actual bytes in non-freed pointers.
3734 </p>
3735 <a name="IDX386"></a>
3736 </dd>
3737 <dt> <code>log-elapsed-time</code></dt>
3738 <dd><p>Log elapsed-time for allocated pointers (see <tt>`conf.h'</tt>).
3739 </p>
3740 <a name="IDX387"></a>
3741 </dd>
3742 <dt> <code>log-current-time</code></dt>
3743 <dd><p>Log current-time for allocated pointers (see <tt>`conf.h'</tt>).
3744 </p>
3745 <a name="IDX388"></a>
3746 </dd>
3747 <dt> <code>check-fence</code></dt>
3748 <dd><p>Check fence-post memory areas.
3749 </p>
3750 <a name="IDX389"></a>
3751 </dd>
3752 <dt> <code>check-heap</code></dt>
3753 <dd><p>Verify heap administrative structure.
3754 </p>
3755 <a name="IDX390"></a>
3756 </dd>
3757 <dt> <code>check-blank</code></dt>
3758 <dd><p>Check to see if space that was blanked when a pointer was allocated or
3759 when it was freed has been overwritten. If this is enabled then it
3760 will enable <code>free-blank</code> and <code>alloc-blank</code> automatically.
3761 </p>
3762 <a name="IDX391"></a>
3763 </dd>
3764 <dt> <code>check-funcs</code></dt>
3765 <dd><p>Check the arguments of some functions (mostly string operations) looking
3766 for bad pointers.
3767 </p>
3768 <a name="IDX392"></a>
3769 </dd>
3770 <dt> <code>check-shutdown</code></dt>
3771 <dd><p>Check all of the pointers in the heap when the program exits.
3772 </p>
3773 <a name="IDX393"></a>
3774 <a name="IDX394"></a>
3775 <a name="IDX395"></a>
3776 <a name="IDX396"></a>
3777 <a name="IDX397"></a>
3778 <a name="IDX398"></a>
3779 <a name="IDX399"></a>
3780 <a name="IDX400"></a>
3781 <a name="IDX401"></a>
3782 </dd>
3783 <dt> <code>catch-signals</code></dt>
3784 <dd><p>Shutdown the library automatically on SIGHUP, SIGINT, or SIGTERM. This
3785 will cause the library to dump its statistics (if requested) when you
3786 press control-c on the program (for example).
3787 </p>
3788 <a name="IDX402"></a>
3789 </dd>
3790 <dt> <code>realloc-copy</code></dt>
3791 <dd><p>Always copy data to a new pointer when realloc.
3792 </p>
3793 <a name="IDX403"></a>
3794 <a name="IDX404"></a>
3795 <a name="IDX405"></a>
3796 <a name="IDX406"></a>
3797 <a name="IDX407"></a>
3798 <a name="IDX408"></a>
3799 <a name="IDX409"></a>
3800 <a name="IDX410"></a>
3801 <a name="IDX411"></a>
3802 <a name="IDX412"></a>
3803 <a name="IDX413"></a>
3804 <a name="IDX414"></a>
3805 <a name="IDX415"></a>
3806 <a name="IDX416"></a>
3807 </dd>
3808 <dt> <code>free-blank</code></dt>
3809 <dd><p>Write special &quot;dmalloc-free&quot; byte (hexadecimal <code>0xdf</code>, octal
3810 <code>0337</code>, decimal <code>223</code>) into space when it is freed. You can
3811 set this to be something else in the <tt>`settings.dist'</tt> file. This
3812 ensures that your program is not using memory after it has been freed.
3813 You can check to see if areas have been improperly overwritten with
3814 the <code>check-blank</code> token. If the free space has been overwritten,
3815 then <code>ERROR_FREE_OVERWRITTEN</code> is triggered. See section <a href="#SEC16">Description of the Internal Error Codes</a>.
3816 </p>
3817 <a name="IDX417"></a>
3818 <a name="IDX418"></a>
3819 <a name="IDX419"></a>
3820 </dd>
3821 <dt> <code>error-abort</code></dt>
3822 <dd><p>Abort the program (and dump core) on errors. See <code>error-dump</code>
3823 below. See section <a href="#SEC14">Generating a Core File on Errors</a>.
3824 </p>
3825 <a name="IDX420"></a>
3826 <a name="IDX421"></a>
3827 <a name="IDX422"></a>
3828 <a name="IDX423"></a>
3829 <a name="IDX424"></a>
3830 <a name="IDX425"></a>
3831 <a name="IDX426"></a>
3832 <a name="IDX427"></a>
3833 <a name="IDX428"></a>
3834 <a name="IDX429"></a>
3835 <a name="IDX430"></a>
3836 <a name="IDX431"></a>
3837 <a name="IDX432"></a>
3838 </dd>
3839 <dt> <code>alloc-blank</code></dt>
3840 <dd><p>Write special &quot;dmalloc-alloc&quot; byte (hexadecimal <code>0xda</code>, octal
3841 <code>0332</code>, decimal <code>218</code>) into space when it is allocated. You
3842 can set this to be something else in the <tt>`settings.dist'</tt> file.
3843 If you are not using <code>calloc</code> this will overwrite the user space
3844 with the special bytes ensuring that your program is initializing its
3845 dynamic memory appropriately. Also, if you ask for 35 bytes and the
3846 library has to give you a block of 64 because of rounding issues, it
3847 will overwrite the extra memory with the special byte. You can then
3848 check to see if the extra areas have been improperly overwritten by
3849 enabling the <code>check-blank</code> token.
3850 </p>
3851 <a name="IDX433"></a>
3852 </dd>
3853 <dt> <code>print-messages</code></dt>
3854 <dd><p>Log any errors and messages to the screen via standard-error.
3855 </p>
3856 <a name="IDX434"></a>
3857 <a name="IDX435"></a>
3858 <a name="IDX436"></a>
3859 </dd>
3860 <dt> <code>catch-null</code></dt>
3861 <dd><p>Abort the program immediately if the library fails to get more heap
3862 space from the heap allocation routine <code>mmap</code> or <code>sbrk</code>.
3863 </p>
3864 <a name="IDX437"></a>
3865 </dd>
3866 <dt> <code>never-reuse</code></dt>
3867 <dd><p>Have the heap never use space that has been used before and freed.
3868 See section <a href="#SEC21">Tracking Down Non-Freed Memory</a>. <em>WARNING</em>: This should be used with caution
3869 since you may run out of heap space.
3870 </p>
3871 <a name="IDX438"></a>
3872 <a name="IDX439"></a>
3873 <a name="IDX440"></a>
3874 </dd>
3875 <dt> <code>error-dump</code></dt>
3876 <dd><p>Dump core on error and then continue. Later core dumps overwrite
3877 earlier ones if the program encounters more than one error. See
3878 <code>error-abort</code> above. See section <a href="#SEC14">Generating a Core File on Errors</a>.
3879 </p>
3880 <p><em>NOTE</em>: This will only work if your system supports the <code>fork</code>
3881 system call and the configuration utility was able to fork without going
3882 recursive.
3883 </p>
3884 <a name="IDX441"></a>
3885 <a name="IDX442"></a>
3886 <a name="IDX443"></a>
3887
3888 </dd>
3889 <dt> <code>error-free-null</code></dt>
3890 <dd><p>By default the library will not generate an error when a program tries
3891 to free a NULL pointer. By enabling this token, you can change this
3892 behavior so an error is reported. See also the ALLOW_FREE_NULL and
3893 ALLOW_FREE_NULL_MESSAGE settings in the <tt>`settings.h'</tt> file to change
3894 the default behavior.
3895 </p>
3896 </dd>
3897 </dl>
3898
3899
3900 <hr size="6">
3901 <a name="RC-File"></a>
3902 <a name="SEC34"></a>
3903 <table cellpadding="1" cellspacing="1" border="0">
3904 <tr><td valign="middle" align="left">[<a href="#SEC33" title="Previous section in reading order"> &lt; </a>]</td>
3905 <td valign="middle" align="left">[<a href="#SEC35" title="Next section in reading order"> &gt; </a>]</td>
3906 <td valign="middle" align="left"> &nbsp; </td>
3907 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
3908 <td valign="middle" align="left">[<a href="#SEC29" title="Up section"> Up </a>]</td>
3909 <td valign="middle" align="left">[<a href="#SEC35" title="Next chapter"> &gt;&gt; </a>]</td>
3910 <td valign="middle" align="left"> &nbsp; </td>
3911 <td valign="middle" align="left"> &nbsp; </td>
3912 <td valign="middle" align="left"> &nbsp; </td>
3913 <td valign="middle" align="left"> &nbsp; </td>
3914 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
3915 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
3916 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
3917 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
3918 </tr></table>
3919 <h2 class="section"> 4.5 Format of the Runtime Configuration File </h2>
3920
3921
3922 <p>By using a <em>RC File</em> (or runtime configuration file) you can alias
3923 tags to combinations of debug tokens. See section <a href="#SEC33">Description of the Debugging Tokens</a>.
3924 </p>
3925 <p><em>NOTE</em>: For beginning users, the dmalloc program has a couple of
3926 tags built into it so it is not necessary for you to setup a RC file:
3927 </p>
3928 <dl compact="compact">
3929 <dd><a name="IDX444"></a>
3930 <a name="IDX445"></a>
3931 </dd>
3932 <dt> <code>runtime</code></dt>
3933 <dd><p>Enables basic runtime tests including fence-post checking, null handling,
3934 and logging of any errors.
3935 </p>
3936 <a name="IDX446"></a>
3937 <a name="IDX447"></a>
3938 </dd>
3939 <dt> <code>low</code></dt>
3940 <dd><p>Runtime settings plus minimal checking of heap structures and
3941 overwriting of allocated and freed space.
3942 </p>
3943 <a name="IDX448"></a>
3944 <a name="IDX449"></a>
3945 </dd>
3946 <dt> <code>medium</code></dt>
3947 <dd><p>Low settings plus checking of all heap structures on each memory call,
3948 always relocates block on realloc, and aborts on errors. You may want
3949 to use <kbd>-i</kbd> option to the dmalloc utility. See section <a href="#SEC29">Dmalloc Utility Program</a>.
3950 </p>
3951 <a name="IDX450"></a>
3952 <a name="IDX451"></a>
3953 </dd>
3954 <dt> <code>high</code></dt>
3955 <dd><p>Medium settings plus checking of overwritten freed and allocated
3956 memory and checking of arguments to a number of common functions. You
3957 may want to use <kbd>-i</kbd> option to the dmalloc utility. See section <a href="#SEC29">Dmalloc Utility Program</a>.
3958 </p>
3959 </dd>
3960 </dl>
3961
3962 <p>For expert users, a sample <tt>`dmallocrc'</tt> file has been provided but
3963 you are encouraged to roll your own combinations. The name of default
3964 rc-file is <tt>`$HOME/.dmallocrc'</tt>. The <samp>`$HOME'</samp> environment
3965 variable should be set by the system to point to your home-directory.
3966 </p>
3967 <p>The file should contain lines in the general form of:
3968 </p>
3969 <table><tr><td>&nbsp;</td><td><pre class="example">tag token1, token2, &hellip;
3970 </pre></td></tr></table>
3971 <p><samp>`tag'</samp> is to be matched with the tag argument passed to the dmalloc
3972 program, while <samp>`token1, token2, &hellip;'</samp> are debug capability
3973 tokens. See section <a href="#SEC29">Dmalloc Utility Program</a>, <a href="#SEC33">Description of the Debugging Tokens</a>.
3974 </p>
3975 <p>A line can be finished with a <samp>`\'</samp> meaning it continues onto the
3976 next line. Lines beginning with <samp>`#'</samp> are treated as comments and
3977 are ignored along with empty lines.
3978 </p>
3979 <p>Here is an example of a <tt>`.dmallocrc'</tt> file:
3980 </p>
3981 <table><tr><td>&nbsp;</td><td><pre class="example">#
3982 # Dmalloc runtime configuration file for the debug malloc library
3983 #
3984
3985 # no debugging
3986 none none
3987
3988 # basic debugging
3989 debug1 log-stats, log-non-free, check-fence
3990
3991 # more logging and some heap checking
3992 debug2 log-stats, log-non-free, log-trans, \
3993 check-fence, check-heap, error-abort
3994
3995 # good utilities
3996 debug3 log-stats, log-non-free, log-trans, \
3997 log-admin, check-fence, check-heap, realloc-copy, \
3998 free-blank, error-abort
3999
4000 &hellip;
4001 </pre></td></tr></table>
4002 <p>For example, with the above file installed, you can type <code>dmalloc
4003 debug1</code> after setting up your shell alias. See section <a href="#SEC29">Dmalloc Utility Program</a>.
4004 This enables the logging of statistics, the logging of non-freed memory,
4005 and the checking of fence-post memory areas.
4006 </p>
4007 <p>Enter <code>dmalloc none</code> to disable all memory debugging features.
4008 </p>
4009
4010 <hr size="6">
4011 <a name="Source-Code"></a>
4012 <a name="SEC35"></a>
4013 <table cellpadding="1" cellspacing="1" border="0">
4014 <tr><td valign="middle" align="left">[<a href="#SEC34" title="Previous section in reading order"> &lt; </a>]</td>
4015 <td valign="middle" align="left">[<a href="#SEC36" title="Next section in reading order"> &gt; </a>]</td>
4016 <td valign="middle" align="left"> &nbsp; </td>
4017 <td valign="middle" align="left">[<a href="#SEC29" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4018 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
4019 <td valign="middle" align="left">[<a href="#SEC39" title="Next chapter"> &gt;&gt; </a>]</td>
4020 <td valign="middle" align="left"> &nbsp; </td>
4021 <td valign="middle" align="left"> &nbsp; </td>
4022 <td valign="middle" align="left"> &nbsp; </td>
4023 <td valign="middle" align="left"> &nbsp; </td>
4024 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4025 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4026 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4027 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4028 </tr></table>
4029 <h1 class="chapter"> 5. Information on the Source Code </h1>
4030
4031
4032 <table class="menu" border="0" cellspacing="0">
4033 <tr><td align="left" valign="top"><a href="#SEC36">5.1 Definition of Terms and other Information</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Definition of terms and other information.
4034 </td></tr>
4035 <tr><td align="left" valign="top"><a href="#SEC37">5.2 General Compatibility Concerns</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> General compatibility concerns.
4036 </td></tr>
4037 <tr><td align="left" valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> Issues important for porting the library.
4038 </td></tr>
4039 </table>
4040
4041
4042 <hr size="6">
4043 <a name="Definitions"></a>
4044 <a name="SEC36"></a>
4045 <table cellpadding="1" cellspacing="1" border="0">
4046 <tr><td valign="middle" align="left">[<a href="#SEC35" title="Previous section in reading order"> &lt; </a>]</td>
4047 <td valign="middle" align="left">[<a href="#SEC37" title="Next section in reading order"> &gt; </a>]</td>
4048 <td valign="middle" align="left"> &nbsp; </td>
4049 <td valign="middle" align="left">[<a href="#SEC35" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4050 <td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up </a>]</td>
4051 <td valign="middle" align="left">[<a href="#SEC39" title="Next chapter"> &gt;&gt; </a>]</td>
4052 <td valign="middle" align="left"> &nbsp; </td>
4053 <td valign="middle" align="left"> &nbsp; </td>
4054 <td valign="middle" align="left"> &nbsp; </td>
4055 <td valign="middle" align="left"> &nbsp; </td>
4056 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4057 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4058 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4059 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4060 </tr></table>
4061 <h2 class="section"> 5.1 Definition of Terms and other Information </h2>
4062
4063
4064 <p>Here are a couple definitions and other information for those interested
4065 in &quot;picking the brain&quot; of the library. The code is a little ugly here
4066 and there and it conforms to the Gray-Watson handbook of coding
4067 standards only.
4068 </p>
4069 <dl compact="compact">
4070 <dt> <em>bblock</em></dt>
4071 <dd><p>basic block containing 2 ^ BASIC_BLOCK bytes of info
4072 </p>
4073 </dd>
4074 <dt> <em>bblock_adm</em></dt>
4075 <dd><p>administration for a set of basic blocks
4076 </p>
4077 </dd>
4078 <dt> <em>dblock</em></dt>
4079 <dd><p>divided block containing some base 2 number of blocks smaller than a
4080 basic block.
4081 </p>
4082 </dd>
4083 <dt> <em>dblock_adm</em></dt>
4084 <dd><p>administration for a set of divided blocks
4085 </p>
4086 </dd>
4087 <dt> <em>chunk</em></dt>
4088 <dd><p>some anonymous amount of memory
4089 </p></dd>
4090 </dl>
4091
4092 <p>For more information about administration structures, see the code and
4093 comments from <tt>`chunk_loc.h'</tt>.
4094 </p>
4095
4096 <hr size="6">
4097 <a name="Compatibility"></a>
4098 <a name="SEC37"></a>
4099 <table cellpadding="1" cellspacing="1" border="0">
4100 <tr><td valign="middle" align="left">[<a href="#SEC36" title="Previous section in reading order"> &lt; </a>]</td>
4101 <td valign="middle" align="left">[<a href="#SEC38" title="Next section in reading order"> &gt; </a>]</td>
4102 <td valign="middle" align="left"> &nbsp; </td>
4103 <td valign="middle" align="left">[<a href="#SEC35" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4104 <td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up </a>]</td>
4105 <td valign="middle" align="left">[<a href="#SEC39" title="Next chapter"> &gt;&gt; </a>]</td>
4106 <td valign="middle" align="left"> &nbsp; </td>
4107 <td valign="middle" align="left"> &nbsp; </td>
4108 <td valign="middle" align="left"> &nbsp; </td>
4109 <td valign="middle" align="left"> &nbsp; </td>
4110 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4111 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4112 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4113 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4114 </tr></table>
4115 <h2 class="section"> 5.2 General Compatibility Concerns </h2>
4116
4117
4118 <ul>
4119 <li>
4120 Realloc() backwards compatibility with being able to realloc from the
4121 last freed block is <em>not</em> supported. The author is interested to
4122 know who is using this (cough, cough) feature and for what reason.
4123
4124 <a name="IDX452"></a>
4125
4126 </li><li>
4127 Realloc() of a NULL pointer is supported in which case the library
4128 will just make a call to malloc(). This can be disabled with the help
4129 of the <code>ALLOW_REALLOC_NULL</code> manual compilation option in the
4130 <tt>`settings.h'</tt> file to adjust the library's default behavior.
4131
4132 <a name="IDX453"></a>
4133
4134 </li><li>
4135 Some systems allow free(0) to not be an error for some reason. Since
4136 0 is not a valid address returned by the malloc call, it is debatable
4137 that this should be allowed. See <tt>`settings.h'</tt> for the
4138 <code>ALLOW_FREE_NULL</code> manual compilation option to adjust the
4139 library's default behavior.
4140
4141 </li><li>
4142 Aside from possibly being slower than the system's memory allocation
4143 functions, the library should be fully compatible with the standard
4144 memory routines. If this is <em>not</em> the case, please bring this to
4145 my attention.
4146 </li></ul>
4147
4148
4149 <hr size="6">
4150 <a name="Portability"></a>
4151 <a name="SEC38"></a>
4152 <table cellpadding="1" cellspacing="1" border="0">
4153 <tr><td valign="middle" align="left">[<a href="#SEC37" title="Previous section in reading order"> &lt; </a>]</td>
4154 <td valign="middle" align="left">[<a href="#SEC39" title="Next section in reading order"> &gt; </a>]</td>
4155 <td valign="middle" align="left"> &nbsp; </td>
4156 <td valign="middle" align="left">[<a href="#SEC35" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4157 <td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up </a>]</td>
4158 <td valign="middle" align="left">[<a href="#SEC39" title="Next chapter"> &gt;&gt; </a>]</td>
4159 <td valign="middle" align="left"> &nbsp; </td>
4160 <td valign="middle" align="left"> &nbsp; </td>
4161 <td valign="middle" align="left"> &nbsp; </td>
4162 <td valign="middle" align="left"> &nbsp; </td>
4163 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4164 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4165 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4166 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4167 </tr></table>
4168 <h2 class="section"> 5.3 Issues Important for Porting the Library </h2>
4169
4170
4171 <p>General portability issues center around:
4172 </p>
4173 <ul>
4174 <li>
4175 <a name="IDX454"></a>
4176 <a name="IDX455"></a>
4177 <a name="IDX456"></a>
4178 <a name="IDX457"></a>
4179 mmap, sbrk, or compatible function usages. The library does support a
4180 preallocated memory chunk heap. See the <code>INTERNAL_MEMORY_SPACE</code>
4181 define in the <tt>`settings.dist'</tt> file.
4182
4183 </li><li>
4184 <a name="IDX458"></a>
4185 The locating of the caller's address from the dmalloc functions.
4186 This is useful in locating problems from dmalloc functions called from C
4187 files which did not include <tt>`dmalloc.h'</tt>: C library calls for
4188 instance.
4189
4190 <a name="IDX459"></a>
4191 <p>See <tt>`return.h'</tt> for the available architecture/compiler
4192 combinations. You may want to examine the assembly code from gcc (GNUs
4193 superior c-compiler) version 2+ being run on the following code. It
4194 should give you a good start on building a hack for your box.
4195 </p>
4196 <table><tr><td>&nbsp;</td><td><pre class="example">static char * x;
4197
4198 a()
4199 {
4200 x = __builtin_return_address(0);
4201 }
4202
4203 main()
4204 {
4205 a();
4206 }
4207 </pre></td></tr></table>
4208 </li></ul>
4209
4210
4211 <hr size="6">
4212 <a name="Troubleshooting"></a>
4213 <a name="SEC39"></a>
4214 <table cellpadding="1" cellspacing="1" border="0">
4215 <tr><td valign="middle" align="left">[<a href="#SEC38" title="Previous section in reading order"> &lt; </a>]</td>
4216 <td valign="middle" align="left">[<a href="#SEC40" title="Next section in reading order"> &gt; </a>]</td>
4217 <td valign="middle" align="left"> &nbsp; </td>
4218 <td valign="middle" align="left">[<a href="#SEC35" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4219 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
4220 <td valign="middle" align="left">[<a href="#SEC40" title="Next chapter"> &gt;&gt; </a>]</td>
4221 <td valign="middle" align="left"> &nbsp; </td>
4222 <td valign="middle" align="left"> &nbsp; </td>
4223 <td valign="middle" align="left"> &nbsp; </td>
4224 <td valign="middle" align="left"> &nbsp; </td>
4225 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4226 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4227 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4228 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4229 </tr></table>
4230 <h1 class="chapter"> 6. Some Solutions to Common Problems </h1>
4231
4232
4233 <p>This section provides some answers to some common problems and
4234 questions. Please send me mail with any additions to
4235 this list - either problems you are still having or tips that you would
4236 like to pass on.
4237 </p>
4238 <p>When diagnosing a problem, if possible, always make sure you are running
4239 the most up to date version of Dmalloc available from the home page at
4240 URL <a href="http://dmalloc.com/">http://dmalloc.com/</a>. Problems are often fixed and a new
4241 release can be published before people encounter them.
4242 </p>
4243 <dl compact="compact">
4244 <dd>
4245 <a name="IDX460"></a>
4246 <a name="IDX461"></a>
4247 <a name="IDX462"></a>
4248 <a name="IDX463"></a>
4249 <a name="IDX464"></a>
4250 </dd>
4251 <dt> <samp>`Why does my program run so slow?'</samp></dt>
4252 <dd>
4253 <a name="IDX465"></a>
4254 <p>This library has never been (and maybe never will be) optimized for
4255 space nor speed. Some of its features make it unable to use some of
4256 the organizational methods of other more efficient heap libraries.
4257 </p>
4258 <p>If you have the <code>check-heap</code> token enabled, your program might
4259 run slow or seem to hang. This is because by default, the library
4260 will run a full check of the heap with every memory allocation or
4261 free. You can have the library check itself less frequently by using
4262 the <kbd>-i</kbd> option to the dmalloc utility. See section <a href="#SEC29">Dmalloc Utility Program</a>.
4263 If you are using the <kbd>high</kbd> token and you need your program to run
4264 faster, try the <kbd>medium</kbd> or <kbd>low</kbd> tokens which don't check as
4265 many heap features and so run faster although they will not catch as
4266 many problems. See section <a href="#SEC34">Format of the Runtime Configuration File</a>.
4267 </p>
4268 <a name="IDX466"></a>
4269 <a name="IDX467"></a>
4270 </dd>
4271 <dt> <samp>`Why was a log-file not produced after I ran my program?'</samp></dt>
4272 <dd>
4273 <p>This could be caused by a number of different problems.
4274 </p>
4275 <ol>
4276 <li> Are you sure you followed all of the items in the &quot;Getting Started&quot;
4277 section? Please review them if there is any doubt. See section <a href="#SEC4">Getting Started with the Library</a>.
4278
4279 <a name="IDX468"></a>
4280 <a name="IDX469"></a>
4281 <a name="IDX470"></a>
4282
4283 </li><li> Use the <kbd>env</kbd> or <kbd>printenv</kbd> commands to make sure that
4284 the <samp>`DMALLOC_OPTIONS'</samp> variable is set in your exported environment.
4285 See section <a href="#SEC32">Environment Variable Name and Features</a>.
4286
4287 <a name="IDX471"></a>
4288 <a name="IDX472"></a>
4289
4290 </li><li> Make sure that your program has been compiled correctly with the
4291 dmalloc library. The <kbd>ident</kbd> program should show chunk.c and other
4292 dmalloc files compiled into your program. You can also do <kbd>strings
4293 -a your-program | grep chunk.c</kbd> and look for something like <samp>`$Id:
4294 chunk.c,v 1.152 1999/08/25 12:37:01 gray Exp $'</samp> with different versions
4295 and date information. If this doesn't show up then chances are dmalloc
4296 was not linked into your program.
4297
4298 </li><li> If your program changes its working directory, it may write the
4299 dmalloc log-file somewhere else in the filesystem. You will need to
4300 check both where the program was started and to where it might change
4301 directory.
4302
4303 </li><li> The logfile is only produced when <code>dmalloc_shutdown()</code> is
4304 called. By default it will be called when <code>exit()</code> gets called.
4305 If you are running your program and press <kbd>Control-C</kbd> under Unix
4306 the program will stop immediately and <code>dmalloc_shutdown()</code> will
4307 not get called. You can either setup a signal handler for
4308 <code>SIGINTR</code> and call exit yourself, or you can enable the
4309 <code>catch-signals</code> token. See section <a href="#SEC33">Description of the Debugging Tokens</a>.
4310
4311 </li><li> If your program is segfaulting or otherwise crashing when it exits, the
4312 <code>exit()</code> routine may not being called. You will have to resolve
4313 these issues so the dmalloc library can gracefully exit and write its
4314 log file.
4315
4316 </li><li> You may want to call <code>dmalloc_log_stats()</code> and
4317 <code>dmalloc_log_unfreed()</code> (or <code>dmalloc_log_changed()</code>) directly
4318 to have the library write its log file. Some system modules may not
4319 have shutdown if you call this before <code>exit()</code> so extra unfreed
4320 memory may be reported.
4321
4322 </li></ol>
4323
4324 </dd>
4325 <dt> <samp>`I don't see any information about my non-freed (leaked) memory?'</samp></dt>
4326 <dd>
4327 <p>The library will not (by default) report on &quot;unknown&quot; non-freed
4328 memory. Unknown means memory that does not have associated file and
4329 line information.
4330 </p>
4331 <p>This will be necessary if you are <em>not</em>
4332 including <tt>`dmalloc.h'</tt> in all of your C files or if you are
4333 interested in tracking leaks in system functions.
4334 </p>
4335 </dd>
4336 <dt> <samp>`Dmalloc is returning the error &quot;malloc library has gone recursive&quot;'</samp></dt>
4337 <dd>
4338 <p>This most likely indicates that you are using the Dmalloc library within
4339 a threaded application and two threads are trying to use the dmalloc
4340 library at once. Please see the section of the manual about threads for
4341 more information about properly configuring the library. See section <a href="#SEC24">Using the Library with a Thread Package</a>.
4342 </p>
4343 <p>If you are not using threads, then your program could have caught a
4344 signal while within Dmalloc, which then in turn called a memory
4345 allocation routine. It is unwise to allocate memory on the heap in most
4346 signal handlers. Lastly, some functions called by the library may call
4347 memory routines that it does not anticipate. If you think this the
4348 case, please report the problem and include a stack trace, operating
4349 system version/type, and the version of Dmalloc you are using.
4350 </p>
4351 </dd>
4352 </dl>
4353
4354
4355 <hr size="6">
4356 <a name="Index-of-Concepts"></a>
4357 <a name="SEC40"></a>
4358 <table cellpadding="1" cellspacing="1" border="0">
4359 <tr><td valign="middle" align="left">[<a href="#SEC39" title="Previous section in reading order"> &lt; </a>]</td>
4360 <td valign="middle" align="left">[ &gt; ]</td>
4361 <td valign="middle" align="left"> &nbsp; </td>
4362 <td valign="middle" align="left">[<a href="#SEC39" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
4363 <td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up </a>]</td>
4364 <td valign="middle" align="left">[ &gt;&gt; ]</td>
4365 <td valign="middle" align="left"> &nbsp; </td>
4366 <td valign="middle" align="left"> &nbsp; </td>
4367 <td valign="middle" align="left"> &nbsp; </td>
4368 <td valign="middle" align="left"> &nbsp; </td>
4369 <td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
4370 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
4371 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
4372 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
4373 </tr></table>
4374 <h1 class="unnumbered"> Index of Concepts </h1>
4375
4376 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a href="#SEC40_0" class="summary-letter"><b>%</b></a>
4377 &nbsp;
4378 <a href="#SEC40_1" class="summary-letter"><b>-</b></a>
4379 &nbsp;
4380 <a href="#SEC40_2" class="summary-letter"><b>.</b></a>
4381 &nbsp;
4382 <a href="#SEC40_3" class="summary-letter"><b>0</b></a>
4383 &nbsp;
4384 <a href="#SEC40_4" class="summary-letter"><b>1</b></a>
4385 &nbsp;
4386 <a href="#SEC40_5" class="summary-letter"><b>2</b></a>
4387 &nbsp;
4388 <a href="#SEC40_6" class="summary-letter"><b>3</b></a>
4389 &nbsp;
4390 <a href="#SEC40_7" class="summary-letter"><b>4</b></a>
4391 &nbsp;
4392 <a href="#SEC40_8" class="summary-letter"><b>6</b></a>
4393 &nbsp;
4394 <a href="#SEC40_9" class="summary-letter"><b>7</b></a>
4395 &nbsp;
4396 <br>
4397 <a href="#SEC40_10" class="summary-letter"><b>A</b></a>
4398 &nbsp;
4399 <a href="#SEC40_11" class="summary-letter"><b>B</b></a>
4400 &nbsp;
4401 <a href="#SEC40_12" class="summary-letter"><b>C</b></a>
4402 &nbsp;
4403 <a href="#SEC40_13" class="summary-letter"><b>D</b></a>
4404 &nbsp;
4405 <a href="#SEC40_14" class="summary-letter"><b>E</b></a>
4406 &nbsp;
4407 <a href="#SEC40_15" class="summary-letter"><b>F</b></a>
4408 &nbsp;
4409 <a href="#SEC40_16" class="summary-letter"><b>G</b></a>
4410 &nbsp;
4411 <a href="#SEC40_17" class="summary-letter"><b>H</b></a>
4412 &nbsp;
4413 <a href="#SEC40_18" class="summary-letter"><b>I</b></a>
4414 &nbsp;
4415 <a href="#SEC40_19" class="summary-letter"><b>J</b></a>
4416 &nbsp;
4417 <a href="#SEC40_20" class="summary-letter"><b>K</b></a>
4418 &nbsp;
4419 <a href="#SEC40_21" class="summary-letter"><b>L</b></a>
4420 &nbsp;
4421 <a href="#SEC40_22" class="summary-letter"><b>M</b></a>
4422 &nbsp;
4423 <a href="#SEC40_23" class="summary-letter"><b>N</b></a>
4424 &nbsp;
4425 <a href="#SEC40_24" class="summary-letter"><b>O</b></a>
4426 &nbsp;
4427 <a href="#SEC40_25" class="summary-letter"><b>P</b></a>
4428 &nbsp;
4429 <a href="#SEC40_26" class="summary-letter"><b>Q</b></a>
4430 &nbsp;
4431 <a href="#SEC40_27" class="summary-letter"><b>R</b></a>
4432 &nbsp;
4433 <a href="#SEC40_28" class="summary-letter"><b>S</b></a>
4434 &nbsp;
4435 <a href="#SEC40_29" class="summary-letter"><b>T</b></a>
4436 &nbsp;
4437 <a href="#SEC40_30" class="summary-letter"><b>U</b></a>
4438 &nbsp;
4439 <a href="#SEC40_31" class="summary-letter"><b>V</b></a>
4440 &nbsp;
4441 <a href="#SEC40_32" class="summary-letter"><b>W</b></a>
4442 &nbsp;
4443 <a href="#SEC40_33" class="summary-letter"><b>Z</b></a>
4444 &nbsp;
4445 </td></tr></table>
4446 <table border="0" class="index-cp">
4447 <tr><td></td><th align="left">Index Entry</th><th align="left"> Section</th></tr>
4448 <tr><td colspan="3"> <hr></td></tr>
4449 <tr><th><a name="SEC40_0">%</a></th><td></td><td></td></tr>
4450 <tr><td></td><td valign="top"><a href="#IDX325">%h</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4451 <tr><td></td><td valign="top"><a href="#IDX329">%i</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4452 <tr><td></td><td valign="top"><a href="#IDX331">%p</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4453 <tr><td></td><td valign="top"><a href="#IDX335">%t</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4454 <tr><td></td><td valign="top"><a href="#IDX338">%u</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4455 <tr><td colspan="3"> <hr></td></tr>
4456 <tr><th><a name="SEC40_1">-</a></th><td></td><td></td></tr>
4457 <tr><td></td><td valign="top"><a href="#IDX3">-disable-cxx</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4458 <tr><td></td><td valign="top"><a href="#IDX5">-enable-shlib</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4459 <tr><td></td><td valign="top"><a href="#IDX4">-enable-threads</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4460 <tr><td colspan="3"> <hr></td></tr>
4461 <tr><th><a name="SEC40_2">.</a></th><td></td><td></td></tr>
4462 <tr><td></td><td valign="top"><a href="#SEC34">.dmallocrc file</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4463 <tr><td colspan="3"> <hr></td></tr>
4464 <tr><th><a name="SEC40_3">0</a></th><td></td><td></td></tr>
4465 <tr><td></td><td valign="top"><a href="#IDX428">0332 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4466 <tr><td></td><td valign="top"><a href="#IDX411">0337 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4467 <tr><td></td><td valign="top"><a href="#IDX430">0xda character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4468 <tr><td></td><td valign="top"><a href="#IDX413">0xdf character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4469 <tr><td colspan="3"> <hr></td></tr>
4470 <tr><th><a name="SEC40_4">1</a></th><td></td><td></td></tr>
4471 <tr><td></td><td valign="top"><a href="#IDX159">1, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4472 <tr><td></td><td valign="top"><a href="#IDX168">10, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4473 <tr><td></td><td valign="top"><a href="#IDX176">11, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4474 <tr><td></td><td valign="top"><a href="#IDX181">13, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4475 <tr><td colspan="3"> <hr></td></tr>
4476 <tr><th><a name="SEC40_5">2</a></th><td></td><td></td></tr>
4477 <tr><td></td><td valign="top"><a href="#IDX163">2, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4478 <tr><td></td><td valign="top"><a href="#IDX187">20, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4479 <tr><td></td><td valign="top"><a href="#IDX194">21, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4480 <tr><td></td><td valign="top"><a href="#IDX425">218 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4481 <tr><td></td><td valign="top"><a href="#IDX200">22, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4482 <tr><td></td><td valign="top"><a href="#IDX408">223 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4483 <tr><td></td><td valign="top"><a href="#IDX206">23, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4484 <tr><td></td><td valign="top"><a href="#IDX211">24, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4485 <tr><td></td><td valign="top"><a href="#IDX216">25, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4486 <tr><td></td><td valign="top"><a href="#IDX221">26, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4487 <tr><td></td><td valign="top"><a href="#IDX226">27, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4488 <tr><td></td><td valign="top"><a href="#IDX231">28, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4489 <tr><td colspan="3"> <hr></td></tr>
4490 <tr><th><a name="SEC40_6">3</a></th><td></td><td></td></tr>
4491 <tr><td></td><td valign="top"><a href="#IDX236">30, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4492 <tr><td></td><td valign="top"><a href="#IDX427">332 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4493 <tr><td></td><td valign="top"><a href="#IDX410">337 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4494 <tr><td colspan="3"> <hr></td></tr>
4495 <tr><th><a name="SEC40_7">4</a></th><td></td><td></td></tr>
4496 <tr><td></td><td valign="top"><a href="#IDX241">40, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4497 <tr><td></td><td valign="top"><a href="#IDX246">41, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4498 <tr><td></td><td valign="top"><a href="#IDX251">43, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4499 <tr><td></td><td valign="top"><a href="#IDX258">45, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4500 <tr><td colspan="3"> <hr></td></tr>
4501 <tr><th><a name="SEC40_8">6</a></th><td></td><td></td></tr>
4502 <tr><td></td><td valign="top"><a href="#IDX264">60, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4503 <tr><td></td><td valign="top"><a href="#IDX269">61, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4504 <tr><td></td><td valign="top"><a href="#IDX274">67, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4505 <tr><td colspan="3"> <hr></td></tr>
4506 <tr><th><a name="SEC40_9">7</a></th><td></td><td></td></tr>
4507 <tr><td></td><td valign="top"><a href="#IDX281">70, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4508 <tr><td></td><td valign="top"><a href="#IDX286">72, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4509 <tr><td></td><td valign="top"><a href="#IDX291">73, error code</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4510 <tr><td colspan="3"> <hr></td></tr>
4511 <tr><th><a name="SEC40_10">A</a></th><td></td><td></td></tr>
4512 <tr><td></td><td valign="top"><a href="#IDX71">abort</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4513 <tr><td></td><td valign="top"><a href="#IDX289">address list error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4514 <tr><td></td><td valign="top"><a href="#IDX374">address locating</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4515 <tr><td></td><td valign="top"><a href="#IDX373">address setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4516 <tr><td></td><td valign="top"><a href="#IDX284">admin list error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4517 <tr><td></td><td valign="top"><a href="#IDX18">alias, shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4518 <tr><td></td><td valign="top"><a href="#IDX318">alias, shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
4519 <tr><td></td><td valign="top"><a href="#IDX254">alloc failed error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4520 <tr><td></td><td valign="top"><a href="#IDX432">alloc-blank</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4521 <tr><td></td><td valign="top"><a href="#SEC5">allocation basics</a></td><td valign="top"><a href="#SEC5">2.3 Basic Description of Terms and Functions</a></td></tr>
4522 <tr><td></td><td valign="top"><a href="#SEC11">allocation macros</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
4523 <tr><td></td><td valign="top"><a href="#IDX33">Allocation of zeros</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4524 <tr><td></td><td valign="top"><a href="#IDX442">ALLOW_FREE_NULL</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4525 <tr><td></td><td valign="top"><a href="#IDX453">ALLOW_FREE_NULL settings.h option</a></td><td valign="top"><a href="#SEC37">5.2 General Compatibility Concerns</a></td></tr>
4526 <tr><td></td><td valign="top"><a href="#IDX316">ALLOW_FREE_NULL_MESSAGE</a></td><td valign="top"><a href="#SEC27">3.13 Explanation of the Logfile Output</a></td></tr>
4527 <tr><td></td><td valign="top"><a href="#IDX443">ALLOW_FREE_NULL_MESSAGE</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4528 <tr><td></td><td valign="top"><a href="#IDX452">ALLOW_REALLOC_NULL settings.h option</a></td><td valign="top"><a href="#SEC37">5.2 General Compatibility Concerns</a></td></tr>
4529 <tr><td></td><td valign="top"><a href="#IDX272">already free error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4530 <tr><td></td><td valign="top"><a href="#IDX10">ANSI-C compiler</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4531 <tr><td></td><td valign="top"><a href="#SEC13">argument checking</a></td><td valign="top"><a href="#SEC13">3.3 Checking of Function Arguments</a></td></tr>
4532 <tr><td></td><td valign="top"><a href="#IDX64">assembly hacks</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4533 <tr><td></td><td valign="top"><a href="#IDX16">atexit</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4534 <tr><td></td><td valign="top"><a href="#IDX84">atexit function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4535 <tr><td></td><td valign="top"><a href="#SEC_Top">author</a></td><td valign="top"><a href="#SEC_Top">Debug Malloc Library</a></td></tr>
4536 <tr><td></td><td valign="top"><a href="#IDX13">automatic shutdown</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4537 <tr><td colspan="3"> <hr></td></tr>
4538 <tr><th><a name="SEC40_11">B</a></th><td></td><td></td></tr>
4539 <tr><td></td><td valign="top"><a href="#IDX283">bad admin structure list</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4540 <tr><td></td><td valign="top"><a href="#IDX214">bad file error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4541 <tr><td></td><td valign="top"><a href="#IDX219">bad line error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4542 <tr><td></td><td valign="top"><a href="#IDX171">bad setup error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4543 <tr><td></td><td valign="top"><a href="#IDX244">bad size error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4544 <tr><td></td><td valign="top"><a href="#IDX19">bash shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4545 <tr><td></td><td valign="top"><a href="#IDX319">bash shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
4546 <tr><td></td><td valign="top"><a href="#IDX362">bash usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4547 <tr><td></td><td valign="top"><a href="#SEC5">basic allocation information</a></td><td valign="top"><a href="#SEC5">2.3 Basic Description of Terms and Functions</a></td></tr>
4548 <tr><td></td><td valign="top"><a href="#SEC6">basic definitions</a></td><td valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td></tr>
4549 <tr><td></td><td valign="top"><a href="#SEC4">beginning</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4550 <tr><td></td><td valign="top"><a href="#IDX403">blank space</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4551 <tr><td></td><td valign="top"><a href="#IDX420">blank space</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4552 <tr><td></td><td valign="top"><a href="#IDX404">blanking memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4553 <tr><td></td><td valign="top"><a href="#IDX421">blanking memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4554 <tr><td></td><td valign="top"><a href="#IDX43">bounds checking</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4555 <tr><td></td><td valign="top"><a href="#IDX360">Bourne shell usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4556 <tr><td></td><td valign="top"><a href="#SEC3">building the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4557 <tr><td colspan="3"> <hr></td></tr>
4558 <tr><th><a name="SEC40_12">C</a></th><td></td><td></td></tr>
4559 <tr><td></td><td valign="top"><a href="#IDX365">C shell usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4560 <tr><td></td><td valign="top"><a href="#SEC18">c++ usage</a></td><td valign="top"><a href="#SEC18">3.8 Using the Library with C++</a></td></tr>
4561 <tr><td></td><td valign="top"><a href="#IDX306">caller address translation</a></td><td valign="top"><a href="#SEC23">3.9.4 Translating Return Addresses into Code Locations</a></td></tr>
4562 <tr><td></td><td valign="top"><a href="#SEC12">caller's address</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4563 <tr><td></td><td valign="top"><a href="#IDX32">calloc</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4564 <tr><td></td><td valign="top"><a href="#IDX202">cannot locate pointer in heap</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4565 <tr><td></td><td valign="top"><a href="#IDX436">catch-null</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4566 <tr><td></td><td valign="top"><a href="#IDX393">catch-signals</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4567 <tr><td></td><td valign="top"><a href="#SEC26">cgi-bin process debugging</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4568 <tr><td></td><td valign="top"><a href="#SEC26">cgi-bin usage of dmalloc</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4569 <tr><td></td><td valign="top"><a href="#IDX138">changed memory log</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4570 <tr><td></td><td valign="top"><a href="#IDX280">check-blank</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4571 <tr><td></td><td valign="top"><a href="#IDX390">check-blank</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4572 <tr><td></td><td valign="top"><a href="#IDX388">check-fence</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4573 <tr><td></td><td valign="top"><a href="#IDX391">check-funcs</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4574 <tr><td></td><td valign="top"><a href="#IDX56">check-heap</a></td><td valign="top"><a href="#SEC9">2.5 How the Library Checks Your Program</a></td></tr>
4575 <tr><td></td><td valign="top"><a href="#IDX389">check-heap</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4576 <tr><td></td><td valign="top"><a href="#IDX465">check-heap</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4577 <tr><td></td><td valign="top"><a href="#IDX392">check-shutdown</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4578 <tr><td></td><td valign="top"><a href="#SEC13">checking arguments</a></td><td valign="top"><a href="#SEC13">3.3 Checking of Function Arguments</a></td></tr>
4579 <tr><td></td><td valign="top"><a href="#IDX44">checking bounds</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4580 <tr><td></td><td valign="top"><a href="#IDX139">checkpoint memory usage</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4581 <tr><td></td><td valign="top"><a href="#SEC26">child process debugging</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4582 <tr><td></td><td valign="top"><a href="#IDX406">clearing memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4583 <tr><td></td><td valign="top"><a href="#IDX423">clearing memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4584 <tr><td></td><td valign="top"><a href="#IDX369">comma separated tokens in env variable</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4585 <tr><td></td><td valign="top"><a href="#SEC39">common problems</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4586 <tr><td></td><td valign="top"><a href="#SEC37">compatibility</a></td><td valign="top"><a href="#SEC37">5.2 General Compatibility Concerns</a></td></tr>
4587 <tr><td></td><td valign="top"><a href="#SEC3">compiling the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4588 <tr><td></td><td valign="top"><a href="#IDX6">conf.h file</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4589 <tr><td></td><td valign="top"><a href="#SEC34">configuration file</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4590 <tr><td></td><td valign="top"><a href="#IDX2">configure script</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4591 <tr><td></td><td valign="top"><a href="#SEC3">configuring the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4592 <tr><td></td><td valign="top"><a href="#IDX45">constancy verification</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4593 <tr><td></td><td valign="top"><a href="#SEC1">copying</a></td><td valign="top"><a href="#SEC1">1. Library Copying and Licensing Conditions</a></td></tr>
4594 <tr><td></td><td valign="top"><a href="#IDX53">core dump</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4595 <tr><td></td><td valign="top"><a href="#SEC14">core dump</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4596 <tr><td></td><td valign="top"><a href="#IDX418">core dump</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4597 <tr><td></td><td valign="top"><a href="#IDX439">core dump</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4598 <tr><td></td><td valign="top"><a href="#IDX69">core dump, none</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4599 <tr><td></td><td valign="top"><a href="#IDX66">core file</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4600 <tr><td></td><td valign="top"><a href="#IDX253">could not grow heap by allocating memory</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4601 <tr><td></td><td valign="top"><a href="#IDX125">count changed</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4602 <tr><td></td><td valign="top"><a href="#IDX126">count number of bytes changed since mark</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4603 <tr><td></td><td valign="top"><a href="#IDX40">cpp</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4604 <tr><td></td><td valign="top"><a href="#IDX22">csh shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4605 <tr><td></td><td valign="top"><a href="#IDX323">csh shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
4606 <tr><td></td><td valign="top"><a href="#IDX366">csh usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4607 <tr><td></td><td valign="top"><a href="#IDX95">current debug value</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4608 <tr><td></td><td valign="top"><a href="#SEC25">cygwin</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4609 <tr><td colspan="3"> <hr></td></tr>
4610 <tr><th><a name="SEC40_13">D</a></th><td></td><td></td></tr>
4611 <tr><td></td><td valign="top"><a href="#IDX431">da character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4612 <tr><td></td><td valign="top"><a href="#SEC26">daemon process debugging</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4613 <tr><td></td><td valign="top"><a href="#IDX368">debug setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4614 <tr><td></td><td valign="top"><a href="#SEC33">debug tokens</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4615 <tr><td></td><td valign="top"><a href="#SEC14">debugger</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4616 <tr><td></td><td valign="top"><a href="#SEC19">debugger usage with dmalloc</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
4617 <tr><td></td><td valign="top"><a href="#SEC26">debugging cgi-bin processes</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4618 <tr><td></td><td valign="top"><a href="#SEC26">debugging child processes</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4619 <tr><td></td><td valign="top"><a href="#SEC26">debugging daemon processes</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4620 <tr><td></td><td valign="top"><a href="#SEC26">debugging server processes</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4621 <tr><td></td><td valign="top"><a href="#IDX424">decimal 218 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4622 <tr><td></td><td valign="top"><a href="#IDX407">decimal 223 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4623 <tr><td></td><td valign="top"><a href="#IDX345">delay heap checking</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4624 <tr><td></td><td valign="top"><a href="#IDX347">delay heap checking</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4625 <tr><td></td><td valign="top"><a href="#IDX354">delay heap checking</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4626 <tr><td></td><td valign="top"><a href="#IDX17">destructor</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4627 <tr><td></td><td valign="top"><a href="#IDX414">df character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4628 <tr><td></td><td valign="top"><a href="#SEC20">diagnosing errors</a></td><td valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td></tr>
4629 <tr><td></td><td valign="top"><a href="#SEC17">disabling library checking</a></td><td valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td></tr>
4630 <tr><td></td><td valign="top"><a href="#SEC17">disabling the library</a></td><td valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td></tr>
4631 <tr><td></td><td valign="top"><a href="#SEC29">dmalloc program</a></td><td valign="top"><a href="#SEC29">4. Dmalloc Utility Program</a></td></tr>
4632 <tr><td></td><td valign="top"><a href="#SEC29">dmalloc utility</a></td><td valign="top"><a href="#SEC29">4. Dmalloc Utility Program</a></td></tr>
4633 <tr><td></td><td valign="top"><a href="#SEC11">dmalloc.h file</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
4634 <tr><td></td><td valign="top"><a href="#SEC17">dmalloc_debug</a></td><td valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td></tr>
4635 <tr><td></td><td valign="top"><a href="#IDX90">dmalloc_debug function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4636 <tr><td></td><td valign="top"><a href="#IDX94">dmalloc_debug_current function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4637 <tr><td></td><td valign="top"><a href="#IDX97">dmalloc_debug_setup</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4638 <tr><td></td><td valign="top"><a href="#IDX314">dmalloc_debug_setup function</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4639 <tr><td></td><td valign="top"><a href="#IDX313">dmalloc_debug_setup usage</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4640 <tr><td></td><td valign="top"><a href="#IDX74">dmalloc_errno number</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4641 <tr><td></td><td valign="top"><a href="#IDX298">dmalloc_error() routine</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
4642 <tr><td></td><td valign="top"><a href="#IDX103">dmalloc_examine function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4643 <tr><td></td><td valign="top"><a href="#IDX25">DMALLOC_FUNC_CHECK</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4644 <tr><td></td><td valign="top"><a href="#SEC13">DMALLOC_FUNC_CHECK flag</a></td><td valign="top"><a href="#SEC13">3.3 Checking of Function Arguments</a></td></tr>
4645 <tr><td></td><td valign="top"><a href="#IDX150">dmalloc_get_stats function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4646 <tr><td></td><td valign="top"><a href="#IDX137">dmalloc_log_changed function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4647 <tr><td></td><td valign="top"><a href="#IDX129">dmalloc_log_stats function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4648 <tr><td></td><td valign="top"><a href="#IDX133">dmalloc_log_unfreed function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4649 <tr><td></td><td valign="top"><a href="#IDX78">dmalloc_logpath variable</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4650 <tr><td></td><td valign="top"><a href="#IDX111">dmalloc_mark function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4651 <tr><td></td><td valign="top"><a href="#IDX118">dmalloc_memory_allocated function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4652 <tr><td></td><td valign="top"><a href="#IDX146">dmalloc_message function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4653 <tr><td></td><td valign="top"><a href="#SEC32">DMALLOC_OPTIONS</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4654 <tr><td></td><td valign="top"><a href="#IDX470">DMALLOC_OPTIONS</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4655 <tr><td></td><td valign="top"><a href="#IDX81">dmalloc_shutdown function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4656 <tr><td></td><td valign="top"><a href="#IDX8">DMALLOC_SIZE option</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4657 <tr><td></td><td valign="top"><a href="#IDX155">dmalloc_strerror function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4658 <tr><td></td><td valign="top"><a href="#IDX12">dmalloc_t test program</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4659 <tr><td></td><td valign="top"><a href="#IDX108">dmalloc_track function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4660 <tr><td></td><td valign="top"><a href="#IDX86">dmalloc_verify function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4661 <tr><td></td><td valign="top"><a href="#IDX301">dmalloc_verify() routine</a></td><td valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td></tr>
4662 <tr><td></td><td valign="top"><a href="#IDX142">dmalloc_vmessage function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4663 <tr><td></td><td valign="top"><a href="#IDX296">dmallocc.cc</a></td><td valign="top"><a href="#SEC18">3.8 Using the Library with C++</a></td></tr>
4664 <tr><td></td><td valign="top"><a href="#SEC18">dmallocc.cc file</a></td><td valign="top"><a href="#SEC18">3.8 Using the Library with C++</a></td></tr>
4665 <tr><td></td><td valign="top"><a href="#SEC34">dmallocrc file</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4666 <tr><td></td><td valign="top"><a href="#IDX52">dump core</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4667 <tr><td></td><td valign="top"><a href="#SEC14">dump core</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4668 <tr><td></td><td valign="top"><a href="#IDX417">dump core</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4669 <tr><td></td><td valign="top"><a href="#IDX438">dump core</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4670 <tr><td colspan="3"> <hr></td></tr>
4671 <tr><th><a name="SEC40_14">E</a></th><td></td><td></td></tr>
4672 <tr><td></td><td valign="top"><a href="#IDX468">env</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4673 <tr><td></td><td valign="top"><a href="#SEC32">environment variable</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4674 <tr><td></td><td valign="top"><a href="#IDX166">errno value is not valid</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4675 <tr><td></td><td valign="top"><a href="#IDX169">error code 10</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4676 <tr><td></td><td valign="top"><a href="#IDX177">error code 11</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4677 <tr><td></td><td valign="top"><a href="#IDX182">error code 13</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4678 <tr><td></td><td valign="top"><a href="#IDX188">error code 20</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4679 <tr><td></td><td valign="top"><a href="#IDX195">error code 21</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4680 <tr><td></td><td valign="top"><a href="#IDX201">error code 22</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4681 <tr><td></td><td valign="top"><a href="#IDX207">error code 23</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4682 <tr><td></td><td valign="top"><a href="#IDX212">error code 24</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4683 <tr><td></td><td valign="top"><a href="#IDX217">error code 25</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4684 <tr><td></td><td valign="top"><a href="#IDX222">error code 26</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4685 <tr><td></td><td valign="top"><a href="#IDX227">error code 27</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4686 <tr><td></td><td valign="top"><a href="#IDX232">error code 28</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4687 <tr><td></td><td valign="top"><a href="#IDX237">error code 30</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4688 <tr><td></td><td valign="top"><a href="#IDX242">error code 40</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4689 <tr><td></td><td valign="top"><a href="#IDX247">error code 41</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4690 <tr><td></td><td valign="top"><a href="#IDX252">error code 43</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4691 <tr><td></td><td valign="top"><a href="#IDX259">error code 45</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4692 <tr><td></td><td valign="top"><a href="#IDX265">error code 60</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4693 <tr><td></td><td valign="top"><a href="#IDX270">error code 61</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4694 <tr><td></td><td valign="top"><a href="#IDX275">error code 67</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4695 <tr><td></td><td valign="top"><a href="#IDX282">error code 70</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4696 <tr><td></td><td valign="top"><a href="#IDX287">error code 72</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4697 <tr><td></td><td valign="top"><a href="#IDX292">error code 73</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4698 <tr><td></td><td valign="top"><a href="#IDX160">error code, 1</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4699 <tr><td></td><td valign="top"><a href="#IDX164">error code, 2</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4700 <tr><td></td><td valign="top"><a href="#SEC16">error codes</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4701 <tr><td></td><td valign="top"><a href="#IDX157">error message</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4702 <tr><td></td><td valign="top"><a href="#IDX76">error number</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4703 <tr><td></td><td valign="top"><a href="#SEC14">error-abort</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4704 <tr><td></td><td valign="top"><a href="#IDX419">error-abort</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4705 <tr><td></td><td valign="top"><a href="#SEC14">error-dump</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4706 <tr><td></td><td valign="top"><a href="#IDX440">error-dump</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4707 <tr><td></td><td valign="top"><a href="#IDX441">error-free-null</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4708 <tr><td></td><td valign="top"><a href="#IDX185">error-free-null token</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4709 <tr><td></td><td valign="top"><a href="#IDX290">ERROR_ADDRESS_LIST</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4710 <tr><td></td><td valign="top"><a href="#IDX285">ERROR_ADMIN_LIST</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4711 <tr><td></td><td valign="top"><a href="#IDX255">ERROR_ALLOC_FAILED</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4712 <tr><td></td><td valign="top"><a href="#IDX273">ERROR_ALREADY_FREE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4713 <tr><td></td><td valign="top"><a href="#IDX215">ERROR_BAD_FILE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4714 <tr><td></td><td valign="top"><a href="#IDX220">ERROR_BAD_LINE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4715 <tr><td></td><td valign="top"><a href="#IDX172">ERROR_BAD_SETUP</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4716 <tr><td></td><td valign="top"><a href="#IDX245">ERROR_BAD_SIZE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4717 <tr><td></td><td valign="top"><a href="#IDX278">ERROR_FREE_OVERWRITTEN</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4718 <tr><td></td><td valign="top"><a href="#IDX416">ERROR_FREE_OVERWRITTEN</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4719 <tr><td></td><td valign="top"><a href="#IDX179">ERROR_IN_TWICE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4720 <tr><td></td><td valign="top"><a href="#IDX210">ERROR_IS_FOUND</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4721 <tr><td></td><td valign="top"><a href="#IDX191">ERROR_IS_NULL</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4722 <tr><td></td><td valign="top"><a href="#IDX184">ERROR_LOCK_NOT_CONFIG</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4723 <tr><td></td><td valign="top"><a href="#IDX162">ERROR_NONE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4724 <tr><td></td><td valign="top"><a href="#IDX203">ERROR_NOT_FOUND</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4725 <tr><td></td><td valign="top"><a href="#IDX197">ERROR_NOT_IN_HEAP</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4726 <tr><td></td><td valign="top"><a href="#IDX268">ERROR_NOT_ON_BLOCK</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4727 <tr><td></td><td valign="top"><a href="#IDX240">ERROR_NOT_START_BLOCK</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4728 <tr><td></td><td valign="top"><a href="#IDX230">ERROR_OVER_FENCE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4729 <tr><td></td><td valign="top"><a href="#IDX263">ERROR_OVER_LIMIT</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4730 <tr><td></td><td valign="top"><a href="#IDX343">ERROR_OVER_LIMIT</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4731 <tr><td></td><td valign="top"><a href="#IDX295">ERROR_SLOT_CORRUPT</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4732 <tr><td></td><td valign="top"><a href="#IDX250">ERROR_TOO_BIG</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4733 <tr><td></td><td valign="top"><a href="#IDX225">ERROR_UNDER_FENCE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4734 <tr><td></td><td valign="top"><a href="#IDX235">ERROR_WOULD_OVERWRITE</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4735 <tr><td></td><td valign="top"><a href="#IDX104">examine a pointer</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4736 <tr><td></td><td valign="top"><a href="#SEC15">extensions</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4737 <tr><td colspan="3"> <hr></td></tr>
4738 <tr><th><a name="SEC40_15">F</a></th><td></td><td></td></tr>
4739 <tr><td></td><td valign="top"><a href="#IDX228">failed over picket-fence magic-number check</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4740 <tr><td></td><td valign="top"><a href="#IDX223">failed under picket-fence magic-number check</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4741 <tr><td></td><td valign="top"><a href="#SEC39">faq</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4742 <tr><td></td><td valign="top"><a href="#SEC8">features</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4743 <tr><td></td><td valign="top"><a href="#IDX42">fence-post checking</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4744 <tr><td></td><td valign="top"><a href="#SEC22">fence-post errors</a></td><td valign="top"><a href="#SEC22">3.9.3 Diagnosing Fence-Post Overwritten Memory</a></td></tr>
4745 <tr><td></td><td valign="top"><a href="#IDX39">file/line numbers</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4746 <tr><td></td><td valign="top"><a href="#IDX208">found pointer the user was looking for</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4747 <tr><td></td><td valign="top"><a href="#IDX38">free</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4748 <tr><td></td><td valign="top"><a href="#IDX186">free null token</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4749 <tr><td></td><td valign="top"><a href="#IDX277">free overwritten error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4750 <tr><td></td><td valign="top"><a href="#IDX276">free space has been overwritten</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4751 <tr><td></td><td valign="top"><a href="#IDX279">free-blank</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4752 <tr><td></td><td valign="top"><a href="#IDX415">free-blank</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4753 <tr><td></td><td valign="top"><a href="#IDX50">freed memory</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4754 <tr><td></td><td valign="top"><a href="#IDX51">freed memory</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4755 <tr><td colspan="3"> <hr></td></tr>
4756 <tr><th><a name="SEC40_16">G</a></th><td></td><td></td></tr>
4757 <tr><td></td><td valign="top"><a href="#IDX459">gcc</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4758 <tr><td></td><td valign="top"><a href="#IDX297">gdb</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
4759 <tr><td></td><td valign="top"><a href="#IDX300">gdb with shared libraries</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
4760 <tr><td></td><td valign="top"><a href="#SEC20">general errors</a></td><td valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td></tr>
4761 <tr><td></td><td valign="top"><a href="#SEC14">generating core dump</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4762 <tr><td></td><td valign="top"><a href="#IDX151">get heap statistics</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4763 <tr><td></td><td valign="top"><a href="#IDX309">getenv, problems with</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4764 <tr><td></td><td valign="top"><a href="#IDX312">GETENV_SAVE conf.h option</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4765 <tr><td></td><td valign="top"><a href="#IDX310">GetEnvironmentVariableA, using with</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4766 <tr><td></td><td valign="top"><a href="#IDX326">gethostname function usage</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4767 <tr><td></td><td valign="top"><a href="#IDX332">getpid function usage</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4768 <tr><td></td><td valign="top"><a href="#SEC4">getting started</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4769 <tr><td></td><td valign="top"><a href="#IDX339">getuid function usage</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4770 <tr><td colspan="3"> <hr></td></tr>
4771 <tr><th><a name="SEC40_17">H</a></th><td></td><td></td></tr>
4772 <tr><td></td><td valign="top"><a href="#IDX464">hanging program</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4773 <tr><td></td><td valign="top"><a href="#IDX311">HAVE_GETENVIRONMENTVARIABLEA</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4774 <tr><td></td><td valign="top"><a href="#IDX28">heap memory</a></td><td valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td></tr>
4775 <tr><td></td><td valign="top"><a href="#IDX152">heap statistics function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4776 <tr><td></td><td valign="top"><a href="#SEC39">help</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4777 <tr><td></td><td valign="top"><a href="#IDX429">hexadecimal 0xda character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4778 <tr><td></td><td valign="top"><a href="#IDX412">hexadecimal 0xdf character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4779 <tr><td></td><td valign="top"><a href="#IDX450">high token</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4780 <tr><td></td><td valign="top"><a href="#SEC28">hints that may help</a></td><td valign="top"><a href="#SEC28">3.14 Various Other Hints That May Help</a></td></tr>
4781 <tr><td></td><td valign="top"><a href="#IDX327">hostname in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4782 <tr><td></td><td valign="top"><a href="#SEC39">how do i...</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4783 <tr><td></td><td valign="top"><a href="#SEC4">how to begin</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4784 <tr><td></td><td valign="top"><a href="#IDX399">HUP signal</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4785 <tr><td colspan="3"> <hr></td></tr>
4786 <tr><th><a name="SEC40_18">I</a></th><td></td><td></td></tr>
4787 <tr><td></td><td valign="top"><a href="#IDX471">ident</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4788 <tr><td></td><td valign="top"><a href="#IDX175">in twice error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4789 <tr><td></td><td valign="top"><a href="#IDX170">initialization and setup failed</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4790 <tr><td></td><td valign="top"><a href="#SEC3">installing the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4791 <tr><td></td><td valign="top"><a href="#IDX400">INT signal</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4792 <tr><td></td><td valign="top"><a href="#IDX115">interaction count</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4793 <tr><td></td><td valign="top"><a href="#IDX350">interaction count</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4794 <tr><td></td><td valign="top"><a href="#IDX288">internal address list corruption</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4795 <tr><td></td><td valign="top"><a href="#IDX75">internal error number</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4796 <tr><td></td><td valign="top"><a href="#IDX293">internal memory slot corruption</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4797 <tr><td></td><td valign="top"><a href="#IDX457">INTERNAL_MEMORY_SPACE</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4798 <tr><td></td><td valign="top"><a href="#IDX324">interval setting</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4799 <tr><td></td><td valign="top"><a href="#IDX376">interval setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4800 <tr><td></td><td valign="top"><a href="#SEC_Top">introduction</a></td><td valign="top"><a href="#SEC_Top">Debug Malloc Library</a></td></tr>
4801 <tr><td></td><td valign="top"><a href="#IDX243">invalid allocation size</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4802 <tr><td></td><td valign="top"><a href="#IDX165">invalid errno value</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4803 <tr><td></td><td valign="top"><a href="#IDX167">INVALID_ERROR</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4804 <tr><td></td><td valign="top"><a href="#IDX209">is found error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4805 <tr><td></td><td valign="top"><a href="#IDX190">is null error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4806 <tr><td></td><td valign="top"><a href="#IDX58">iteration count</a></td><td valign="top"><a href="#SEC9">2.5 How the Library Checks Your Program</a></td></tr>
4807 <tr><td colspan="3"> <hr></td></tr>
4808 <tr><th><a name="SEC40_19">J</a></th><td></td><td></td></tr>
4809 <tr><td></td><td valign="top"><a href="#SEC4">jump start</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4810 <tr><td colspan="3"> <hr></td></tr>
4811 <tr><th><a name="SEC40_20">K</a></th><td></td><td></td></tr>
4812 <tr><td></td><td valign="top"><a href="#IDX72">kill process</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4813 <tr><td></td><td valign="top"><a href="#IDX73">KILL_PROCESS</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4814 <tr><td></td><td valign="top"><a href="#IDX20">ksh shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4815 <tr><td></td><td valign="top"><a href="#IDX320">ksh shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
4816 <tr><td></td><td valign="top"><a href="#IDX363">ksh usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4817 <tr><td colspan="3"> <hr></td></tr>
4818 <tr><th><a name="SEC40_21">L</a></th><td></td><td></td></tr>
4819 <tr><td></td><td valign="top"><a href="#IDX248">largest maximum allocation size exceeded</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4820 <tr><td></td><td valign="top"><a href="#IDX49">leaking memory</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4821 <tr><td></td><td valign="top"><a href="#SEC21">leaking memory</a></td><td valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td></tr>
4822 <tr><td></td><td valign="top"><a href="#SEC18">libdmallocxx.a</a></td><td valign="top"><a href="#SEC18">3.8 Using the Library with C++</a></td></tr>
4823 <tr><td></td><td valign="top"><a href="#SEC1">library permissions</a></td><td valign="top"><a href="#SEC1">1. Library Copying and Licensing Conditions</a></td></tr>
4824 <tr><td></td><td valign="top"><a href="#SEC29">library utility</a></td><td valign="top"><a href="#SEC29">4. Dmalloc Utility Program</a></td></tr>
4825 <tr><td></td><td valign="top"><a href="#IDX357">library version</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4826 <tr><td></td><td valign="top"><a href="#SEC1">license</a></td><td valign="top"><a href="#SEC1">1. Library Copying and Licensing Conditions</a></td></tr>
4827 <tr><td></td><td valign="top"><a href="#IDX307">lock on</a></td><td valign="top"><a href="#SEC24">3.10 Using the Library with a Thread Package</a></td></tr>
4828 <tr><td></td><td valign="top"><a href="#IDX344">lock on</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4829 <tr><td></td><td valign="top"><a href="#IDX173">lock-on</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4830 <tr><td></td><td valign="top"><a href="#IDX180">lock-on not configured</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4831 <tr><td></td><td valign="top"><a href="#IDX370">lockon setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4832 <tr><td></td><td valign="top"><a href="#IDX140">log memory changes</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4833 <tr><td></td><td valign="top"><a href="#IDX130">log statistics</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4834 <tr><td></td><td valign="top"><a href="#IDX134">log unfreed memory</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4835 <tr><td></td><td valign="top"><a href="#IDX383">log-admin</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4836 <tr><td></td><td valign="top"><a href="#IDX384">log-bad-space</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4837 <tr><td></td><td valign="top"><a href="#IDX387">log-current-time</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4838 <tr><td></td><td valign="top"><a href="#IDX386">log-elapsed-time</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4839 <tr><td></td><td valign="top"><a href="#IDX381">log-known</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4840 <tr><td></td><td valign="top"><a href="#IDX380">log-non-free</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4841 <tr><td></td><td valign="top"><a href="#IDX385">log-nonfree-space</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4842 <tr><td></td><td valign="top"><a href="#IDX379">log-stats</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4843 <tr><td></td><td valign="top"><a href="#IDX382">log-trans</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4844 <tr><td></td><td valign="top"><a href="#IDX114">LOG_ITERATION</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4845 <tr><td></td><td valign="top"><a href="#IDX349">LOG_ITERATION</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4846 <tr><td></td><td valign="top"><a href="#IDX57">LOG_ITERATION_COUNT</a></td><td valign="top"><a href="#SEC9">2.5 How the Library Checks Your Program</a></td></tr>
4847 <tr><td></td><td valign="top"><a href="#SEC27">logfile format</a></td><td valign="top"><a href="#SEC27">3.13 Explanation of the Logfile Output</a></td></tr>
4848 <tr><td></td><td valign="top"><a href="#IDX144">logfile message writer</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4849 <tr><td></td><td valign="top"><a href="#IDX148">logfile message writer</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4850 <tr><td></td><td valign="top"><a href="#IDX79">logfile name</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4851 <tr><td></td><td valign="top"><a href="#IDX466">logfile not produced</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4852 <tr><td></td><td valign="top"><a href="#IDX371">logfile setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4853 <tr><td></td><td valign="top"><a href="#IDX372">logging information to disk</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4854 <tr><td></td><td valign="top"><a href="#IDX46">logging statistics</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4855 <tr><td></td><td valign="top"><a href="#IDX446">low token</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4856 <tr><td colspan="3"> <hr></td></tr>
4857 <tr><th><a name="SEC40_22">M</a></th><td></td><td></td></tr>
4858 <tr><td></td><td valign="top"><a href="#SEC11">macros, allocation</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
4859 <tr><td></td><td valign="top"><a href="#SEC3">making the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4860 <tr><td></td><td valign="top"><a href="#IDX29">malloc</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4861 <tr><td></td><td valign="top"><a href="#SEC7">malloc functions</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4862 <tr><td></td><td valign="top"><a href="#IDX178">malloc library has gone recursive</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4863 <tr><td></td><td valign="top"><a href="#IDX352">mark count</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4864 <tr><td></td><td valign="top"><a href="#IDX113">mark memory position</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4865 <tr><td></td><td valign="top"><a href="#IDX448">medium token</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4866 <tr><td></td><td valign="top"><a href="#IDX61">memalign</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
4867 <tr><td></td><td valign="top"><a href="#IDX119">memory allocated function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4868 <tr><td></td><td valign="top"><a href="#SEC6">memory definitions</a></td><td valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td></tr>
4869 <tr><td></td><td valign="top"><a href="#IDX48">memory leaks</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4870 <tr><td></td><td valign="top"><a href="#SEC21">memory leaks</a></td><td valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td></tr>
4871 <tr><td></td><td valign="top"><a href="#IDX260">memory limit</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4872 <tr><td></td><td valign="top"><a href="#IDX342">memory limit</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4873 <tr><td></td><td valign="top"><a href="#IDX112">memory position marker</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4874 <tr><td></td><td valign="top"><a href="#IDX55">memory problems in system functions</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4875 <tr><td></td><td valign="top"><a href="#IDX59">memory transaction count</a></td><td valign="top"><a href="#SEC9">2.5 How the Library Checks Your Program</a></td></tr>
4876 <tr><td></td><td valign="top"><a href="#IDX353">memory transaction count</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4877 <tr><td></td><td valign="top"><a href="#IDX70">missing core dump</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4878 <tr><td></td><td valign="top"><a href="#IDX204">mmap</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4879 <tr><td></td><td valign="top"><a href="#IDX256">mmap</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4880 <tr><td></td><td valign="top"><a href="#SEC20">mmap</a></td><td valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td></tr>
4881 <tr><td></td><td valign="top"><a href="#IDX434">mmap</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4882 <tr><td></td><td valign="top"><a href="#IDX454">mmap, usage without</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4883 <tr><td colspan="3"> <hr></td></tr>
4884 <tr><th><a name="SEC40_23">N</a></th><td></td><td></td></tr>
4885 <tr><td></td><td valign="top"><a href="#IDX328">name of host in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4886 <tr><td></td><td valign="top"><a href="#IDX437">never-reuse</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4887 <tr><td></td><td valign="top"><a href="#IDX68">no core dump</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4888 <tr><td></td><td valign="top"><a href="#IDX161">no error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4889 <tr><td></td><td valign="top"><a href="#IDX467">no logfile produced</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4890 <tr><td></td><td valign="top"><a href="#IDX378">none token</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4891 <tr><td></td><td valign="top"><a href="#IDX198">not found error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4892 <tr><td></td><td valign="top"><a href="#IDX193">not in heap error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4893 <tr><td></td><td valign="top"><a href="#IDX267">not on block boundary error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4894 <tr><td></td><td valign="top"><a href="#IDX239">not start block error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4895 <tr><td></td><td valign="top"><a href="#IDX127">number bytes changed since mark</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4896 <tr><td></td><td valign="top"><a href="#IDX120">number of bytes allocated</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4897 <tr><td colspan="3"> <hr></td></tr>
4898 <tr><th><a name="SEC40_24">O</a></th><td></td><td></td></tr>
4899 <tr><td></td><td valign="top"><a href="#IDX426">octal 332 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4900 <tr><td></td><td valign="top"><a href="#IDX409">octal 337 character</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4901 <tr><td></td><td valign="top"><a href="#IDX15">on_exit</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4902 <tr><td></td><td valign="top"><a href="#IDX85">on_exit function</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4903 <tr><td></td><td valign="top"><a href="#SEC28">other hints</a></td><td valign="top"><a href="#SEC28">3.14 Various Other Hints That May Help</a></td></tr>
4904 <tr><td></td><td valign="top"><a href="#IDX229">over fence error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4905 <tr><td></td><td valign="top"><a href="#IDX262">over limit error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4906 <tr><td></td><td valign="top"><a href="#IDX261">over user specified allocation limit error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4907 <tr><td></td><td valign="top"><a href="#IDX91">override debug settings</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4908 <tr><td></td><td valign="top"><a href="#IDX98">override debug settings</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4909 <tr><td></td><td valign="top"><a href="#SEC2">overview</a></td><td valign="top"><a href="#SEC2">2. Description of Features and How to Get Started</a></td></tr>
4910 <tr><td></td><td valign="top"><a href="#IDX405">overwriting memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4911 <tr><td></td><td valign="top"><a href="#IDX422">overwriting memory</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4912 <tr><td colspan="3"> <hr></td></tr>
4913 <tr><th><a name="SEC40_25">P</a></th><td></td><td></td></tr>
4914 <tr><td></td><td valign="top"><a href="#IDX122">page size</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4915 <tr><td></td><td valign="top"><a href="#SEC1">permissions of the library</a></td><td valign="top"><a href="#SEC1">1. Library Copying and Licensing Conditions</a></td></tr>
4916 <tr><td></td><td valign="top"><a href="#IDX333">pid in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4917 <tr><td></td><td valign="top"><a href="#IDX105">pointer information</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4918 <tr><td></td><td valign="top"><a href="#IDX266">pointer is not on block boundary</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4919 <tr><td></td><td valign="top"><a href="#IDX196">pointer is not pointing to heap data space</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4920 <tr><td></td><td valign="top"><a href="#IDX238">pointer is not to start of memory block</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4921 <tr><td></td><td valign="top"><a href="#IDX189">pointer is null error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4922 <tr><td></td><td valign="top"><a href="#IDX199">pointer not found error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4923 <tr><td></td><td valign="top"><a href="#IDX192">pointer not in heap error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4924 <tr><td></td><td valign="top"><a href="#IDX303">pointer seen count</a></td><td valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td></tr>
4925 <tr><td></td><td valign="top"><a href="#SEC38">portability</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4926 <tr><td></td><td valign="top"><a href="#IDX218">possibly bad .c file line-number</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4927 <tr><td></td><td valign="top"><a href="#IDX213">possibly bad .c filename pointer</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4928 <tr><td></td><td valign="top"><a href="#IDX456">preallocated memory heap</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4929 <tr><td></td><td valign="top"><a href="#IDX433">print-messages</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4930 <tr><td></td><td valign="top"><a href="#IDX469">printenv</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4931 <tr><td></td><td valign="top"><a href="#SEC39">problems</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4932 <tr><td></td><td valign="top"><a href="#IDX334">process-id in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4933 <tr><td></td><td valign="top"><a href="#IDX67">program core</a></td><td valign="top"><a href="#SEC14">3.4 Generating a Core File on Errors</a></td></tr>
4934 <tr><td></td><td valign="top"><a href="#SEC10">programming</a></td><td valign="top"><a href="#SEC10">3. How to Program with the Library</a></td></tr>
4935 <tr><td></td><td valign="top"><a href="#SEC24">pthreads</a></td><td valign="top"><a href="#SEC24">3.10 Using the Library with a Thread Package</a></td></tr>
4936 <tr><td colspan="3"> <hr></td></tr>
4937 <tr><th><a name="SEC40_26">Q</a></th><td></td><td></td></tr>
4938 <tr><td></td><td valign="top"><a href="#SEC39">questions</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4939 <tr><td></td><td valign="top"><a href="#SEC4">quick start</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4940 <tr><td colspan="3"> <hr></td></tr>
4941 <tr><th><a name="SEC40_27">R</a></th><td></td><td></td></tr>
4942 <tr><td></td><td valign="top"><a href="#SEC12">ra</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4943 <tr><td></td><td valign="top"><a href="#IDX65">ra_info.pl</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4944 <tr><td></td><td valign="top"><a href="#SEC23">ra_info.pl</a></td><td valign="top"><a href="#SEC23">3.9.4 Translating Return Addresses into Code Locations</a></td></tr>
4945 <tr><td></td><td valign="top"><a href="#SEC34">rc file</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4946 <tr><td></td><td valign="top"><a href="#IDX24">rc shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4947 <tr><td></td><td valign="top"><a href="#IDX308">reading environment, problems with</a></td><td valign="top"><a href="#SEC25">3.11 Using the library with Cygwin environment.</a></td></tr>
4948 <tr><td></td><td valign="top"><a href="#IDX36">realloc</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
4949 <tr><td></td><td valign="top"><a href="#IDX402">realloc-copy</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4950 <tr><td></td><td valign="top"><a href="#IDX60">recalloc</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
4951 <tr><td></td><td valign="top"><a href="#IDX174">recursion</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4952 <tr><td></td><td valign="top"><a href="#IDX153">report heap statistics</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4953 <tr><td></td><td valign="top"><a href="#SEC17">restoring library flags</a></td><td valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td></tr>
4954 <tr><td></td><td valign="top"><a href="#IDX41">return-address</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4955 <tr><td></td><td valign="top"><a href="#SEC12">return-address</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4956 <tr><td></td><td valign="top"><a href="#IDX458">return-address</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4957 <tr><td></td><td valign="top"><a href="#IDX305">return-address translation</a></td><td valign="top"><a href="#SEC23">3.9.4 Translating Return Addresses into Code Locations</a></td></tr>
4958 <tr><td></td><td valign="top"><a href="#SEC12">return.h file</a></td><td valign="top"><a href="#SEC12">3.2 Getting Caller Address Information</a></td></tr>
4959 <tr><td></td><td valign="top"><a href="#IDX444">runtime token</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4960 <tr><td></td><td valign="top"><a href="#SEC34">runtime-config file</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
4961 <tr><td colspan="3"> <hr></td></tr>
4962 <tr><th><a name="SEC40_28">S</a></th><td></td><td></td></tr>
4963 <tr><td></td><td valign="top"><a href="#IDX205">sbrk</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4964 <tr><td></td><td valign="top"><a href="#SEC20">sbrk</a></td><td valign="top"><a href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></td></tr>
4965 <tr><td></td><td valign="top"><a href="#IDX435">sbrk</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4966 <tr><td></td><td valign="top"><a href="#IDX455">sbrk, usage without</a></td><td valign="top"><a href="#SEC38">5.3 Issues Important for Porting the Library</a></td></tr>
4967 <tr><td></td><td valign="top"><a href="#IDX107">seen count</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4968 <tr><td></td><td valign="top"><a href="#IDX304">seen count</a></td><td valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td></tr>
4969 <tr><td></td><td valign="top"><a href="#IDX317">seen count</a></td><td valign="top"><a href="#SEC27">3.13 Explanation of the Logfile Output</a></td></tr>
4970 <tr><td></td><td valign="top"><a href="#SEC26">server process debugging</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
4971 <tr><td></td><td valign="top"><a href="#IDX92">set debug functionality flags</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4972 <tr><td></td><td valign="top"><a href="#IDX99">set debug functionality flags</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4973 <tr><td></td><td valign="top"><a href="#IDX1">settings.dist file</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4974 <tr><td></td><td valign="top"><a href="#IDX7">settings.h file</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
4975 <tr><td></td><td valign="top"><a href="#IDX100">setup debug flags</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4976 <tr><td></td><td valign="top"><a href="#IDX361">sh usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4977 <tr><td></td><td valign="top"><a href="#IDX299">shared libraries with gdb</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
4978 <tr><td></td><td valign="top"><a href="#IDX359">shell usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4979 <tr><td></td><td valign="top"><a href="#IDX395">shutdown on signal</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4980 <tr><td></td><td valign="top"><a href="#IDX82">shutdown the library</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4981 <tr><td></td><td valign="top"><a href="#IDX14">shutdown, automatic</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
4982 <tr><td></td><td valign="top"><a href="#IDX396">SIGHUP</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4983 <tr><td></td><td valign="top"><a href="#IDX397">SIGINT</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4984 <tr><td></td><td valign="top"><a href="#IDX394">signal shutdown</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4985 <tr><td></td><td valign="top"><a href="#IDX398">SIGTERM</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
4986 <tr><td></td><td valign="top"><a href="#IDX123">size of memory pages</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4987 <tr><td></td><td valign="top"><a href="#IDX294">slot corrupt error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
4988 <tr><td></td><td valign="top"><a href="#IDX460">slow running</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
4989 <tr><td></td><td valign="top"><a href="#SEC35">source code</a></td><td valign="top"><a href="#SEC35">5. Information on the Source Code</a></td></tr>
4990 <tr><td></td><td valign="top"><a href="#SEC36">source definitions</a></td><td valign="top"><a href="#SEC36">5.1 Definition of Terms and other Information</a></td></tr>
4991 <tr><td></td><td valign="top"><a href="#IDX27">stack memory</a></td><td valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td></tr>
4992 <tr><td></td><td valign="top"><a href="#IDX346">start heap check later</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4993 <tr><td></td><td valign="top"><a href="#IDX348">start heap check later</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4994 <tr><td></td><td valign="top"><a href="#IDX355">start heap check later</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
4995 <tr><td></td><td valign="top"><a href="#IDX377">start setting</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
4996 <tr><td></td><td valign="top"><a href="#IDX26">static memory</a></td><td valign="top"><a href="#SEC6">2.3.1 General Memory Terms and Concepts</a></td></tr>
4997 <tr><td></td><td valign="top"><a href="#IDX47">statistics</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
4998 <tr><td></td><td valign="top"><a href="#IDX131">statistics logging</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
4999 <tr><td></td><td valign="top"><a href="#IDX302">STORE_SEEN_COUNT conf.h option</a></td><td valign="top"><a href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></td></tr>
5000 <tr><td></td><td valign="top"><a href="#IDX63">strdup</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
5001 <tr><td></td><td valign="top"><a href="#IDX156">string error message</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5002 <tr><td></td><td valign="top"><a href="#IDX101">string of debug tokens</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5003 <tr><td></td><td valign="top"><a href="#IDX472">strings</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
5004 <tr><td></td><td valign="top"><a href="#IDX54">system memory problems</a></td><td valign="top"><a href="#SEC8">2.4 General Features of the Library</a></td></tr>
5005 <tr><td colspan="3"> <hr></td></tr>
5006 <tr><th><a name="SEC40_29">T</a></th><td></td><td></td></tr>
5007 <tr><td></td><td valign="top"><a href="#IDX23">tcsh shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
5008 <tr><td></td><td valign="top"><a href="#IDX322">tcsh shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
5009 <tr><td></td><td valign="top"><a href="#IDX367">tcsh usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
5010 <tr><td></td><td valign="top"><a href="#IDX401">TERM signal</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
5011 <tr><td></td><td valign="top"><a href="#IDX11">testing the library</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
5012 <tr><td></td><td valign="top"><a href="#IDX183">thread locking has not been configured</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5013 <tr><td></td><td valign="top"><a href="#IDX330">thread-id in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5014 <tr><td></td><td valign="top"><a href="#SEC24">threads</a></td><td valign="top"><a href="#SEC24">3.10 Using the Library with a Thread Package</a></td></tr>
5015 <tr><td></td><td valign="top"><a href="#IDX336">time function usage</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5016 <tr><td></td><td valign="top"><a href="#IDX337">time in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5017 <tr><td></td><td valign="top"><a href="#IDX451">token high</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
5018 <tr><td></td><td valign="top"><a href="#IDX447">token low</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
5019 <tr><td></td><td valign="top"><a href="#IDX449">token medium</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
5020 <tr><td></td><td valign="top"><a href="#IDX445">token runtime</a></td><td valign="top"><a href="#SEC34">4.5 Format of the Runtime Configuration File</a></td></tr>
5021 <tr><td></td><td valign="top"><a href="#SEC33">tokens, debug</a></td><td valign="top"><a href="#SEC33">4.4 Description of the Debugging Tokens</a></td></tr>
5022 <tr><td></td><td valign="top"><a href="#IDX249">too big error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5023 <tr><td></td><td valign="top"><a href="#IDX462">too slow</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
5024 <tr><td></td><td valign="top"><a href="#IDX109">track memory calls</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5025 <tr><td></td><td valign="top"><a href="#IDX375">tracking addresses</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
5026 <tr><td></td><td valign="top"><a href="#IDX116">transaction count</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5027 <tr><td></td><td valign="top"><a href="#IDX351">transaction count</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5028 <tr><td></td><td valign="top"><a href="#IDX271">tried to free previously freed pointer</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5029 <tr><td></td><td valign="top"><a href="#SEC39">troubleshooting</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
5030 <tr><td></td><td valign="top"><a href="#SEC17">turning off library flags</a></td><td valign="top"><a href="#SEC17">3.7 How to Disable the library</a></td></tr>
5031 <tr><td colspan="3"> <hr></td></tr>
5032 <tr><th><a name="SEC40_30">U</a></th><td></td><td></td></tr>
5033 <tr><td></td><td valign="top"><a href="#IDX340">uid in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5034 <tr><td></td><td valign="top"><a href="#IDX224">under fence error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5035 <tr><td></td><td valign="top"><a href="#IDX135">unfreed memory log</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5036 <tr><td></td><td valign="top"><a href="#SEC26">usage of dmalloc in a daemon</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
5037 <tr><td></td><td valign="top"><a href="#SEC26">usage of dmalloc in a server</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
5038 <tr><td></td><td valign="top"><a href="#SEC26">usage of dmalloc with cgi-bin</a></td><td valign="top"><a href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td></tr>
5039 <tr><td></td><td valign="top"><a href="#SEC31">usage of the utility</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5040 <tr><td></td><td valign="top"><a href="#IDX233">use of pointer would exceed allocation</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5041 <tr><td></td><td valign="top"><a href="#IDX257">USE_MMAP conf.h option</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5042 <tr><td></td><td valign="top"><a href="#IDX9">USE_RETURN_MACROS conf.h option</a></td><td valign="top"><a href="#SEC3">2.1 How to Install the Library</a></td></tr>
5043 <tr><td></td><td valign="top"><a href="#IDX341">user-id in logfile path</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5044 <tr><td></td><td valign="top"><a href="#SEC19">using a debugger with dmalloc</a></td><td valign="top"><a href="#SEC19">3.9 Using Dmalloc With a Debugger</a></td></tr>
5045 <tr><td></td><td valign="top"><a href="#SEC29">utility program</a></td><td valign="top"><a href="#SEC29">4. Dmalloc Utility Program</a></td></tr>
5046 <tr><td></td><td valign="top"><a href="#SEC31">utility usage</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5047 <tr><td></td><td valign="top"><a href="#IDX356">utility version</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5048 <tr><td colspan="3"> <hr></td></tr>
5049 <tr><th><a name="SEC40_31">V</a></th><td></td><td></td></tr>
5050 <tr><td></td><td valign="top"><a href="#IDX62">valloc</a></td><td valign="top"><a href="#SEC11">3.1 Macros Providing File and Line Information</a></td></tr>
5051 <tr><td></td><td valign="top"><a href="#SEC28">various hints</a></td><td valign="top"><a href="#SEC28">3.14 Various Other Hints That May Help</a></td></tr>
5052 <tr><td></td><td valign="top"><a href="#IDX87">verify pointers</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5053 <tr><td></td><td valign="top"><a href="#IDX88">verify the heap</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5054 <tr><td></td><td valign="top"><a href="#IDX315">version of library</a></td><td valign="top"><a href="#SEC27">3.13 Explanation of the Logfile Output</a></td></tr>
5055 <tr><td></td><td valign="top"><a href="#IDX358">version of utility</a></td><td valign="top"><a href="#SEC31">4.2 How to Use the Dmalloc Program</a></td></tr>
5056 <tr><td colspan="3"> <hr></td></tr>
5057 <tr><th><a name="SEC40_32">W</a></th><td></td><td></td></tr>
5058 <tr><td></td><td valign="top"><a href="#SEC4">where to begin</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
5059 <tr><td></td><td valign="top"><a href="#IDX463">why hanging</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
5060 <tr><td></td><td valign="top"><a href="#IDX461">why running slow</a></td><td valign="top"><a href="#SEC39">6. Some Solutions to Common Problems</a></td></tr>
5061 <tr><td></td><td valign="top"><a href="#IDX234">would overwrite error</a></td><td valign="top"><a href="#SEC16">3.6 Description of the Internal Error Codes</a></td></tr>
5062 <tr><td></td><td valign="top"><a href="#IDX143">write message to logfile</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5063 <tr><td></td><td valign="top"><a href="#IDX147">write message to logfile</a></td><td valign="top"><a href="#SEC15">3.5 Additional Non-standard Routines</a></td></tr>
5064 <tr><td colspan="3"> <hr></td></tr>
5065 <tr><th><a name="SEC40_33">Z</a></th><td></td><td></td></tr>
5066 <tr><td></td><td valign="top"><a href="#IDX34">zeros, allocation of</a></td><td valign="top"><a href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></td></tr>
5067 <tr><td></td><td valign="top"><a href="#IDX21">zsh shell</a></td><td valign="top"><a href="#SEC4">2.2 Getting Started with the Library</a></td></tr>
5068 <tr><td></td><td valign="top"><a href="#IDX321">zsh shell</a></td><td valign="top"><a href="#SEC30">4.1 Using a Shell Alias with the Utility</a></td></tr>
5069 <tr><td></td><td valign="top"><a href="#IDX364">zsh usage</a></td><td valign="top"><a href="#SEC32">4.3 Environment Variable Name and Features</a></td></tr>
5070 <tr><td colspan="3"> <hr></td></tr>
5071 </table>
5072 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a href="#SEC40_0" class="summary-letter"><b>%</b></a>
5073 &nbsp;
5074 <a href="#SEC40_1" class="summary-letter"><b>-</b></a>
5075 &nbsp;
5076 <a href="#SEC40_2" class="summary-letter"><b>.</b></a>
5077 &nbsp;
5078 <a href="#SEC40_3" class="summary-letter"><b>0</b></a>
5079 &nbsp;
5080 <a href="#SEC40_4" class="summary-letter"><b>1</b></a>
5081 &nbsp;
5082 <a href="#SEC40_5" class="summary-letter"><b>2</b></a>
5083 &nbsp;
5084 <a href="#SEC40_6" class="summary-letter"><b>3</b></a>
5085 &nbsp;
5086 <a href="#SEC40_7" class="summary-letter"><b>4</b></a>
5087 &nbsp;
5088 <a href="#SEC40_8" class="summary-letter"><b>6</b></a>
5089 &nbsp;
5090 <a href="#SEC40_9" class="summary-letter"><b>7</b></a>
5091 &nbsp;
5092 <br>
5093 <a href="#SEC40_10" class="summary-letter"><b>A</b></a>
5094 &nbsp;
5095 <a href="#SEC40_11" class="summary-letter"><b>B</b></a>
5096 &nbsp;
5097 <a href="#SEC40_12" class="summary-letter"><b>C</b></a>
5098 &nbsp;
5099 <a href="#SEC40_13" class="summary-letter"><b>D</b></a>
5100 &nbsp;
5101 <a href="#SEC40_14" class="summary-letter"><b>E</b></a>
5102 &nbsp;
5103 <a href="#SEC40_15" class="summary-letter"><b>F</b></a>
5104 &nbsp;
5105 <a href="#SEC40_16" class="summary-letter"><b>G</b></a>
5106 &nbsp;
5107 <a href="#SEC40_17" class="summary-letter"><b>H</b></a>
5108 &nbsp;
5109 <a href="#SEC40_18" class="summary-letter"><b>I</b></a>
5110 &nbsp;
5111 <a href="#SEC40_19" class="summary-letter"><b>J</b></a>
5112 &nbsp;
5113 <a href="#SEC40_20" class="summary-letter"><b>K</b></a>
5114 &nbsp;
5115 <a href="#SEC40_21" class="summary-letter"><b>L</b></a>
5116 &nbsp;
5117 <a href="#SEC40_22" class="summary-letter"><b>M</b></a>
5118 &nbsp;
5119 <a href="#SEC40_23" class="summary-letter"><b>N</b></a>
5120 &nbsp;
5121 <a href="#SEC40_24" class="summary-letter"><b>O</b></a>
5122 &nbsp;
5123 <a href="#SEC40_25" class="summary-letter"><b>P</b></a>
5124 &nbsp;
5125 <a href="#SEC40_26" class="summary-letter"><b>Q</b></a>
5126 &nbsp;
5127 <a href="#SEC40_27" class="summary-letter"><b>R</b></a>
5128 &nbsp;
5129 <a href="#SEC40_28" class="summary-letter"><b>S</b></a>
5130 &nbsp;
5131 <a href="#SEC40_29" class="summary-letter"><b>T</b></a>
5132 &nbsp;
5133 <a href="#SEC40_30" class="summary-letter"><b>U</b></a>
5134 &nbsp;
5135 <a href="#SEC40_31" class="summary-letter"><b>V</b></a>
5136 &nbsp;
5137 <a href="#SEC40_32" class="summary-letter"><b>W</b></a>
5138 &nbsp;
5139 <a href="#SEC40_33" class="summary-letter"><b>Z</b></a>
5140 &nbsp;
5141 </td></tr></table>
5142
5143 <hr size="6">
5144 <a name="SEC_Contents"></a>
5145 <table cellpadding="1" cellspacing="1" border="0">
5146 <tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
5147 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
5148 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
5149 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
5150 </tr></table>
5151 <h1>Table of Contents</h1>
5152 <div class="contents">
5153
5154 <ul class="toc">
5155 <li><a name="TOC1" href="#SEC1">1. Library Copying and Licensing Conditions</a></li>
5156 <li><a name="TOC2" href="#SEC2">2. Description of Features and How to Get Started</a>
5157 <ul class="toc">
5158 <li><a name="TOC3" href="#SEC3">2.1 How to Install the Library</a></li>
5159 <li><a name="TOC4" href="#SEC4">2.2 Getting Started with the Library</a></li>
5160 <li><a name="TOC5" href="#SEC5">2.3 Basic Description of Terms and Functions</a>
5161 <ul class="toc">
5162 <li><a name="TOC6" href="#SEC6">2.3.1 General Memory Terms and Concepts</a></li>
5163 <li><a name="TOC7" href="#SEC7">2.3.2 Functionality Supported by All Malloc Libraries</a></li>
5164 </ul></li>
5165 <li><a name="TOC8" href="#SEC8">2.4 General Features of the Library</a></li>
5166 <li><a name="TOC9" href="#SEC9">2.5 How the Library Checks Your Program</a></li>
5167 </ul></li>
5168 <li><a name="TOC10" href="#SEC10">3. How to Program with the Library</a>
5169 <ul class="toc">
5170 <li><a name="TOC11" href="#SEC11">3.1 Macros Providing File and Line Information</a></li>
5171 <li><a name="TOC12" href="#SEC12">3.2 Getting Caller Address Information</a></li>
5172 <li><a name="TOC13" href="#SEC13">3.3 Checking of Function Arguments</a></li>
5173 <li><a name="TOC14" href="#SEC14">3.4 Generating a Core File on Errors</a></li>
5174 <li><a name="TOC15" href="#SEC15">3.5 Additional Non-standard Routines</a></li>
5175 <li><a name="TOC16" href="#SEC16">3.6 Description of the Internal Error Codes</a></li>
5176 <li><a name="TOC17" href="#SEC17">3.7 How to Disable the library</a></li>
5177 <li><a name="TOC18" href="#SEC18">3.8 Using the Library with C++</a></li>
5178 <li><a name="TOC19" href="#SEC19">3.9 Using Dmalloc With a Debugger</a>
5179 <ul class="toc">
5180 <li><a name="TOC20" href="#SEC20">3.9.1 Diagnosing General Problems with a Debugger</a></li>
5181 <li><a name="TOC21" href="#SEC21">3.9.2 Tracking Down Non-Freed Memory</a></li>
5182 <li><a name="TOC22" href="#SEC22">3.9.3 Diagnosing Fence-Post Overwritten Memory</a></li>
5183 <li><a name="TOC23" href="#SEC23">3.9.4 Translating Return Addresses into Code Locations</a></li>
5184 </ul></li>
5185 <li><a name="TOC24" href="#SEC24">3.10 Using the Library with a Thread Package</a></li>
5186 <li><a name="TOC25" href="#SEC25">3.11 Using the library with Cygwin environment.</a></li>
5187 <li><a name="TOC26" href="#SEC26">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></li>
5188 <li><a name="TOC27" href="#SEC27">3.13 Explanation of the Logfile Output</a></li>
5189 <li><a name="TOC28" href="#SEC28">3.14 Various Other Hints That May Help</a></li>
5190 </ul></li>
5191 <li><a name="TOC29" href="#SEC29">4. Dmalloc Utility Program</a>
5192 <ul class="toc">
5193 <li><a name="TOC30" href="#SEC30">4.1 Using a Shell Alias with the Utility</a></li>
5194 <li><a name="TOC31" href="#SEC31">4.2 How to Use the Dmalloc Program</a></li>
5195 <li><a name="TOC32" href="#SEC32">4.3 Environment Variable Name and Features</a></li>
5196 <li><a name="TOC33" href="#SEC33">4.4 Description of the Debugging Tokens</a></li>
5197 <li><a name="TOC34" href="#SEC34">4.5 Format of the Runtime Configuration File</a></li>
5198 </ul></li>
5199 <li><a name="TOC35" href="#SEC35">5. Information on the Source Code</a>
5200 <ul class="toc">
5201 <li><a name="TOC36" href="#SEC36">5.1 Definition of Terms and other Information</a></li>
5202 <li><a name="TOC37" href="#SEC37">5.2 General Compatibility Concerns</a></li>
5203 <li><a name="TOC38" href="#SEC38">5.3 Issues Important for Porting the Library</a></li>
5204 </ul></li>
5205 <li><a name="TOC39" href="#SEC39">6. Some Solutions to Common Problems</a></li>
5206 <li><a name="TOC40" href="#SEC40">Index of Concepts</a></li>
5207 </ul>
5208 </div>
5209 <hr size="1">
5210 <a name="SEC_About"></a>
5211 <table cellpadding="1" cellspacing="1" border="0">
5212 <tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of document">Top</a>]</td>
5213 <td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
5214 <td valign="middle" align="left">[<a href="#SEC40" title="Index">Index</a>]</td>
5215 <td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
5216 </tr></table>
5217 <h1>About This Document</h1>
5218 <p>
5219 This document was generated by <em>Gray Watson</em> on <em>May, 14 2007</em> using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
5220 </p>
5221 <p>
5222 The buttons in the navigation panels have the following meaning:
5223 </p>
5224 <table border="1">
5225 <tr>
5226 <th> Button </th>
5227 <th> Name </th>
5228 <th> Go to </th>
5229 <th> From 1.2.3 go to</th>
5230 </tr>
5231 <tr>
5232 <td align="center"> [ &lt; ] </td>
5233 <td align="center">Back</td>
5234 <td>previous section in reading order</td>
5235 <td>1.2.2</td>
5236 </tr>
5237 <tr>
5238 <td align="center"> [ &gt; ] </td>
5239 <td align="center">Forward</td>
5240 <td>next section in reading order</td>
5241 <td>1.2.4</td>
5242 </tr>
5243 <tr>
5244 <td align="center"> [ &lt;&lt; ] </td>
5245 <td align="center">FastBack</td>
5246 <td>beginning of this chapter or previous chapter</td>
5247 <td>1</td>
5248 </tr>
5249 <tr>
5250 <td align="center"> [ Up ] </td>
5251 <td align="center">Up</td>
5252 <td>up section</td>
5253 <td>1.2</td>
5254 </tr>
5255 <tr>
5256 <td align="center"> [ &gt;&gt; ] </td>
5257 <td align="center">FastForward</td>
5258 <td>next chapter</td>
5259 <td>2</td>
5260 </tr>
5261 <tr>
5262 <td align="center"> [Top] </td>
5263 <td align="center">Top</td>
5264 <td>cover (top) of document</td>
5265 <td> &nbsp; </td>
5266 </tr>
5267 <tr>
5268 <td align="center"> [Contents] </td>
5269 <td align="center">Contents</td>
5270 <td>table of contents</td>
5271 <td> &nbsp; </td>
5272 </tr>
5273 <tr>
5274 <td align="center"> [Index] </td>
5275 <td align="center">Index</td>
5276 <td>index</td>
5277 <td> &nbsp; </td>
5278 </tr>
5279 <tr>
5280 <td align="center"> [ ? ] </td>
5281 <td align="center">About</td>
5282 <td>about (help)</td>
5283 <td> &nbsp; </td>
5284 </tr>
5285 </table>
5286
5287 <p>
5288 where the <strong> Example </strong> assumes that the current position is at <strong> Subsubsection One-Two-Three </strong> of a document of the following structure:
5289 </p>
5290
5291 <ul>
5292 <li> 1. Section One
5293 <ul>
5294 <li>1.1 Subsection One-One
5295 <ul>
5296 <li>...</li>
5297 </ul>
5298 </li>
5299 <li>1.2 Subsection One-Two
5300 <ul>
5301 <li>1.2.1 Subsubsection One-Two-One</li>
5302 <li>1.2.2 Subsubsection One-Two-Two</li>
5303 <li>1.2.3 Subsubsection One-Two-Three &nbsp; &nbsp;
5304 <strong>&lt;== Current Position </strong></li>
5305 <li>1.2.4 Subsubsection One-Two-Four</li>
5306 </ul>
5307 </li>
5308 <li>1.3 Subsection One-Three
5309 <ul>
5310 <li>...</li>
5311 </ul>
5312 </li>
5313 <li>1.4 Subsection One-Four</li>
5314 </ul>
5315 </li>
5316 </ul>
5317
5318 <hr size="1">
5319 <p>
5320 <font size="-1">
5321 This document was generated by <em>Gray Watson</em> on <em>May, 14 2007</em> using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
5322 </font>
5323 <br>
5324
5325 </p>
5326 </body>
5327 </html>