dmalloc.texi

减少内存碎片的malloc分配函数

@cindex error code 23
@cindex found pointer the user was looking for
@cindex is found error
@cindex ERROR_IS_FOUND

@item 23 (ERROR_IS_FOUND)
This indicates that the pointer specified in the address part of the
environmental variable was discovered by the library.  @xref{Environment
Variable}.  This error is useful so you can put a breakpoint in a
debugger to find where a particular address was allocated.  @xref{Using
With a Debugger}.

@c --------------------------------

@cindex 24, error code
@cindex error code 24
@cindex possibly bad .c filename pointer
@cindex bad file error
@cindex ERROR_BAD_FILE

@item 24 (ERROR_BAD_FILE)
A possibly invalid filename was discovered in the dmalloc administrative
sections.  This could indicate some corruption of the internal tables.
It also could mean that you have a source file whose name is longer than
100 characters.  See @code{MAX_FILE_LENGTH} in the @file{settings.dist}
file.

@c --------------------------------

@cindex 25, error code
@cindex error code 25
@cindex possibly bad .c file line-number
@cindex bad line error
@cindex ERROR_BAD_LINE

@item 25 (ERROR_BAD_LINE)
A line-number was out-of-bounds in the dmalloc administrative sections.
This could indicate some corruption of the internal tables.  It also
could mean that you have a source file containing more than @code{30000}
lines of code.  See @code{MAX_LINE_NUMBER} in the @file{settings.dist}
file.

@c --------------------------------

@cindex 26, error code
@cindex error code 26
@cindex failed under picket-fence magic-number check
@cindex under fence error
@cindex ERROR_UNDER_FENCE

@item 26 (ERROR_UNDER_FENCE)
This indicates that a pointer had its lower bound picket-fence magic
number overwritten.  If the @samp{check-fence} token is enabled, the
library writes magic values above and below allocations to protect
against overflow.  Most likely this is because a pointer below it went
past its allocate and wrote into the next pointer's space.

@c --------------------------------

@cindex 27, error code
@cindex error code 27
@cindex failed over picket-fence magic-number check
@cindex over fence error
@cindex ERROR_OVER_FENCE

@item 27 (ERROR_OVER_FENCE)
This indicates that a pointer had its upper bound picket-fence magic
space overwritten.  If the @samp{check-fence} token is enabled, the
library writes magic values above and below allocations to protect
against overflow.  Most likely this is because an array or string
allocation wrote past the end of the allocation.

Check for improper usage of @code{strcat}, @code{sprintf},
@code{strcpy}, and any other functions which work with strings and do
not protect themselves by tracking the size of the string.  These
functions should @emph{always} be replaced with: @code{strncat},
@code{snprintf}, @code{strncpy}, and others.

@c --------------------------------

@cindex 28, error code
@cindex error code 28
@cindex use of pointer would exceed allocation
@cindex would overwrite error
@cindex ERROR_WOULD_OVERWRITE

@item 28 (ERROR_WOULD_OVERWRITE)
This error is generated by the function pointer checking code usually
enabled wit the @code{check-funcs} token.  Dmalloc overloads a number of
string and memory copying functions and verifies that the buffers (if
allocated in the heap) would not be overwritten by the function.

@c --------------------------------

@cindex 30, error code
@cindex error code 30
@cindex pointer is not to start of memory block
@cindex not start block error
@cindex ERROR_NOT_START_BLOCK

@item 30 (ERROR_NOT_START_BLOCK)
This indicates that the user passed in a pointer to be freed or
reallocated that was not at the start of the allocation.  You would get
this error, for example, if you allocate and get pointer @code{X} but
then try to free @code{X+1}.

@c --------------------------------

@cindex 40, error code
@cindex error code 40
@cindex invalid allocation size
@cindex bad size error
@cindex ERROR_BAD_SIZE

@item 40 (ERROR_BAD_SIZE)
This error indicates that a size value in the internal structures of the
library were corrupted.  This could be a random pointer problem, pointer
overflow, or some other corruption.

@c --------------------------------

@cindex 41, error code
@cindex error code 41
@cindex largest maximum allocation size exceeded
@cindex too big error
@cindex ERROR_TOO_BIG

@item 41 (ERROR_TOO_BIG)
An allocation asked for memory larger than the configured maximum.  This
is a user configured setting.  See @code{LARGEST_ALLOCATION} in the
@file{settings.dist} file.  It is used to protect against wild
allocation sizes.  If you have super large allocation sizes then you
should tune the @code{LARGEST_ALLOCATION} value appropriately.

@c --------------------------------

@cindex 43, error code
@cindex error code 43
@cindex could not grow heap by allocating memory
@cindex alloc failed error
@cindex ERROR_ALLOC_FAILED

@item 43 (ERROR_ALLOC_FAILED)
The library could not allocate more heap space and the program has run
out of memory.  This could indicate that you've overflowed some system
imposed limit.  On many operation systems, the @code{ulimit} call can
tune system defaults.

@c --------------------------------

@cindex 44, error code
@cindex error code 44
@cindex heap failed to produce linear address space
@cindex alloc nonlinear error
@cindex ERROR_ALLOC_NONLINEAR

@item 44 (ERROR_ALLOC_NONLINEAR)
If the @code{force-linear} token is enabled, the library will ensure
that the heap memory returned, is linear and contiguous.  This should
only be used in special circumstances.

@c --------------------------------

@cindex 45, error code
@cindex error code 45
@cindex memory limit
@cindex over user specified allocation limit error
@cindex over limit error
@cindex ERROR_OVER_LIMIT

@item 45 (ERROR_OVER_LIMIT)
The library has allocated more memory than was specified in the
memory-limit environmental variable.  @xref{Environment Variable}.

@c --------------------------------

@cindex 60, error code
@cindex error code 60
@cindex pointer is not on block boundary
@cindex not on block boundary error
@cindex ERROR_NOT_ON_BLOCK

@item 60 (ERROR_NOT_ON_BLOCK)
The user tried to free or realloc a pointer that was not pointing to a
block boundary.  You would get this error, for example, if you allocate
and get pointer @code{X} but then try to free @code{X+1}.

@c --------------------------------

@cindex 61, error code
@cindex error code 61
@cindex tried to free previously freed pointer
@cindex already free error
@cindex ERROR_ALREADY_FREE

@item 61 (ERROR_ALREADY_FREE)
The user tried to free a pointer than has already been freed.  This is a
very common mistake and can lead to serious problems.  It can be because
a destructor is being called twice for some reason.  Although tracking
down the specific source is highly recommended, it is good to set
pointers to NULL (0L) after you free them as a rule.

@c --------------------------------

@cindex 67, error code
@cindex error code 67
@cindex free space has been overwritten
@cindex free overwritten error
@cindex ERROR_FREE_OVERWRITTEN
@cindex free-blank
@cindex check-blank

@item 67 (ERROR_FREE_OVERWRITTEN)
If either the @code{free-blank} or @code{check-blank} tokens are enabled
then the library will overwrite memory when it is freed with the
``dmalloc-free'' byte (hex 0xdf, octal 0337, decimal 223).  If the
program writes into this space, then the library will detect the write
and trigger this error.  This could indicate that the program is using a
pointer after it has been freed.

@c --------------------------------

@cindex 70, error code
@cindex error code 70
@cindex bad admin structure list
@cindex admin list error
@cindex ERROR_ADMIN_LIST

@item 70 (ERROR_ADMIN_LIST)
An internal corruption in the library's administrative structures has
been detected.  This could be a random pointer problem, pointer
overflow, or some other corruption.

@c --------------------------------

@cindex 72, error code
@cindex error code 72
@cindex internal address list corruption
@cindex address list error
@cindex ERROR_ADDRESS_LIST

@item 72 (ERROR_ADDRESS_LIST)
An internal corruption in the library's administrative structures has
been detected.  This could be a random pointer problem, pointer
overflow, or some other corruption.

@c --------------------------------

@cindex 73, error code
@cindex error code 73
@cindex internal memory slot corruption
@cindex slot corrupt error
@cindex ERROR_SLOT_CORRUPT

@item 73 (ERROR_SLOT_CORRUPT)
An internal corruption in the library's administrative structures has
been detected.  This could be a random pointer problem, pointer
overflow, or some other corruption.

@end table

@c --------------------------------

@node Disabling the Library, Using With C++, Error Codes, Programming
@section How to Disable the library

@cindex disabling the library

When you are finished with the development and debugging sessions, you
may want to disable the dmalloc library and put in its place either the
system's memory-allocation routines, gnu-malloc, or maybe your own.
Attempts have been made to make this a reasonably painless process.  The
ease of the extraction depends heavily on how many of the library's
features your made use of during your coding.

Reasonable suggestions are welcome as to how to improve this process
while maintaining the effectiveness of the debugging.

@itemize @bullet
@item
If you want to @emph{totally} disable the dmalloc library then you will
need to recompile all the C files that include @file{dmalloc.h} while
defining @code{DMALLOC_DISABLE}.  This will cause the dmalloc macros to
not be applied.  @xref{Allocation Macros}.

@example
cc -g -DDMALLOC_DISABLE main.c
@end example

An alternative is to surround the @code{dmalloc.h} inclusion or any
direct dmalloc references with an @code{#ifdef DMALLOC} and then just
remove the -DDMALLOC.

@example
#ifdef DMALLOC
#include "dmalloc.h"
#endif

main()
@{
  @dots{}

#ifdef DMALLOC
  dmalloc_verify(0L);
#endif
  return 0;
@}
@end example

@example
// to get dmalloc information
$ cc -Ddmalloc main.c

// without dmalloc information
$ cc main.c
@end example

@item
If you compiled any of your source modules with @code{DMALLOC_FUNC_CHECK}
defined then you must first recompile all those modules without the flag
enabled.

If you have disabled dmalloc with the @code{DMALLOC_DISABLED} flag or
never included @file{dmalloc.h} in any of your C files, then you will
not need to recompile your sources when you need to disable the library.

If you get unresolved references like @code{_dmalloc_malloc} or
@code{_dmalloc_bcopy} then something was not disabled as it should have
been.
@end itemize

@c --------------------------------

@node Using With C++, Using With a Debugger, Disabling the Library, Programming
@section Using the Library with C++

@cindex c++ usage
@cindex dmallocc.cc file

@cindex libdmallocxx.a
For those people using the C++ language, the library tries to configure
and build @file{libdmallocxx.a} library.  This library should be linked
into your C++ programs instead of @file{libdmalloc.a}.

@cindex dmallocc.cc
Dmalloc is not as good with C++ as C because the dynamic memory routines
in C++ are @code{new()} and @code{delete()} as opposed to
@code{malloc()} and @code{free()}.  Since new and delete are usually not
used as functions but rather as @code{x = new type}, there is no easy
way for dmalloc to pass in file and line information unfortunately.  The
@file{libdmallocxx.a} library provides the file @file{dmallocc.cc} which
effectively redirects @code{new} to the more familiar @code{malloc} and
@code{delete} to the more familiar @code{free}.

@emph{NOTE}: The author is not a C++ hacker so feedback in the form of
other hints and ideas for C++ users would be much appreciated.

@c --------------------------------

@node Using With a Debugger, Using With Threads, Using With C++, Programming
@section Using Dmalloc With a Debugger

@cindex debugger usage with dmalloc
@cindex using a debugger with dmalloc

Here are a number of possible scenarios for using the dmalloc library to
track down problems with your program.

You should