dmalloc.texi

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

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.

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.

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.

@cindex check-heap
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
'check-heap' debug token.  @xref{Debug Tokens}.  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.

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.  @xref{Dmalloc Program}.  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.

@cindex LOG_ITERATION_COUNT
@cindex iteration count
@cindex memory transaction count
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} enabled in your
@file{settings.h} file.

The start option can also have the format @samp{file:line}.  For
instance, if it is set to @samp{dmalloc_t.c:126}, dmalloc will start
checking the heap after it sees a dmalloc call from the
@file{dmalloc_t.c} file, line number 126.  If you use
@samp{dmalloc_t.c:0}, with a 0 line number, then dmalloc will start
checking the heap after it sees a call from anywhere in the
@file{dmalloc_t.c} file.

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

@node Programming, Dmalloc Program, Overview, Top
@chapter How to Program with the Library

@cindex programming

@menu
* Allocation Macros::          Macros providing file and line information.
* Return Address::             Getting caller address information.
* Argument Checking::          Checking of function arguments.
* Extensions::                 Additional non-standard routines.
* Error Codes::                Description of the internal error numbers.
* Disabling the Library::      How to disable the library.
* Using With C++::             Using the library with C++.
* Using With a Debugger::      Using a debugger with the library.
* Using With Threads::         Using the library with a thread package.
* Using With Cygwin::          Using the library with Cygwin environment.
* Debugging A Server::         Debugging memory in a server or cgi-bin process.
@end menu

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

@node Allocation Macros, Return Address, Programming, Programming
@section Macros Providing File and Line Information

@cindex allocation macros
@cindex macros, allocation
@cindex dmalloc.h file

By including @file{dmalloc.h} 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.

These macros use the c-preprocessor @code{__FILE__} and @code{__LINE__}
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.

@example
not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
@end example

This line from a log file shows that memory was not freed from file
@file{dmalloc_t.c} line 92.  @xref{Memory Leaks}.

@cindex recalloc
@cindex memalign
@cindex valloc
@cindex strdup

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.

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.

@emph{WARNING}: If you are including the @file{dmalloc.h} 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.

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

@node Return Address, Argument Checking, Allocation Macros, Programming
@section Getting Caller Address Information

@cindex caller's address
@cindex return-address
@cindex return.h file
@cindex ra

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 @file{dmalloc.h} (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.  @xref{Portability}.

@cindex assembly hacks

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.

@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'
@end example

@cindex ra_info.pl
With the help of a debugger, these return-addresses (or ra) can then be
identified.  I've provided a @file{ra_info.pl} perl script in the
@file{contrib/} directory with the dmalloc sources which seems to work
well with gdb.  You can also use manual methods for gdb to find the
return-address location.  @xref{Translate Return Addresses}.

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

@node Argument Checking, Extensions, Return Address, Programming
@section Checking of Function Arguments

@cindex argument checking
@cindex checking arguments
@cindex DMALLOC_FUNC_CHECK flag

One potential problem with the library and its multitude of checks and
diagnoses is that they only get performed when a dmalloc function is
called.  One solution this is to include @file{dmalloc.h} and compile
your source code with the @code{DMALLOC_FUNC_CHECK} flag defined and
enable the @code{check-funcs} token.  @xref{Debug Tokens}.

@example
cc -DDMALLOC_FUNC_CHECK file.c
@end example

@emph{NOTE}: Once you have compiled your source with DMALLOC_FUNC_CHECK
enabled, you will have to recompile with it off to disconnect the
library.  @xref{Disabling the Library}.

@emph{WARNING}: You should be sure to have @file{dmalloc.h} included at
the end of your include file list because dmalloc uses macros and may
try to change declarations of the checked functions if they come after
it.

When this is defined dmalloc will override a number of functions and
will insert a routine which knows how to check its own arguments and
then call the real function.  Dmalloc can check such functions as
@code{bcopy}, @code{index}, @code{strcat}, and @code{strcasecmp}.  For
the full list see the end of @file{dmalloc.h}.

When you call @code{strlen}, for instance, dmalloc will make sure the
string argument's fence-post areas have not been overwritten, its file
and line number locations are good, etc.  With @code{bcopy}, dmalloc
will make sure that the destination string has enough space to store the
number of bytes specified.

For all of the arguments checked, if the pointer is not in the heap then
it is ignored since dmalloc does not know anything about it.

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

@node Extensions, Error Codes, Argument Checking, Programming
@section Additional Non-standard Routines

@cindex extensions

The library has a number of variables that are not a standard part of
most malloc libraries:

@table @code

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

@cindex dmalloc_errno number
@cindex internal error number
@cindex error number

@item int dmalloc_errno

This variable stores the internal dmalloc library error number like errno
does for the system calls.  It can be passed to @code{dmalloc_strerror()}
(see below) to get a string version of the error.  It will have a value
of zero if the library has not detected any problems.

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

@cindex dmalloc_logpath variable
@cindex logfile name

@item char * dmalloc_logpath

This variable can be used to set the dmalloc log filename.  The env
variable DMALLOC_LOGFILE overrides this variable.

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

@end table

Additionally the library provides a number of non-standard malloc
routines:

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

@cindex dmalloc_shutdown function
@cindex shutdown the library

@deftypefun
void dmalloc_shutdown ( void )

This function shuts the library down and logs the final statistics and
information especially the non-freed memory pointers.  The library has
code to support auto-shutdown if your system has the @code{on_exit()}
call, @code{atexit()} call, or compiler destructor support (see
@file{conf.h}).  If you do not have these, then @code{dmalloc_shutdown}
should be called right before @code{exit()} or as the last function in
@code{main()}.

@example
main()
@{
        @dots{}
        dmalloc_shutdown();
        exit(0);
@}
@end example
@end deftypefun

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

@cindex dmalloc_verify function
@cindex verify pointers
@cindex verify the heap

@deftypefun
int dmalloc_verify ( char * @var{pnt} )

This function verifies individual memory pointers that are suspect of
memory problems.  To check the entire heap pass in a NULL or 0 pointer.
The routine returns DMALLOC_VERIFY_ERROR or DMALLOC_VERIFY_NOERROR.

@emph{NOTE}: @samp{dmalloc_verify()} can only check the heap with the
functions that have been enabled.  For example, if fence-post checking
is not enabled, @samp{dmalloc_verify()} cannot check the fence-post
areas in the heap.
@end deftypefun

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

@cindex dmalloc_debug function
@cindex override debug settings
@cindex set debug functionality flags

@deftypefun
unsigned int dmalloc_debug ( const unsigned int @var{flags} )

This routine sets the debug functionality flags and returns the
previous flag value.  It is helpful in server or cgi-bin programs
where environmental variables cannot be used.  @xref{Debugging A
Server}.  For instance, if debugging should never be enabled for a
program, a call to @code{dmalloc_debug(0)} as the first call in
@code{main()} will disable all the memory debugging from that point
on.

@emph{NOTE}: you cannot add or remove certain flags such as signal
handlers since they are setup at initialization time only.

@emph{NOTE}: you can also use @code{dmalloc_debug_setup} below.

@end deftypefun

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

@cindex dmalloc_debug_current function
@cindex current debug value

@deftypefun
unsigned int dmalloc_debug_current ( void )

This routine returns the current debug functionality value value.  This
allows you to save a copy of the debug dmalloc settings to be changed
and then restored later.

@end deftypefun

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

@cindex dmalloc_debug_setup
@cindex override debug settings
@cindex set debug functionality flags
@cindex setup debug flags
@cindex string of debug tokens

@deftypefun
void dmalloc_debug_setup ( const char * @var{options_str} )

This routine sets the global debugging functionality as an option
string.  Normally this would be passed in in the DMALLOC_OPTIONS
environmental variable.  This is here to override the env or for
circumstances where modifying the environment is not possible or does
not apply such as servers or cgi-bin programs.  @xref{Debugging A
Server}.

Some examples:

@example
/* debug tokens high, threaded lock-on at 20, log to dmalloc.%p (pid) */