mmalloc/mmalloc.texi - binutils-gdb - Git at Google

 \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, based on GNU malloc written by mike@@ai.mit.edu.

 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
 @author Mike Haertel
 @author Free Software Foundation
 @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 obtaining memory from the
 system, rather than @code{sbrk}.  This gives it several advantages over the
 more traditional malloc:

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

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

 @item
 Because multiple heaps can be managed, data used for a
 specific purpose can be allocated into its own heap, 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}.

 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 an @code{sbrk} managed
 region.
 The @code{mmalloc} package provides compatible @code{malloc}, @code{realloc},
 and @code{free} functions using this mechanism internally.
 Applications can avoid this extra interface layer by simply including the
 following defines:

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

 @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.
 (This function is not yet implemented).
 @end table

 @bye
	\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, based on GNU malloc written by mike@@ai.mit.edu.

	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
	@author Mike Haertel
	@author Free Software Foundation
	@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 obtaining memory from the
	system, rather than @code{sbrk}. This gives it several advantages over the
	more traditional malloc:

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

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

	@item
	Because multiple heaps can be managed, data used for a
	specific purpose can be allocated into its own heap, 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}.

	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 an @code{sbrk} managed
	region.
	The @code{mmalloc} package provides compatible @code{malloc}, @code{realloc},
	and @code{free} functions using this mechanism internally.
	Applications can avoid this extra interface layer by simply including the
	following defines:

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

	@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.
	(This function is not yet implemented).
	@end table

	@bye