dmalloc.html

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

It will return DMALLOC_NOERROR or DMALLOC_ERROR depending on whether pnt
is good or not.


<P>
<EM>NOTE</EM>: This function is <EM>certainly</EM> not provided by most if
not all other malloc libraries.


</DL>

<P>
<A NAME="IDX127"></A>
<A NAME="IDX128"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX129"></A>
void dmalloc_track ( const dmalloc_track_t <VAR>track_func</VAR> )


<P>
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.


</DL>

<P>
<A NAME="IDX130"></A>
<A NAME="IDX131"></A>
<A NAME="IDX132"></A>
<A NAME="IDX133"></A>
<A NAME="IDX134"></A>
<A NAME="IDX135"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX136"></A>
unsigned unsigned long dmalloc_mark ( void )


<P>
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</CODE> function.  Multiple marks can be saved and
used.


<P>
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</CODE> function below.  See section <A HREF="dmalloc.html#SEC25">3.11 Debugging Memory in a Server or Cgi-Bin Process</A>.


<P>
If you <CODE>LOG_ITERATION</CODE> enabled in your <TT>`settings.h'</TT> 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</CODE> in <TT>`settings.h'</TT> to store the memory
transaction number with each pointer.


</DL>

<P>
<A NAME="IDX137"></A>
<A NAME="IDX138"></A>
<A NAME="IDX139"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX140"></A>
unsigned unsigned long dmalloc_memory_allocated ( void )


<P>
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.


</DL>

<P>
<A NAME="IDX141"></A>
<A NAME="IDX142"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX143"></A>
unsigned unsigned int dmalloc_page_size ( void )


<P>
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()</CODE> function, if available.


</DL>

<P>
<A NAME="IDX144"></A>
<A NAME="IDX145"></A>
<A NAME="IDX146"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX147"></A>
unsigned unsigned long dmalloc_count_changed ( const unsigned long <VAR>mark</VAR>,
const int <VAR>not_freed_b</VAR>, const int <VAR>free_b</VAR> )


<P>
Count the pointers that have changed since the mark which was returned by
<CODE>dmalloc_mark</CODE>.  If <CODE>not_freed_b</CODE> is set to non-0 then count the
pointers that have not been freed.  If <CODE>free_b</CODE> is set to non-0
then count the pointers that have been freed.


<P>
This can be used in conjunction with the <CODE>dmalloc_mark()</CODE>
function to help servers which never exit ensure that transactions or
events are not leaking memory.  See section <A HREF="dmalloc.html#SEC25">3.11 Debugging Memory in a Server or Cgi-Bin Process</A>.



<PRE>
unsigned long mark = dmalloc_mark() ;
...
assert(dmalloc_count_changed(mark, 1, 0) == 0) ;
</PRE>

</DL>

<P>
<A NAME="IDX148"></A>
<A NAME="IDX149"></A>
<A NAME="IDX150"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX151"></A>
void dmalloc_log_stats ( void )


<P>
This routine outputs the current dmalloc statistics to the log file.
</DL>


<P>
<A NAME="IDX152"></A>
<A NAME="IDX153"></A>
<A NAME="IDX154"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX155"></A>
void dmalloc_log_unfreed( void )


<P>
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.


</DL>

<P>
<A NAME="IDX156"></A>
<A NAME="IDX157"></A>
<A NAME="IDX158"></A>
<A NAME="IDX159"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX160"></A>
void dmalloc_log_changed ( const unsigned long <VAR>mark</VAR>, const int
<VAR>not_freed_b</VAR>, const int <VAR>freed_b</VAR>, const int <VAR>details_b</VAR> )


<P>
Log the pointers that have changed since the mark which was returned by
<CODE>dmalloc_mark</CODE>.  If <CODE>not_freed_b</CODE> is set to non-0 then log the
pointers that have not been freed.  If <CODE>free_b</CODE> is set to non-0
then log the pointers that have been freed.  If <CODE>details_b</CODE> set to
non-0 then log the individual pointers that have changed otherwise just
log the summaries.


<P>
This can be used in conjunction with the <CODE>dmalloc_mark()</CODE>
function to help servers which never exit find transactions or events
which are leaking memory.  See section <A HREF="dmalloc.html#SEC25">3.11 Debugging Memory in a Server or Cgi-Bin Process</A>.


</DL>

<P>
<A NAME="IDX161"></A>
<A NAME="IDX162"></A>
<A NAME="IDX163"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX164"></A>
void dmalloc_vmessage ( const char * <VAR>format</VAR>, va_list <VAR>args</VAR> )


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


</DL>

<P>
<A NAME="IDX165"></A>
<A NAME="IDX166"></A>
<A NAME="IDX167"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX168"></A>
void dmalloc_message ( const char * <VAR>format</VAR>, <VAR>...</VAR> )


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


</DL>

<P>
<A NAME="IDX169"></A>
<A NAME="IDX170"></A>
<A NAME="IDX171"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX172"></A>
const char * dmalloc_strerror ( const int <VAR>error_number</VAR> )


<P>
This function returns the string representation of the error value in
<CODE>error_number</CODE> (which probably should be dmalloc_errno).  This
allows the logging of more verbose memory error messages.


<P>
You can also display the string representation of an error value by a
call to the <TT>`dmalloc'</TT> program with a <SAMP>`-e #'</SAMP> option.
See section <A HREF="dmalloc.html#SEC26">4. Dmalloc Utility Program</A>.


</DL>



<H2><A NAME="SEC15" HREF="dmalloc.html#TOC15">3.5 Description of the Internal Error Codes</A></H2>

<P>
<A NAME="IDX173"></A>


<P>
The following error codes are defined in <TT>`error_val.h'</TT>.  They are
used by the library to indicate a detected problem.  They can be caused
by the user (<SAMP>`ERROR_TOO_BIG'</SAMP>) or can indicate an internal library
problem (<SAMP>`ERROR_SLOT_CORRUPT'</SAMP>).  The <TT>`dmalloc'</TT> utility can
give you the string version of the error with the <CODE>-e</CODE> argument:



<PRE>
$ dmalloc -e 60
dmalloc: dmalloc_errno value '60' = 
   'pointer is not on block boundary'
</PRE>

<P>
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.


<DL COMPACT>

<DT><CODE>1 (ERROR_NONE)</CODE>
<DD>
<A NAME="IDX174"></A>
 <A NAME="IDX175"></A>
 <A NAME="IDX176"></A>
 <A NAME="IDX177"></A>
 
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.

<A NAME="IDX178"></A>
<A NAME="IDX179"></A>
<A NAME="IDX180"></A>
<A NAME="IDX181"></A>
<A NAME="IDX182"></A>

<DT><CODE>2 (INVALID_ERROR)</CODE>
<DD>
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.

<A NAME="IDX183"></A>
<A NAME="IDX184"></A>
<A NAME="IDX185"></A>
<A NAME="IDX186"></A>
<A NAME="IDX187"></A>

<DT><CODE>10 (ERROR_BAD_SETUP)</CODE>
<DD>
Bad setup value.  This is currently unused but it is intended to report
on invalid setup configuration information.

<A NAME="IDX188"></A>
<A NAME="IDX189"></A>
<A NAME="IDX190"></A>
<A NAME="IDX191"></A>
<A NAME="IDX192"></A>
<A NAME="IDX193"></A>
<A NAME="IDX194"></A>

<DT><CODE>11 (ERROR_IN_TWICE)</CODE>
<DD>
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'</SAMP> "lock-on" option.  See section <A HREF="dmalloc.html#SEC23">3.9 Using the Library with a Thread Package</A>.

<A NAME="IDX195"></A>
<A NAME="IDX196"></A>
<A NAME="IDX197"></A>
<A NAME="IDX198"></A>
<A NAME="IDX199"></A>

<DT><CODE>13 (ERROR_LOCK_NOT_CONFIG)</CODE>
<DD>
Thread locking has not been configured.  This indicates that you
attempted to use the <SAMP>`-o'</SAMP> "lock-on" option without linking with the
thread version of the library.

<A NAME="IDX200"></A>
<A NAME="IDX201"></A>
<A NAME="IDX202"></A>
<A NAME="IDX203"></A>
<A NAME="IDX204"></A>
<A NAME="IDX205"></A>
<A NAME="IDX206"></A>

<DT><CODE>20 (ERROR_IS_NULL)</CODE>
<DD>
Pointer is null.  The program passed a NULL (0L) pointer to <CODE>free</CODE>
and you have the <SAMP>`error-free-null'</SAMP> token enabled.

<A NAME="IDX207"></A>
<A NAME="IDX208"></A>
<A NAME="IDX209"></A>
<A NAME="IDX210"></A>
<A NAME="IDX211"></A>
<A NAME="IDX212"></A>

<DT><CODE>21 (ERROR_NOT_IN_HEAP)</CODE>
<DD>
Pointer is not pointing to heap data space.  This means that the program
passed an out-of-bounds pointer to <CODE>free</CODE> or <CODE>realloc</CODE>.  This
could be someone trying to work with a wild pointer or trying to free a
pointer from a different source than <CODE>malloc</CODE>.

<A NAME="IDX213"></A>
<A NAME="IDX214"></A>
<A NAME="IDX215"></A>
<A NAME="IDX216"></A>
<A NAME="IDX217"></A>
<A NAME="IDX218"></A>
<A NAME="IDX219"></A>
<A NAME="IDX220"></A>

<DT><CODE>22 (ERROR_NOT_FOUND)</CODE>
<DD>
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</CODE> or <CODE>sbrk</CODE> 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.

<A NAME="IDX221"></A>
<A NAME="IDX222"></A>