dmalloc.texi

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

dmalloc_debug_setup("debug=0x4f46d03,lockon=20,log=dmalloc.%p");

/* turn on some debug tokens directly and log to the file 'logfile' */
dmalloc_debug_setup("log-stats,log-non-free,check-fence,log=logfile");
@end example

@end deftypefun

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

@cindex dmalloc_examine function
@cindex examine a pointer
@cindex pointer information

@deftypefun
int dmalloc_examine ( const DMALLOC_PNT @var{pnt}, DMALLOC_SIZE *
@var{user_size_p}, DMALLOC_SIZE * @var{total_size_p}, char **
@var{file_p}, int * @var{line_p}, DMALLOC_PNT * @var{ret_addr_p},
unsigned long * @var{user_mark_p}, unsigned long * @var{seen_p} )

This function returns the size of a pointer's allocation as well as the
total size given including administrative overhead, file and line or the
return-address from where it was allocated, the last pointer when the
pointer was "used", and the number of times the pointer has been "seen".
It will return DMALLOC_NOERROR or DMALLOC_ERROR depending on whether pnt
is good or not.

@emph{NOTE}: This function is @emph{certainly} not provided by most if
not all other malloc libraries.

@end deftypefun

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

@cindex dmalloc_track function
@cindex track memory calls

@deftypefun
void dmalloc_track ( const dmalloc_track_t @var{track_func} )

Register an allocation tracking function which will be called each time
an allocation occurs.  Pass in NULL to disable.  To take a look at what
information is provided, see the dmalloc_track_t function typedef in
dmalloc.h.

@end deftypefun

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

@cindex dmalloc_mark function
@cindex memory position marker
@cindex mark memory position
@cindex LOG_ITERATION
@cindex interaction count
@cindex transaction count

@deftypefun
unsigned unsigned long dmalloc_mark ( void )

Return to the caller the current "mark" which can be used later to log
the pointers which have changed since this mark with the
@code{dmalloc_log_changed} function.  Multiple marks can be saved and
used.

This is very useful when using the library with a server which does
not exit.  You can then save a mark before a transaction or event
happens and then check to see what has changed using the
@code{dmalloc_log_changed} function below.  @xref{Debugging A Server}.

If you @code{LOG_ITERATION} enabled in your @file{settings.h} file then
the entries in the log file will be prepended with the number of memory
transactions that the library has handled so far.  You can also enable
@code{LOG_PNT_ITERATION} in @file{settings.h} to store the memory
transaction number with each pointer.

@end deftypefun

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

@cindex dmalloc_memory_allocated function
@cindex memory allocated function
@cindex number of bytes allocated

@deftypefun
unsigned unsigned long dmalloc_memory_allocated ( void )

Return to the caller the total number of bytes that have been allocated
by the library.  This is not the current in use but the total number of
bytes returned by allocation functions.

@end deftypefun

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

@cindex page size
@cindex size of memory pages

@deftypefun
unsigned unsigned int dmalloc_page_size ( void )

Return to the caller the memory page-size being used by the library.
This should be the same value as the one returned by the
@code{getpagesize()} function, if available.

@end deftypefun

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

@cindex count changed
@cindex count number of bytes changed since mark
@cindex number bytes changed since mark

@deftypefun
unsigned unsigned long dmalloc_count_changed ( const unsigned long @var{mark},
const int @var{not_freed_b}, const int @var{free_b} )

Count the pointers that have changed since the mark which was returned by
@code{dmalloc_mark}.  If @code{not_freed_b} is set to non-0 then count the
pointers that have not been freed.  If @code{free_b} is set to non-0
then count the pointers that have been freed.

This can be used in conjunction with the @code{dmalloc_mark()}
function to help servers which never exit ensure that transactions or
events are not leaking memory.  @xref{Debugging A Server}.

@example
unsigned long mark = dmalloc_mark() ;
@dots{}
assert(dmalloc_count_changed(mark, 1, 0) == 0) ;
@end example

@end deftypefun

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

@cindex dmalloc_log_stats function
@cindex log statistics
@cindex statistics logging

@deftypefun
void dmalloc_log_stats ( void )

This routine outputs the current dmalloc statistics to the log file.
@end deftypefun

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

@cindex dmalloc_log_unfreed function
@cindex log unfreed memory
@cindex unfreed memory log

@deftypefun
void dmalloc_log_unfreed( void )

This function logs the unfreed-memory information to the log file.
This is also useful to log the currently allocated points to the log
file to be compared against another dump later on.

@end deftypefun

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

@cindex dmalloc_log_changed function
@cindex changed memory log
@cindex checkpoint memory usage
@cindex log memory changes

@deftypefun
void dmalloc_log_changed ( const unsigned long @var{mark}, const int
@var{not_freed_b}, const int @var{freed_b}, const int @var{details_b} )

Log the pointers that have changed since the mark which was returned by
@code{dmalloc_mark}.  If @code{not_freed_b} is set to non-0 then log the
pointers that have not been freed.  If @code{free_b} is set to non-0
then log the pointers that have been freed.  If @code{details_b} set to
non-0 then log the individual pointers that have changed otherwise just
log the summaries.

This can be used in conjunction with the @code{dmalloc_mark()}
function to help servers which never exit find transactions or events
which are leaking memory.  @xref{Debugging A Server}.

@end deftypefun

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

@cindex dmalloc_vmessage function
@cindex write message to logfile
@cindex logfile message writer

@deftypefun
void dmalloc_vmessage ( const char * @var{format}, va_list @var{args} )

Write a message into the dmalloc logfile using vprintf-like arguments.

@end deftypefun

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

@cindex dmalloc_message function
@cindex write message to logfile
@cindex logfile message writer

@deftypefun
void dmalloc_message ( const char * @var{format}, @var{...} )

Write a message into the dmalloc logfile using printf-like arguments.

@end deftypefun

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

@cindex dmalloc_strerror function
@cindex string error message
@cindex error message

@deftypefun
const char * dmalloc_strerror ( const int @var{error_number} )

This function returns the string representation of the error value in
@code{error_number} (which probably should be dmalloc_errno).  This
allows the logging of more verbose memory error messages.

You can also display the string representation of an error value by a
call to the @file{dmalloc} program with a @samp{-e #} option.
@xref{Dmalloc Program}.

@end deftypefun

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

@node Error Codes, Disabling the Library, Extensions, Programming
@section Description of the Internal Error Codes

@cindex error codes

The following error codes are defined in @file{error_val.h}.  They are
used by the library to indicate a detected problem.  They can be caused
by the user (@samp{ERROR_TOO_BIG}) or can indicate an internal library
problem (@samp{ERROR_SLOT_CORRUPT}).  The @file{dmalloc} utility can
give you the string version of the error with the @code{-e} argument:

@example
$ dmalloc -e 60
dmalloc: dmalloc_errno value '60' = 
   'pointer is not on block boundary'
@end example

Here are the error codes set by the library.  They are non contiguous on
purpose because I add and delete codes all of the time and there are
sections for various error-code types.

@table @code

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

@cindex 1, error code
@cindex error code, 1
@cindex no error
@cindex ERROR_NONE

@item 1 (ERROR_NONE)
No error.  It is good coding practice to set the no-error code to be
non-0 value because it forces you to set it explicitly.

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

@cindex 2, error code
@cindex error code, 2
@cindex invalid errno value
@cindex errno value is not valid
@cindex INVALID_ERROR

@item 2 (INVALID_ERROR)
Invalid error number.  If the library outputs this error however the
dmalloc utility says that it is invalid then your dmalloc utility may be
out of date with the library you linked against.  This will be returned
with all error codes not listed here.

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

@cindex 10, error code
@cindex error code 10
@cindex initialization and setup failed
@cindex bad setup error
@cindex ERROR_BAD_SETUP

@item 10 (ERROR_BAD_SETUP)
Bad setup value.  This is currently unused but it is intended to report
on invalid setup configuration information.

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

@cindex lock-on
@cindex recursion
@cindex in twice error
@cindex 11, error code
@cindex error code 11
@cindex malloc library has gone recursive
@cindex ERROR_IN_TWICE

@item 11 (ERROR_IN_TWICE)
Library went recursive.  This usually indicates that you are not using
the threaded version of the library.  Or if you are then you are not
using the @samp{-o} "lock-on" option.  @xref{Using With Threads}.

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

@cindex lock-on not configured
@cindex 13, error code
@cindex error code 13
@cindex thread locking has not been configured
@cindex ERROR_LOCK_NOT_CONFIG

@item 13 (ERROR_LOCK_NOT_CONFIG)
Thread locking has not been configured.  This indicates that you
attempted to use the @samp{-o} "lock-on" option without linking with the
thread version of the library.

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

@cindex error-free-null token
@cindex free null token
@cindex 20, error code
@cindex error code 20
@cindex pointer is null error
@cindex is null error
@cindex ERROR_IS_NULL

@item 20 (ERROR_IS_NULL)
Pointer is null.  The program passed a NULL (0L) pointer to @code{free}
and you have the @samp{error-free-null} token enabled.

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

@cindex pointer not in heap error
@cindex not in heap error
@cindex 21, error code
@cindex error code 21
@cindex pointer is not pointing to heap data space
@cindex ERROR_NOT_IN_HEAP

@item 21 (ERROR_NOT_IN_HEAP)
Pointer is not pointing to heap data space.  This means that the program
passed an out-of-bounds pointer to @code{free} or @code{realloc}.  This
could be someone trying to work with a wild pointer or trying to free a
pointer from a different source than @code{malloc}.

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

@cindex not found error
@cindex pointer not found error
@cindex 22, error code
@cindex error code 22
@cindex cannot locate pointer in heap
@cindex ERROR_NOT_FOUND
@cindex mmap
@cindex sbrk

@item 22 (ERROR_NOT_FOUND)
Cannot locate pointer in heap.  The user passed in a pointer which the
heap did not know about.  Either this pointer was allocated by some
other mechanism (like @code{mmap} or @code{sbrk} directly) or it is a
random invalid pointer.

In some rare circumstances, sometimes seen with shared libraries, there
can be two separate copies of the dmalloc library in a program.  Each
one does not know about the pointers allocated by the other.

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

@cindex 23, error code