dmalloc.texi

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

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename dmalloc.info
@settitle Dmalloc Tutorial
@setchapternewpage odd
@headings double
@c %**end of header
  
@dircategory Libraries
@direntry
* Dmalloc: (dmalloc).			Malloc debug library.
@end direntry

@c ----------------------------------------------------------------
@c $Id: dmalloc.texi,v 1.267 2004/10/19 14:50:52 gray Exp $
@c ----------------------------------------------------------------

@c ----------------------------------------------------------------
@set dmalloc_version Version 5.4.2
@set dmalloc_date October 2004
@set dmalloc_copyright Copyright 1992 to 2004 by Gray Watson.
@c ----------------------------------------------------------------

@ifinfo
This file is an introduction to the Dmalloc library which handles general
memory heap management.

@value{dmalloc_copyright}

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
chapter entitled ``Copying'' are included exactly as in the original,
and provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the chapter entitled ``Copying'' may be included in a
translation approved by the author instead of in the original English.
@end ifinfo

@titlepage
@title Debug Malloc Library
@subtitle @value{dmalloc_version}
@subtitle @value{dmalloc_date}
@author Gray Watson

@page
@value{dmalloc_copyright}

Published by Gray Watson

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
chapter entitled ``Copying'' are included exactly as in the original,
and provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the chapter entitled ``Copying'' may be included in a
translation approved by the author instead of in the original English.
@end titlepage

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

@node Top, Copying, (dir), (dir)
@top Debug Malloc Library

@ifinfo
@value{dmalloc_version} -- @value{dmalloc_date}
@end ifinfo

@cindex introduction
@cindex author

The debug memory allocation or @dfn{dmalloc} library has been designed
as a drop in replacement for the system's @code{malloc}, @code{realloc},
@code{calloc}, @code{free} and other memory management routines while
providing powerful debugging facilities configurable at runtime.  These
facilities include such things as memory-leak tracking, fence-post write
detection, file/line number reporting, and general logging of
statistics.

The library is reasonably portable having been run successfully on at
least the following operating systems: AIX, DGUX, Free/Net/OpenBSD,
GNU/Hurd, HPUX, Irix, Linux, Mac OSX, NeXT, OSF/DUX, SCO, Solaris,
Ultrix, Unixware, MS Windows, and Unicos on a Cray T3E.  It also
provides support for the debugging of threaded programs.  @xref{Using
With Threads}.

The package includes the library, configuration scripts, debug utility
application, test program, and documentation.  Online documentation as
well as the full source is available at URL @uref{http://dmalloc.com/}.
Details on the library's mailing list are available there as well.

Please use the forums at URL @uref{http://dmalloc.com/forums/} to
discuss any problems or to request features.  If you are still having
problems, the author can be reached via his home page at URL
@uref{http://256.com/gray/} with questions or feedback.  Please include
the version number of the library that you are using, your machine and
operating system types, and the value of the DMALLOC_OPTIONS environment
variable.

Gray Watson.

@menu
* Copying::                     Library copying and licensing conditions.
* Overview::                    Description of features and how to get started.
* Programming::                 How to program with the library.
* Dmalloc Program::             How to use the library's utility.
* Source Code::                 Information on the source code.
* Troubleshooting::             Some solutions to common problems.
* Index of Concepts::           Index of concepts in the manual.
@end menu

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

@node Copying, Overview, Top, Top
@chapter Library Copying and Licensing Conditions

@cindex copying
@cindex license
@cindex library permissions
@cindex permissions of the library

@value{dmalloc_copyright}

Permission to use, copy, modify, and distribute this software for any
purpose and without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies, and
that the name of Gray Watson not be used in advertising or publicity
pertaining to distribution of the document or software without specific,
written prior permission.

Gray Watson makes no representations about the suitability of the
software described herein for any purpose.  It is provided ``as is''
without express or implied warranty.

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

@node Overview, Programming, Copying, Top
@chapter Description of Features and How to Get Started

@cindex overview

@menu
* Installation::                How to install the library.
* Getting Started::             Getting started with the library.
* Allocation Basics::           Basic description of terms and functions.
* Features::                    General features of the library.
* How It Works::                How the library checks your program.
@end menu

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

@node Installation, Getting Started, Overview, Overview
@section How to Install the Library

@cindex installing the library
@cindex compiling the library
@cindex building the library
@cindex configuring the library
@cindex making the library

To configure, compile, and install the library, follow these steps
carefully.

@enumerate

@item Make sure you have the latest version of the library available
from the home page at URL @uref{http://dmalloc.com/}.

@cindex settings.dist file

@item You may want to edit or at least review the settings in
@file{settings.dist} to tune specific features of the library.  The
@file{configure} script will copy this file to @file{settings.h} which
is where you should be adding per-architecture settings.

@cindex configure script
@cindex --disable-cxx
@cindex --enable-threads
@cindex --enable-shlib
@cindex conf.h file

@item Type @kbd{sh ./configure} to configure the library.  You may want
to first examine the @file{config.help} file for some information about
configure.  You may want to use the @kbd{--disable-cxx} option if you do
not want the Makefile to build the C++ version of dmalloc.  You may want
to use the @kbd{--enable-threads} option to build the threaded version
of dmalloc.  You may want to use the @kbd{--enable-shlib} option to
build the shared versions of the dmalloc libraries.  @kbd{sh ./configure
--help} lists the available options to configure.  Configure should
generate the @file{Makefile} and configuration files automatically.

@item You may want to examine the @file{Makefile} and @file{conf.h} files
created by configure to make sure it did its job correctly.

@cindex settings.h file

@item You might want to tune the settings in @file{settings.h} file to
tune the library to the local architecture.  This file contains relevant
settings if you are using pthreads or another thread library.
@xref{Using With Threads}.  The @file{configure} script created this
file from the @file{settings.dist} file.  Any permanent changes to these
settings should made to the @file{settings.dist} file.  You then can run
@file{config.status} to re-create the @file{settings.h} file.

@cindex DMALLOC_SIZE variable

@item The @code{DMALLOC_SIZE} variable gets auto-configured in
@file{dmalloc.h.2} but it may not generate correct settings for all
systems.  You may have to alter the definitions in this file to get
things to stop complaining when you go to compile about the size
arguments to malloc routines.  Comments on this please.

@item Typing @kbd{make} should be enough to build @file{libdmalloc.a},
and @file{dmalloc} program.  If it does not work, please see if there
are any notes in the contrib directory about your system-type.  If not
and you figure your problem out, please send me some notes so future
users can profit from your experiences.

@emph{NOTE}: You may experience some errors compiling some of the
return.h assembly macros which attempt to determine the callers address
for logging purposes.  You may want to first try disabling any compiler
optimization flags.  If this doesn't work then you may need to disable
the @samp{USE_RETURN_MACROS} variable in the @file{settings.h} file.

@cindex ANSI-C compiler

@emph{NOTE}: The code is dependent on an ANSI-C compiler.  If the
configure script gives the @samp{WARNING} that you do not have an ANSI-C
compiler, you may still be able to add some sort of option to your
compiler to make it ANSI.  If there such is an option, please send it to
the author so it can be added to the configure script.

@item If you use threads and did not add the @kbd{--enable-threads}
argument to configure, typing @kbd{make threads} should be enough to
build @file{libdmallocth.a} which is the threaded version of the
library.  This may or may not work depending on the configuration
scripts ability to detect your local thread functionality.  Feel free to
send me mail with improvements.

See the ``Using With Threads'' section for more information about the
operation of the library with your threaded program.  @xref{Using With
Threads}.

@item If you have a C++ compiler installed, the library should have
automatically built @file{libdmallocxx.a} which is the C++ version of
the library.  If it was not done automatically, you can build it by
typing @kbd{make cxx}.  You should link this library into your C++
programs instead of @file{libdmalloc.a}.  See the @file{dmallocc.cc} C++
file which contains basic code to overload the @code{new}, @code{new[]},
@code{delete}, and @code{delete[]} C++ operators.  My apologies on the
minimal C++ support.  I am still living in a mostly C world.  Any help
improving this interface without sacrificing portability would be
appreciated.

@cindex testing the library
@cindex dmalloc_t test program

@item Typing @kbd{make light} should build and run the @file{dmalloc_t} test
program through a set of light trials.  By default this will execute
@file{dmalloc_t} 5 times -- each time will execute 10,000 malloc
operations in a very random manner.  Anal folks can type @kbd{make
heavy} to up the ante.  Use @kbd{dmalloc_t --usage} for the list of all
@file{dmalloc_t} options.

@item Typing @kbd{make install} should install the @file{libdmalloc.a}
library in @file{/usr/local/lib}, the @file{dmalloc.h} include file in
@file{/usr/local/include}, and the @file{dmalloc} utility in
@file{/usr/local/bin}.  You may also want to type @kbd{make installth}
to install the thread library into place and/or @kbd{make installcc} to
install the C++ library into place.

You may have specified a @samp{--prefix=PATH} option to configure in
which case @samp{/usr/local} will have been replaced with @samp{PATH}.

@end enumerate

See the ``Getting Started'' section to get up and running with the
library.  @xref{Getting Started}.

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

@node Getting Started, Allocation Basics, Installation, Overview
@section Getting Started with the Library

@cindex quick start
@cindex getting started
@cindex jump start
@cindex how to begin
@cindex where to begin
@cindex beginning

This section should give you a quick idea on how to get going.
Basically, you need to do the following things to make use of the
library:

@enumerate

@item Make sure you have the latest version of the library available
from the home page at URL @uref{http://dmalloc.com/}.

@item Follow the installation instructions on how to configure,
make, and install the library (i.e. type: @kbd{make install}).
@xref{Installation}.

@cindex automatic shutdown
@cindex shutdown, automatic
@cindex on_exit
@cindex atexit
@cindex destructor

@item You need to make sure that the library configuration and
build process above was able to locate one of the @code{on_exit}
function, @code{atexit} function, or had compiler destructor support.
If one of these functions or support is available then the dmalloc
library should be able to automatically shut itself down when the
program exits.  This causes the memory statistics and unfreed
information to be dumped to the log file.  However, if your system has
none of the above, then you will need to call @code{dmalloc_shutdown}
yourself before your program exits.

@cindex alias, shell
@cindex bash shell
@cindex ksh shell
@cindex zsh shell

@item Add an alias for dmalloc to your shell's rc file if supported.
The idea is to have the shell capture the dmalloc program's output and
adjust the environment.  Bash, ksh, and zsh users should add the
following to their @file{.bashrc}, @file{.profile}, or @file{.zshrc}
file respectively (notice the @kbd{-b} option for bourne shell output):

@example
function dmalloc @{ eval `command dmalloc -b $*`; @}
@end example

If your shell does not support the @code{command} function then try:

@example
function dmalloc @{ eval `\dmalloc -b $*`; @}
@end example
or
@example
function dmalloc @{ eval `/usr/local/bin/dmalloc -b $*`; @}
@end example

@cindex csh shell
@cindex tcsh shell

If you are @emph{still} using csh or tcsh, you should add the following
to your @file{.cshrc} file (notice the @kbd{-C} option for c-shell
output):