dmalloc.html

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

<A NAME="IDX78"></A>
<A NAME="IDX79"></A>
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>
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.




<H1><A NAME="SEC10" HREF="dmalloc.html#TOC10">3. How to Program with the Library</A></H1>

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




<H2><A NAME="SEC11" HREF="dmalloc.html#TOC11">3.1 Macros Providing File and Line Information</A></H2>

<P>
<A NAME="IDX81"></A>
<A NAME="IDX82"></A>
<A NAME="IDX83"></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>
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.



<PRE>
not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
</PRE>

<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="dmalloc.html#SEC20">3.8.2 Tracking Down Non-Freed Memory</A>.


<P>
<A NAME="IDX84"></A>
<A NAME="IDX85"></A>
<A NAME="IDX86"></A>
<A NAME="IDX87"></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>
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>
<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.




<H2><A NAME="SEC12" HREF="dmalloc.html#TOC12">3.2 Getting Caller Address Information</A></H2>

<P>
<A NAME="IDX88"></A>
<A NAME="IDX89"></A>
<A NAME="IDX90"></A>
<A NAME="IDX91"></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="dmalloc.html#SEC35">5.3 Issues Important for Porting the Library</A>.


<P>
<A NAME="IDX92"></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.



<PRE>
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>

<P>
<A NAME="IDX93"></A>
With the help of a debugger, these return-addresses (or ra) can then be
identified.  I've provided a <TT>`ra_info.pl'</TT> perl script in the
<TT>`contrib/'</TT> 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.  See section <A HREF="dmalloc.html#SEC22">3.8.4 Translating Return Addresses into Code Locations</A>.




<H2><A NAME="SEC13" HREF="dmalloc.html#TOC13">3.3 Checking of Function Arguments</A></H2>

<P>
<A NAME="IDX94"></A>
<A NAME="IDX95"></A>
<A NAME="IDX96"></A>


<P>
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 <TT>`dmalloc.h'</TT> and compile
your source code with the <CODE>DMALLOC_FUNC_CHECK</CODE> flag defined and
enable the <CODE>check-funcs</CODE> token.  See section <A HREF="dmalloc.html#SEC30">4.4 Description of the Debugging Tokens</A>.



<PRE>
cc -DDMALLOC_FUNC_CHECK file.c
</PRE>

<P>
<EM>NOTE</EM>: Once you have compiled your source with DMALLOC_FUNC_CHECK
enabled, you will have to recompile with it off to disconnect the
library.  See section <A HREF="dmalloc.html#SEC16">3.6 How to Disable the library</A>.


<P>
<EM>WARNING</EM>: You should be sure to have <TT>`dmalloc.h'</TT> 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.


<P>
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>, <CODE>index</CODE>, <CODE>strcat</CODE>, and <CODE>strcasecmp</CODE>.  For
the full list see the end of <TT>`dmalloc.h'</TT>.


<P>
When you call <CODE>strlen</CODE>, 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</CODE>, dmalloc
will make sure that the destination string has enough space to store the
number of bytes specified.


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




<H2><A NAME="SEC14" HREF="dmalloc.html#TOC14">3.4 Additional Non-standard Routines</A></H2>

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


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


<DL COMPACT>

<DT><CODE>int dmalloc_errno</CODE>
<DD>
<A NAME="IDX98"></A>
 <A NAME="IDX99"></A>
 <A NAME="IDX100"></A>
 

This variable stores the internal dmalloc library error number like errno
does for the system calls.  It can be passed to <CODE>dmalloc_strerror()</CODE>
(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.

<A NAME="IDX101"></A>
<A NAME="IDX102"></A>

<DT><CODE>char * dmalloc_logpath</CODE>
<DD>
This variable can be used to set the dmalloc log filename.  The env
variable DMALLOC_LOGFILE overrides this variable.

</DL>

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


<P>
<A NAME="IDX103"></A>
<A NAME="IDX104"></A>


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


<P>
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()</CODE>
call, <CODE>atexit()</CODE> call, or compiler destructor support (see
<TT>`conf.h'</TT>).  If you do not have these, then <CODE>dmalloc_shutdown</CODE>
should be called right before <CODE>exit()</CODE> or as the last function in
<CODE>main()</CODE>.



<PRE>
main()
{
        ...
        dmalloc_shutdown();
        exit(0);
}
</PRE>

</DL>

<P>
<A NAME="IDX106"></A>
<A NAME="IDX107"></A>
<A NAME="IDX108"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX109"></A>
int dmalloc_verify ( char * <VAR>pnt</VAR> )


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


<P>
<EM>NOTE</EM>: <SAMP>`dmalloc_verify()'</SAMP> can only check the heap with the
functions that have been enabled.  For example, if fence-post checking
is not enabled, <SAMP>`dmalloc_verify()'</SAMP> cannot check the fence-post
areas in the heap.
</DL>


<P>
<A NAME="IDX110"></A>
<A NAME="IDX111"></A>
<A NAME="IDX112"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX113"></A>
unsigned int dmalloc_debug ( const unsigned int <VAR>flags</VAR> )


<P>
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.  See section <A HREF="dmalloc.html#SEC25">3.11 Debugging Memory in a Server or Cgi-Bin Process</A>.  For instance, if debugging should never be enabled for a
program, a call to <CODE>dmalloc_debug(0)</CODE> as the first call in
<CODE>main()</CODE> will disable all the memory debugging from that point
on.


<P>
<EM>NOTE</EM>: you cannot add or remove certain flags such as signal
handlers since they are setup at initialization time only.


<P>
<EM>NOTE</EM>: you can also use <CODE>dmalloc_debug_setup</CODE> below.


</DL>

<P>
<A NAME="IDX114"></A>
<A NAME="IDX115"></A>


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


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


</DL>

<P>
<A NAME="IDX117"></A>
<A NAME="IDX118"></A>
<A NAME="IDX119"></A>
<A NAME="IDX120"></A>
<A NAME="IDX121"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX122"></A>
void dmalloc_debug_setup ( const char * <VAR>options_str</VAR> )


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


<P>
Some examples:



<PRE>
/* debug tokens high, threaded lock-on at 20, log to dmalloc.%p (pid) */
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");
</PRE>

</DL>

<P>
<A NAME="IDX123"></A>
<A NAME="IDX124"></A>
<A NAME="IDX125"></A>


<P>
<DL>
<DT><U>Function:</U>  <B></B>
<DD><A NAME="IDX126"></A>
int dmalloc_examine ( const DMALLOC_PNT <VAR>pnt</VAR>, DMALLOC_SIZE *
<VAR>user_size_p</VAR>, DMALLOC_SIZE * <VAR>total_size_p</VAR>, char **
<VAR>file_p</VAR>, int * <VAR>line_p</VAR>, DMALLOC_PNT * <VAR>ret_addr_p</VAR>,
unsigned long * <VAR>user_mark_p</VAR>, unsigned long * <VAR>seen_p</VAR> )


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