* sim-endian.h: Move host {LITTLE,BIG}_ENDIAN support from here,

[binutils.git] / mmalloc / mmalloc.texi

\input texinfo  @c                                  -*- Texinfo -*-
@setfilename mmalloc.info

@ifinfo
@format
START-INFO-DIR-ENTRY
* Mmalloc: (mmalloc).		The GNU mapped-malloc package.
END-INFO-DIR-ENTRY
@end format

This file documents the GNU mmalloc (mapped-malloc) package, written by
fnf@@cygnus.com.

Copyright (C) 1992 Free Software Foundation, Inc.

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 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
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.
@end ifinfo
@iftex
@c @finalout
@setchapternewpage odd
@settitle MMALLOC, the GNU memory-mapped malloc package
@titlepage
@title mmalloc
@subtitle The GNU memory-mapped malloc package
@author Fred Fish
@author Cygnus Support
@page

@tex
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
\xdef\manvers{\$Revision$}  % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Support\par
\hfill fnf\@cygnus.com\par
\hfill {\it MMALLOC, the GNU memory-mapped malloc package}, \manvers\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1992 Free Software Foundation, Inc.

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 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.
@end titlepage
@end iftex

@ifinfo
@node Top, Overview, (dir), (dir)
@top mmalloc
This file documents the GNU memory-mapped malloc package mmalloc.

@menu
* Overview::                    Overall Description
* Implementation::              Implementation

 --- The Detailed Node Listing ---

Implementation

* Compatibility::               Backwards Compatibility
* Functions::                   Function Descriptions
@end menu

@end ifinfo

@node Overview, Implementation, Top, Top
@chapter Overall Description

This is a heavily modified version of GNU @code{malloc}.  It uses
@code{mmap} as the basic mechanism for for obtaining memory from the
system, rather than @code{sbrk}.  This gives it several advantages over the
more traditional malloc:

@itemize @bullet
@item
Providing suitable precautions are taken to avoid memory region
collisions, @code{sbrk} is now available for use by applications that
use this package and still need to use some memory management
package that includes functions like @code{malloc}, @code{realloc}, and
@code{free}.

@item
Several different memory pools can be used, each of them growing
or shinking under control of @code{mmap}, with the @code{mmalloc} functions
using a specific pool on a call by call basis.

@item
By using @code{mmap}, it is easy to create data pools which are intended to
be persistent and exist as a filesystem object after the creating
process has gone away.

@item
Because multiple memory pools can be managed, data used for a 
specific purpose can be allocated into its own memory pool, making
it easier to allow applications to ``dump'' and ``restore'' initialized
malloc-managed memory regions.  For example, the ``unexec'' hack popularized
by GNU Emacs could potentially go away.
@end itemize

@node Implementation,  , Overview, Top
@chapter Implementation

The @code{mmalloc} functions contain no internal static state.  All
@code{mmalloc} internal data is allocated in the mapped in region, along
with the user data that it manages.  This allows it to manage multiple
such regions and to ``pick up where it left off'' when such regions are
later dynamically mapped back in.

In some sense, malloc has been ``purified'' to contain no internal state
information and generalized to use multiple memory regions rather than a
single region managed by @code{sbrk}.  However the new routines now need an
extra parameter which informs @code{mmalloc} which memory region it is dealing
with (along with other information).  This parameter is called the
@dfn{malloc descriptor}.

For ease of initial implementation, and to avoid exporting or importing
any more global variables or routines than necessary, this package is
implemented with all functions contained within a single source file.
At some future point, once everything has stabilized, it may be desirable
to split it up into separate files.

The functions initially provided by @code{mmalloc} are:

@example
void *mmalloc_attach (int fd, void *baseaddr);
void *mmalloc_detach (void *md);
int mmalloc_errno (void *md);
int mmalloc_setkey (void *md, int keynum, void *key);
void *mmalloc_getkey (void *md, int keynum);

void *mmalloc (void *md, size_t size);
void *mrealloc (void *md, void *ptr, size_t size);
void *mvalloc (void *md, size_t size);
void mfree (void *md, void *ptr);
@end example

@menu
* Compatibility::               Backwards Compatibility
* Functions::                   Function Descriptions
@end menu

@node Compatibility, Functions, Implementation, Implementation
@section Backwards Compatibility

To allow a single malloc package to be used in a given application,
provision is made for the traditional @code{malloc}, @code{realloc}, and
@code{free} functions to be implemented as special cases of the
@code{mmalloc} functions.  In particular, if any of the functions that
expect malloc descriptors are called with a @code{NULL} pointer rather than a
valid malloc descriptor, then they default to using a memory-mapped region
starting at the current @code{sbrk} value and mapped to @file{/dev/zero}.
Applications can simply include the following defines to use the
@code{mmalloc} versions:

@example
#define malloc(size)		mmalloc ((void *)0, (size))
#define realloc(ptr,size)	mrealloc ((void *)0, (ptr), (size));
#define free(ptr)		mfree ((void *)0, (ptr))
@end example

@noindent
or replace the existing @code{malloc}, @code{realloc}, and @code{free}
calls with the above patterns if using @code{#define} causes problems.

Note that this does not prevent calls to @code{malloc}, @code{realloc},
or @code{free} within libraries from continuing to use the library
version of malloc, so if this is a problem, the compatibility issue
needs to be dealt with in another way. 


@node Functions,  , Compatibility, Implementation
@section Function Descriptions

These are the details on the functions that make up the @code{mmalloc}
package. 

@table @code
@item void *mmalloc_attach (int @var{fd}, void *@var{baseaddr});
Initialize access to a @code{mmalloc} managed region.

If @var{fd} is a valid file descriptor for an open file, then data for the
@code{mmalloc} managed region is mapped to that file.   Otherwise
@file{/dev/zero} is used and the data will not exist in any filesystem object.

If the open file corresponding to @var{fd} is from a previous use of
@code{mmalloc} and passes some basic sanity checks to ensure that it is
compatible with the current @code{mmalloc} package, then its data is
mapped in and is immediately accessible at the same addresses in
the current process as the process that created the file.

If @var{baseaddr} is not @code{NULL}, the mapping is established
starting at the specified address in the process address space.  If
@var{baseaddr} is @code{NULL}, the @code{mmalloc} package chooses a
suitable address at which to start the mapped region, which will be the
value of the previous mapping if opening an existing file which was
previously built by @code{mmalloc}, or for new files will be a value
chosen by @code{mmap}.

Specifying @var{baseaddr} provides more control over where the regions
start and how big they can be before bumping into existing mapped
regions or future mapped regions.

On success, returns a malloc descriptor which is used in subsequent
calls to other @code{mmalloc} package functions.  It is explicitly
@samp{void *} (@samp{char *} for systems that don't fully support
@code{void}) so that users of the package don't have to worry about the
actual implementation details.

On failure returns @code{NULL}.

@item void *mmalloc_detach (void *@var{md});
Terminate access to a @code{mmalloc} managed region identified by the
descriptor @var{md}, by closing the base file and unmapping all memory
pages associated with the region. 

Returns @code{NULL} on success.

Returns the malloc descriptor on failure, which can subsequently
be used for further action (such as obtaining more information about
the nature of the failure).

@item void *mmalloc (void *@var{md}, size_t @var{size});
Given an @code{mmalloc} descriptor @var{md}, allocate additional memory of
@var{size} bytes in the associated mapped region.

@item *mrealloc (void *@var{md}, void *@var{ptr}, size_t @var{size});
Given an @code{mmalloc} descriptor @var{md} and a pointer to memory
previously allocated by @code{mmalloc} in @var{ptr}, reallocate the
memory to be @var{size} bytes long, possibly moving the existing
contents of memory if necessary.
	
@item void *mvalloc (void *@var{md}, size_t @var{size});
Like @code{mmalloc} but the resulting memory is aligned on a page boundary.

@item void mfree (void *@var{md}, void *@var{ptr});
Given an @code{mmalloc} descriptor @var{md} and a pointer to memory previously
allocated by @code{mmalloc} in @var{ptr}, free the previously allocated memory.

@item int mmalloc_errno (void *@var{md});
Given a @code{mmalloc} descriptor, if the last @code{mmalloc} operation
failed for some reason due to a system call failure, then
returns the associated @code{errno}.  Returns 0 otherwise.
@end table

@bye