Debian Codegraph @

INSTALL

raw
1 -------------------------------------------------------------------------------
2
3 2.1 How to Install the Library
4 ==============================
5
6 To configure, compile, and install the library, follow these steps
7 carefully.
8
9 1. Make sure you have downloaded the latest version of the library
10 available from the home page at URL `http://dmalloc.com/'.
11
12 2. The release files have a `.tgz' file extension which means that
13 they are a tar'd gzip'd directory of files. You will need to
14 ungzip and then untar the release file into your source work
15 directory. You may have to rename the file to `.tar.gz' to get
16 some old zip programs to handle the file correctly.
17
18 3. You may want to edit or at least review the settings in
19 `settings.dist' to tune specific features of the library. The
20 `configure' script will copy this file to `settings.h' which is
21 where you should be adding per-architecture settings.
22
23 4. Type `sh ./configure' to configure the library. You may want to
24 first examine the `config.help' file for some information about
25 configure. You may want to use the `--disable-cxx' option if you
26 do not want the Makefile to build the C++ version of dmalloc. You
27 may want to use the `--enable-threads' option to build the
28 threaded version of dmalloc. You may want to use the
29 `--enable-shlib' option to build the shared versions of the
30 dmalloc libraries. `sh ./configure --help' lists the available
31 options to configure. Configure should generate the `Makefile'
32 and configuration files automatically.
33
34 5. You may want to examine the `Makefile' and `conf.h' files created
35 by configure to make sure it did its job correctly.
36
37 6. You might want to tune the settings in `settings.h' file to tune
38 the library to the local architecture. This file contains relevant
39 settings if you are using pthreads or another thread library.
40 *Note Using With Threads::. The `configure' script created this
41 file from the `settings.dist' file. Any permanent changes to these
42 settings should made to the `settings.dist' file. You then can run
43 `config.status' to re-create the `settings.h' file.
44
45 7. The `DMALLOC_SIZE' variable gets auto-configured in `dmalloc.h.2'
46 but it may not generate correct settings for all systems. You may
47 have to alter the definitions in this file to get things to stop
48 complaining when you go to compile about the size arguments to
49 malloc routines. Comments on this please.
50
51 8. Typing `make' should be enough to build `libdmalloc.a', and
52 `dmalloc' program. If it does not work, please see if there are
53 any notes in the contrib directory about your system-type. If not
54 and you figure your problem out, please send me some notes so
55 future users can profit from your experiences.
56
57 _NOTE_: You may experience some errors compiling some of the
58 `return.h' assembly macros which attempt to determine the callers
59 address for logging purposes. *Note Portability::. You may want
60 to first try disabling any compiler optimization flags. If this
61 doesn't work then you may need to disable the `USE_RETURN_MACROS'
62 variable in the `settings.h' file.
63
64 _NOTE_: The code is dependent on an ANSI-C compiler. If the
65 configure script gives the `WARNING' that you do not have an ANSI-C
66 compiler, you may still be able to add some sort of option to your
67 compiler to make it ANSI. If there such is an option, please send
68 it to the author so it can be added to the configure script.
69
70 9. If you use threads and did not add the `--enable-threads' argument
71 to configure, typing `make threads' should be enough to build
72 `libdmallocth.a' which is the threaded version of the library.
73 This may or may not work depending on the configuration scripts
74 ability to detect your local thread functionality. Feel free to
75 send me mail with improvements.
76
77 See the section of the manual on threads for more information about
78 the operation of the library with your threaded program. *Note
79 Using With Threads::.
80
81 10. If you have a C++ compiler installed, the library should have
82 automatically built `libdmallocxx.a' which is the C++ version of
83 the library. If it was not done automatically, you can build it by
84 typing `make cxx'. You should link this library into your C++
85 programs instead of `libdmalloc.a'. See the `dmallocc.cc' C++
86 file which contains basic code to overload the `new', `new[]',
87 `delete', and `delete[]' C++ operators. My apologies on the
88 minimal C++ support. I am still living in a mostly C world. Any
89 help improving this interface without sacrificing portability
90 would be appreciated.
91
92 11. Typing `make light' should build and run the `dmalloc_t' test
93 program through a set of light trials. By default this will
94 execute `dmalloc_t' 5 times - each time will execute 10,000 malloc
95 operations in a very random manner. Anal folks can type `make
96 heavy' to up the ante. Use `dmalloc_t --usage' for the list of all
97 `dmalloc_t' options.
98
99 12. Typing `make install' should install the `libdmalloc.a' library in
100 `/usr/local/lib', the `dmalloc.h' include file in
101 `/usr/local/include', and the `dmalloc' utility in
102 `/usr/local/bin'. You may also want to type `make installth' to
103 install the thread library into place and/or `make installcc' to
104 install the C++ library into place.
105
106 You may have specified a `--prefix=PATH' option to configure in
107 which case `/usr/local' will have been replaced with `PATH'.
108
109
110 See the "Getting Started" section to get up and running with the
111 library. *Note Getting Started::.
112
113
114 -------------------------------------------------------------------------------
115
116 2.2 Getting Started with the Library
117 ====================================
118
119 This section should give you a quick idea on how to get going.
120 Basically, you need to do the following things to make use of the
121 library:
122
123 1. Make sure you have downloaded the latest version of the library
124 available from the home page at URL `http://dmalloc.com/'.
125
126 2. Follow the installation instructions on how to configure, make,
127 and install the library (i.e. type: `make install'). *Note
128 Installation::.
129
130 3. You need to make sure that the library configuration and build
131 process above was able to locate one of the `on_exit' function,
132 `atexit' function, or had compiler destructor support. If one of
133 these functions or support is available then the dmalloc library
134 should be able to automatically shut itself down when the program
135 exits. This causes the memory statistics and unfreed information
136 to be dumped to the log file. However, if your system has none of
137 the above, then you will need to call `dmalloc_shutdown' yourself
138 before your program exits.
139
140 4. To get the dmalloc utility to work you need to add an alias for
141 dmalloc to your shell's runtime configuration file if supported.
142 The idea is to have the shell capture the dmalloc program's output
143 and adjust the environment.
144
145 After you add the alias to the shell config file you need to log
146 out and log back in to have it take effect, or you can execute the
147 appropriate command below on the command line directly. After you
148 setup the alias, if you enter `dmalloc runtime' and see any output
149 with DMALLOC_OPTIONS in it then the alias did not take effect.
150
151 Bash, ksh, and zsh (`http://www.zsh.org/') users should add the
152 following to their `.bashrc', `.profile', or `.zshrc' file
153 respectively (notice the `-b' option for bourne shell output):
154
155 function dmalloc { eval `command dmalloc -b $*`; }
156
157 If your shell does not support the `command' function then try:
158
159 function dmalloc { eval `\dmalloc -b $*`; }
160 or
161 function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
162
163 If you are still using csh or tcsh, you should add the following to
164 your `.cshrc' file (notice the `-C' option for c-shell output):
165
166 alias dmalloc 'eval `\dmalloc -C \!*`'
167
168 If you are using rc shell, you should add the following to your
169 `.rcrc' file (notice the `-R' option for rc-shell output):
170
171 fn dmalloc {eval `{/usr/local/bin/dmalloc $*}}
172
173 5. Although not necessary, you may want to include `dmalloc.h' in
174 your C files and recompile. This will allow the library to report
175 the file/line numbers of calls that generate problems. *Note
176 Allocation Macros::. It should be inserted at the _bottom_ of
177 your include files as to not conflict with wother includes. You
178 may want to ifdef it as well and compile with `cc -DDMALLOC ...':
179
180 /* other includes above ^^^ */
181
182 #ifdef DMALLOC
183 #include "dmalloc.h"
184 #endif
185
186 6. Another optional task is to compile all of your source with the
187 `dmalloc.h' with the `DMALLOC_FUNC_CHECK' compilation flag. This
188 willallow the library to check all of the arguments of a number of
189 common string and utility routines. *Note Argument Checking::.
190
191 cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
192
193 7. Link the dmalloc library into your program. The dmalloc library
194 should probably be placed at or near the end of the library list.
195
196 8. Enable the debugging features by typing `dmalloc -l logfile -i 100
197 low' (for example). You should not see any messages printed by
198 the dmalloc utility (see NOTE below). This will:
199
200 * Set the malloc logfile name to `logfile' (`-l logfile'). For
201 programs which change directories, you may want to specify the
202 full path to your logfile.
203
204 * Have the library check itself every 100 iterations (`-i 100').
205 This controls how fast your program will run. Larger numbers
206 check the heap less and so it will run faster. Lower numbers
207 will be more likely to catch memory problems.
208
209 * Enable a number of debug features (`low'). You can also try
210 `runtime' for minimal checking or `medium' or `high' for more
211 extensive heap verification.
212
213 * By default, the low, medium, and high values enable the
214 `error-abort' token which will cause the library to abort and
215 usually dump core immediately upon seeing an error. *Note
216 Dumping Core::. You can disable this feature by entering
217 `dmalloc -m error-abort' (-m for minus) to remove the
218 `error-abort' token and your program will just log errors and
219 continue.
220
221
222 `dmalloc --usage' will provide verbose usage info for the dmalloc
223 program. *Note Dmalloc Program::.
224
225 You may also want to install the `dmallocrc' file in your home
226 directory as `.dmallocrc'. This allows you to add your own
227 combination of debug tokens. *Note RC File::.
228
229 _NOTE_: The output from the dmalloc utility should be captured by
230 your shell. If you see a bunch of stuff which includes the string
231 `DMALLOC_OPTIONS' then the alias you should have created above is
232 not working and he environmental variables are not being set. Make
233 sure you've logged out and back in to have the alias take effect.
234
235 9. Run your program, examine the logfile that should have been
236 created by `dmalloc_shutdown', and use its information to help
237 debug your program.
238
239
240
241 File: dmalloc.info, Node: Allocation Basics, Next: Features, Prev: Getting Started, Up: Overview
242
243 2.3 Basic Description of Terms and Functions
244 ============================================
245
246 * Menu:
247
248 * Basic Definitions:: General memory terms and concepts.
249 * Malloc Functions:: Functionality supported by all malloc libs.
250
251
252 File: dmalloc.info, Node: Basic Definitions, Next: Malloc Functions, Prev: Allocation Basics, Up: Allocation Basics
253
254 2.3.1 General Memory Terms and Concepts
255 ---------------------------------------
256
257 Any program can be divided into 2 logical parts: text and data. Text is
258 the actual program code in machine-readable format and data is the
259 information that the text operates on when it is executing. The data,
260 in turn, can be divided into 3 logical parts according to where it is
261 stored: "static", "stack", and "heap".
262
263 Static data is the information whose storage space is compiled into
264 the program.
265
266 /* global variables are allocated as static data */
267 int numbers[10];
268
269 main()
270 {
271 ...
272 }
273
274 Stack data is data allocated at runtime to hold information used
275 inside of functions. This data is managed by the system in the space
276 called stack space.
277
278 void foo()
279 {
280 /* this local variable is stored on the stack */
281 float total;
282 ...
283 }
284
285 main()
286 {
287 foo();
288 }
289
290 Heap data is also allocated at runtime and provides a programmer with
291 dynamic memory capabilities.
292
293 main()
294 {
295 /* the address is stored on the stack */
296 char * string;
297 ...
298
299 /*
300 * Allocate a string of 10 bytes on the heap. Store the
301 * address in string which is on the stack.
302 */
303 string = (char *)malloc(10);
304 ...
305
306 /* de-allocate the heap memory now that we're done with it */
307 (void)free(string);
308 ...
309 }
310
311 It is the heap data that is managed by this library.
312
313 Although the above is an example of how to use the malloc and free
314 commands, it is not a good example of why using the heap for runtime
315 storage is useful.
316
317 Consider this: You write a program that reads a file into memory,
318 processes it, and displays results. You would like to handle files with
319 arbitrary size (from 10 bytes to 1.2 megabytes and more). One problem,
320 however, is that the entire file must be in memory at one time to do the
321 calculations. You don't want to have to allocate 1.2 megabytes when you
322 might only be reading in a 10 byte file because it is wasteful of system
323 resources. Also, you are worried that your program might have to handle
324 files of more than 1.2 megabytes.
325
326 A solution: first check out the file's size and then, using the
327 heap-allocation routines, get enough storage to read the entire file
328 into memory. The program will only be using the system resources
329 necessary for the job and you will be guaranteed that your program can
330 handle any sized file.
331
332
333 File: dmalloc.info, Node: Malloc Functions, Prev: Basic Definitions, Up: Allocation Basics
334
335 2.3.2 Functionality Supported by All Malloc Libraries
336 -----------------------------------------------------
337
338 All malloc libraries support 4 basic memory allocation commands. These
339 include "malloc", "calloc", "realloc", and "free". For more
340 information about their capabilities, check your system's manual pages
341 - in unix, do a `man 3 malloc'.
342
343 -- Function: void *malloc ( unsigned int SIZE )
344 Usage: `pnt = (type *)malloc(size)'
345
346 The malloc routine is the basic memory allocation routine. It
347 allocates an area of `size' bytes. It will return a pointer to
348 the space requested.
349
350
351 -- Function: void *calloc ( unsigned int NUMBER, unsigned intSIZE )
352 Usage: `pnt = (type *)calloc(number, size)'
353
354 The calloc routine allocates a certain `number' of items, each of
355 `size' bytes, and returns a pointer to the space. It is
356 appropriate to pass in a `sizeof(type)' value as the size argument.
357
358 Also, calloc nulls the space that it returns, assuring that the
359 memory is all zeros.
360
361
362 -- Function: void *realloc ( void *OLD_PNT, unsigned int NEW_SIZE )
363 Usage: `new_pnt = (type *)realloc(old_pnt, new_size)'
364
365 The realloc function expands or shrinks the memory allocation in
366 `old_pnt' to `new_size' number of bytes. Realloc copies as much
367 of the information from `old_pnt' as it can into the `new_pnt'
368 space it returns, up to `new_size' bytes. If there is a problem
369 allocating this memory, 0L will be returned.
370
371 If the `old_pnt' is 0L then realloc will do the equivalent of a
372 `malloc(new_size)'. If `new_size' is 0 and `old_pnt' is not 0L,
373 then it will do the equivalent of `free(old_pnt)' and will return
374 0L.
375
376
377 -- Function: void free ( void *PNT )
378 Usage: `free(pnt)'
379
380 The free routine releases allocation in `pnt' which was returned by
381 malloc, calloc, or realloc back to the heap. This allows other
382 parts of the program to re-use memory that is not needed anymore.
383 It guarantees that the process does not grow too big and swallow a
384 large portion of the system resources.
385
386
387 _WARNING_: there is a quite common myth that all of the space that
388 is returned by malloc libraries has already been cleared. _Only_ the
389 `calloc' routine will zero the memory space it returns.
390
391
392 File: dmalloc.info, Node: Features, Next: How It Works, Prev: Allocation Basics, Up: Overview
393
394 2.4 General Features of the Library
395 ===================================
396
397 The debugging features that are available in this debug malloc library
398 can be divided into a couple basic classifications:
399
400 file and line number information
401 One of the nice things about a good debugger is its ability to
402 provide the file and line number of an offending piece of code.
403 This library attempts to give this functionality with the help of
404 "cpp", the C preprocessor. *Note Allocation Macros::.
405
406 return-address information
407 To debug calls to the library from external sources (i.e. those
408 files that could not use the allocation macros), some facilities
409 have been provided to supply the caller's address. This address,
410 with the help of a debugger, can help you locate the source of a
411 problem. *Note Return Address::.
412
413 fence-post (i.e. bounds) checking
414 "Fence-post" memory is the area immediately above or below memory
415 allocations. It is all too easy to write code that accesses above
416 or below an allocation - especially when dealing with arrays or
417 strings. The library can write special values in the areas around
418 every allocation so it will notice when these areas have been
419 overwritten. *Note Fence-Post Overruns::.
420
421 _NOTE_: The library cannot notice when the program _reads_ from
422 these areas, only when it writes values. Also, fence-post checking
423 will increase the amount of memory the program allocates.
424
425 heap-constancy verification
426 The administration of the library is reasonably complex. If any
427 of the heap-maintenance information is corrupted, the program will
428 either crash or give unpredictable results.
429
430 By enabling heap-consistency checking, the library will run
431 through its administrative structures to make sure all is in
432 order. This will mean that problems will be caught faster and
433 diagnosed better.
434
435 The drawback of this is, of course, that the library often takes
436 quite a long time to do this. It is suitable to enable this only
437 during development and debugging sessions.
438
439 _NOTE_: the heap checking routines cannot guarantee that the tests
440 will not cause a segmentation-fault if the heap administration
441 structures are properly (or improperly if you will) overwritten.
442 In other words, the tests will verify that everything is okay but
443 may not inform the user of problems in a graceful manner.
444
445 logging statistics
446 One of the reasons why the debug malloc library was initially
447 developed was to track programs' memory usage - specifically to
448 locate "memory leaks" which are places where allocated memory is
449 never getting freed. *Note Memory Leaks::.
450
451 The library has a number of logging capabilities that can track
452 un-freed memory pointers as well as runtime memory usage, memory
453 transactions, administrative actions, and final statistics.
454
455 examining freed memory
456 Another common problem happens when a program frees a memory
457 pointer but goes on to use it again by mistake. This can lead to
458 mysterious crashes and unexplained problems.
459
460 To combat this, the library can write special values into a block
461 of memory after it has been freed. This serves two purposes: it
462 will make sure that the program will get garbage data if it trying
463 to access the area again, and it will allow the library to verify
464 the area later for signs of overwriting.
465
466 If any of the above debugging features detect an error, the library
467 will try to recover. If logging is enabled then an error will be
468 logged with as much information as possible.
469
470 The error messages that the library displays are designed to give the
471 most information for developers. If the error message is not
472 understood, then it is most likely just trying to indicate that a part
473 of the heap has been corrupted.
474
475 The library can be configured to quit immediately when an error is
476 detected and to dump a core file or memory-image. This can be examined
477 with a debugger to determine the source of the problem. The library
478 can either stop after dumping core or continue running. *Note Dumping
479 Core::.
480
481 _NOTE_: do not be surprised if the library catches problems with
482 your system's routines. It took me hours to finally come to the
483 conclusion that the localtime call, included in SunOS release 4.1,
484 overwrites one of its fence-post markers.
485
486
487 File: dmalloc.info, Node: How It Works, Prev: Features, Up: Overview
488
489 2.5 How the Library Checks Your Program
490 =======================================
491
492 This is one of the newer sections of the library implying that it is
493 incomplete. If you have any questions or issues that you'd like to see
494 handled here, please let me know.
495
496 The dmalloc library replaces the heap library calls normally found in
497 your system libraries with its own versions. When you make a call to
498 malloc (for example), you are calling dmalloc's version of the memory
499 allocation function. When you allocate memory with these functions, the
500 dmalloc library keeps track of a number of pieces of debugging
501 information about your pointer including: where it was allocated,
502 exactly how much memory was requested, when the call was made, etc..
503 This information can then be verified when the pointer is freed or
504 reallocated and the details can be logged on any errors.
505
506 Whenever you reallocate or free a memory address, the dmalloc library
507 always performs a number of checks on the pointer to make sure that it
508 is valid and has not been corrupted. You can configure the library to
509 perform additional checks such as detected fence-post writing. The
510 library can also be configured to overwrite memory with non-zeros (only
511 if calloc is not called) when it is allocated and erase the memory when
512 the pointers are freed.
513
514 In addition to per-pointer checks, you can configure the library to
515 perform complete heap checks. These complete checks verify all
516 internal heap structures and include walking all of the known allocated
517 pointers to verify each one in turn. You need this level of checking
518 to find random pointers in your program which got corrupted but that
519 won't be freed for a while. To turn on these checks, you will need to
520 enable the `check-heap' debug token. *Note Debug Tokens::. By default
521 this will cause the heap to be fully checked each and every time
522 dmalloc is called whether it is a malloc, free, realloc, or another
523 dmalloc overloaded function.
524
525 Performing a full heap check can take a good bit of CPU and it may be
526 that you will want to run it sporadically. This can be accomplished in
527 a couple different ways including the '-i' interval argument to the
528 dmalloc utility. *Note Dmalloc Program::. This will cause the check to
529 be run every N-th time. For instance, 'dmalloc -i 3' will cause the
530 heap to be checked before every 3rd call to a memory function. Values
531 of 100 or even 1000 for high memory usage programs are more useful than
532 smaller ones.
533
534 You can also cause the program to start doing detailed heap checking
535 after a certain point. For instance, with 'dmalloc -s 1000' option, you
536 can tell the dmalloc library to enable the heap checks after the 1000th
537 memory call. Examine the dmalloc log file produced and use the
538 iteration count if you have `LOG_ITERATION_COUNT' enabled in your
539 `settings.h' file.
540
541 The start option can also have the format `file:line'. For
542 instance, if it is set to `dmalloc_t.c:126', dmalloc will start
543 checking the heap after it sees a dmalloc call from the `dmalloc_t.c'
544 file, line number 126. If you use `dmalloc_t.c:0', with a 0 line
545 number, then dmalloc will start checking the heap after it sees a call
546 from anywhere in the `dmalloc_t.c' file.
547
548
549 File: dmalloc.info, Node: Programming, Next: Dmalloc Program, Prev: Overview, Up: Top
550
551 3 How to Program with the Library
552 *********************************
553
554 * Menu:
555
556 * Allocation Macros:: Macros providing file and line information.
557 * Return Address:: Getting caller address information.
558 * Argument Checking:: Checking of function arguments.
559 * Dumping Core:: Generating a core file on errors for debugging.
560 * Extensions:: Additional non-standard routines.
561 * Error Codes:: Description of the internal error numbers.
562 * Disabling the Library:: How to disable the library.
563 * Using With C++:: Using the library with C++.
564 * Using With a Debugger:: Using a debugger with the library.
565 * Using With Threads:: Using the library with a thread package.
566 * Using With Cygwin:: Using the library with Cygwin environment.
567 * Debugging A Server:: Debugging memory in a server or cgi-bin process.
568 * Logfile Details:: Explanation of the Logfile Output.
569 * Other Hints:: Various other hints that may help.
570
571
572 File: dmalloc.info, Node: Allocation Macros, Next: Return Address, Prev: Programming, Up: Programming
573
574 3.1 Macros Providing File and Line Information
575 ==============================================
576
577 By including `dmalloc.h' in your C files, your calls to malloc, calloc,
578 realloc, recalloc, memalign, valloc, strdup, and free are replaced with
579 calls to _dmalloc_malloc, _dmalloc_realloc, and _dmalloc_free with
580 various flags. Additionally the library replaces calls to xmalloc,
581 xcalloc, xrealloc, xrecalloc, xmemalign, xvalloc, xstrdup, and xfree
582 with associated calls.
583
584 These macros use the c-preprocessor `__FILE__' and `__LINE__' macros
585 which get replaced at compilation time with the current file and
586 line-number of the source code in question. The routines use this
587 information to produce verbose reports on memory problems.
588
589 not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
590
591 This line from a log file shows that memory was not freed from file
592 `dmalloc_t.c' line 92. *Note Memory Leaks::.
593
594 You may notice some non standard memory allocation functions in the
595 above list. Recalloc is a routine like realloc that reallocates
596 previously allocated memory to a new size. If the new memory size is
597 larger than the old, recalloc initializes the new space to all zeros.
598 This may or may not be supported natively by your operating system.
599 Memalign is like malloc but should insure that the returned pointer is
600 aligned to a certain number of specified bytes. Currently, the memalign
601 function is not supported by the library. It defaults to returning
602 possibly non-aligned memory for alignment values less than a block-size.
603 Valloc is like malloc but insures that the returned pointer will be
604 aligned to a page boundary. This may or may not be supported natively
605 by your operating system but is fully supported by the library. Strdup
606 is a string duplicating routine which takes in a null terminated string
607 pointer and returns an allocated copy of the string that will need to be
608 passed to free later to deallocate.
609
610 The X versions of the standard memory functions (xmalloc, xfree,
611 etc.) will print out an error message to standard error and will stop
612 if the library is unable to allocate any additional memory. It is
613 useful to use these routines instead of checking everywhere in your
614 program for allocation routines returning NULL pointers.
615
616 _WARNING_: If you are including the `dmalloc.h' file in your
617 sources, it is recommended that it be at the end of your include file
618 list because dmalloc uses macros and may try to change declarations of
619 the malloc functions if they come after it.
620
621
622 File: dmalloc.info, Node: Return Address, Next: Argument Checking, Prev: Allocation Macros, Up: Programming
623
624 3.2 Getting Caller Address Information
625 ======================================
626
627 Even though the allocation macros can provide file/line information for
628 some of your code, there are still modules which either you can't
629 include `dmalloc.h' (such as library routines) or you just don't want
630 to. You can still get information about the routines that call dmalloc
631 function from the return-address information. To accomplish this, you
632 must be using this library on one of the supported
633 architecture/compilers. *Note Portability::.
634
635 The library attempts to use some assembly hacks to get the
636 return-address or the address of the line that called the dmalloc
637 function. If you have unfreed memory that does not have associated file
638 and line information, you might see the following non-freed memory
639 messages.
640
641 not freed: '0x38410' (22 bytes) from 'ra=0xdd2c'
642 not freed: '0x38600' (10232 bytes) from 'ra=0x10234d'
643 not freed: '0x38220' (137 bytes) from 'ra=0x82cc'
644
645 With the help of a debugger, these return-addresses (or ra) can then
646 be identified. I've provided a `ra_info.pl' perl script in the
647 `contrib/' directory with the dmalloc sources which seems to work well
648 with gdb. You can also use manual methods for gdb to find the
649 return-address location. *Note Translate Return Addresses::.
650
651
652 File: dmalloc.info, Node: Argument Checking, Next: Dumping Core, Prev: Return Address, Up: Programming
653
654 3.3 Checking of Function Arguments
655 ==================================
656
657 One potential problem with the library and its multitude of checks and
658 diagnoses is that they only get performed when a dmalloc function is
659 called. One solution this is to include `dmalloc.h' and compile your
660 source code with the `DMALLOC_FUNC_CHECK' flag defined and enable the
661 `check-funcs' token. *Note Debug Tokens::.
662
663 cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
664
665 _NOTE_: Once you have compiled your source with DMALLOC_FUNC_CHECK
666 enabled, you will have to recompile with it off to disconnect the
667 library. *Note Disabling the Library::.
668
669 _WARNING_: You should be sure to have `dmalloc.h' included at the
670 end of your include file list because dmalloc uses macros and may try
671 to change declarations of the checked functions if they come after it.
672
673 When this is defined dmalloc will override a number of functions and
674 will insert a routine which knows how to check its own arguments and
675 then call the real function. Dmalloc can check such functions as
676 `bcopy', `index', `strcat', and `strcasecmp'. For the full list see
677 the end of `dmalloc.h'.
678
679 When you call `strlen', for instance, dmalloc will make sure the
680 string argument's fence-post areas have not been overwritten, its file
681 and line number locations are good, etc. With `bcopy', dmalloc will
682 make sure that the destination string has enough space to store the
683 number of bytes specified.
684
685 For all of the arguments checked, if the pointer is not in the heap
686 then it is ignored since dmalloc does not know anything about it.
687
688
689 File: dmalloc.info, Node: Dumping Core, Next: Extensions, Prev: Argument Checking, Up: Programming
690
691 3.4 Generating a Core File on Errors
692 ====================================
693
694 If the `error-abort' debug token has been enabled, when the library
695 detects any problems with the heap memory, it will immediately attempt
696 to dump a core file. *Note Debug Tokens::. Core files are a complete
697 copy of the program and it's state and can be used by a debugger to see
698 specifically what is going on when the error occurred. *Note Using
699 With a Debugger::. By default, the low, medium, and high arguments to
700 the library utility enable the `error-abort' token. You can disable
701 this feature by entering `dmalloc -m error-abort' (-m for minus) to
702 remove the `error-abort' token and your program will just log errors
703 and continue. You can also use the `error-dump' token which tries to
704 dump core when it sees an error but still continue running. *Note
705 Debug Tokens::.
706
707 When a program dumps core, the system writes the program and all of
708 its memory to a file on disk usually named `core'. If your program is
709 called `foo' then your system may dump core as `foo.core'. If you are
710 not getting a `core' file, make sure that your program has not changed
711 to a new directory meaning that it may have written the core file in a
712 different location. Also insure that your program has write privileges
713 over the directory that it is in otherwise it will not be able to dump
714 a core file. Core dumps are often security problems since they contain
715 all program memory so systems often block their being produced. You
716 will want to check your user and system's core dump size ulimit
717 settings.
718
719 The library by default uses the `abort' function to dump core which
720 may or may not work depending on your operating system. If the
721 following program does not dump core then this may be the problem. See
722 `KILL_PROCESS' definition in `settings.dist'.
723
724 main()
725 {
726 abort();
727 }
728
729 If `abort' does work then you may want to try the following setting
730 in `settings.dist'. This code tries to generate a segmentation fault
731 by dereferencing a `NULL' pointer.
732
733 #define KILL_PROCESS { int *_int_p = 0L; *_int_p = 1; }
734
735
736 File: dmalloc.info, Node: Extensions, Next: Error Codes, Prev: Dumping Core, Up: Programming
737
738 3.5 Additional Non-standard Routines
739 ====================================
740
741 The library has a number of variables that are not a standard part of
742 most malloc libraries:
743
744 -- Variable: int dmalloc_errno
745 This variable stores the internal dmalloc library error number
746 like errno does for the system calls. It can be passed to
747 `dmalloc_strerror()' (see below) to get a string version of the
748 error. It will have a value of zero if the library has not
749 detected any problems.
750
751
752 -- Variable: char* dmalloc_logpath
753 This variable can be used to set the dmalloc log filename. The env
754 variable `DMALLOC_LOGFILE' overrides this variable.
755
756
757 Additionally the library provides a number of non-standard malloc
758 routines:
759
760 -- Function: void dmalloc_shutdown ( void )
761 This function shuts the library down and logs the final statistics
762 and information especially the non-freed memory pointers. The
763 library has code to support auto-shutdown if your system has the
764 `on_exit()' call, `atexit()' call, or compiler destructor support
765 (see `conf.h'). If you do not have these, then `dmalloc_shutdown'
766 should be called right before `exit()' or as the last function in
767 `main()'.
768
769 main()
770 {
771 ...
772 dmalloc_shutdown();
773 exit(0);
774 }
775
776 -- Function: int dmalloc_verify ( char * PNT )
777 This function verifies individual memory pointers that are suspect
778 of memory problems. To check the entire heap pass in a NULL or 0
779 pointer. The routine returns DMALLOC_VERIFY_ERROR or
780 DMALLOC_VERIFY_NOERROR.
781
782 _NOTE_: `dmalloc_verify()' can only check the heap with the
783 functions that have been enabled. For example, if fence-post
784 checking is not enabled, `dmalloc_verify()' cannot check the
785 fence-post areas in the heap.
786
787 -- Function: unsigned-int dmalloc_debug ( const unsigned int FLAGS )
788 This routine sets the debug functionality flags and returns the
789 previous flag value. It is helpful in server or cgi-bin programs
790 where environmental variables cannot be used. *Note Debugging A
791 Server::. For instance, if debugging should never be enabled for a
792 program, a call to `dmalloc_debug(0)' as the first call in
793 `main()' will disable all the memory debugging from that point on.
794
795 _NOTE_: you cannot add or remove certain flags such as signal
796 handlers since they are setup at initialization time only.
797
798 _NOTE_: you can also use `dmalloc_debug_setup' below.
799
800
801 -- Function: unsigned-int dmalloc_debug_current ( void )
802 This routine returns the current debug functionality value value.
803 This allows you to save a copy of the debug dmalloc settings to be
804 changed and then restored later.
805
806
807 -- Function: void dmalloc_debug_setup ( const char * OPTIONS_STR )
808 This routine sets the global debugging functionality as an option
809 string. Normally this would be passed in in the DMALLOC_OPTIONS
810 environmental variable. This is here to override the env or for
811 circumstances where modifying the environment is not possible or
812 does not apply such as servers or cgi-bin programs. *Note
813 Debugging A Server::.
814
815 Some examples:
816
817 /*
818 * debug tokens high, threaded lock-on at 20,
819 * log to dmalloc.%p (pid)
820 */
821 dmalloc_debug_setup("debug=0x4f46d03,lockon=20,log=dmalloc.%p");
822
823 /*
824 * turn on some debug tokens directly and log to the
825 * file 'logfile'
826 */
827 dmalloc_debug_setup(
828 "log-stats,log-non-free,check-fence,log=logfile");
829
830
831 -- Function: int dmalloc_examine ( const DMALLOC_PNT PNT, DMALLOC_SIZE
832 * USER_SIZE_P, DMALLOC_SIZE * TOTAL_SIZE_P, char ** FILE_P,
833 int * LINE_P, DMALLOC_PNT * RET_ADDR_P, unsigned long *
834 USER_MARK_P, unsigned long * SEEN_P )
835 This function returns the size of a pointer's allocation as well
836 as the total size given including administrative overhead, file
837 and line or the return-address from where it was allocated, the
838 last pointer when the pointer was "used", and the number of times
839 the pointer has been "seen". It will return DMALLOC_NOERROR or
840 DMALLOC_ERROR depending on whether pnt is good or not.
841
842 _NOTE_: This function is _certainly_ not provided by most if not
843 all other malloc libraries.
844
845
846 -- Function: void dmalloc_track ( const dmalloc_track_t TRACK_FUNC )
847 Register an allocation tracking function which will be called each
848 time an allocation occurs. Pass in NULL to disable. To take a
849 look at what information is provided, see the dmalloc_track_t
850 function typedef in dmalloc.h.
851
852
853 -- Function: unsigned-long dmalloc_mark ( void )
854 Return to the caller the current "mark" which can be used later to
855 log the pointers which have changed since this mark with the
856 `dmalloc_log_changed' function. Multiple marks can be saved and
857 used.
858
859 This is very useful when using the library with a server which does
860 not exit. You can then save a mark before a transaction or event
861 happens and then check to see what has changed using the
862 `dmalloc_log_changed' function below. *Note Debugging A Server::.
863
864 If you `LOG_ITERATION' enabled in your `settings.h' file then the
865 entries in the log file will be prepended with the number of memory
866 transactions that the library has handled so far. You can also
867 enable `LOG_PNT_ITERATION' in `settings.h' to store the memory
868 transaction number with each pointer.
869
870
871 -- Function: unsigned-long dmalloc_memory_allocated ( void )
872 Return to the caller the total number of bytes that have been
873 allocated by the library. This is not the current in use but the
874 total number of bytes returned by allocation functions.
875
876
877 -- Function: unsigned-int dmalloc_page_size ( void )
878 Return to the caller the memory page-size being used by the
879 library. This should be the same value as the one returned by the
880 `getpagesize()' function, if available.
881
882
883 -- Function: unsigned-long dmalloc_count_changed ( const unsigned long
884 MARK, const int NOT_FREED_B, const int FREE_B )
885 Count the pointers that have changed since the mark which was
886 returned by `dmalloc_mark'. If `not_freed_b' is set to non-0 then
887 count the pointers that have not been freed. If `free_b' is set
888 to non-0 then count the pointers that have been freed.
889
890 This can be used in conjunction with the `dmalloc_mark()' function
891 to help servers which never exit ensure that transactions or
892 events are not leaking memory. *Note Debugging A Server::.
893
894 unsigned long mark = dmalloc_mark() ;
895 ...
896 assert(dmalloc_count_changed(mark, 1, 0) == 0) ;
897
898
899 -- Function: void dmalloc_log_stats ( void )
900 This routine outputs the current dmalloc statistics to the log
901 file.
902
903 -- Function: void dmalloc_log_unfreed ( void )
904 This function logs the unfreed-memory information to the log file.
905 This is also useful to log the currently allocated points to the
906 log file to be compared against another dump later on.
907
908
909 -- Function: void dmalloc_log_changed ( const unsigned long MARK,
910 const int NOT_FREED_B, const int FREED_B, const int DETAILS_B
911 )
912 Log the pointers that have changed since the mark which was
913 returned by `dmalloc_mark'. If `not_freed_b' is set to non-0 then
914 log the pointers that have not been freed. If `free_b' is set to
915 non-0 then log the pointers that have been freed. If `details_b'
916 set to non-0 then log the individual pointers that have changed
917 otherwise just log the summaries.
918
919 This can be used in conjunction with the `dmalloc_mark()' function
920 to help servers which never exit find transactions or events which
921 are leaking memory. *Note Debugging A Server::.
922
923
924 -- Function: void dmalloc_vmessage ( const char * FORMAT, va_list ARGS
925 )
926 Write a message into the dmalloc logfile using vprintf-like
927 arguments.
928
929
930 -- Function: void dmalloc_message ( const char * FORMAT, ... )
931 Write a message into the dmalloc logfile using printf-like
932 arguments.
933
934
935 -- Function: void dmalloc_get_stats ( DMALLOC_PNT * HEAP_LOW_P,
936 DMALLOC_PNT * HEAP_HIGH_P, unsigned long * TOTAL_SPACE_P,
937 unsigned long * USER_SPACE_P, unsigned long *
938 CURRENT_ALLOCATED_P, unsigned long * CURRENT_PNT_NP, unsigned
939 long * MAX_ALLOCATED_P, unsigned long * MAX_PNT_NP, unsigned
940 long * MAX_ONE_P)
941 This function return a number of statistics about the current heap.
942 The pointers `heap_low_p' and `heap_high_p' will be set to the low
943 and high spots in the heap. `total_space_p' will be set to the
944 total space in the heap including user space, administrative
945 space, and overhead. `user_space_p' will be set to the space
946 given to the user process (allocated and free space).
947 `current_allocated_p' will be set to the current allocated space
948 given to the user process. `current_pnt_np' will be set to the
949 current number of pointers allocated by the user process.
950 `max_allocated_p' will be set to the maximum allocated space given
951 to the user process. `max_pnt_np' will be set to the maximum
952 number of pointers allocated by the user process. `max_on_p' will
953 be set to the maximum space allocated with one call by the user
954 process.
955
956
957 -- Function: const-char* dmalloc_strerror ( const int ERROR_NUMBER )
958 This function returns the string representation of the error value
959 in `error_number' (which probably should be dmalloc_errno). This
960 allows the logging of more verbose memory error messages.
961
962 You can also display the string representation of an error value
963 by a call to the `dmalloc' program with a `-e #' option. *Note
964 Dmalloc Program::.
965
966
967
968 File: dmalloc.info, Node: Error Codes, Next: Disabling the Library, Prev: Extensions, Up: Programming
969
970 3.6 Description of the Internal Error Codes
971 ===========================================
972
973 The following error codes are defined in `error_val.h'. They are used
974 by the library to indicate a detected problem. They can be caused by
975 the user (`ERROR_TOO_BIG') or can indicate an internal library problem
976 (`ERROR_SLOT_CORRUPT'). The `dmalloc' utility can give you the string
977 version of the error with the `-e' argument:
978
979 $ dmalloc -e 60
980 dmalloc: dmalloc_errno value '60' =
981 'pointer is not on block boundary'
982
983 Here are the error codes set by the library. They are non
984 contiguous on purpose because I add and delete codes all of the time
985 and there are sections for various error-code types.
986
987 `1 (ERROR_NONE) no error'
988 No error. It is good coding practice to set the no-error code to
989 be non-0 value because it forces you to set it explicitly.
990
991 `2 (INVALID_ERROR)'
992 Invalid error number. If the library outputs this error then your
993 dmalloc utility may be out of date with the library you linked
994 against. This will be returned with all error codes not listed
995 here.
996
997 `10 (ERROR_BAD_SETUP) initialization and setup failed'
998 Bad setup value. This is currently unused but it is intended to
999 report on invalid setup configuration information.
1000
1001 `11 (ERROR_IN_TWICE) malloc library has gone recursive'
1002 Library went recursive. This usually indicates that you are not
1003 using the threaded version of the library. Or if you are then you
1004 are not using the `-o' "lock-on" option. *Note Using With
1005 Threads::.
1006
1007 `13 (ERROR_LOCK_NOT_CONFIG) thread locking has not been configured'
1008 Thread locking has not been configured. This indicates that you
1009 attempted to use the `-o' "lock-on" option without linking with
1010 the thread version of the library. You should probably be using
1011 `-ldmallocth' _not_ `-ldmalloc' when you are linking. Or you
1012 should include `.../lib/libdmallocth.a' on your compilation line.
1013
1014 `20 (ERROR_IS_NULL) pointer is null'
1015 Pointer is null. The program passed a NULL (0L) pointer to `free'
1016 and you have the `error-free-null' token enabled.
1017
1018 `21 (ERROR_NOT_IN_HEAP) pointer is not pointing to heap data space'
1019 Pointer is not pointing to heap data space. This means that the
1020 program passed an out-of-bounds pointer to `free' or `realloc'.
1021 This could be someone trying to work with a wild pointer or trying
1022 to free a pointer from a different source than `malloc'.
1023
1024 `22 (ERROR_NOT_FOUND) cannot locate pointer in heap'
1025 Cannot locate pointer in heap. The user passed in a pointer which
1026 the heap did not know about. Either this pointer was allocated by
1027 some other mechanism (like `mmap' or `sbrk' directly) or it is a
1028 random invalid pointer.
1029
1030 In some rare circumstances, sometimes seen with shared libraries,
1031 there can be two separate copies of the dmalloc library in a
1032 program. Each one does not know about the pointers allocated by
1033 the other.
1034
1035 `23 (ERROR_IS_FOUND) found pointer the user was looking for'
1036 This indicates that the pointer specified in the address part of
1037 the environmental variable was discovered by the library. *Note
1038 Environment Variable::. This error is useful so you can put a
1039 breakpoint in a debugger to find where a particular address was
1040 allocated. *Note Using With a Debugger::.
1041
1042 `24 (ERROR_BAD_FILE) possibly bad .c filename pointer'
1043 A possibly invalid filename was discovered in the dmalloc
1044 administrative sections. This could indicate some corruption of
1045 the internal tables. It also could mean that you have a source
1046 file whose name is longer than 100 characters. See
1047 `MAX_FILE_LENGTH' in the `settings.dist' file.
1048
1049 `25 (ERROR_BAD_LINE) possibly bad .c file line-number'
1050 A line-number was out-of-bounds in the dmalloc administrative
1051 sections. This could indicate some corruption of the internal
1052 tables. It also could mean that you have a source file containing
1053 more than `30000' lines of code. See `MAX_LINE_NUMBER' in the
1054 `settings.dist' file.
1055
1056 `26 (ERROR_UNDER_FENCE) failed UNDER picket-fence magic-number check'
1057 This indicates that a pointer had its lower bound picket-fence
1058 magic number overwritten. If the `check-fence' token is enabled,
1059 the library writes magic values above and below allocations to
1060 protect against overflow. Most likely this is because a pointer
1061 below it went past its allocate and wrote into the next pointer's
1062 space.
1063
1064 `27 (ERROR_OVER_FENCE) failed OVER picket-fence magic-number check'
1065 This indicates that a pointer had its upper bound picket-fence
1066 magic space overwritten. If the `check-fence' token is enabled,
1067 the library writes magic values above and below allocations to
1068 protect against overflow. Most likely this is because an array or
1069 string allocation wrote past the end of the allocation.
1070
1071 Check for improper usage of `strcat', `sprintf', `strcpy', and any
1072 other functions which work with strings and do not protect
1073 themselves by tracking the size of the string. These functions
1074 should _always_ be replaced with: `strncat', `snprintf',
1075 `strncpy', and others.
1076
1077 `28 (ERROR_WOULD_OVERWRITE) use of pointer would exceed allocation'
1078 This error is generated by the function pointer checking code
1079 usually enabled with the `check-funcs' token. Dmalloc overloads a
1080 number of string and memory copying functions and verifies that
1081 the buffers (if allocated in the heap) would not be overwritten by
1082 the function.
1083
1084 `30 (ERROR_NOT_START_BLOCK) pointer is not to start of memory block'
1085 This indicates that the user passed in a pointer to be freed or
1086 reallocated that was not at the start of the allocation. You
1087 would get this error, for example, if you allocate and get pointer
1088 `X' but then try to free `X+1'.
1089
1090 `40 (ERROR_BAD_SIZE) invalid allocation size'
1091 This error indicates that a size value in the internal structures
1092 of the library were corrupted. This could be a random pointer
1093 problem, pointer overflow, or some other corruption.
1094
1095 `41 (ERROR_TOO_BIG) largest maximum allocation size exceeded'
1096 An allocation asked for memory larger than the configured maximum.
1097 This is a user configured setting. See `LARGEST_ALLOCATION' in
1098 the `settings.dist' file. It is used to protect against wild
1099 allocation sizes. If you have super large allocation sizes then
1100 you should tune the `LARGEST_ALLOCATION' value appropriately.
1101
1102 `43 (ERROR_ALLOC_FAILED) could not grow heap by allocating memory'
1103 The library could not allocate more heap space and the program has
1104 run out of memory. This could indicate that you've overflowed
1105 some system imposed limit. On many operation systems, the
1106 `ulimit' call can tune system defaults. The library uses a lot
1107 more memory compared to the system malloc library because it
1108 stores a lot more information about the allocated pointers.
1109
1110 _NOTE_: This also may be due to an inability of your operating
1111 system to use the `mmap' system call to allocate memory. You may
1112 need to force the `USE_MMAP' setting to be 0. Please use the
1113 forums at URL `http://dmalloc.com/' to report issues with this.
1114
1115 `45 (ERROR_OVER_LIMIT) over user specified allocation limit'
1116 The library has allocated more memory than was specified in the
1117 memory-limit environmental variable. *Note Environment Variable::.
1118
1119 `60 (ERROR_NOT_ON_BLOCK) pointer is not on block boundary'
1120 The user tried to free or realloc a pointer that was not pointing
1121 to a block boundary. You would get this error, for example, if
1122 you allocate and get pointer `X' but then try to free `X+1'.
1123
1124 `61 (ERROR_ALREADY_FREE) tried to free previously freed pointer'
1125 The user tried to free a pointer than has already been freed.
1126 This is a very common mistake and can lead to serious problems.
1127 It can be because a destructor is being called twice for some
1128 reason. Although tracking down the specific source is highly
1129 recommended, it is good to set pointers to NULL (0L) after you
1130 free them as a rule.
1131
1132 `67 (ERROR_FREE_OVERWRITTEN) free space has been overwritten'
1133 If either the `free-blank' or `check-blank' tokens are enabled
1134 then the library will overwrite memory when it is freed with the
1135 "dmalloc-free" byte (hex 0xdf, octal 0337, decimal 223). If the
1136 program writes into this space, then the library will detect the
1137 write and trigger this error. This could indicate that the
1138 program is using a pointer after it has been freed.
1139
1140 `70 (ERROR_ADMIN_LIST) bad admin structure list'
1141 An internal corruption in the library's administrative structures
1142 has been detected. This could be a random pointer problem, pointer
1143 overflow, or some other corruption.
1144
1145 `72 (ERROR_ADDRESS_LIST) internal address list corruption'
1146 An internal corruption in the library's administrative structures
1147 has been detected. This could be a random pointer problem, pointer
1148 overflow, or some other corruption.
1149
1150 `73 (ERROR_SLOT_CORRUPT) internal memory slot corruption'
1151 An internal corruption in the library's administrative structures
1152 has been detected. This could be a random pointer problem, pointer
1153 overflow, or some other corruption.
1154
1155
1156
1157 File: dmalloc.info, Node: Disabling the Library, Next: Using With C++, Prev: Error Codes, Up: Programming
1158
1159 3.7 How to Disable the library
1160 ==============================
1161
1162 If you would like to disable the library's detailed checking features
1163 during a particularly allocation intensive section of code, you can do
1164 something like the following:
1165
1166 unsigned int dmalloc_flags;
1167 ...
1168 /* turn off all debug flags and save a copy of old value */
1169 dmalloc_flags = dmalloc_debug(0);
1170
1171 /* section of a lot of allocations */
1172 ...
1173 /* end of section */
1174
1175 /* restore the dmalloc flag setting */
1176 dmalloc_debug(dmalloc_flags);
1177
1178 When you are finished with the development and debugging sessions,
1179 you may want to disable the dmalloc library and put in its place either
1180 the system's memory-allocation routines, gnu-malloc, or maybe your own.
1181 Attempts have been made to make this a reasonably painless process. The
1182 ease of the extraction depends heavily on how many of the library's
1183 features your made use of during your coding.
1184
1185 Reasonable suggestions are welcome as to how to improve this process
1186 while maintaining the effectiveness of the debugging.
1187
1188 * If you want to _totally_ disable the dmalloc library then you will
1189 need to recompile all the C files that include `dmalloc.h' while
1190 defining `DMALLOC_DISABLE'. This will cause the dmalloc macros to
1191 not be applied. *Note Allocation Macros::.
1192
1193 cc -g -DDMALLOC_DISABLE file.c
1194
1195 An alternative is to surround the `dmalloc.h' inclusion or any
1196 direct dmalloc references with an `#ifdef DMALLOC' and then just
1197 remove the -DDMALLOC.
1198
1199 #ifdef DMALLOC
1200 #include "dmalloc.h"
1201 #endif
1202
1203 main()
1204 {
1205 ...
1206
1207 #ifdef DMALLOC
1208 dmalloc_verify(0L);
1209 #endif
1210 return 0;
1211 }
1212
1213 // to get dmalloc information
1214 $ cc -DDMALLOC main.c
1215
1216 // without dmalloc information
1217 $ cc main.c
1218
1219 * If you compiled any of your source modules with
1220 `DMALLOC_FUNC_CHECK' defined then you must first recompile all
1221 those modules without the flag enabled.
1222
1223 If you have disabled dmalloc with the `DMALLOC_DISABLED' flag or
1224 never included `dmalloc.h' in any of your C files, then you will
1225 not need to recompile your sources when you need to disable the
1226 library.
1227
1228 If you get unresolved references like `_dmalloc_malloc' or
1229 `_dmalloc_bcopy' then something was not disabled as it should have
1230 been.
1231
1232
1233 File: dmalloc.info, Node: Using With C++, Next: Using With a Debugger, Prev: Disabling the Library, Up: Programming
1234
1235 3.8 Using the Library with C++
1236 ==============================
1237
1238 For those people using the C++ language, the library tries to configure
1239 and build `libdmallocxx.a' library. This library should be linked into
1240 your C++ programs instead of `libdmalloc.a'.
1241
1242 Dmalloc is not as good with C++ as C because the dynamic memory
1243 routines in C++ are `new()' and `delete()' as opposed to `malloc()' and
1244 `free()'. Since new and delete are usually not used as functions but
1245 rather as `x = new type', there is no easy way for dmalloc to pass in
1246 file and line information unfortunately. The `libdmallocxx.a' library
1247 provides the file `dmallocc.cc' which effectively redirects `new' to
1248 the more familiar `malloc' and `delete' to the more familiar `free'.
1249
1250 _NOTE_: The author is not a C++ hacker so feedback in the form of
1251 other hints and ideas for C++ users would be much appreciated.
1252
1253
1254 File: dmalloc.info, Node: Using With a Debugger, Next: Using With Threads, Prev: Using With C++, Up: Programming
1255
1256 3.9 Using Dmalloc With a Debugger
1257 =================================
1258
1259 Here are a number of possible scenarios for using the dmalloc library to
1260 track down problems with your program.
1261
1262 You should first enable a logfile filename and turn on a set of debug
1263 features. You can use `dmalloc -l logfile low' to accomplish this. If
1264 you are interested in having the error messages printed to your
1265 terminal as well, enable the `print-messages' token by typing `dmalloc
1266 -p print-messages' afterwards. *Note Dmalloc Program::.
1267
1268 Now you can enter your debugger (I use the _excellent_ GNU debugger
1269 gdb), and put a break-point in `dmalloc_error()' which is the internal
1270 error routine for the library. When your program is run, it will stop
1271 there if a memory problem is detected.
1272
1273 If you are using GDB, I would recommend adding the contents of
1274 `dmalloc.gdb' in the `contrib' subdirectory to your `.gdbinit' file in
1275 your home directory. This enables the `dmalloc' command which will
1276 prompt you for the arguments to the dmalloc command and will set a
1277 break point in `dmalloc_error()' automatically.
1278
1279 If you are using shared libraries, you may want to execute the
1280 following commands initially to load in dmalloc and other library
1281 symbols:
1282
1283 (gdb) sharedlibrary
1284 (gdb) add-shared-symbol-files
1285
1286 * Menu:
1287
1288 * General Errors:: Diagnosing general problems with a debugger.
1289 * Memory Leaks:: Tracking down non-freed memory.
1290 * Fence-Post Overruns:: Diagnosing fence-post overwritten memory.
1291 * Translate Return Addresses:: Convert ra return-addresses into a location.
1292
1293
1294 File: dmalloc.info, Node: General Errors, Next: Memory Leaks, Prev: Using With a Debugger, Up: Using With a Debugger
1295
1296 3.9.1 Diagnosing General Problems with a Debugger
1297 -------------------------------------------------
1298
1299 If your program stops at the `dmalloc_error()' routine then one of a
1300 number of problems could be happening. Incorrect arguments could have
1301 been passed to a malloc call: asking for negative number of bytes,
1302 trying to realloc a non-heap pointer, etc.. There also could be a
1303 problem with the system's allocations: you've run out of memory, some
1304 other function in your program is using the heap allocation functions
1305 `mmap' or `sbrk', etc.. However, it is most likely that some code that
1306 has been executed was naughty.
1307
1308 To get more information about the problem, first print via the
1309 debugger the dmalloc_errno variable to get the library's internal error
1310 code. You can suspend your debugger and run `dmalloc -e
1311 value-returned-from-print' to get an English translation of the error.
1312 A number of the error messages are designed to indicate specific
1313 problems with the library administrative structures and may not be
1314 user-friendly.
1315
1316 If the problem was due to the arguments or system allocations then
1317 the source of the problem has been found. However, if some code did
1318 something wrong, you may have some more work to do to locate the actual
1319 problem. The `check-heap' token should be enabled and the interval
1320 setting disabled or set to a low value so that the library can find the
1321 problem as close as possible to its source. The code that was execute
1322 right before the library halted, can then be examined closely for
1323 irregularities. *Note Debug Tokens::, *Note Dmalloc Program::.
1324
1325 You may also want to put calls to `dmalloc_verify(0)' in your code
1326 before the section which generated the error. This should locate the
1327 problem faster by checking the library's structures at that point.
1328 *Note Extensions::.
1329
1330
1331 File: dmalloc.info, Node: Memory Leaks, Next: Fence-Post Overruns, Prev: General Errors, Up: Using With a Debugger
1332
1333 3.9.2 Tracking Down Non-Freed Memory
1334 ------------------------------------
1335
1336 So you've run your program, examined the log-file and discovered (to
1337 your horror) some un-freed memory. Memory leaks can become large
1338 problems since even the smallest and most insignificant leak can starve
1339 the program given the right circumstances.
1340
1341 not freed: '0x45008' (12 bytes) from 'ra=0x1f8f4'
1342 not freed: '0x45028' (12 bytes) from 'unknown'
1343 not freed: '0x45048' (10 bytes) from 'argv.c:1077'
1344 known memory not freed: 1 pointer, 10 bytes
1345 unknown memory not freed: 2 pointers, 24 bytes
1346
1347 Above you will see a sample of some non-freed memory messages from
1348 the logfile. In the first line the `0x45008' is the pointer that was
1349 not freed, the `12 bytes' is the size of the unfreed block, and the
1350 `ra=0x1f8f4' or return-address shows where the allocation originated
1351 from. *Note Translate Return Addresses::.
1352
1353 The systems which cannot provide return-address information show
1354 `unknown' instead, as in the 2nd line in the sample above.
1355
1356 The `argv.c:1077' information from the 3rd line shows the file and
1357 line number which allocated the memory which was not freed. This
1358 information comes from the calls from C files which included
1359 `dmalloc.h'. *Note Allocation Macros::.
1360
1361 At the bottom of the sample it totals the memory for you and breaks
1362 it down to known memory (those calls which supplied the file/line
1363 information) and unknown (the rest).
1364
1365 Often, you may allocate memory in via `strdup()' or another routine,
1366 so the logfile listing where in the `strdup' routine the memory was
1367 allocated does not help locate the true source of the memory leak - the
1368 routine that called `strdup'. Without a mechanism to trace the calling
1369 stack, there is no way for the library to see who the caller of the
1370 caller (so to speak) was.
1371
1372 However, there is a way to track down unfreed memory in this
1373 circumstance. You need to compile the library with `STORE_SEEN_COUNT'
1374 defined in `conf.h'. The library will then record how many times a
1375 pointer has been allocated or freed. It will display the unfreed
1376 memory as:
1377
1378 not freed: '0x45008|s3' (12 bytes) from 'ra=0x1f8f4'
1379
1380 The `STORE_SEEN_COUNT' option adds a `|s#' qualifier to the address.
1381 This means that the address in question was seen `#' many times. In
1382 the above example, the address `0x45008' was seen `3' times. The last
1383 time it was allocated, it was not freed.
1384
1385 How can a pointer be "seen" 3 times? Let say you `strdup' a string
1386 of 12 characters and get address `0x45008' - this is #1 time the
1387 pointer is seen. You then free the pointer (seen #2) but later
1388 `strdup' another 12 character string and it gets the `0x45008' address
1389 from the free list (seen #3).
1390
1391 So to find out who is allocating this particular 12 bytes the 3rd
1392 time, try `dmalloc -a 0x45008:3'. The library will stop the program the
1393 third time it sees the `0x45008' address. You then enter a debugger
1394 and put a break point at `dmalloc_error'. Run the program and when the
1395 breakpoint is reached you can examine the stack frame to determine who
1396 called `strdup' to allocate the pointer.
1397
1398 To not bother with the `STORE_SEEN_COUNT' feature, you can also run
1399 your program with the `never-reuse' token enabled. This token will
1400 cause the library to never reuse memory that has been freed. Unique
1401 addresses are always generated. This should be used with caution since
1402 it may cause your program to run out of memory.
1403
1404
1405 File: dmalloc.info, Node: Fence-Post Overruns, Next: Translate Return Addresses, Prev: Memory Leaks, Up: Using With a Debugger
1406
1407 3.9.3 Diagnosing Fence-Post Overwritten Memory
1408 ----------------------------------------------
1409
1410 For a definition of fence-posts please see the "Features" section.
1411 *Note Features::.
1412
1413 To detect fence-post overruns, you need to enable the `check-fence'
1414 token. *Note Debug Tokens::. This pads your allocations with some
1415 extra bytes at the front and the end and watches the space to make sure
1416 that they don't get overwritten. _NOTE:_ The library cannot detect if
1417 this space gets read, only written.
1418
1419 If you have encountered a fence-post memory error, the logfile
1420 should be able to tell you the offending address.
1421
1422 free: failed UNDER picket-fence magic-number checking:
1423 pointer '0x1d008' from 'dmalloc_t.c:427'
1424 Dump of proper fence-bottom bytes: '\e\253\300\300\e\253\300\300'
1425 Dump of '0x1d008'-8: '\e\253\300\300WOW!\003\001pforger\023\001\123'
1426
1427 The above sample shows that the pointer `0x1d008' has had its lower
1428 fence-post area overwritten. This means that the code wrote below the
1429 bottom of the address or above the address right below this one. In the
1430 sample, the string that did it was `WOW!'.
1431
1432 The library first shows you what the proper fence-post information
1433 should look like, and then shows what the pointer's bad information was.
1434 If it cannot print the character, it will display the value as `\ddd'
1435 where ddd are three octal digits.
1436
1437 By enabling the `check-heap' debugging token and assigning the
1438 interval setting to a low number, you should be able to locate
1439 approximately when this problem happened. *Note Debug Tokens::, *Note
1440 Dmalloc Program::.
1441
1442
1443 File: dmalloc.info, Node: Translate Return Addresses, Prev: Fence-Post Overruns, Up: Using With a Debugger
1444
1445 3.9.4 Translating Return Addresses into Code Locations
1446 ------------------------------------------------------
1447
1448 The following gdb commands help you translate the return-addresses (ra=)
1449 entries in the logfile into locations in your code. I've provided a
1450 `ra_info.pl' perl script in the `contrib/' directory with the dmalloc
1451 sources which seems to work well with gdb. But, if you need to do it
1452 manually, here are the commands in gdb to use.
1453
1454 # you may need to add the following commands to load in shared libraries
1455 (gdb) sharedlibrary
1456 (gdb) add-shared-symbol-files
1457
1458 (gdb) x 0x10234d
1459 0x10234d <_findbuf+132>: 0x7fffceb7
1460
1461 (gdb) info line *(0x82cc)
1462 Line 1092 of argv.c starts at pc 0x7540 and ends at 0x7550.
1463
1464 In the above example, gdb was used to find that the two non-freed
1465 memory pointers were allocated in `_findbuf()' and in file argv.c line
1466 1092 respectively. The `x address' (for examine) can always be used on
1467 the return-addresses but the `info line *(address)' will only work if
1468 that file was compiled using the `-g' option and has not been stripped.
1469 This limitation may not be true in later versions of gdb.
1470
1471
1472 File: dmalloc.info, Node: Using With Threads, Next: Using With Cygwin, Prev: Using With a Debugger, Up: Programming
1473
1474 3.10 Using the Library with a Thread Package
1475 ============================================
1476
1477 Threads are special operating system facilities which allow your
1478 programs to have multiple threads of execution (hence the name). In
1479 effect your program can be doing a number of things "at the same time".
1480 This allows you to take full advantage of modern operating system
1481 scheduling and multi-processor hardware. If I've already lost you or
1482 if any of the terminology below does not make sense, see manuals about
1483 POSIX threads (pthreads) before going any further. O'Reilly publishes
1484 a pretty good pthreads manual for example.
1485
1486 To use dmalloc with your threaded program, you will first need to
1487 make sure that you are linking with `libdmallocth.a' which is the
1488 threaded version of the library. The support for threads in dmalloc
1489 should be adequate for most if not all testing scenarios. It provides
1490 support for mutex locking itself to protect against race conditions that
1491 result in multiple simultaneous execution. One of the major problems is
1492 that most thread libraries uses malloc themselves. Since all of
1493 dmalloc's initialization happens when a call to malloc is made, we may
1494 be attempting to initialize or lock the mutex while the thread library
1495 is booting up. A very bad thing since thread libraries don't expect to
1496 recurse.
1497
1498 The solution to this problem is to have the library not initialize or
1499 lock its mutex variable until after a certain number of allocation calls
1500 have been completed. If the library does not wait before initializing
1501 the locks, the thread library will probably core dump. If it waits too
1502 long then it can't protect itself from multiple execution and it will
1503 abort or other bad things might happen. You adjust the number of times
1504 to wait at runtime with the `lock-on' option to the dmalloc program
1505 (for example `dmalloc -o 20'). *Note Dmalloc Program::. Times values
1506 between 5 and 30 are probably good although operating systems will vary
1507 significantly. You know its too low if your program immediately core
1508 dumps and too high if the dmalloc library says its gone recursive
1509 although with low values, you might get either problem.
1510
1511 An additional complexity is when we are initializing the lock before
1512 mutex locking around the library. As mentioned, the initialization
1513 itself may generate a malloc call causing the library to go recursive
1514 and the pthread library to possibly core dump. With the THREAD_INIT_LOCK
1515 setting defined in `settings.h', you can tune how many times before we
1516 start locking to try and initialize the mutex lock. It defaults to 2
1517 which seems to work for me. If people need to have this runtime
1518 configurable or would like to present an alternative default, please let
1519 me know.
1520
1521 So to use dmalloc with a threaded program, follow the following steps
1522 carefully.
1523
1524 1. Follow the installation instructions on how to configure, make,
1525 and install the library but make sure to add the
1526 `--enable-threads' argument to configure. *Note Installation::.
1527
1528 2. Typing `make' should be enough to build the threaded versions of
1529 the libraries including `libdmallocth.a'.
1530
1531 3. Link the dmalloc threaded library into your program. The dmalloc
1532 library should probably be placed at or near the end of the library
1533 list.
1534
1535 4. Enable the debugging options that you need by typing `dmalloc -l
1536 logfile -i 100 low' (for example). `dmalloc --usage' will provide
1537 verbose usage info for the dmalloc program. *Note Dmalloc
1538 Program::.
1539
1540 5. Enable the "lock-on" option (for example `dmalloc -o 20'). As
1541 explained above, you may have to try different values before
1542 getting it right. Values between 5 and 30 are probably good.
1543
1544 6. If you get a dmalloc error #13 `thread locking has not been
1545 configured' then you have not compiled you program with the
1546 threaded version of dmalloc or there was a problem building it.
1547
1548 7. If everything works, you should be able to run your program, have
1549 it not immediately crash, and the dmalloc library should not
1550 complain about recursion.
1551
1552
1553 If you have any specific questions or would like addition information
1554 posted in this section, please let me know. Experienced thread
1555 programmers only please.
1556
1557
1558 File: dmalloc.info, Node: Using With Cygwin, Next: Debugging A Server, Prev: Using With Threads, Up: Programming
1559
1560 3.11 Using the library with Cygwin environment.
1561 ===============================================
1562
1563 The Cygwin environment is a Linux-like environment for Windows. It
1564 provides Linux look and feel as well as a programming environment. See
1565 URL `http://www.cygwin.com/' for more details.
1566
1567 Cygwin uses the `GetEnvironmentVariableA' function to read in
1568 environmental variables instead of `getenv'. This functions are used
1569 to get the value of the `DMALLOC_OPTIONS' variable which sets the
1570 debugging options. *Note Environment Variable::.
1571
1572 As of right now, dmalloc is not detecting the
1573 `GetEnvironmentVariableA' function correctly so you may need to tune
1574 the `conf.h' file to get it to work. See the sections on
1575 `HAVE_GETENVIRONMENTVARIABLEA' and `GETENV_SAVE' settings. Feedback is
1576 welcome here.
1577
1578 If you still have problems reading in the environmental variables,
1579 you can work around this issue. You can add some code into the `main'
1580 function in your program to initialize the dmalloc flags yourself.
1581 Here is a code sample:
1582
1583 main(int argc, char **argv)
1584 {
1585 #ifdef DMALLOC
1586 /*
1587 * Get environ variable DMALLOC_OPTIONS and pass the settings string
1588 * on to dmalloc_debug_setup to setup the dmalloc debugging flags.
1589 */
1590 dmalloc_debug_setup(getenv("DMALLOC_OPTIONS"));
1591 #endif
1592
1593 /* rest of code in main starts here */
1594 ...
1595 }
1596
1597 The `#ifdef' is just a good idea. I means that when debugging with
1598 dmalloc you need to compile your code with `-DDMALLOC'. When you are
1599 done debugging you can remove the flag and the call to
1600 `dmalloc_debug_setup' will be removed.
1601
1602 Please let me know if there is a better way to do this.
1603
1604
1605 File: dmalloc.info, Node: Debugging A Server, Next: Logfile Details, Prev: Using With Cygwin, Up: Programming
1606
1607 3.12 Debugging Memory in a Server or Cgi-Bin Process
1608 ====================================================
1609
1610 There are some specified challenges when trying to debug allocations in
1611 processes which do not startup, run, and then shutdown. Server
1612 processes (often called daemons) are those that are started (often at
1613 system boot time) and run perpetually. Other processes which are
1614 difficult to debug are CGI programs which are spawned by web servers or
1615 when you want to start debugging inside of a child process.
1616
1617 1. Build your server or cgi-bin program with the dmalloc library like
1618 any other program. *Note Getting Started::.
1619
1620 2. Add code into your program to enable the library flags to perform
1621 the memory checks that you require. Since these programs often do
1622 not run from the command line, you cannot use the dmalloc utility
1623 program and modify the process environment. *Note Dmalloc
1624 Program::. The library provides a couple of functions to set the
1625 debugging flags when a program is running.
1626
1627 3. To set the memory debugging flags, use the `dmalloc_debug_setup'
1628 function which takes a string in the same format of the
1629 `DMALLOC_OPTIONS' environmental variable. *Note Environment
1630 Variable::. Use the dmalloc utility with the `-n' no-changes
1631 argument to see the appropriate settings for the `DMALLOC_OPTIONS'
1632 environmental variable.
1633
1634 > dmalloc -n -l logfile high
1635 Outputed:
1636 DMALLOC_OPTIONS=debug=0x4f4ed03,log=logfile
1637 export DMALLOC_OPTIONS
1638
1639 So if you want to turn on `high' debugging and log to the file
1640 `logfile' then you would copy the above `DMALLOC_OPTIONS' value
1641 into a call to `dmalloc_debug_setup'. Notice that I have
1642 surrounded the dmalloc code with an `#ifdef DMALLOC' so you'll
1643 have to compile using the `-DDMALLOC' flag.
1644
1645 main()
1646 {
1647 #ifdef DMALLOC
1648 /* set the 'high' flags */
1649 dmalloc_debug_setup("debug=0x4f47d03,log=logfile");
1650 #endif
1651 ...
1652 }
1653
1654 _Please note_ that the `dmalloc_debug_setup' function does not
1655 know about `high', `low', or other debug tokens but needs the
1656 actual flag values.
1657
1658 4. For earlier versions of the library (before 5.0.0) without
1659 `dmalloc_debug_setup', the `dmalloc_debug' function is available
1660 to set the flags directly, but it cannot adjust the logfile name
1661 and the other environment settings. You can use the dmalloc
1662 utility program to see what the numerical equivalent of the `high'
1663 token.
1664
1665 > dmalloc -n high
1666 Outputed:
1667 DMALLOC_OPTIONS=debug=0x4f4ed03
1668 export DMALLOC_OPTIONS
1669
1670 You can then take the `0x4f4ed03' hexadecimal number and call
1671 `dmalloc_debug' with that number.
1672
1673 main()
1674 {
1675 #ifdef DMALLOC
1676 /* set the 'high' flags */
1677 dmalloc_debug(0x4f4ed03);
1678 #endif
1679 ...
1680 }
1681
1682 5. Even with the settings enabled, you may have problems getting the
1683 logfile to be written if your program is running as `nobody' or
1684 another user without permissions for security reasons. This is
1685 especially true for cgi-bin programs. In this case you should
1686 specify a full path to your malloc logfile in a world writable
1687 directory (ex.
1688 `dmalloc_debug_setup("debug=0x4f47d03,log=/var/tmp/malloc");').
1689 Watch for programs which change into other directories and which
1690 may cause logfiles specified as relative or local paths to be
1691 dropped in other locations. You may always want to use a full
1692 path logfile.
1693
1694 6. Once you have your settings enabled and your log is being
1695 generated, you may now want to check out how your process is doing
1696 in terms of unfreed memory. Since it is not shutting down, the
1697 automatic unfreed log entries are not being dropped to the
1698 logfile. By using the `dmalloc_mark' and `dmalloc_log_changed'
1699 functions, you can set a mark point at a certain place inside of
1700 your program, and then later see whether there are any unfreed
1701 pointers since the mark.
1702
1703 main()
1704 {
1705 #ifdef DMALLOC
1706 /* set the 'high' flags */
1707 dmalloc_debug_setup("debug=0x4f47d03,log=logfile");
1708 #endif
1709
1710 while (1) {
1711 /* accept a connection from a client */
1712 accept_connection();
1713
1714 while (1) {
1715 #ifdef DMALLOC
1716 unsigned long mark;
1717 /* get the current dmalloc position */
1718 mark = dmalloc_mark() ;
1719 #endif
1720 /* process the connection */
1721 if (process_connection() != PROCESS_OK) {
1722 break;
1723 }
1724 #ifdef DMALLOC
1725 /*
1726 * log unfreed pointers that have been added to
1727 * the heap since mark
1728 */
1729 dmalloc_log_changed(mark,
1730 1 /* log unfreed pointers */,
1731 0 /* do not log freed pointers */,
1732 1 /* log each pnt otherwise summary */);
1733 #endif
1734 }
1735 /* close the connection with the client */
1736 close_connection();
1737 }
1738 ...
1739 }
1740
1741 Usually you would set the mark after the initializations and before
1742 each transaction is processed. Then for each transaction you can
1743 use `dmalloc_log_changed' to show the unfreed memory. *Note
1744 Extensions::.
1745
1746 7. You can also use the `dmalloc_log_stats' function to dump general
1747 information about the heap. Also, remember that you can use the
1748 `dmalloc_message' and `dmalloc_vmessage' routines to annotate the
1749 dmalloc logfile with details to help you debug memory problems.
1750 *Note Extensions::.
1751
1752
1753
1754 File: dmalloc.info, Node: Logfile Details, Next: Other Hints, Prev: Debugging A Server, Up: Programming
1755
1756 3.13 Explanation of the Logfile Output
1757 ======================================
1758
1759 Most of time you will be using the logfile output from library as the
1760 sole information source for diagnosing problems in and getting
1761 statistics for your program.
1762
1763 1098918225: 3: Dmalloc version 'Version 5.5.2'
1764 1098918225: 3: flags = 0x4f4e503, logfile '/tmp/dmalloc.log'
1765 1098918225: 3: interval = 500, addr = 0, seen # = 0, limit = 0
1766 1098918225: 3: starting time = 1098918225
1767 1098918225: 3: process pid = 32406
1768 1098918226: 4: WARNING: tried to free(0) from foo.c:708'
1769 1098918228: 20: *** free: at 'unknown' pnt '0xed310080|s2': \
1770 size 12, alloced at 'bar.c:102'
1771 1098918230: 50: ERROR: heap_check: free space was overwritten (err 67)
1772 1098918230: 50: error details: checking free pointer
1773 1098918230: 50: pointer '0x291c5' from 'unknown' prev access 'foo.c:787'
1774
1775 Here is a short example of some logfile information. Each of the
1776 lines are prefixed by the time (in epoch seconds since 1/1/1970) and
1777 the iteration or call count which is the number of times the library
1778 has been called from malloc, free, verify, etc.. In the above example,
1779 the first 5 log entries where written at epoch 1098918225 or `Wed Oct
1780 27 19:03:45 2004 EST' and they were generated by the 3rd call to the
1781 library. See the `settings.dist' file entries to tune what elements
1782 appear on each line: LOG_TIME_NUMBER, LOG_ITERATION, LOG_PID, etc..
1783 You can convert the epoch seconds to a date from the command line with
1784 the following perl code: `perl -e 'print localtime($ARGV[0])."\n";'
1785 epoch-seconds-number'
1786
1787 The first 5 lines of the sample logfile contain header information
1788 for all logfiles. They show the version number and URL for the library
1789 as well as all of the settings that the library is currently using.
1790 These settings are tuned using the dmalloc utility program. *Note
1791 Dmalloc Program::. The 5th line of is the process-id that generated
1792 the logfile.
1793
1794 The 6th line in the above example is what causes the logfile to be
1795 opened and the header to be written. It is a warning that tells you
1796 that you tried to free a 0L pointer at a certain location. You can
1797 disable these warnings by setting `ALLOW_FREE_NULL_MESSAGE' to 0 in
1798 `settings.dist'.
1799
1800 Line 7 is an example of a transaction log that you get when you
1801 enable the `log-trans' debug token. *Note Debug Tokens::. This line
1802 shows that a call to free was made from an unknown location. It is
1803 unknown because the file in question did not include `dmalloc.h' to get
1804 file/line-number information. The call to free was freeing the pointer
1805 address `0xed310080' which we have "seen" 2 times (s2). We saw the
1806 pointer when it was allocated and then we are seeing it again when it
1807 was freed. Because the library is reusing pointers (reclaiming freed
1808 memory) the seen count helps to track how many times a pointer was
1809 used. The last part of the line shows that the pointer to be freed was
1810 allocated by `bar.c' line 102.
1811
1812 Lines 8-10 is the next problem that the library caught and this one
1813 is an error. It happened 5 seconds from the start of the log
1814 (1098918230) and at the 50th call into the library. It shows that an
1815 allocation that had been freed then was overwritten. This may imply
1816 that someone tried to use memory after it was freed or that there was a
1817 loose pointer reference. The last two lines give more details about
1818 when the error was discovered, the address of the offending pointer,
1819 and when the pointer was previous accessed, in this case freed. To
1820 discover where this problem is happening, you can use a debugger.
1821 *Note Using With a Debugger::.
1822
1823
1824 File: dmalloc.info, Node: Other Hints, Prev: Logfile Details, Up: Programming
1825
1826 3.14 Various Other Hints That May Help
1827 ======================================
1828
1829 One of the problems that is often seen is that a program crashes in the
1830 `libc' memory code and you suspect a heap memory problem but both
1831 dmalloc and maybe valgrind don't show any problems. One of the big
1832 problems with debugging is that it is very difficult to do it without
1833 effecting how the program is run. Sometimes errors are due to subtle
1834 race conditions that are only seen when the program is running at full
1835 speed - not slowed down by debugging code.
1836
1837 This is especially true with threaded code which is often heavily
1838 affected when used with dmalloc and valgrind. Older versions of
1839 valgrid (maybe current) forced all threads into a single virtual system
1840 by design, which often masks reentrance bugs.
1841
1842 One way to work through these issues is to run with the library with
1843 very few debugging flags enabled. Many memory problems are fence-post
1844 areas so start with dmalloc checking just the fence post and error
1845 logging enabled:
1846
1847 dmalloc -d 0 -l dmalloc.log -p log-stats -p log-non-free -p check-fence -p check-funcs
1848
1849 This enabled a small number of checks and should cause your program
1850 to run at close to full speed. The library has never been optimized for
1851 speed so some performance penalties will be felt.
1852
1853
1854 File: dmalloc.info, Node: Dmalloc Program, Next: Source Code, Prev: Programming, Up: Top
1855
1856 4 Dmalloc Utility Program
1857 *************************
1858
1859 The dmalloc program is designed to assist in the setting of the
1860 environment variable `DMALLOC_OPTIONS'. *Note Environment Variable::.
1861 It is designed to print the shell commands necessary to make the
1862 appropriate changes to the environment. Unfortunately, it cannot make
1863 the changes on its own so the output from dmalloc should be sent
1864 through the `eval' shell command which will do the commands.
1865
1866 * Menu:
1867
1868 * Shell Alias:: Using a shell alias with the utility.
1869 * Utility Usage:: How to use the dmalloc program.
1870 * Environment Variable:: Environment variable name and features.
1871 * Debug Tokens:: Description of the debugging tokens.
1872 * RC File:: Format of the runtime configuration file.
1873
1874
1875 File: dmalloc.info, Node: Shell Alias, Next: Utility Usage, Prev: Dmalloc Program, Up: Dmalloc Program
1876
1877 4.1 Using a Shell Alias with the Utility
1878 ========================================
1879
1880 The dmalloc program is designed to assist in the setting of the
1881 environment variable `DMALLOC_OPTIONS'. *Note Environment Variable::.
1882 It is designed to print the shell commands necessary to make the
1883 appropriate changes to the environment. Unfortunately, it cannot make
1884 the changes on its own so the output from dmalloc should be sent
1885 through the `eval' shell command which will do the commands.
1886
1887 With shells that have aliasing or macro capabilities: csh, bash, ksh,
1888 tcsh, zsh, etc., setting up an alias to dmalloc to do the eval call is
1889 recommended. Bash, ksh, and zsh users should add the following to their
1890 `.bashrc', `.profile', or `.zshrc' file respectively (notice the `-b'
1891 option for bourne shell output):
1892
1893 function dmalloc { eval `command dmalloc -b $*`; }
1894
1895 If your shell does not support the `command' function then try:
1896
1897 function dmalloc { eval `\dmalloc -b $*`; }
1898 or
1899 function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
1900
1901 If you are _still_ using csh or tcsh, you should add the following
1902 to your `.cshrc' file (notice the `-C' option for c-shell output):
1903
1904 alias dmalloc 'eval `\dmalloc -C \!*`'
1905
1906 This allows the user to execute the dmalloc command as `dmalloc
1907 arguments'.
1908
1909 Users of versions of the Bourne shell (usually known as /bin/sh) that
1910 don't have command functions will need to send the output to a temporary
1911 file and the read it back in with the "." command:
1912
1913 $ dmalloc -b arguments ... > /tmp/out
1914 $ . /tmp/out
1915
1916 By the way, if you are looking for a shell, I heartily recommend
1917 trying out zsh. It is a bourne shell written from scratch with much
1918 the same features as tcsh without the csh crap.
1919
1920 _NOTE_: After you add the alias to the file you need to log out and
1921 log back in to have it take effect, or you can execute the above
1922 appropriate command on the command line. If you enter `dmalloc
1923 runtime' and see any output with DMALLOC_OPTIONS in it then the alias
1924 did not work.
1925
1926
1927 File: dmalloc.info, Node: Utility Usage, Next: Environment Variable, Prev: Shell Alias, Up: Dmalloc Program
1928
1929 4.2 How to Use the Dmalloc Program
1930 ==================================
1931
1932 The most basic usage for the program is `dmalloc [-bC] tag'. The `-b'
1933 or `-C' (either but not both flags used at a time) are for generating
1934 Bourne or C shell type commands respectively. dmalloc will try and use
1935 the `SHELL' environment variable to determine whether bourne or C shell
1936 commands should be generated but you may want to explicitly specify the
1937 correct flag.
1938
1939 The `tag' argument to dmalloc should match a line from the user's
1940 runtime configuration file or should be one of the built-in tags.
1941 *Note RC File::. If no tag is specified and no other option-commands
1942 used, dmalloc will display the current settings of the environment
1943 variable. It is useful to specify one of the verbose options when doing
1944 this.
1945
1946 To find out the usage for the debug malloc program try `dmalloc
1947 --usage-long'. The standardized usage message that will be displayed is
1948 one of the many features of the argv library included with this package.
1949
1950 It is available on the web at URL `http://256.com/sources/argv/'.
1951 See the documentation there for more information.
1952
1953 Here is a detailed list of the flags that can passed to dmalloc:
1954
1955 `-a address'
1956 Set the `addr' part of the `DMALLOC_OPTIONS' variable to address
1957 (or alternatively address:number).
1958
1959 `-b'
1960 Output Bourne shell type commands. Usually handled automagically.
1961
1962 `-C'
1963 Output C shell type commands. Usually handled automagically.
1964
1965 `-c'
1966 Clear/unset all of the settings not specified with other
1967 arguments. You can do this automatically when you set to a new
1968 tag with the `-r' option.
1969
1970 _NOTE_: clear will never unset the `debug' setting. Use `-d 0' or
1971 a tag to `none' to achieve this.
1972
1973 `-d bitmask'
1974 Set the `debug' part of the `DMALLOC_OPTIONS' env variable to the
1975 bitmask value which should be in hex. This is overridden (and
1976 unnecessary) if a tag is specified.
1977
1978 `-D'
1979 List all of the debug-tokens. Useful for finding a token to be
1980 used with the `-p' or `-m' options. Use with `-v' or `-V' verbose
1981 options.
1982
1983 `-e errno'
1984 Print the dmalloc error string that corresponds to the error number
1985 errno.
1986
1987 `-f filename'
1988 Use this configuration file instead of the RC file
1989 `$HOME/.dmallocrc'.
1990
1991 `-g'
1992 Output gdb type commands for using inside of the gdb debugger.
1993
1994 `-h (or --help)'
1995 Output a help message for the utility.
1996
1997 `-i number'
1998 Set the checking interval to number. If the `check-heap' token is
1999 enabled, this causes the library to only check the heap every Nth
2000 time which can _significantly_ increase the running speed of your
2001 program. If a problem is found, however, this limits your ability
2002 to determine when the problem occurred. Try values of 50 or 100
2003 initially.
2004
2005 `-k'
2006 Do not reset all of the settings when a tag is specified. This
2007 specifically overrides the `-r' option and is provided here to
2008 override `-r' if it has been added to the dmalloc alias.
2009
2010 `-l filename'
2011 Write the debugging output and other log-file information to the
2012 filename. Filename can include some of the following patterns
2013 which get expanded into strings:
2014
2015 `%h'
2016 Gets expanded into the hostname if the `gethostname()'
2017 function is available.
2018
2019 `%i'
2020 Gets expanded into the thread-id if the library has been
2021 configure to be used with threads. *Note Using With
2022 Threads::. See the end of the `settings.dist' file for
2023 settings which return the thread-id and convert it into a
2024 string.
2025
2026 `%p'
2027 Gets expanded into the process-id if the `getpid()' function
2028 is available.
2029
2030 `%t'
2031 Gets expanded into the time value in seconds if the `time()'
2032 function is available.
2033
2034 `%u'
2035 Gets expanded into the user-id number if the `getuid()'
2036 function is available.
2037
2038
2039 Some examples:
2040
2041 # logfile produced with pid extension:
2042 # logfile.8412 or logfile.31451
2043 dmalloc -l logfile.%p
2044
2045 # hostname and time extensions:
2046 # dmalloc-box1.foo.com-1055213240
2047 dmalloc -l dmalloc-%h-%t
2048
2049 # if threads enabled, have thread-id extension: log.thread32
2050 dmalloc -l log.thread%i
2051
2052 `-L'
2053 Write the debug-value into the environment not in hex but by
2054 individual debug-tokens in long form.
2055
2056 `-m token(s)'
2057 Remove (minus) the debug capabilities of token(s) from the current
2058 debug setting or from the selected tag (or `-d' value). Multiple
2059 `-m' options can be specified.
2060
2061 `-M limit'
2062 Set the memory allocation limit which will abort the program if the
2063 total memory allocations exceed this number of bytes. The limit
2064 can be a number with a k, m, or g at the end to indicate kilobyte,
2065 megabyte, and gigabyte respectively. Ex: 100k, 200m, 1g. If the
2066 limit is exceeded, this will generate an `ERROR_OVER_LIMIT' error.
2067 *Note Error Codes::.
2068
2069 `-n'
2070 Without changing the environment, output the commands resulting
2071 from the supplied options.
2072
2073 `-o times'
2074 Set the "lock-on" period which dictates to the threaded version of
2075 the library to not initialize or lock the mutex lock around the
2076 library until after a certain number of allocation calls have been
2077 made. Some number between 2 and 30 is probably good. See the
2078 "Using With Threads" section for more information about the
2079 operation of the library with threads. *Note Using With Threads::.
2080
2081 `-p token(s)'
2082 Add (plus) the debug capabilities of token(s) to the current debug
2083 setting or to the selected tag (or `-d' value). Multiple `-p'
2084 options can be specified.
2085
2086 `-r'
2087 Remove (unset) all settings when using a tag. This is useful when
2088 you are returning to a standard development tag and want the
2089 logfile, address, and interval settings to be cleared
2090 automatically. If you want this behavior by default, this can be
2091 put into the dmalloc alias.
2092
2093 `-R'
2094 Output rc shell type commands. This is not for the runtime
2095 configuration file but for the rc shell program.
2096
2097 `-s file:line'
2098 Set the `start' part of the `DMALLOC_OPTIONS' env variable to a
2099 file-name and line-number location in the source where the library
2100 should begin more extensive heap checking. The file and line
2101 numbers for heap transactions must be working for this option to
2102 be obeyed. This is used if you are trying to locate a problem and
2103 you want the extensive checking to not happen initially because
2104 it's too slow.
2105
2106 `-S number'
2107 Set the `start' part of the `DMALLOC_OPTIONS' env variable to an
2108 dmalloc mark number. The library will begin more extensive heap
2109 checking after this number of memory transactions. If you
2110 `LOG_ITERATION' enabled in your `settings.h' file then the entries
2111 in the log file will be prepended with the number of memory
2112 transactions that the library has handled so far. This number can
2113 be used to delay the start of the fine grained heap checking which
2114 can be very slow.
2115
2116 `--start-size size'
2117 Set the `start' part of the `DMALLOC_OPTIONS' env variable to a
2118 number of bytes. The library will begin more extensive heap
2119 checking after this amount of memory has been allocated by the
2120 library. This allows you to start the slow and detailed checking
2121 of the library later in the program execution. You can use
2122 patterns like 250m, 1g, or 102k to mean 250 megabytes, 1 gigabyte,
2123 and 102 kilobytes respectively.
2124
2125 `-t'
2126 List all of the tags in the rc-file. Use with `-v' or `-V'
2127 verbose options.
2128
2129 `-u (or --usage)'
2130 Output the usage information for the utility.
2131
2132 `-v'
2133 Give verbose output. Especially useful when dumping current
2134 settings or listing all of the tags.
2135
2136 `-V'
2137 Give very verbose output for outputting even more details about
2138 settings.
2139
2140 `--version'
2141 Output the version string for the utility. _Please note_ that the
2142 version of the library that is installed or has been linked into
2143 your application may be different from the utility version.
2144
2145
2146 If no arguments are specified, dmalloc dumps out the current settings
2147 that you have for the environment variable. For example:
2148
2149 Debug-Flags '0x40005c7' (runtime)
2150 Address 0x1f008, count = 3
2151 Interval 100
2152 Logpath 'malloc'
2153 Start-File not-set
2154
2155 With a -v option and no arguments, dmalloc dumps out the current
2156 settings in a verbose manner. For example:
2157
2158 Debug-Flags '0x40005c7' (runtime)
2159 log-stats, log-non-free, log-bad-space, check-fence, catch-null
2160 Address 0x1f008, count = 10
2161 Interval 100
2162 Logpath 'malloc'
2163 Start-File not-set
2164
2165 Here are some examples of dmalloc usage:
2166
2167 # start tough debugging, check the heap every 100 times,
2168 # send the log information to file 'logfile'
2169 dmalloc high -i 100 -l logfile
2170
2171 # find out what error code 20 is (from the logfile)
2172 dmalloc -e 20
2173
2174 # cause the library to halt itself when it sees the address 0x34238
2175 # for the 6th time.
2176 dmalloc -a 0x34238:6
2177
2178 # send the log information to file 'logfile' with the time in seconds
2179 # as an extension.
2180 dmalloc -l logfile.%t
2181
2182 # return to the normal 'runtime' settings and clear out all
2183 # other settings
2184 dmalloc -c runtime
2185
2186 # enable basic 'low' settings plus (-p) the logging of
2187 # transactions (log-trans) to file 'logfile'
2188 dmalloc low -p log-trans -l logfile
2189
2190 # print out the current settings with Very-verbose output
2191 dmalloc -V
2192
2193 # list the available debug malloc tokens with Very-verbose output
2194 dmalloc -DV
2195
2196 # list the available tags from the rc file with verbose output
2197 dmalloc -tv
2198
2199
2200 File: dmalloc.info, Node: Environment Variable, Next: Debug Tokens, Prev: Utility Usage, Up: Dmalloc Program
2201
2202 4.3 Environment Variable Name and Features
2203 ==========================================
2204
2205 An "environment variable" is a variable that is part of the user's
2206 working environment and is shared by all the programs. The
2207 `DMALLOC_OPTIONS' variable is used by the dmalloc library to enable or
2208 disable the memory debugging features, at runtime. _NOTE:_ you can
2209 also use the `dmalloc_debug_setup' function to set the option string.
2210 It can be set either by hand or with the help of the dmalloc program.
2211 *Note Dmalloc Program::.
2212
2213 To set it by hand, Bourne shell (sh, bash, ksh, or zsh) users should
2214 use:
2215
2216 DMALLOC_OPTIONS=value
2217 export DMALLOC_OPTIONS
2218
2219 C shell (csh or tcsh) users need to invoke:
2220
2221 setenv DMALLOC_OPTIONS value
2222
2223 The value in the above examples is a comma separated list of tokens
2224 each having a corresponding value. The tokens are described below:
2225
2226 `debug'
2227 This should be set to a value in hexadecimal which corresponds to
2228 the functionality token values added together. *Note Debug
2229 Tokens::. For instance, if the user wanted to enable the logging
2230 of memory transactions (value `0x008') and wanted to check
2231 fence-post memory (value `0x400') then `debug' should be set to
2232 `0x408' (`0x008' + `0x400').
2233
2234 _NOTE_: You don't have to worry about remembering all the hex
2235 values of the tokens because the dmalloc program automates the
2236 setting of this variable especially.
2237
2238 _NOTE_: You can also specify the debug tokens directly, separated
2239 by commas. *Note Debug Tokens::. If `debug' and the tokens are
2240 both used, the token values will be added to the debug value.
2241
2242 `lockon'
2243 Set this to a number which is the "lock-on" period. This dictates
2244 to the threaded version of the library to not initialize or lock
2245 the mutex lock around the library until after a certain number of
2246 allocation calls have been made. See the "Using With Threads"
2247 section for more information about the operation of the library
2248 with threads. *Note Using With Threads::.
2249
2250 `log'
2251 Set this to a filename so that if `debug' has logging enabled, the
2252 library can log transactions, administration information, and/or
2253 errors to the file so memory problems and usage can be tracked.
2254
2255 To get different logfiles for different processes, you can assign
2256 `log' to a string with `%d' in it (for instance `logfile.%d').
2257 This will be replaced with the pid of the running process (for
2258 instance `logfile.2451').
2259
2260 _WARNING_: it is easy to core dump any program with dmalloc, if
2261 you send in a format with arguments other than the one `%d'.
2262
2263 `addr'
2264 When this is set to a hex address (taken from the dmalloc log-file
2265 for instance) dmalloc will abort when it finds itself either
2266 allocating or freeing that address.
2267
2268 The address can also have an `:number' argument. For instance, if
2269 it was set it to `0x3e45:10', the library will kill itself the 10th
2270 time it sees address `0x3e45'. By setting the number argument to
2271 0, the program will never stop when it sees the address. This is
2272 useful for logging all activity on the address and makes it easier
2273 to track down specific addresses not being freed.
2274
2275 This works well in conjunction with the `STORE_SEEN_COUNT' option.
2276 *Note Memory Leaks::.
2277
2278 _NOTE_: dmalloc will also log all activity on this address along
2279 with a count.
2280
2281 `inter'
2282 By setting this to a number X, dmalloc will only check the heap
2283 every X times. This means a number of debugging features can be
2284 enabled while still running the program within a finite amount of
2285 time.
2286
2287 A setting of `100' works well with reasonably memory intensive
2288 programs. This of course means that the library will not catch
2289 errors exactly when they happen but possibly 100 library calls
2290 later.
2291
2292 `start'
2293 Set this to a number X and dmalloc will begin checking the heap
2294 after X times. This means the intensive debugging can be started
2295 after a certain point in a program.
2296
2297 `start' also has the format `file:line'. For instance, if it is
2298 set to `dmalloc_t.c:126' dmalloc will start checking the heap
2299 after it sees a dmalloc call from the `dmalloc_t.c' file, line
2300 number 126. If you use `dmalloc_t.c:0', with a 0 line number, then
2301 dmalloc will start checking the heap after it sees a call from
2302 anywhere in the `dmalloc_t.c' file.
2303
2304 This allows the intensive debugging to be started after a certain
2305 routine or file has been reached in the program.
2306
2307 Some examples are:
2308
2309 # turn on transaction and stats logging and set
2310 # 'logfile' as the log-file
2311 setenv DMALLOC_OPTIONS log-trans,log-stats,log=logfile
2312
2313 # enable debug flags 0x1f as well as heap-checking and
2314 # set the interval to be 100
2315 setenv DMALLOC_OPTIONS debug=0x1f,check-heap,inter=100
2316
2317 # enable 'logfile' as the log-file, watch for
2318 # address '0x1234', and start checking when we see
2319 # file.c line 123
2320 setenv DMALLOC_OPTIONS log=logfile,addr=0x1234,start=file.c:123
2321
2322
2323 File: dmalloc.info, Node: Debug Tokens, Next: RC File, Prev: Environment Variable, Up: Dmalloc Program
2324
2325 4.4 Description of the Debugging Tokens
2326 =======================================
2327
2328 The below tokens and their corresponding descriptions are for the
2329 setting of the debug library setting in the environment variable.
2330 *Note Environment Variable::. They should be specified in the user's
2331 `.dmallocrc' file. *Note RC File::.
2332
2333 Each token, when specified, enables a specific debugging feature.
2334 For instance, if you have the `log-stats' token enabled, the library
2335 will log general statistics to the logfile.
2336
2337 To get this information on the fly, use `dmalloc -DV'. This will
2338 print out the Debug tokens in Very-verbose mode. *Note Dmalloc
2339 Program::.
2340
2341 `none'
2342 No debugging functionality
2343
2344 `log-stats'
2345 Log general statistics when dmalloc_shutdown or dmalloc_log_stats
2346 is called.
2347
2348 `log-non-free'
2349 Log non-freed memory pointers when dmalloc_shutdown or
2350 dmalloc_log_unfreed is called.
2351
2352 `log-known'
2353 Log only known memory pointers that have not been freed. Pointers
2354 which do not have file/line or return-address information will not
2355 be logged.
2356
2357 `log-trans'
2358 Log general memory transactions (quite verbose).
2359
2360 `log-admin'
2361 Log administrative information (quite verbose).
2362
2363 `log-bad-space'
2364 Log actual bytes in and around bad pointers.
2365
2366 `log-nonfree-space'
2367 Log actual bytes in non-freed pointers.
2368
2369 `log-elapsed-time'
2370 Log elapsed-time for allocated pointers (see `conf.h').
2371
2372 `log-current-time'
2373 Log current-time for allocated pointers (see `conf.h').
2374
2375 `check-fence'
2376 Check fence-post memory areas.
2377
2378 `check-heap'
2379 Verify heap administrative structure.
2380
2381 `check-blank'
2382 Check to see if space that was blanked when a pointer was
2383 allocated or when it was freed has been overwritten. If this is
2384 enabled then it will enable `free-blank' and `alloc-blank'
2385 automatically.
2386
2387 `check-funcs'
2388 Check the arguments of some functions (mostly string operations)
2389 looking for bad pointers.
2390
2391 `check-shutdown'
2392 Check all of the pointers in the heap when the program exits.
2393
2394 `catch-signals'
2395 Shutdown the library automatically on SIGHUP, SIGINT, or SIGTERM.
2396 This will cause the library to dump its statistics (if requested)
2397 when you press control-c on the program (for example).
2398
2399 `realloc-copy'
2400 Always copy data to a new pointer when realloc.
2401
2402 `free-blank'
2403 Write special "dmalloc-free" byte (hexadecimal `0xdf', octal
2404 `0337', decimal `223') into space when it is freed. You can set
2405 this to be something else in the `settings.dist' file. This
2406 ensures that your program is not using memory after it has been
2407 freed. You can check to see if areas have been improperly
2408 overwritten with the `check-blank' token. If the free space has
2409 been overwritten, then `ERROR_FREE_OVERWRITTEN' is triggered.
2410 *Note Error Codes::.
2411
2412 `error-abort'
2413 Abort the program (and dump core) on errors. See `error-dump'
2414 below. *Note Dumping Core::.
2415
2416 `alloc-blank'
2417 Write special "dmalloc-alloc" byte (hexadecimal `0xda', octal
2418 `0332', decimal `218') into space when it is allocated. You can
2419 set this to be something else in the `settings.dist' file. If you
2420 are not using `calloc' this will overwrite the user space with the
2421 special bytes ensuring that your program is initializing its
2422 dynamic memory appropriately. Also, if you ask for 35 bytes and
2423 the library has to give you a block of 64 because of rounding
2424 issues, it will overwrite the extra memory with the special byte.
2425 You can then check to see if the extra areas have been improperly
2426 overwritten by enabling the `check-blank' token.
2427
2428 `print-messages'
2429 Log any errors and messages to the screen via standard-error.
2430
2431 `catch-null'
2432 Abort the program immediately if the library fails to get more heap
2433 space from the heap allocation routine `mmap' or `sbrk'.
2434
2435 `never-reuse'
2436 Have the heap never use space that has been used before and freed.
2437 *Note Memory Leaks::. _WARNING_: This should be used with caution
2438 since you may run out of heap space.
2439
2440 `error-dump'
2441 Dump core on error and then continue. Later core dumps overwrite
2442 earlier ones if the program encounters more than one error. See
2443 `error-abort' above. *Note Dumping Core::.
2444
2445 _NOTE_: This will only work if your system supports the `fork'
2446 system call and the configuration utility was able to fork without
2447 going recursive.
2448
2449 `error-free-null'
2450 By default the library will not generate an error when a program
2451 tries to free a NULL pointer. By enabling this token, you can
2452 change this behavior so an error is reported. See also the
2453 ALLOW_FREE_NULL and ALLOW_FREE_NULL_MESSAGE settings in the
2454 `settings.h' file to change the default behavior.
2455
2456
2457
2458 File: dmalloc.info, Node: RC File, Prev: Debug Tokens, Up: Dmalloc Program
2459
2460 4.5 Format of the Runtime Configuration File
2461 ============================================
2462
2463 By using a "RC File" (or runtime configuration file) you can alias tags
2464 to combinations of debug tokens. *Note Debug Tokens::.
2465
2466 _NOTE_: For beginning users, the dmalloc program has a couple of
2467 tags built into it so it is not necessary for you to setup a RC file:
2468
2469 `runtime'
2470 Enables basic runtime tests including fence-post checking, null
2471 handling, and logging of any errors.
2472
2473 `low'
2474 Runtime settings plus minimal checking of heap structures and
2475 overwriting of allocated and freed space.
2476
2477 `medium'
2478 Low settings plus checking of all heap structures on each memory
2479 call, always relocates block on realloc, and aborts on errors.
2480 You may want to use `-i' option to the dmalloc utility. *Note
2481 Dmalloc Program::.
2482
2483 `high'
2484 Medium settings plus checking of overwritten freed and allocated
2485 memory and checking of arguments to a number of common functions.
2486 You may want to use `-i' option to the dmalloc utility. *Note
2487 Dmalloc Program::.
2488
2489
2490 For expert users, a sample `dmallocrc' file has been provided but
2491 you are encouraged to roll your own combinations. The name of default
2492 rc-file is `$HOME/.dmallocrc'. The `$HOME' environment variable should
2493 be set by the system to point to your home-directory.
2494
2495 The file should contain lines in the general form of:
2496
2497 tag token1, token2, ...
2498
2499 `tag' is to be matched with the tag argument passed to the dmalloc
2500 program, while `token1, token2, ...' are debug capability tokens.
2501 *Note Dmalloc Program::, *Note Debug Tokens::.
2502
2503 A line can be finished with a `\' meaning it continues onto the next
2504 line. Lines beginning with `#' are treated as comments and are ignored
2505 along with empty lines.
2506
2507 Here is an example of a `.dmallocrc' file:
2508
2509 #
2510 # Dmalloc runtime configuration file for the debug malloc library
2511 #
2512
2513 # no debugging
2514 none none
2515
2516 # basic debugging
2517 debug1 log-stats, log-non-free, check-fence
2518
2519 # more logging and some heap checking
2520 debug2 log-stats, log-non-free, log-trans, \
2521 check-fence, check-heap, error-abort
2522
2523 # good utilities
2524 debug3 log-stats, log-non-free, log-trans, \
2525 log-admin, check-fence, check-heap, realloc-copy, \
2526 free-blank, error-abort
2527
2528 ...
2529
2530 For example, with the above file installed, you can type `dmalloc
2531 debug1' after setting up your shell alias. *Note Dmalloc Program::.
2532 This enables the logging of statistics, the logging of non-freed memory,
2533 and the checking of fence-post memory areas.
2534
2535 Enter `dmalloc none' to disable all memory debugging features.
2536
2537
2538 File: dmalloc.info, Node: Source Code, Next: Troubleshooting, Prev: Dmalloc Program, Up: Top
2539
2540 5 Information on the Source Code
2541 ********************************
2542
2543 * Menu:
2544
2545 * Definitions:: Definition of terms and other information.
2546 * Compatibility:: General compatibility concerns.
2547 * Portability:: Issues important for porting the library.
2548
2549
2550 File: dmalloc.info, Node: Definitions, Next: Compatibility, Prev: Source Code, Up: Source Code
2551
2552 5.1 Definition of Terms and other Information
2553 =============================================
2554
2555 Here are a couple definitions and other information for those interested
2556 in "picking the brain" of the library. The code is a little ugly here
2557 and there and it conforms to the Gray-Watson handbook of coding
2558 standards only.
2559
2560 "bblock"
2561 basic block containing 2 ^ BASIC_BLOCK bytes of info
2562
2563 "bblock_adm"
2564 administration for a set of basic blocks
2565
2566 "dblock"
2567 divided block containing some base 2 number of blocks smaller than
2568 a basic block.
2569
2570 "dblock_adm"
2571 administration for a set of divided blocks
2572
2573 "chunk"
2574 some anonymous amount of memory
2575
2576 For more information about administration structures, see the code
2577 and comments from `chunk_loc.h'.
2578
2579
2580 File: dmalloc.info, Node: Compatibility, Next: Portability, Prev: Definitions, Up: Source Code
2581
2582 5.2 General Compatibility Concerns
2583 ==================================
2584
2585 * Realloc() backwards compatibility with being able to realloc from
2586 the last freed block is _not_ supported. The author is interested
2587 to know who is using this (cough, cough) feature and for what
2588 reason.
2589
2590 * Realloc() of a NULL pointer is supported in which case the library
2591 will just make a call to malloc(). This can be disabled with the
2592 help of the `ALLOW_REALLOC_NULL' manual compilation option in the
2593 `settings.h' file to adjust the library's default behavior.
2594
2595 * Some systems allow free(0) to not be an error for some reason.
2596 Since 0 is not a valid address returned by the malloc call, it is
2597 debatable that this should be allowed. See `settings.h' for the
2598 `ALLOW_FREE_NULL' manual compilation option to adjust the
2599 library's default behavior.
2600
2601 * Aside from possibly being slower than the system's memory
2602 allocation functions, the library should be fully compatible with
2603 the standard memory routines. If this is _not_ the case, please
2604 bring this to my attention.
2605
2606
2607 File: dmalloc.info, Node: Portability, Prev: Compatibility, Up: Source Code
2608
2609 5.3 Issues Important for Porting the Library
2610 ============================================
2611
2612 General portability issues center around:
2613
2614 * mmap, sbrk, or compatible function usages. The library does
2615 support a preallocated memory chunk heap. See the
2616 `INTERNAL_MEMORY_SPACE' define in the `settings.dist' file.
2617
2618 * The locating of the caller's address from the dmalloc functions.
2619 This is useful in locating problems from dmalloc functions called
2620 from C files which did not include `dmalloc.h': C library calls for
2621 instance.
2622
2623 See `return.h' for the available architecture/compiler
2624 combinations. You may want to examine the assembly code from gcc
2625 (GNUs superior c-compiler) version 2+ being run on the following
2626 code. It should give you a good start on building a hack for your
2627 box.
2628
2629 static char * x;
2630
2631 a()
2632 {
2633 x = __builtin_return_address(0);
2634 }
2635
2636 main()
2637 {
2638 a();
2639 }
2640
2641
2642
2643 -------------------------------------------------------------------------------
2644
2645 6 Some Solutions to Common Problems
2646 ***********************************
2647
2648 This section provides some answers to some common problems and
2649 questions. Please send me mail with any additions to this list -
2650 either problems you are still having or tips that you would like to
2651 pass on.
2652
2653 When diagnosing a problem, if possible, always make sure you are
2654 running the most up to date version of Dmalloc available from the home
2655 page at URL `http://dmalloc.com/'. Problems are often fixed and a new
2656 release can be published before people encounter them.
2657
2658 `Why does my program run so slow?'
2659 This library has never been (and maybe never will be) optimized for
2660 space nor speed. Some of its features make it unable to use some
2661 of the organizational methods of other more efficient heap
2662 libraries.
2663
2664 If you have the `check-heap' token enabled, your program might run
2665 slow or seem to hang. This is because by default, the library
2666 will run a full check of the heap with every memory allocation or
2667 free. You can have the library check itself less frequently by
2668 using the `-i' option to the dmalloc utility. *Note Dmalloc
2669 Program::. If you are using the `high' token and you need your
2670 program to run faster, try the `medium' or `low' tokens which
2671 don't check as many heap features and so run faster although they
2672 will not catch as many problems. *Note RC File::.
2673
2674 `Why was a log-file not produced after I ran my program?'
2675 This could be caused by a number of different problems.
2676
2677 1. Are you sure you followed all of the items in the "Getting
2678 Started" section? Please review them if there is any doubt.
2679 *Note Getting Started::.
2680
2681 2. Use the `env' or `printenv' commands to make sure that the
2682 `DMALLOC_OPTIONS' variable is set in your exported
2683 environment. *Note Environment Variable::.
2684
2685 3. Make sure that your program has been compiled correctly with
2686 the dmalloc library. The `ident' program should show chunk.c
2687 and other dmalloc files compiled into your program. You can
2688 also do `strings -a your-program | grep chunk.c' and look for
2689 something like `$Id: chunk.c,v 1.152 1999/08/25 12:37:01 gray
2690 Exp $' with different versions and date information. If this
2691 doesn't show up then chances are dmalloc was not linked into
2692 your program.
2693
2694 4. If your program changes its working directory, it may write
2695 the dmalloc log-file somewhere else in the filesystem. You
2696 will need to check both where the program was started and to
2697 where it might change directory.
2698
2699 5. The logfile is only produced when `dmalloc_shutdown()' is
2700 called. By default it will be called when `exit()' gets
2701 called. If you are running your program and press
2702 `Control-C' under Unix the program will stop immediately and
2703 `dmalloc_shutdown()' will not get called. You can either
2704 setup a signal handler for `SIGINTR' and call exit yourself,
2705 or you can enable the `catch-signals' token. *Note Debug
2706 Tokens::.
2707
2708 6. If your program is segfaulting or otherwise crashing when it
2709 exits, the `exit()' routine may not being called. You will
2710 have to resolve these issues so the dmalloc library can
2711 gracefully exit and write its log file.
2712
2713 7. You may want to call `dmalloc_log_stats()' and
2714 `dmalloc_log_unfreed()' (or `dmalloc_log_changed()') directly
2715 to have the library write its log file. Some system modules
2716 may not have shutdown if you call this before `exit()' so
2717 extra unfreed memory may be reported.
2718
2719
2720 `I don't see any information about my non-freed (leaked) memory?'
2721 The library will not (by default) report on "unknown" non-freed
2722 memory. Unknown means memory that does not have associated file
2723 and line information.
2724
2725 This will be necessary if you are _not_ including `dmalloc.h' in
2726 all of your C files or if you are interested in tracking leaks in
2727 system functions.
2728
2729 `Dmalloc is returning the error "malloc library has gone recursive"'
2730 This most likely indicates that you are using the Dmalloc library
2731 within a threaded application and two threads are trying to use
2732 the dmalloc library at once. Please see the section of the manual
2733 about threads for more information about properly configuring the
2734 library. *Note Using With Threads::.
2735
2736 If you are not using threads, then your program could have caught a
2737 signal while within Dmalloc, which then in turn called a memory
2738 allocation routine. It is unwise to allocate memory on the heap
2739 in most signal handlers. Lastly, some functions called by the
2740 library may call memory routines that it does not anticipate. If
2741 you think this the case, please report the problem and include a
2742 stack trace, operating system version/type, and the version of
2743 Dmalloc you are using.
2744
2745
2746
2747 File: dmalloc.info, Node: Index of Concepts, Prev: Troubleshooting, Up: Top
2748
2749 Index of Concepts
2750 *****************
2751
2752 [index]
2753 * Menu:
2754
2755 * %h: Utility Usage. (line 89)
2756 * %i: Utility Usage. (line 93)
2757 * %p: Utility Usage. (line 100)
2758 * %t: Utility Usage. (line 104)
2759 * %u: Utility Usage. (line 108)
2760 * -disable-cxx: Installation. (line 23)
2761 * -enable-shlib: Installation. (line 23)
2762 * -enable-threads: Installation. (line 23)
2763 * .dmallocrc file: RC File. (line 6)
2764 * 0332 character: Debug Tokens. (line 94)
2765 * 0337 character: Debug Tokens. (line 80)
2766 * 0xda character: Debug Tokens. (line 94)
2767 * 0xdf character: Debug Tokens. (line 80)
2768 * 1, error code: Error Codes. (line 20)
2769 * 10, error code: Error Codes. (line 30)
2770 * 11, error code: Error Codes. (line 34)
2771 * 13, error code: Error Codes. (line 40)
2772 * 2, error code: Error Codes. (line 24)
2773 * 20, error code: Error Codes. (line 47)
2774 * 21, error code: Error Codes. (line 51)
2775 * 218 character: Debug Tokens. (line 94)
2776 * 22, error code: Error Codes. (line 57)
2777 * 223 character: Debug Tokens. (line 80)
2778 * 23, error code: Error Codes. (line 68)
2779 * 24, error code: Error Codes. (line 75)
2780 * 25, error code: Error Codes. (line 82)
2781 * 26, error code: Error Codes. (line 89)
2782 * 27, error code: Error Codes. (line 97)
2783 * 28, error code: Error Codes. (line 110)
2784 * 30, error code: Error Codes. (line 117)
2785 * 332 character: Debug Tokens. (line 94)
2786 * 337 character: Debug Tokens. (line 80)
2787 * 40, error code: Error Codes. (line 123)
2788 * 41, error code: Error Codes. (line 128)
2789 * 43, error code: Error Codes. (line 135)
2790 * 45, error code: Error Codes. (line 148)
2791 * 60, error code: Error Codes. (line 152)
2792 * 61, error code: Error Codes. (line 157)
2793 * 67, error code: Error Codes. (line 165)
2794 * 70, error code: Error Codes. (line 173)
2795 * 72, error code: Error Codes. (line 178)
2796 * 73, error code: Error Codes. (line 183)
2797 * abort: Dumping Core. (line 31)
2798 * address list error: Error Codes. (line 178)
2799 * address locating: Environment Variable.
2800 (line 65)
2801 * address setting: Environment Variable.
2802 (line 65)
2803 * admin list error: Error Codes. (line 173)
2804 * alias, shell <1>: Getting Started. (line 27)
2805 * alias, shell: Shell Alias. (line 13)
2806 * alloc failed error: Error Codes. (line 135)
2807 * alloc-blank: Debug Tokens. (line 94)
2808 * allocation basics: Allocation Basics. (line 6)
2809 * allocation macros: Allocation Macros. (line 6)
2810 * Allocation of zeros: Malloc Functions. (line 20)
2811 * ALLOW_FREE_NULL: Debug Tokens. (line 127)
2812 * ALLOW_FREE_NULL settings.h option: Compatibility. (line 16)
2813 * ALLOW_FREE_NULL_MESSAGE <1>: Logfile Details. (line 41)
2814 * ALLOW_FREE_NULL_MESSAGE: Debug Tokens. (line 127)
2815 * ALLOW_REALLOC_NULL settings.h option: Compatibility. (line 11)
2816 * already free error: Error Codes. (line 157)
2817 * ANSI-C compiler: Installation. (line 64)
2818 * argument checking: Argument Checking. (line 6)
2819 * assembly hacks: Return Address. (line 14)
2820 * atexit: Getting Started. (line 17)
2821 * atexit function: Extensions. (line 26)
2822 * author: Top. (line 8)
2823 * automatic shutdown: Getting Started. (line 17)
2824 * bad admin structure list: Error Codes. (line 173)
2825 * bad file error: Error Codes. (line 75)
2826 * bad line error: Error Codes. (line 82)
2827 * bad setup error: Error Codes. (line 30)
2828 * bad size error: Error Codes. (line 123)
2829 * bash shell <1>: Getting Started. (line 27)
2830 * bash shell: Shell Alias. (line 13)
2831 * bash usage: Environment Variable.
2832 (line 14)
2833 * basic allocation information: Allocation Basics. (line 6)
2834 * basic definitions: Basic Definitions. (line 6)
2835 * beginning: Getting Started. (line 6)
2836 * blank space: Debug Tokens. (line 80)
2837 * blanking memory: Debug Tokens. (line 94)
2838 * bounds checking: Features. (line 23)
2839 * Bourne shell usage: Environment Variable.
2840 (line 14)
2841 * building the library: Installation. (line 6)
2842 * C shell usage: Environment Variable.
2843 (line 20)
2844 * c++ usage: Using With C++. (line 6)
2845 * caller address translation: Translate Return Addresses.
2846 (line 12)
2847 * caller's address: Return Address. (line 6)
2848 * calloc: Malloc Functions. (line 20)
2849 * cannot locate pointer in heap: Error Codes. (line 57)
2850 * catch-null: Debug Tokens. (line 109)
2851 * catch-signals: Debug Tokens. (line 72)
2852 * cgi-bin process debugging: Debugging A Server. (line 6)
2853 * cgi-bin usage of dmalloc: Debugging A Server. (line 6)
2854 * changed memory log: Extensions. (line 174)
2855 * check-blank <1>: Error Codes. (line 165)
2856 * check-blank: Debug Tokens. (line 59)
2857 * check-fence: Debug Tokens. (line 53)
2858 * check-funcs: Debug Tokens. (line 65)
2859 * check-heap <1>: Debug Tokens. (line 56)
2860 * check-heap <2>: Troubleshooting. (line 17)
2861 * check-heap: How It Works. (line 28)
2862 * check-shutdown: Debug Tokens. (line 69)
2863 * checking arguments: Argument Checking. (line 6)
2864 * checking bounds: Features. (line 23)
2865 * checkpoint memory usage: Extensions. (line 174)
2866 * child process debugging: Debugging A Server. (line 6)
2867 * clearing memory: Debug Tokens. (line 94)
2868 * comma separated tokens in env variable: Environment Variable.
2869 (line 39)
2870 * common problems: Troubleshooting. (line 6)
2871 * compatibility: Compatibility. (line 6)
2872 * compiling the library: Installation. (line 6)
2873 * conf.h file: Installation. (line 23)
2874 * configuration file: RC File. (line 6)
2875 * configure script: Installation. (line 23)
2876 * configuring the library: Installation. (line 6)
2877 * constancy verification: Features. (line 35)
2878 * copying: Copying. (line 6)
2879 * core dump <1>: Dumping Core. (line 6)
2880 * core dump <2>: Debug Tokens. (line 90)
2881 * core dump <3>: Features. (line 84)
2882 * core dump: Debug Tokens. (line 118)
2883 * core dump, none: Dumping Core. (line 19)
2884 * core file: Dumping Core. (line 19)
2885 * could not grow heap by allocating memory: Error Codes. (line 135)
2886 * count changed: Extensions. (line 148)
2887 * count number of bytes changed since mark: Extensions. (line 148)
2888 * cpp: Features. (line 10)
2889 * csh shell <1>: Shell Alias. (line 27)
2890 * csh shell: Getting Started. (line 50)
2891 * csh usage: Environment Variable.
2892 (line 20)
2893 * current debug value: Extensions. (line 66)
2894 * cygwin: Using With Cygwin. (line 6)
2895 * da character: Debug Tokens. (line 94)
2896 * daemon process debugging: Debugging A Server. (line 6)
2897 * debug setting: Environment Variable.
2898 (line 28)
2899 * debug tokens: Debug Tokens. (line 6)
2900 * debugger: Dumping Core. (line 6)
2901 * debugger usage with dmalloc: Using With a Debugger.
2902 (line 6)
2903 * debugging cgi-bin processes: Debugging A Server. (line 6)
2904 * debugging child processes: Debugging A Server. (line 6)
2905 * debugging daemon processes: Debugging A Server. (line 6)
2906 * debugging server processes: Debugging A Server. (line 6)
2907 * decimal 218 character: Debug Tokens. (line 94)
2908 * decimal 223 character: Debug Tokens. (line 80)
2909 * delay heap checking: Utility Usage. (line 180)
2910 * destructor: Getting Started. (line 17)
2911 * df character: Debug Tokens. (line 80)
2912 * diagnosing errors: General Errors. (line 6)
2913 * disabling library checking: Disabling the Library.
2914 (line 6)
2915 * disabling the library: Disabling the Library.
2916 (line 6)
2917 * dmalloc program: Dmalloc Program. (line 6)
2918 * dmalloc utility: Dmalloc Program. (line 6)
2919 * dmalloc.h file: Allocation Macros. (line 6)
2920 * dmalloc_debug: Disabling the Library.
2921 (line 6)
2922 * dmalloc_debug function: Extensions. (line 52)
2923 * dmalloc_debug_current function: Extensions. (line 66)
2924 * dmalloc_debug_setup: Extensions. (line 72)
2925 * dmalloc_debug_setup function: Debugging A Server. (line 23)
2926 * dmalloc_debug_setup usage: Using With Cygwin. (line 26)
2927 * dmalloc_errno number: Extensions. (line 9)
2928 * dmalloc_error() routine: Using With a Debugger.
2929 (line 15)
2930 * dmalloc_examine function: Extensions. (line 96)
2931 * DMALLOC_FUNC_CHECK: Getting Started. (line 73)
2932 * DMALLOC_FUNC_CHECK flag: Argument Checking. (line 6)
2933 * dmalloc_get_stats function: Extensions. (line 200)
2934 * dmalloc_log_changed function: Extensions. (line 174)
2935 * dmalloc_log_stats function: Extensions. (line 164)
2936 * dmalloc_log_unfreed function: Extensions. (line 168)
2937 * dmalloc_logpath variable: Extensions. (line 17)
2938 * dmalloc_mark function: Extensions. (line 118)
2939 * dmalloc_memory_allocated function: Extensions. (line 136)
2940 * dmalloc_message function: Extensions. (line 195)
2941 * DMALLOC_OPTIONS <1>: Troubleshooting. (line 39)
2942 * DMALLOC_OPTIONS: Environment Variable.
2943 (line 6)
2944 * dmalloc_shutdown function: Extensions. (line 25)
2945 * DMALLOC_SIZE option: Installation. (line 45)
2946 * dmalloc_strerror function: Extensions. (line 222)
2947 * dmalloc_t test program: Installation. (line 92)
2948 * dmalloc_track function: Extensions. (line 111)
2949 * dmalloc_verify function: Extensions. (line 41)
2950 * dmalloc_verify() routine: General Errors. (line 32)
2951 * dmalloc_vmessage function: Extensions. (line 189)
2952 * dmallocc.cc: Using With C++. (line 10)
2953 * dmallocc.cc file: Using With C++. (line 6)
2954 * dmallocrc file: RC File. (line 6)
2955 * dump core <1>: Dumping Core. (line 6)
2956 * dump core <2>: Features. (line 84)
2957 * dump core: Debug Tokens. (line 118)
2958 * env: Troubleshooting. (line 39)
2959 * environment variable: Environment Variable.
2960 (line 6)
2961 * errno value is not valid: Error Codes. (line 24)
2962 * error code 10: Error Codes. (line 30)
2963 * error code 11: Error Codes. (line 34)
2964 * error code 13: Error Codes. (line 40)
2965 * error code 20: Error Codes. (line 47)
2966 * error code 21: Error Codes. (line 51)
2967 * error code 22: Error Codes. (line 57)
2968 * error code 23: Error Codes. (line 68)
2969 * error code 24: Error Codes. (line 75)
2970 * error code 25: Error Codes. (line 82)
2971 * error code 26: Error Codes. (line 89)
2972 * error code 27: Error Codes. (line 97)
2973 * error code 28: Error Codes. (line 110)
2974 * error code 30: Error Codes. (line 117)
2975 * error code 40: Error Codes. (line 123)
2976 * error code 41: Error Codes. (line 128)
2977 * error code 43: Error Codes. (line 135)
2978 * error code 45: Error Codes. (line 148)
2979 * error code 60: Error Codes. (line 152)
2980 * error code 61: Error Codes. (line 157)
2981 * error code 67: Error Codes. (line 165)
2982 * error code 70: Error Codes. (line 173)
2983 * error code 72: Error Codes. (line 178)
2984 * error code 73: Error Codes. (line 183)
2985 * error code, 1: Error Codes. (line 20)
2986 * error code, 2: Error Codes. (line 24)
2987 * error codes: Error Codes. (line 6)
2988 * error message: Extensions. (line 222)
2989 * error number: Extensions. (line 9)
2990 * error-abort <1>: Debug Tokens. (line 90)
2991 * error-abort: Dumping Core. (line 6)
2992 * error-dump <1>: Debug Tokens. (line 118)
2993 * error-dump: Dumping Core. (line 6)
2994 * error-free-null: Debug Tokens. (line 127)
2995 * error-free-null token: Error Codes. (line 47)
2996 * ERROR_ADDRESS_LIST: Error Codes. (line 178)
2997 * ERROR_ADMIN_LIST: Error Codes. (line 173)
2998 * ERROR_ALLOC_FAILED: Error Codes. (line 135)
2999 * ERROR_ALREADY_FREE: Error Codes. (line 157)
3000 * ERROR_BAD_FILE: Error Codes. (line 75)
3001 * ERROR_BAD_LINE: Error Codes. (line 82)
3002 * ERROR_BAD_SETUP: Error Codes. (line 30)
3003 * ERROR_BAD_SIZE: Error Codes. (line 123)
3004 * ERROR_FREE_OVERWRITTEN <1>: Debug Tokens. (line 80)
3005 * ERROR_FREE_OVERWRITTEN: Error Codes. (line 165)
3006 * ERROR_IN_TWICE: Error Codes. (line 34)
3007 * ERROR_IS_FOUND: Error Codes. (line 68)
3008 * ERROR_IS_NULL: Error Codes. (line 47)
3009 * ERROR_LOCK_NOT_CONFIG: Error Codes. (line 40)
3010 * ERROR_NONE: Error Codes. (line 20)
3011 * ERROR_NOT_FOUND: Error Codes. (line 57)
3012 * ERROR_NOT_IN_HEAP: Error Codes. (line 51)
3013 * ERROR_NOT_ON_BLOCK: Error Codes. (line 152)
3014 * ERROR_NOT_START_BLOCK: Error Codes. (line 117)
3015 * ERROR_OVER_FENCE: Error Codes. (line 97)
3016 * ERROR_OVER_LIMIT <1>: Utility Usage. (line 135)
3017 * ERROR_OVER_LIMIT: Error Codes. (line 148)
3018 * ERROR_SLOT_CORRUPT: Error Codes. (line 183)
3019 * ERROR_TOO_BIG: Error Codes. (line 128)
3020 * ERROR_UNDER_FENCE: Error Codes. (line 89)
3021 * ERROR_WOULD_OVERWRITE: Error Codes. (line 110)
3022 * examine a pointer: Extensions. (line 96)
3023 * extensions: Extensions. (line 6)
3024 * failed over picket-fence magic-number check: Error Codes. (line 97)
3025 * failed under picket-fence magic-number check: Error Codes. (line 89)
3026 * faq: Troubleshooting. (line 6)
3027 * features: Features. (line 6)
3028 * fence-post checking: Features. (line 23)
3029 * fence-post errors: Fence-Post Overruns. (line 6)
3030 * file/line numbers: Features. (line 10)
3031 * found pointer the user was looking for: Error Codes. (line 68)
3032 * free: Malloc Functions. (line 46)
3033 * free null token: Error Codes. (line 47)
3034 * free overwritten error: Error Codes. (line 165)
3035 * free space has been overwritten: Error Codes. (line 165)
3036 * free-blank <1>: Debug Tokens. (line 80)
3037 * free-blank: Error Codes. (line 165)
3038 * freed memory: Features. (line 65)
3039 * gcc: Portability. (line 17)
3040 * gdb: Using With a Debugger.
3041 (line 15)
3042 * gdb with shared libraries: Using With a Debugger.
3043 (line 26)
3044 * general errors: General Errors. (line 6)
3045 * generating core dump: Dumping Core. (line 6)
3046 * get heap statistics: Extensions. (line 200)
3047 * getenv, problems with: Using With Cygwin. (line 10)
3048 * GETENV_SAVE conf.h option: Using With Cygwin. (line 15)
3049 * GetEnvironmentVariableA, using with: Using With Cygwin. (line 10)
3050 * gethostname function usage: Utility Usage. (line 89)
3051 * getpid function usage: Utility Usage. (line 100)
3052 * getting started: Getting Started. (line 6)
3053 * getuid function usage: Utility Usage. (line 108)
3054 * hanging program: Troubleshooting. (line 16)
3055 * HAVE_GETENVIRONMENTVARIABLEA: Using With Cygwin. (line 15)
3056 * heap memory: Basic Definitions. (line 39)
3057 * heap statistics function: Extensions. (line 200)
3058 * help: Troubleshooting. (line 6)
3059 * hexadecimal 0xda character: Debug Tokens. (line 94)
3060 * hexadecimal 0xdf character: Debug Tokens. (line 80)
3061 * high token: RC File. (line 26)
3062 * hints that may help: Other Hints. (line 6)
3063 * hostname in logfile path: Utility Usage. (line 89)
3064 * how do i...: Troubleshooting. (line 6)
3065 * how to begin: Getting Started. (line 6)
3066 * HUP signal: Debug Tokens. (line 72)
3067 * ident: Troubleshooting. (line 43)
3068 * in twice error: Error Codes. (line 34)
3069 * initialization and setup failed: Error Codes. (line 30)
3070 * installing the library: Installation. (line 6)
3071 * INT signal: Debug Tokens. (line 72)
3072 * interaction count <1>: Extensions. (line 118)
3073 * interaction count: Utility Usage. (line 180)
3074 * internal address list corruption: Error Codes. (line 178)
3075 * internal error number: Extensions. (line 9)
3076 * internal memory slot corruption: Error Codes. (line 183)
3077 * INTERNAL_MEMORY_SPACE: Portability. (line 8)
3078 * interval setting <1>: Environment Variable.
3079 (line 83)
3080 * interval setting: Utility Usage. (line 72)
3081 * introduction: Top. (line 8)
3082 * invalid allocation size: Error Codes. (line 123)
3083 * invalid errno value: Error Codes. (line 24)
3084 * INVALID_ERROR: Error Codes. (line 24)
3085 * is found error: Error Codes. (line 68)
3086 * is null error: Error Codes. (line 47)
3087 * iteration count: How It Works. (line 48)
3088 * jump start: Getting Started. (line 6)
3089 * kill process: Dumping Core. (line 31)
3090 * KILL_PROCESS: Dumping Core. (line 31)
3091 * ksh shell <1>: Shell Alias. (line 13)
3092 * ksh shell: Getting Started. (line 27)
3093 * ksh usage: Environment Variable.
3094 (line 14)
3095 * largest maximum allocation size exceeded: Error Codes. (line 128)
3096 * leaking memory <1>: Memory Leaks. (line 6)
3097 * leaking memory: Features. (line 55)
3098 * libdmallocxx.a: Using With C++. (line 6)
3099 * library permissions: Copying. (line 6)
3100 * library utility: Dmalloc Program. (line 6)
3101 * library version: Utility Usage. (line 214)
3102 * license: Copying. (line 6)
3103 * lock on <1>: Using With Threads. (line 27)
3104 * lock on: Utility Usage. (line 147)
3105 * lock-on: Error Codes. (line 34)
3106 * lock-on not configured: Error Codes. (line 40)
3107 * lockon setting: Environment Variable.
3108 (line 44)
3109 * log memory changes: Extensions. (line 174)
3110 * log statistics: Extensions. (line 164)
3111 * log unfreed memory: Extensions. (line 168)
3112 * log-admin: Debug Tokens. (line 38)
3113 * log-bad-space: Debug Tokens. (line 41)
3114 * log-current-time: Debug Tokens. (line 50)
3115 * log-elapsed-time: Debug Tokens. (line 47)
3116 * log-known: Debug Tokens. (line 30)
3117 * log-non-free: Debug Tokens. (line 26)
3118 * log-nonfree-space: Debug Tokens. (line 44)
3119 * log-stats: Debug Tokens. (line 22)
3120 * log-trans: Debug Tokens. (line 35)
3121 * LOG_ITERATION <1>: Extensions. (line 118)
3122 * LOG_ITERATION: Utility Usage. (line 180)
3123 * LOG_ITERATION_COUNT: How It Works. (line 48)
3124 * logfile format: Logfile Details. (line 6)
3125 * logfile message writer: Extensions. (line 189)
3126 * logfile name: Extensions. (line 17)
3127 * logfile not produced: Troubleshooting. (line 32)
3128 * logfile setting: Environment Variable.
3129 (line 52)
3130 * logging information to disk: Environment Variable.
3131 (line 52)
3132 * logging statistics: Features. (line 55)
3133 * low token: RC File. (line 16)
3134 * macros, allocation: Allocation Macros. (line 6)
3135 * making the library: Installation. (line 6)
3136 * malloc: Malloc Functions. (line 11)
3137 * malloc functions: Malloc Functions. (line 6)
3138 * malloc library has gone recursive: Error Codes. (line 34)
3139 * mark count: Utility Usage. (line 180)
3140 * mark memory position: Extensions. (line 118)
3141 * medium token: RC File. (line 20)
3142 * memalign: Allocation Macros. (line 23)
3143 * memory allocated function: Extensions. (line 136)
3144 * memory definitions: Basic Definitions. (line 6)
3145 * memory leaks <1>: Memory Leaks. (line 6)
3146 * memory leaks: Features. (line 55)
3147 * memory limit <1>: Error Codes. (line 148)
3148 * memory limit: Utility Usage. (line 135)
3149 * memory position marker: Extensions. (line 118)
3150 * memory problems in system functions: Features. (line 90)
3151 * memory transaction count <1>: Utility Usage. (line 180)
3152 * memory transaction count: How It Works. (line 48)
3153 * missing core dump: Dumping Core. (line 19)
3154 * mmap <1>: General Errors. (line 6)
3155 * mmap <2>: Error Codes. (line 57)
3156 * mmap <3>: Debug Tokens. (line 109)
3157 * mmap: Error Codes. (line 143)
3158 * mmap, usage without: Portability. (line 8)
3159 * name of host in logfile path: Utility Usage. (line 89)
3160 * never-reuse: Debug Tokens. (line 113)
3161 * no core dump: Dumping Core. (line 19)
3162 * no error: Error Codes. (line 20)
3163 * no logfile produced: Troubleshooting. (line 32)
3164 * none token: Debug Tokens. (line 19)
3165 * not found error: Error Codes. (line 57)
3166 * not in heap error: Error Codes. (line 51)
3167 * not on block boundary error: Error Codes. (line 152)
3168 * not start block error: Error Codes. (line 117)
3169 * number bytes changed since mark: Extensions. (line 148)
3170 * number of bytes allocated: Extensions. (line 136)
3171 * octal 332 character: Debug Tokens. (line 94)
3172 * octal 337 character: Debug Tokens. (line 80)
3173 * on_exit: Getting Started. (line 17)
3174 * on_exit function: Extensions. (line 26)
3175 * other hints: Other Hints. (line 6)
3176 * over fence error: Error Codes. (line 97)
3177 * over limit error: Error Codes. (line 148)
3178 * over user specified allocation limit error: Error Codes. (line 148)
3179 * override debug settings: Extensions. (line 52)
3180 * overview: Overview. (line 6)
3181 * overwriting memory: Debug Tokens. (line 94)
3182 * page size: Extensions. (line 142)
3183 * permissions of the library: Copying. (line 6)
3184 * pid in logfile path: Utility Usage. (line 100)
3185 * pointer information: Extensions. (line 96)
3186 * pointer is not on block boundary: Error Codes. (line 152)
3187 * pointer is not pointing to heap data space: Error Codes. (line 51)
3188 * pointer is not to start of memory block: Error Codes. (line 117)
3189 * pointer is null error: Error Codes. (line 47)
3190 * pointer not found error: Error Codes. (line 57)
3191 * pointer not in heap error: Error Codes. (line 51)
3192 * pointer seen count: Memory Leaks. (line 42)
3193 * portability: Portability. (line 6)
3194 * possibly bad .c file line-number: Error Codes. (line 82)
3195 * possibly bad .c filename pointer: Error Codes. (line 75)
3196 * preallocated memory heap: Portability. (line 8)
3197 * print-messages: Debug Tokens. (line 106)
3198 * printenv: Troubleshooting. (line 39)
3199 * problems: Troubleshooting. (line 6)
3200 * process-id in logfile path: Utility Usage. (line 100)
3201 * program core: Dumping Core. (line 19)
3202 * programming: Programming. (line 6)
3203 * pthreads: Using With Threads. (line 6)
3204 * questions: Troubleshooting. (line 6)
3205 * quick start: Getting Started. (line 6)
3206 * ra: Return Address. (line 6)
3207 * ra_info.pl <1>: Return Address. (line 24)
3208 * ra_info.pl: Translate Return Addresses.
3209 (line 6)
3210 * rc file: RC File. (line 6)
3211 * rc shell: Getting Started. (line 55)
3212 * reading environment, problems with: Using With Cygwin. (line 10)
3213 * realloc: Malloc Functions. (line 31)
3214 * realloc-copy: Debug Tokens. (line 77)
3215 * recalloc: Allocation Macros. (line 23)
3216 * recursion: Error Codes. (line 34)
3217 * report heap statistics: Extensions. (line 200)
3218 * restoring library flags: Disabling the Library.
3219 (line 6)
3220 * return-address <1>: Return Address. (line 6)
3221 * return-address <2>: Features. (line 16)
3222 * return-address: Portability. (line 12)
3223 * return-address translation: Translate Return Addresses.
3224 (line 12)
3225 * return.h file: Return Address. (line 6)
3226 * runtime token: RC File. (line 12)
3227 * runtime-config file: RC File. (line 6)
3228 * sbrk <1>: General Errors. (line 6)
3229 * sbrk <2>: Error Codes. (line 57)
3230 * sbrk: Debug Tokens. (line 109)
3231 * sbrk, usage without: Portability. (line 8)
3232 * seen count <1>: Extensions. (line 100)
3233 * seen count <2>: Memory Leaks. (line 42)
3234 * seen count: Logfile Details. (line 47)
3235 * server process debugging: Debugging A Server. (line 6)
3236 * set debug functionality flags: Extensions. (line 52)
3237 * settings.dist file: Installation. (line 18)
3238 * settings.h file: Installation. (line 37)
3239 * setup debug flags: Extensions. (line 72)
3240 * sh usage: Environment Variable.
3241 (line 14)
3242 * shared libraries with gdb: Using With a Debugger.
3243 (line 26)
3244 * shell usage: Environment Variable.
3245 (line 14)
3246 * shutdown on signal: Debug Tokens. (line 72)
3247 * shutdown the library: Extensions. (line 25)
3248 * shutdown, automatic: Getting Started. (line 17)
3249 * SIGHUP: Debug Tokens. (line 72)
3250 * SIGINT: Debug Tokens. (line 72)
3251 * signal shutdown: Debug Tokens. (line 72)
3252 * SIGTERM: Debug Tokens. (line 72)
3253 * size of memory pages: Extensions. (line 142)
3254 * slot corrupt error: Error Codes. (line 183)
3255 * slow running: Troubleshooting. (line 16)
3256 * source code: Source Code. (line 6)
3257 * source definitions: Definitions. (line 6)
3258 * stack memory: Basic Definitions. (line 23)
3259 * start heap check later: Utility Usage. (line 180)
3260 * start setting: Environment Variable.
3261 (line 94)
3262 * static memory: Basic Definitions. (line 12)
3263 * statistics: Features. (line 55)
3264 * statistics logging: Extensions. (line 164)
3265 * STORE_SEEN_COUNT conf.h option: Memory Leaks. (line 42)
3266 * strdup: Allocation Macros. (line 23)
3267 * string error message: Extensions. (line 222)
3268 * string of debug tokens: Extensions. (line 72)
3269 * strings: Troubleshooting. (line 43)
3270 * system memory problems: Features. (line 90)
3271 * tcsh shell <1>: Shell Alias. (line 27)
3272 * tcsh shell: Getting Started. (line 50)
3273 * tcsh usage: Environment Variable.
3274 (line 20)
3275 * TERM signal: Debug Tokens. (line 72)
3276 * testing the library: Installation. (line 92)
3277 * thread locking has not been configured: Error Codes. (line 40)
3278 * thread-id in logfile path: Utility Usage. (line 93)
3279 * threads: Using With Threads. (line 6)
3280 * time function usage: Utility Usage. (line 104)
3281 * time in logfile path: Utility Usage. (line 104)
3282 * token high: RC File. (line 26)
3283 * token low: RC File. (line 16)
3284 * token medium: RC File. (line 20)
3285 * token runtime: RC File. (line 12)
3286 * tokens, debug: Debug Tokens. (line 6)
3287 * too big error: Error Codes. (line 128)
3288 * too slow: Troubleshooting. (line 16)
3289 * track memory calls: Extensions. (line 111)
3290 * tracking addresses: Environment Variable.
3291 (line 65)
3292 * transaction count <1>: Extensions. (line 118)
3293 * transaction count: Utility Usage. (line 180)
3294 * tried to free previously freed pointer: Error Codes. (line 157)
3295 * troubleshooting: Troubleshooting. (line 6)
3296 * turning off library flags: Disabling the Library.
3297 (line 6)
3298 * uid in logfile path: Utility Usage. (line 108)
3299 * under fence error: Error Codes. (line 89)
3300 * unfreed memory log: Extensions. (line 168)
3301 * usage of dmalloc in a daemon: Debugging A Server. (line 6)
3302 * usage of dmalloc in a server: Debugging A Server. (line 6)
3303 * usage of dmalloc with cgi-bin: Debugging A Server. (line 6)
3304 * usage of the utility: Utility Usage. (line 6)
3305 * use of pointer would exceed allocation: Error Codes. (line 110)
3306 * USE_MMAP conf.h option: Error Codes. (line 143)
3307 * USE_RETURN_MACROS conf.h option: Installation. (line 57)
3308 * user-id in logfile path: Utility Usage. (line 108)
3309 * using a debugger with dmalloc: Using With a Debugger.
3310 (line 6)
3311 * utility program: Dmalloc Program. (line 6)
3312 * utility usage: Utility Usage. (line 6)
3313 * utility version: Utility Usage. (line 214)
3314 * valloc: Allocation Macros. (line 23)
3315 * various hints: Other Hints. (line 6)
3316 * verify pointers: Extensions. (line 41)
3317 * verify the heap: Extensions. (line 41)
3318 * version of library: Logfile Details. (line 34)
3319 * version of utility: Utility Usage. (line 214)
3320 * where to begin: Getting Started. (line 6)
3321 * why hanging: Troubleshooting. (line 16)
3322 * why running slow: Troubleshooting. (line 16)
3323 * would overwrite error: Error Codes. (line 110)
3324 * write message to logfile: Extensions. (line 189)
3325 * zeros, allocation of: Malloc Functions. (line 20)
3326 * zsh shell <1>: Shell Alias. (line 13)
3327 * zsh shell: Getting Started. (line 27)
3328 * zsh usage: Environment Variable.
3329 (line 14)
3330
3331
3332
3333 Tag Table:
3334 Node: Top1132
3335 Node: Copying3246
3336 Node: Overview4003
3337 Node: Installation4531
3338 Node: Getting Started10335
3339 Node: Allocation Basics16089
3340 Node: Basic Definitions16437
3341 Node: Malloc Functions19142
3342 Node: Features21534
3343 Node: How It Works26077
3344 Node: Programming29378
3345 Node: Allocation Macros30515
3346 Node: Return Address33137
3347 Node: Argument Checking34561
3348 Node: Dumping Core36246
3349 Node: Extensions38461
3350 Node: Error Codes48555
3351 Node: Disabling the Library58099
3352 Node: Using With C++60731
3353 Node: Using With a Debugger61729
3354 Node: General Errors63456
3355 Node: Memory Leaks65394
3356 Node: Fence-Post Overruns68972
3357 Node: Translate Return Addresses70702
3358 Node: Using With Threads71969
3359 Node: Using With Cygwin76339
3360 Node: Debugging A Server78151
3361 Node: Logfile Details84186
3362 Node: Other Hints87949
3363 Node: Dmalloc Program89342
3364 Node: Shell Alias90248
3365 Node: Utility Usage92400
3366 Node: Environment Variable102401
3367 Node: Debug Tokens107633
3368 Node: RC File112544
3369 Node: Source Code115322
3370 Node: Definitions115712
3371 Node: Compatibility116574
3372 Node: Portability117795
3373 Node: Troubleshooting118897
3374 Node: Index of Concepts124060
3375
3376 End Tag Table
3377 -------------------------------------------------------------------------------