-
-
Notifications
You must be signed in to change notification settings - Fork 44
/
Copy pathdmalloc.html
4885 lines (4443 loc) · 336 KB
/
dmalloc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on November 11, 2022 by texi2html 1.82
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Dmalloc Tutorial</title>
<meta name="description" content="Dmalloc Tutorial">
<meta name="keywords" content="Dmalloc Tutorial">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Top"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Debug-Malloc-Library"></a>
<h1 class="settitle">Debug Malloc Library</h1>
<p>Version Version 5.6.5 – December 2020
</p>
<a name="index-introduction"></a>
<a name="index-author"></a>
<p>The debug memory allocation or <em>dmalloc</em> library has been designed as a drop in replacement for the system’s
<code>malloc</code>, <code>realloc</code>, <code>calloc</code>, <code>free</code> and other memory management routines while providing powerful
debugging facilities configurable at runtime. These facilities include such things as memory-leak tracking, fence-post
write detection, file/line number reporting, and general logging of statistics.
</p>
<p>The library is reasonably portable having been run successfully on at least the following operating systems: AIX, DGUX,
Free/Net/OpenBSD, GNU/Hurd, HPUX, Irix, Linux, OSX, NeXT, OSF/DUX, SCO, Solaris, Ultrix, Unixware, Windows, and Unicos
on a Cray T3E. It also provides support for the debugging of threaded programs. See section <a href="#Using-With-Threads">Using the Library with a Thread Package</a>.
</p>
<p>The package includes the library, configuration scripts, debug utility application, test program, and documentation.
Online documentation as well as the full source is available at URL <a href="https://dmalloc.com/">https://dmalloc.com/</a>. Details on the
library’s mailing list are available there as well.
</p>
<p>Please use the github issues URL <a href="https://github.com/j256/dmalloc/issues">https://github.com/j256/dmalloc/issues</a> if you have any problems or to request
features. Please include the version number of the library that you are using, your machine and operating system types,
and the value of the DMALLOC_OPTIONS environment variable.
</p>
<p>Gray Watson.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#License">1. Library License and Copying Information</a></td><td> </td><td align="left" valign="top"> Library license and copying information.
</td></tr>
<tr><td align="left" valign="top"><a href="#Overview">2. Description of Features and How to Get Started</a></td><td> </td><td align="left" valign="top"> Description of features and how to get started.
</td></tr>
<tr><td align="left" valign="top"><a href="#Programming">3. How to Program with the Library</a></td><td> </td><td align="left" valign="top"> How to program with the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#Dmalloc-Program">4. Dmalloc Utility Program</a></td><td> </td><td align="left" valign="top"> How to use the library’s utility.
</td></tr>
<tr><td align="left" valign="top"><a href="#Source-Code">5. Information on the Source Code</a></td><td> </td><td align="left" valign="top"> Information on the source code.
</td></tr>
<tr><td align="left" valign="top"><a href="#Troubleshooting">6. Some Solutions to Common Problems</a></td><td> </td><td align="left" valign="top"> Some solutions to common problems.
</td></tr>
<tr><td align="left" valign="top"><a href="#Index-of-Concepts">Index of Concepts</a></td><td> </td><td align="left" valign="top"> Index of concepts in the manual.
</td></tr>
</table>
<hr size="1">
<a name="License"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Top" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Library-License-and-Copying-Information"></a>
<h1 class="chapter">1. Library License and Copying Information</h1>
<a name="index-copying"></a>
<a name="index-license"></a>
<a name="index-isc-license"></a>
<a name="index-open-source-license"></a>
<a name="index-library-permissions"></a>
<a name="index-permissions-of-the-library"></a>
<p>Copyright 1992 to 2020 by Gray Watson.
</p>
<p>Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,
provided that the above copyright notice and this permission notice appear in all copies.
</p>
<p>THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.
</p>
<hr size="6">
<a name="Overview"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#License" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Installation" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#License" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Description-of-Features-and-How-to-Get-Started"></a>
<h1 class="chapter">2. Description of Features and How to Get Started</h1>
<a name="index-overview"></a>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Installation">2.1 How to Install the Library</a></td><td> </td><td align="left" valign="top"> How to install the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#Getting-Started">2.2 Getting Started with the Library</a></td><td> </td><td align="left" valign="top"> Getting started with the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#Allocation-Basics">2.3 Basic Description of Terms and Functions</a></td><td> </td><td align="left" valign="top"> Basic description of terms and functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Features">2.4 General Features of the Library</a></td><td> </td><td align="left" valign="top"> General features of the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#How-It-Works">2.5 How the Library Checks Your Program</a></td><td> </td><td align="left" valign="top"> How the library checks your program.
</td></tr>
</table>
<hr size="6">
<a name="Installation"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Overview" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Getting-Started" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="How-to-Install-the-Library"></a>
<h2 class="section">2.1 How to Install the Library</h2>
<a name="index-installing-the-library"></a>
<a name="index-compiling-the-library"></a>
<a name="index-building-the-library"></a>
<a name="index-configuring-the-library"></a>
<a name="index-making-the-library"></a>
<p>To configure, compile, and install the library, follow these steps carefully.
</p>
<ol>
<li> Download the latest version of the library available from <a href="https://dmalloc.com/">https://dmalloc.com/</a>.
</li><li> The release files have a ‘<tt>.tgz</tt>’ file extension which means that they are a tar’d gzip’d directory of files.
You will need to ungzip and then untar the release file into your source work directory. You may have to rename the
file to ‘<tt>.tar.gz</tt>’ to get some old zip programs to handle the file correctly.
<a name="index-settings_002edist-file"></a>
</li><li> You may want to edit or at least review the settings in ‘<tt>settings.dist</tt>’ to tune specific features of the
library. The ‘<tt>configure</tt>’ script will copy this file to ‘<tt>settings.h</tt>’ which is where you should be adding
per-architecture settings.
<a name="index-configure-script"></a>
<a name="index-_002d_002ddisable_002dcxx"></a>
<a name="index-_002d_002denable_002dthreads"></a>
<a name="index-_002d_002denable_002dshlib"></a>
<a name="index-conf_002eh-file"></a>
</li><li> Type <kbd>sh ./configure</kbd> to configure the library. You may want to first examine <kbd>sh ./configure --help</kbd>
output for some information about configure. You may want to use the <kbd>--disable-cxx</kbd> option if you do not want the
Makefile to build the C++ version of dmalloc. You may want to use the <kbd>--enable-threads</kbd> option to build the
threaded version of dmalloc. You may want to use the <kbd>--enable-shlib</kbd> option to build the shared versions of the
dmalloc libraries. <kbd>sh ./configure --help</kbd> lists the available options to configure. Configure should generate the
‘<tt>Makefile</tt>’ and configuration files automatically.
</li><li> You may want to examine the ‘<tt>Makefile</tt>’ and ‘<tt>conf.h</tt>’ files created by configure to make sure it did its
job correctly.
<a name="index-settings_002eh-file"></a>
</li><li> You might want to tune the settings in ‘<tt>settings.h</tt>’ file to tune the library to the local architecture.
This file contains relevant settings if you are using pthreads or another thread library. See section <a href="#Using-With-Threads">Using the Library with a Thread Package</a>.
The ‘<tt>configure</tt>’ script created this file from the ‘<tt>settings.dist</tt>’ file. Any permanent changes to these
settings should made to the ‘<tt>settings.dist</tt>’ file. You then can run ‘<tt>config.status</tt>’ to re-create the
‘<tt>settings.h</tt>’ file.
<a name="index-DMALLOC_005fSIZE-option"></a>
</li><li> The <code>DMALLOC_SIZE</code> variable gets auto-configured in ‘<tt>dmalloc.h.2</tt>’ but it may not generate correct
settings for all systems. You may have to alter the definitions in this file to get things to stop complaining when you
go to compile about the size arguments to malloc routines. Comments on this please.
</li><li> Typing <kbd>make</kbd> should be enough to build ‘<tt>libdmalloc.a</tt>’, and ‘<tt>dmalloc</tt>’ program. If you figure your
problem out, please send me some notes so future users can profit from your experiences.
<a name="index-USE_005fRETURN_005fMACROS-conf_002eh-option"></a>
<p><em>NOTE</em>: You may experience some errors compiling some of the ‘<tt>return.h</tt>’ assembly macros which attempt to
determine the callers address for logging purposes. See section <a href="#Portability">Issues Important for Porting the Library</a>. You may want to first try disabling any
compiler optimization flags. If this doesn’t work then you may need to disable the ‘<samp>USE_RETURN_MACROS</samp>’ variable in
the ‘<tt>settings.h</tt>’ file.
</p>
<a name="index-ANSI_002dC-compiler"></a>
<p><em>NOTE</em>: The code is dependent on an ANSI-C compiler. If the configure script gives the ‘<samp>WARNING</samp>’ that you do
not have an ANSI-C compiler, you may still be able to add some sort of option to your compiler to make it ANSI. If
there such is an option, please send it to the author so it can be added to the configure script.
</p>
</li><li> If you use threads and did not add the <kbd>--enable-threads</kbd> argument to configure, typing <kbd>make threads</kbd>
should be enough to build ‘<tt>libdmallocth.a</tt>’ which is the threaded version of the library. This may or may not work
depending on the configuration scripts ability to detect your local thread functionality. Feel free to send me mail
with improvements.
<p>See the section of the manual on threads for more information about the operation of the library with your threaded
program. See section <a href="#Using-With-Threads">Using the Library with a Thread Package</a>.
</p>
</li><li> If you have a C++ compiler installed, the library should have automatically built ‘<tt>libdmallocxx.a</tt>’ which is
the C++ version of the library. If it was not done automatically, you can build it by typing <kbd>make cxx</kbd>. You
should link this library into your C++ programs instead of ‘<tt>libdmalloc.a</tt>’. See the ‘<tt>dmallocc.cc</tt>’ C++ file
which contains basic code to overload the <code>new</code>, <code>new[]</code>, <code>delete</code>, and <code>delete[]</code> C++ operators.
My apologies on the minimal C++ support. I am still living in a mostly C world. Any help improving this interface
without sacrificing portability would be appreciated.
<a name="index-testing-the-library"></a>
<a name="index-dmalloc_005ft-test-program"></a>
</li><li> Typing <kbd>make light</kbd> should build and run the ‘<tt>dmalloc_t</tt>’ test program through a set of light trials.
By default this will execute ‘<tt>dmalloc_t</tt>’ 5 times – each time will execute 10,000 malloc operations in a very
random manner. Anal folks can type <kbd>make heavy</kbd> to up the ante. Use <kbd>dmalloc_t --usage</kbd> for the list of all
‘<tt>dmalloc_t</tt>’ options.
</li><li> Typing <kbd>make install</kbd> should install the ‘<tt>libdmalloc.a</tt>’ library in ‘<tt>/usr/local/lib</tt>’, the
‘<tt>dmalloc.h</tt>’ include file in ‘<tt>/usr/local/include</tt>’, and the ‘<tt>dmalloc</tt>’ utility in ‘<tt>/usr/local/bin</tt>’.
You may also want to type <kbd>make installth</kbd> to install the thread library into place and/or <kbd>make installcc</kbd> to
install the C++ library into place.
<p>You may have specified a ‘<samp>--prefix=PATH</samp>’ option to configure in which case ‘<samp>/usr/local</samp>’ will have been
replaced with ‘<samp>PATH</samp>’.
</p>
</li></ol>
<p>See the “Getting Started” section to get up and running with the library. See section <a href="#Getting-Started">Getting Started with the Library</a>.
</p>
<hr size="6">
<a name="Getting-Started"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Installation" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Allocation-Basics" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Getting-Started-with-the-Library"></a>
<h2 class="section">2.2 Getting Started with the Library</h2>
<a name="index-quick-start"></a>
<a name="index-getting-started"></a>
<a name="index-jump-start"></a>
<a name="index-how-to-begin"></a>
<a name="index-where-to-begin"></a>
<a name="index-beginning"></a>
<p>This section should give you a quick idea on how to get going. Basically, you need to do the following things to make
use of the library:
</p>
<ol>
<li> Download the latest version of the library from <a href="https://dmalloc.com/">https://dmalloc.com/</a>.
<a name="index-configure-script-1"></a>
</li><li> Run <kbd>./configure</kbd> to configure the library. Follow the installation instructions on how to
configure, make, and install the library (i.e. type: <kbd>make install</kbd>). See section <a href="#Installation">How to Install the Library</a>.
</li><li> Run <kbd>./make install</kbd> to install the library on your system.
<a name="index-automatic-shutdown"></a>
<a name="index-shutdown_002c-automatic"></a>
<a name="index-on_005fexit"></a>
<a name="index-atexit"></a>
<a name="index-destructor"></a>
</li><li> You need to make sure that the library configuration and build process above was able to locate one of the
<code>on_exit</code> function, <code>atexit</code> function, or had compiler destructor support. If one of these functions or
support is available then the dmalloc library should be able to automatically shut itself down when the program exits.
This causes the memory statistics and unfreed information to be dumped to the log file. However, if your system has
none of the above, then you will need to call <code>dmalloc_shutdown</code> yourself before your program exits.
<a name="index-alias_002c-shell"></a>
<a name="index-bash-shell"></a>
<a name="index-ksh-shell"></a>
<a name="index-zsh-shell"></a>
</li><li> To get the dmalloc utility to work you need to add an alias for dmalloc to your shell’s runtime configuration
file if supported. The idea is to have the shell capture the dmalloc program’s output and adjust the environment.
<p>After you add the alias to the shell config file you need to log out and log back in to have it take effect, or you can
execute the appropriate command below on the command line directly. After you setup the alias, if you enter
<kbd>dmalloc runtime</kbd> and see any output with DMALLOC_OPTIONS in it then the alias did not take effect.
</p>
<p>Bash, ksh, and zsh (<a href="https://zsh.org/">https://zsh.org/</a>) users should add the following to their ‘<tt>.bashrc</tt>’, ‘<tt>.profile</tt>’,
or ‘<tt>.zshrc</tt>’ file respectively (notice the <kbd>-b</kbd> option for bourne shell output):
</p>
<table><tr><td> </td><td><pre class="example">function dmalloc { eval `command dmalloc -b $*`; }
</pre></td></tr></table>
<p>If your shell does not support the <code>command</code> function then try:
</p>
<table><tr><td> </td><td><pre class="example">function dmalloc { eval `\dmalloc -b $*`; }
</pre></td></tr></table>
<p>or use a full path to where the dmalloc binary is installed:
</p><table><tr><td> </td><td><pre class="example">function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
</pre></td></tr></table>
<a name="index-csh-shell"></a>
<a name="index-tcsh-shell"></a>
<p>If you are still using csh or tcsh, you should add the following to your ‘<tt>.cshrc</tt>’ file (notice the <kbd>-C</kbd> option
for c-shell output):
</p>
<table><tr><td> </td><td><pre class="example">alias dmalloc 'eval `\dmalloc -C \!*`'
</pre></td></tr></table>
<a name="index-rc-shell"></a>
<p>If you are using rc shell, you should add the following to your ‘<tt>.rcrc</tt>’ file (notice the <kbd>-R</kbd> option for
rc-shell output):
</p>
<table><tr><td> </td><td><pre class="example">fn dmalloc {eval `{/usr/local/bin/dmalloc $*}}
</pre></td></tr></table>
</li><li> Although not necessary, you may want to include ‘<tt>dmalloc.h</tt>’ in your C files and recompile. This will allow
the library to report the file/line numbers of calls that generate problems. See section <a href="#Allocation-Macros">Macros Providing File and Line Information</a>. It should be
inserted at the <em>bottom</em> of your include files as to not conflict with other includes. You may want to ifdef it
as well and compile with <kbd>cc -DDMALLOC …</kbd>:
<table><tr><td> </td><td><pre class="example">/* other includes above ^^^ */
#ifdef DMALLOC
#include "dmalloc.h"
#endif
</pre></td></tr></table>
<a name="index-DMALLOC_005fFUNC_005fCHECK"></a>
</li><li> Another optional task is to compile all of your source with the ‘<tt>dmalloc.h</tt>’ with the
<code>DMALLOC_FUNC_CHECK</code> compilation flag. This will allow the library to check all of the arguments of a number of
common string and utility routines. See section <a href="#Argument-Checking">Checking of Function Arguments</a>.
<table><tr><td> </td><td><pre class="example">cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
</pre></td></tr></table>
</li><li> Link the dmalloc library into your program. The dmalloc library should probably be placed at or near the end
of the library list.
</li><li> Enable the debugging features by typing <kbd>dmalloc -l logfile -i 100 low</kbd> (for example). You should not see
any messages printed by the dmalloc utility (see NOTE below). This will:
<ul>
<li> Set the malloc logfile name to ‘<tt>logfile</tt>’ (<kbd>-l logfile</kbd>). For programs which change directories, you may
want to specify the full path to your logfile.
</li><li> Have the library check itself every 100 iterations (<kbd>-i 100</kbd>). This controls how fast your program will run.
Larger numbers check the heap less and so it will run faster. Lower numbers will be more likely to catch memory
problems.
</li><li> Enable a number of debug features (<kbd>low</kbd>). You can also try <kbd>runtime</kbd> for minimal checking or
<kbd>medium</kbd> or <kbd>high</kbd> for more extensive heap verification.
</li><li> By default, the low, medium, and high values enable the <code>error-abort</code> token which will cause the library to
abort and usually dump core immediately upon seeing an error. See section <a href="#Dumping-Core">Generating a Core File on Errors</a>. You can disable this feature by
entering <kbd>dmalloc -m error-abort</kbd> (-m for minus) to remove the <code>error-abort</code> token and your program will just
log errors and continue.
</li></ul>
<p><kbd>dmalloc --usage</kbd> will provide verbose usage info for the dmalloc program. See section <a href="#Dmalloc-Program">Dmalloc Utility Program</a>.
</p>
<p>You may also want to install the ‘<tt>dmallocrc</tt>’ file in your home directory as ‘<tt>.dmallocrc</tt>’. This allows you to
add your own combination of debug tokens. See section <a href="#RC-File">Format of the Runtime Configuration File</a>.
</p>
<p><em>NOTE</em>: The output from the dmalloc utility should be captured by your shell. If you see a bunch of stuff which
includes the string <code>DMALLOC_OPTIONS</code> then the alias you should have created above is not working and he
environmental variables are not being set. Make sure you’ve logged out and back in to have the alias take effect.
</p>
</li><li> Run your program, examine the logfile that should have been created by <code>dmalloc_shutdown</code>, and use its
information to help debug your program.
</li></ol>
<hr size="6">
<a name="Allocation-Basics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Getting-Started" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Basic-Definitions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Basic-Description-of-Terms-and-Functions"></a>
<h2 class="section">2.3 Basic Description of Terms and Functions</h2>
<a name="index-allocation-basics"></a>
<a name="index-basic-allocation-information"></a>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Basic-Definitions">2.3.1 General Memory Terms and Concepts</a></td><td> </td><td align="left" valign="top"> General memory terms and concepts.
</td></tr>
<tr><td align="left" valign="top"><a href="#Malloc-Functions">2.3.2 Functionality Supported by All Malloc Libraries</a></td><td> </td><td align="left" valign="top"> Functionality supported by all malloc libs.
</td></tr>
</table>
<hr size="6">
<a name="Basic-Definitions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Allocation-Basics" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Malloc-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Allocation-Basics" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="General-Memory-Terms-and-Concepts"></a>
<h3 class="subsection">2.3.1 General Memory Terms and Concepts</h3>
<a name="index-basic-definitions"></a>
<a name="index-memory-definitions"></a>
<p>Any program can be divided into 2 logical parts: text and data. Text is the actual program code in machine-readable
format and data is the information that the text operates on when it is executing. The data, in turn, can be divided
into 3 logical parts according to where it is stored: <em>static</em>, <em>stack</em>, and <em>heap</em>.
</p>
<a name="index-static-memory"></a>
<p>Static data is the information whose storage space is compiled into the program.
</p>
<table><tr><td> </td><td><pre class="example">/* global variables are allocated as static data */
int numbers[10];
main()
{
…
}
</pre></td></tr></table>
<a name="index-stack-memory"></a>
<p>Stack data is data allocated at runtime to hold information used inside of functions. This data is managed by the
system in the space called stack space.
</p>
<table><tr><td> </td><td><pre class="example">void foo()
{
/* this local variable is stored on the stack */
float total;
…
}
main()
{
foo();
}
</pre></td></tr></table>
<a name="index-heap-memory"></a>
<p>Heap data is also allocated at runtime and provides a programmer with dynamic memory capabilities.
</p>
<table><tr><td> </td><td><pre class="example">main()
{
/* the address is stored on the stack */
char * string;
…
/*
* Allocate a string of 10 bytes on the heap. Store the
* address in string which is on the stack.
*/
string = (char *)malloc(10);
…
/* de-allocate the heap memory now that we're done with it */
(void)free(string);
…
}
</pre></td></tr></table>
<p>It is the heap data that is managed by this library.
</p>
<p>Although the above is an example of how to use the malloc and free commands, it is not a good example of why using the
heap for runtime storage is useful.
</p>
<p>Consider this: You write a program that reads a file into memory, processes it, and displays results. You would like to
handle files with arbitrary size (from 10 bytes to 1.2 megabytes and more). One problem, however, is that the entire
file must be in memory at one time to do the calculations. You don’t want to have to allocate 1.2 megabytes when you
might only be reading in a 10 byte file because it is wasteful of system resources. Also, you are worried that your
program might have to handle files of more than 1.2 megabytes.
</p>
<p>A solution: first check out the file’s size and then, using the heap-allocation routines, get enough storage to read the
entire file into memory. The program will only be using the system resources necessary for the job and you will be
guaranteed that your program can handle any sized file.
</p>
<hr size="6">
<a name="Malloc-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Basic-Definitions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Features" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Allocation-Basics" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Functionality-Supported-by-All-Malloc-Libraries"></a>
<h3 class="subsection">2.3.2 Functionality Supported by All Malloc Libraries</h3>
<a name="index-malloc-functions"></a>
<p>All malloc libraries support 4 basic memory allocation commands. These include <em>malloc</em>, <em>calloc</em>,
<em>realloc</em>, and <em>free</em>. For more information about their capabilities, check your system’s manual pages – in
unix, do a <code>man 3 malloc</code>.
</p>
<a name="index-malloc"></a>
<dl>
<dt><a name="index-_002amalloc"></a><u>Function:</u> void <b>*malloc</b><i> ( unsigned int <var>size</var> )</i></dt>
<dd>
<p>Usage: <code>pnt = (type *)malloc(size)</code>
</p>
<p>The malloc routine is the basic memory allocation routine. It allocates an area of <code>size</code> bytes. It will return a
pointer to the space requested.
</p>
</dd></dl>
<dl>
<dt><a name="index-_002acalloc"></a><u>Function:</u> void <b>*calloc</b><i> ( unsigned int <var>number</var>, unsigned int <var>size</var> )</i></dt>
<dd><a name="index-calloc"></a>
<a name="index-Allocation-of-zeros"></a>
<a name="index-zeros_002c-allocation-of"></a>
<p>Usage: <code>pnt = (type *)calloc(number, size)</code>
</p>
<p>The calloc routine allocates a certain <code>number</code> of items, each of <code>size</code> bytes, and returns a pointer to the
space. It is appropriate to pass in a <code>sizeof(type)</code> value as the size argument.
</p>
<p>Also, calloc nulls the space that it returns, assuring that the memory is all zeros.
</p>
</dd></dl>
<dl>
<dt><a name="index-_002arealloc"></a><u>Function:</u> void <b>*realloc</b><i> ( void *<var>old_pnt</var>, unsigned int <var>new_size</var> )</i></dt>
<dd><a name="index-realloc"></a>
<p>Usage: <code>new_pnt = (type *)realloc(old_pnt, new_size)</code>
</p>
<p>The realloc function expands or shrinks the memory allocation in <code>old_pnt</code> to <code>new_size</code> number of bytes.
Realloc copies as much of the information from <code>old_pnt</code> as it can into the <code>new_pnt</code> space it returns, up to
<code>new_size</code> bytes. If there is a problem allocating this memory, 0L will be returned.
</p>
<p>If the <code>old_pnt</code> is 0L then realloc will do the equivalent of a <code>malloc(new_size)</code>. If <code>new_size</code> is 0
and <code>old_pnt</code> is not 0L, then it will do the equivalent of <code>free(old_pnt)</code> and will return 0L.
</p>
</dd></dl>
<dl>
<dt><a name="index-free"></a><u>Function:</u> void <b>free</b><i> ( void *<var>pnt</var> )</i></dt>
<dd><a name="index-free-1"></a>
<p>Usage: <code>free(pnt)</code>
</p>
<p>The free routine releases allocation in <code>pnt</code> which was returned by malloc, calloc, or realloc back to the heap.
This allows other parts of the program to re-use memory that is not needed anymore. It guarantees that the process does
not grow too big and swallow a large portion of the system resources.
</p>
</dd></dl>
<p><em>WARNING</em>: there is a quite common myth that all of the space that is returned by malloc libraries has already been
cleared. <em>Only</em> the <code>calloc</code> routine will zero the memory space it returns.
</p>
<hr size="6">
<a name="Features"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Malloc-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#How-It-Works" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="General-Features-of-the-Library"></a>
<h2 class="section">2.4 General Features of the Library</h2>
<a name="index-features"></a>
<p>The debugging features that are available in this debug malloc library can be divided into a couple basic
classifications:
</p>
<dl compact="compact">
<dt> file and line number information</dt>
<dd><a name="index-file_002fline-numbers"></a>
<a name="index-cpp"></a>
<p>One of the nice things about a good debugger is its ability to provide the file and line number of an offending piece of
code. This library attempts to give this functionality with the help of <em>cpp</em>, the C preprocessor.
See section <a href="#Allocation-Macros">Macros Providing File and Line Information</a>.
</p>
</dd>
<dt> return-address information</dt>
<dd><a name="index-return_002daddress"></a>
<p>To debug calls to the library from external sources (i.e. those files that could not use the allocation macros), some
facilities have been provided to supply the caller’s address. This address, with the help of a debugger, can help you
locate the source of a problem. See section <a href="#Return-Address">Getting Caller Address Information</a>.
</p>
</dd>
<dt> fence-post (i.e. bounds) checking</dt>
<dd><a name="index-fence_002dpost-checking"></a>
<a name="index-bounds-checking"></a>
<a name="index-checking-bounds"></a>
<p><em>Fence-post</em> memory is the area immediately above or below memory allocations. It is all too easy to write code
that accesses above or below an allocation – especially when dealing with arrays or strings. The library can write
special values in the areas around every allocation so it will notice when these areas have been overwritten.
See section <a href="#Fence_002dPost-Overruns">Diagnosing Fence-Post Overwritten Memory</a>.
</p>
<p><em>NOTE</em>: The library cannot notice when the program <em>reads</em> from these areas, only when it writes values.
Also, fence-post checking will increase the amount of memory the program allocates.
</p>
</dd>
<dt> heap-constancy verification</dt>
<dd><a name="index-constancy-verification"></a>
<p>The administration of the library is reasonably complex. If any of the heap-maintenance information is corrupted, the
program will either crash or give unpredictable results.
</p>
<p>By enabling heap-consistency checking, the library will run through its administrative structures to make sure all is in
order. This will mean that problems will be caught faster and diagnosed better.
</p>
<p>The drawback of this is, of course, that the library often takes quite a long time to do this. It is suitable to enable
this only during development and debugging sessions.
</p>
<p><em>NOTE</em>: the heap checking routines cannot guarantee that the tests will not cause a segmentation-fault if the heap
administration structures are properly (or improperly if you will) overwritten. In other words, the tests will verify
that everything is okay but may not inform the user of problems in a graceful manner.
</p>
</dd>
<dt> logging statistics</dt>
<dd><a name="index-logging-statistics"></a>
<a name="index-statistics"></a>
<a name="index-memory-leaks"></a>
<a name="index-leaking-memory"></a>
<p>One of the reasons why the debug malloc library was initially developed was to track programs’ memory usage –
specifically to locate <em>memory leaks</em> which are places where allocated memory is never getting freed. See section <a href="#Memory-Leaks">Tracking Down Non-Freed Memory</a>.
</p>
<p>The library has a number of logging capabilities that can track un-freed memory pointers as well as runtime memory
usage, memory transactions, administrative actions, and final statistics.
</p>
</dd>
<dt> examining freed memory</dt>
<dd><a name="index-freed-memory"></a>
<a name="index-freed-memory-1"></a>
<p>Another common problem happens when a program frees a memory pointer but goes on to use it again by mistake. This can
lead to mysterious crashes and unexplained problems.
</p>
<p>To combat this, the library can write special values into a block of memory after it has been freed. This serves two
purposes: it will make sure that the program will get garbage data if it trying to access the area again, and it will
allow the library to verify the area later for signs of overwriting.
</p></dd>
</dl>
<p>If any of the above debugging features detect an error, the library will try to recover. If logging is enabled then an
error will be logged with as much information as possible.
</p>
<p>The error messages that the library displays are designed to give the most information for developers. If the error
message is not understood, then it is most likely just trying to indicate that a part of the heap has been corrupted.
</p>
<a name="index-dump-core"></a>
<a name="index-core-dump"></a>
<p>The library can be configured to quit immediately when an error is detected and to dump a core file or memory-image.
This can be examined with a debugger to determine the source of the problem. The library can either stop after dumping
core or continue running. See section <a href="#Dumping-Core">Generating a Core File on Errors</a>.
</p>
<a name="index-system-memory-problems"></a>
<a name="index-memory-problems-in-system-functions"></a>
<p><em>NOTE</em>: do not be surprised if the library catches problems with your system’s routines. It took me hours to
finally come to the conclusion that the localtime call, included in SunOS release 4.1, overwrites one of its fence-post
markers.
</p>
<hr size="6">
<a name="How-It-Works"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Features" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Overview" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="How-the-Library-Checks-Your-Program"></a>
<h2 class="section">2.5 How the Library Checks Your Program</h2>
<p>This is one of the newer sections of the library implying that it is incomplete. If you have any questions or issues
that you’d like to see handled here, please let me know.
</p>
<p>The dmalloc library replaces the heap library calls normally found in your system libraries with its own versions. When
you make a call to malloc (for example), you are calling dmalloc’s version of the memory allocation function. When you
allocate memory with these functions, the dmalloc library keeps track of a number of pieces of debugging information
about your pointer including: where it was allocated, exactly how much memory was requested, when the call was made,
etc.. This information can then be verified when the pointer is freed or reallocated and the details can be logged on
any errors.
</p>
<p>Whenever you reallocate or free a memory address, the dmalloc library always performs a number of checks on the pointer
to make sure that it is valid and has not been corrupted. You can configure the library to perform additional checks
such as detected fence-post writing. The library can also be configured to overwrite memory with non-zeros (only if
calloc is not called) when it is allocated and erase the memory when the pointers are freed.
</p>
<a name="index-check_002dheap"></a>
<p>In addition to per-pointer checks, you can configure the library to perform complete heap checks. These complete checks
verify all internal heap structures and include walking all of the known allocated pointers to verify each one in turn.
You need this level of checking to find random pointers in your program which got corrupted but that won’t be freed for
a while. To turn on these checks, you will need to enable the <code>check-heap</code> debug token. See section <a href="#Debug-Tokens">Description of the Debugging Tokens</a>. By
default this will cause the heap to be fully checked each and every time dmalloc is called whether it is a malloc, free,
realloc, or another dmalloc overloaded function.
</p>
<p>Performing a full heap check can take a good bit of CPU and it may be that you will want to run it sporadically. This
can be accomplished in a couple different ways including the ’-i’ interval argument to the dmalloc utility.
See section <a href="#Dmalloc-Program">Dmalloc Utility Program</a>. This will cause the check to be run every N-th time. For instance, ’dmalloc -i 3’ will cause
the heap to be checked before every 3rd call to a memory function. Values of 100 or even 1000 for high memory usage
programs are more useful than smaller ones.
</p>
<a name="index-LOG_005fITERATION_005fCOUNT"></a>
<a name="index-iteration-count"></a>
<a name="index-memory-transaction-count"></a>
<p>You can also cause the program to start doing detailed heap checking after a certain point. For instance, with ’dmalloc
-s 1000’ option, you can tell the dmalloc library to enable the heap checks after the 1000th memory call. Examine the
dmalloc log file produced and use the iteration count if you have <code>LOG_ITERATION_COUNT</code> enabled in your
‘<tt>settings.h</tt>’ file.
</p>
<p>The start option can also have the format ‘<samp>file:line</samp>’. For instance, if it is set to ‘<samp>dmalloc_t.c:126</samp>’,
dmalloc will start checking the heap after it sees a dmalloc call from the ‘<tt>dmalloc_t.c</tt>’ file, line number 126. If
you use ‘<samp>dmalloc_t.c:0</samp>’, with a 0 line number, then dmalloc will start checking the heap after it sees a call from
anywhere in the ‘<tt>dmalloc_t.c</tt>’ file.
</p>
<hr size="6">
<a name="Programming"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#How-It-Works" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Allocation-Macros" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Overview" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Dmalloc-Program" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="How-to-Program-with-the-Library"></a>
<h1 class="chapter">3. How to Program with the Library</h1>
<a name="index-programming"></a>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Allocation-Macros">3.1 Macros Providing File and Line Information</a></td><td> </td><td align="left" valign="top"> Macros providing file and line information.
</td></tr>
<tr><td align="left" valign="top"><a href="#Return-Address">3.2 Getting Caller Address Information</a></td><td> </td><td align="left" valign="top"> Getting caller address information.
</td></tr>
<tr><td align="left" valign="top"><a href="#Argument-Checking">3.3 Checking of Function Arguments</a></td><td> </td><td align="left" valign="top"> Checking of function arguments.
</td></tr>
<tr><td align="left" valign="top"><a href="#Dumping-Core">3.4 Generating a Core File on Errors</a></td><td> </td><td align="left" valign="top"> Generating a core file on errors for debugging.
</td></tr>
<tr><td align="left" valign="top"><a href="#Extensions">3.5 Additional Non-standard Routines</a></td><td> </td><td align="left" valign="top"> Additional non-standard routines.
</td></tr>
<tr><td align="left" valign="top"><a href="#Error-Codes">3.6 Description of the Internal Error Codes</a></td><td> </td><td align="left" valign="top"> Description of the internal error numbers.
</td></tr>
<tr><td align="left" valign="top"><a href="#Disabling-the-Library">3.7 How to Disable the library</a></td><td> </td><td align="left" valign="top"> How to disable the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#Using-With-C_002b_002b">3.8 Using the Library with C++</a></td><td> </td><td align="left" valign="top"> Using the library with C++.
</td></tr>
<tr><td align="left" valign="top"><a href="#Using-With-a-Debugger">3.9 Using Dmalloc With a Debugger</a></td><td> </td><td align="left" valign="top"> Using a debugger with the library.
</td></tr>
<tr><td align="left" valign="top"><a href="#Using-With-Threads">3.10 Using the Library with a Thread Package</a></td><td> </td><td align="left" valign="top"> Using the library with a thread package.
</td></tr>
<tr><td align="left" valign="top"><a href="#Using-With-Cygwin">3.11 Using the library with Cygwin environment.</a></td><td> </td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#Debugging-A-Server">3.12 Debugging Memory in a Server or Cgi-Bin Process</a></td><td> </td><td align="left" valign="top"> Debugging memory in a server or cgi-bin process.
</td></tr>
<tr><td align="left" valign="top"><a href="#Logfile-Details">3.13 Explanation of the Logfile Output</a></td><td> </td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#Other-Hints">3.14 Various Other Hints That May Help</a></td><td> </td><td align="left" valign="top"> Various other hints that may help.
</td></tr>
</table>
<hr size="6">
<a name="Allocation-Macros"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Programming" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Return-Address" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Programming" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Dmalloc-Program" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Macros-Providing-File-and-Line-Information"></a>
<h2 class="section">3.1 Macros Providing File and Line Information</h2>
<a name="index-allocation-macros"></a>
<a name="index-macros_002c-allocation"></a>
<a name="index-dmalloc_002eh-file"></a>
<p>By including ‘<tt>dmalloc.h</tt>’ in your C files, your calls to malloc, calloc, realloc, recalloc, memalign, valloc,
strdup, and free are replaced with calls to _dmalloc_malloc, _dmalloc_realloc, and _dmalloc_free with various flags.
Additionally the library replaces calls to xmalloc, xcalloc, xrealloc, xrecalloc, xmemalign, xvalloc, xstrdup, and xfree
with associated calls.
</p>
<p>These macros use the c-preprocessor <code>__FILE__</code> and <code>__LINE__</code> macros which get replaced at compilation time
with the current file and line-number of the source code in question. The routines use this information to produce
verbose reports on memory problems.
</p>
<table><tr><td> </td><td><pre class="example">not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
</pre></td></tr></table>
<p>This line from a log file shows that memory was not freed from file ‘<tt>dmalloc_t.c</tt>’ line 92. See section <a href="#Memory-Leaks">Tracking Down Non-Freed Memory</a>.
</p>
<a name="index-recalloc"></a>
<a name="index-memalign"></a>
<a name="index-valloc"></a>
<a name="index-strdup"></a>
<p>You may notice some non standard memory allocation functions in the above list. Recalloc is a routine like realloc that
reallocates previously allocated memory to a new size. If the new memory size is larger than the old, recalloc
initializes the new space to all zeros. This may or may not be supported natively by your operating system. Memalign
is like malloc but should insure that the returned pointer is aligned to a certain number of specified bytes.
Currently, the memalign function is not supported by the library. It defaults to returning possibly non-aligned memory
for alignment values less than a block-size. Valloc is like malloc but insures that the returned pointer will be
aligned to a page boundary. This may or may not be supported natively by your operating system but is fully supported
by the library. Strdup is a string duplicating routine which takes in a null terminated string pointer and returns an
allocated copy of the string that will need to be passed to free later to deallocate.
</p>
<p>The X versions of the standard memory functions (xmalloc, xfree, etc.) will print out an error message to standard
error and will stop if the library is unable to allocate any additional memory. It is useful to use these routines
instead of checking everywhere in your program for allocation routines returning NULL pointers.
</p>
<p><em>WARNING</em>: If you are including the ‘<tt>dmalloc.h</tt>’ file in your sources, it is recommended that it be at the end
of your include file list because dmalloc uses macros and may try to change declarations of the malloc functions if they
come after it.
</p>
<hr size="6">
<a name="Return-Address"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Allocation-Macros" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Argument-Checking" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Programming" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Programming" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Dmalloc-Program" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="#Index-of-Concepts" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Getting-Caller-Address-Information"></a>
<h2 class="section">3.2 Getting Caller Address Information</h2>
<a name="index-caller_0027s-address"></a>
<a name="index-return_002daddress-1"></a>
<a name="index-return_002eh-file"></a>
<a name="index-ra"></a>
<p>Even though the allocation macros can provide file/line information for some of your code, there are still modules which
either you can’t include ‘<tt>dmalloc.h</tt>’ (such as library routines) or you just don’t want to. You can still get
information about the routines that call dmalloc function from the return-address information. To accomplish this, you
must be using this library on one of the supported architecture/compilers. See section <a href="#Portability">Issues Important for Porting the Library</a>.
</p>
<a name="index-assembly-hacks"></a>
<p>The library attempts to use some assembly hacks to get the return-address or the address of the line that called the
dmalloc function. If you have unfreed memory that does not have associated file and line information, you might see the
following non-freed memory messages.
</p>
<table><tr><td> </td><td><pre class="example">not freed: '0x38410' (22 bytes) from 'ra=0xdd2c'
not freed: '0x38600' (10232 bytes) from 'ra=0x10234d'
not freed: '0x38220' (137 bytes) from 'ra=0x82cc'
</pre></td></tr></table>
<a name="index-ra_005finfo_002epl"></a>
<p>With the help of a debugger, these return-addresses (or ra) can then be identified. I’ve provided a ‘<tt>ra_info.pl</tt>’