This is ./mmalloc.info, produced by makeinfo version 4.1 from
|
This is ./mmalloc.info, produced by makeinfo version 4.1 from
|
mmalloc.texi.
|
mmalloc.texi.
|
|
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Mmalloc: (mmalloc). The GNU mapped-malloc package.
|
* Mmalloc: (mmalloc). The GNU mapped-malloc package.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU mmalloc (mapped-malloc) package, written
|
This file documents the GNU mmalloc (mapped-malloc) package, written
|
by fnf@cygnus.com, based on GNU malloc written by mike@ai.mit.edu.
|
by fnf@cygnus.com, based on GNU malloc written by mike@ai.mit.edu.
|
|
|
Copyright (C) 1992 Free Software Foundation, Inc.
|
Copyright (C) 1992 Free Software Foundation, Inc.
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
Permission is granted to make and distribute verbatim copies of this
|
manual provided the copyright notice and this permission notice are
|
manual provided the copyright notice and this permission notice are
|
preserved on all copies.
|
preserved on all copies.
|
|
|
Permission is granted to copy and distribute modified versions of
|
Permission is granted to copy and distribute modified versions of
|
this manual under the conditions for verbatim copying, provided also
|
this manual under the conditions for verbatim copying, provided also
|
that the entire resulting derived work is distributed under the terms
|
that the entire resulting derived work is distributed under the terms
|
of a permission notice identical to this one.
|
of a permission notice identical to this one.
|
|
|
Permission is granted to copy and distribute translations of this
|
Permission is granted to copy and distribute translations of this
|
manual into another language, under the above conditions for modified
|
manual into another language, under the above conditions for modified
|
versions.
|
versions.
|
|
|
|
|
File: mmalloc.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
|
File: mmalloc.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
|
|
|
mmalloc
|
mmalloc
|
*******
|
*******
|
|
|
This file documents the GNU memory-mapped malloc package mmalloc.
|
This file documents the GNU memory-mapped malloc package mmalloc.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Overview:: Overall Description
|
* Overview:: Overall Description
|
* Implementation:: Implementation
|
* Implementation:: Implementation
|
|
|
--- The Detailed Node Listing ---
|
--- The Detailed Node Listing ---
|
|
|
Implementation
|
Implementation
|
|
|
* Compatibility:: Backwards Compatibility
|
* Compatibility:: Backwards Compatibility
|
* Functions:: Function Descriptions
|
* Functions:: Function Descriptions
|
|
|
|
|
File: mmalloc.info, Node: Overview, Next: Implementation, Prev: Top, Up: Top
|
File: mmalloc.info, Node: Overview, Next: Implementation, Prev: Top, Up: Top
|
|
|
Overall Description
|
Overall Description
|
*******************
|
*******************
|
|
|
This is a heavily modified version of GNU `malloc'. It uses `mmap'
|
This is a heavily modified version of GNU `malloc'. It uses `mmap'
|
as the basic mechanism for obtaining memory from the system, rather
|
as the basic mechanism for obtaining memory from the system, rather
|
than `sbrk'. This gives it several advantages over the more
|
than `sbrk'. This gives it several advantages over the more
|
traditional malloc:
|
traditional malloc:
|
|
|
* Several different heaps can be used, each of them growing or
|
* Several different heaps can be used, each of them growing or
|
shinking under control of `mmap', with the `mmalloc' functions
|
shinking under control of `mmap', with the `mmalloc' functions
|
using a specific heap on a call by call basis.
|
using a specific heap on a call by call basis.
|
|
|
* By using `mmap', it is easy to create heaps which are intended to
|
* By using `mmap', it is easy to create heaps which are intended to
|
be persistent and exist as a filesystem object after the creating
|
be persistent and exist as a filesystem object after the creating
|
process has gone away.
|
process has gone away.
|
|
|
* Because multiple heaps can be managed, data used for a specific
|
* Because multiple heaps can be managed, data used for a specific
|
purpose can be allocated into its own heap, making it easier to
|
purpose can be allocated into its own heap, making it easier to
|
allow applications to "dump" and "restore" initialized
|
allow applications to "dump" and "restore" initialized
|
malloc-managed memory regions. For example, the "unexec" hack
|
malloc-managed memory regions. For example, the "unexec" hack
|
popularized by GNU Emacs could potentially go away.
|
popularized by GNU Emacs could potentially go away.
|
|
|
|
|
File: mmalloc.info, Node: Implementation, Prev: Overview, Up: Top
|
File: mmalloc.info, Node: Implementation, Prev: Overview, Up: Top
|
|
|
Implementation
|
Implementation
|
**************
|
**************
|
|
|
The `mmalloc' functions contain no internal static state. All
|
The `mmalloc' functions contain no internal static state. All
|
`mmalloc' internal data is allocated in the mapped in region, along
|
`mmalloc' internal data is allocated in the mapped in region, along
|
with the user data that it manages. This allows it to manage multiple
|
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
|
such regions and to "pick up where it left off" when such regions are
|
later dynamically mapped back in.
|
later dynamically mapped back in.
|
|
|
In some sense, malloc has been "purified" to contain no internal
|
In some sense, malloc has been "purified" to contain no internal
|
state information and generalized to use multiple memory regions rather
|
state information and generalized to use multiple memory regions rather
|
than a single region managed by `sbrk'. However the new routines now
|
than a single region managed by `sbrk'. However the new routines now
|
need an extra parameter which informs `mmalloc' which memory region it
|
need an extra parameter which informs `mmalloc' which memory region it
|
is dealing with (along with other information). This parameter is
|
is dealing with (along with other information). This parameter is
|
called the "malloc descriptor".
|
called the "malloc descriptor".
|
|
|
The functions initially provided by `mmalloc' are:
|
The functions initially provided by `mmalloc' are:
|
|
|
void *mmalloc_attach (int fd, void *baseaddr);
|
void *mmalloc_attach (int fd, void *baseaddr);
|
void *mmalloc_detach (void *md);
|
void *mmalloc_detach (void *md);
|
int mmalloc_errno (void *md);
|
int mmalloc_errno (void *md);
|
int mmalloc_setkey (void *md, int keynum, void *key);
|
int mmalloc_setkey (void *md, int keynum, void *key);
|
void *mmalloc_getkey (void *md, int keynum);
|
void *mmalloc_getkey (void *md, int keynum);
|
|
|
void *mmalloc (void *md, size_t size);
|
void *mmalloc (void *md, size_t size);
|
void *mrealloc (void *md, void *ptr, size_t size);
|
void *mrealloc (void *md, void *ptr, size_t size);
|
void *mvalloc (void *md, size_t size);
|
void *mvalloc (void *md, size_t size);
|
void mfree (void *md, void *ptr);
|
void mfree (void *md, void *ptr);
|
|
|
* Menu:
|
* Menu:
|
|
|
* Compatibility:: Backwards Compatibility
|
* Compatibility:: Backwards Compatibility
|
* Functions:: Function Descriptions
|
* Functions:: Function Descriptions
|
|
|
|
|
File: mmalloc.info, Node: Compatibility, Next: Functions, Prev: Implementation, Up: Implementation
|
File: mmalloc.info, Node: Compatibility, Next: Functions, Prev: Implementation, Up: Implementation
|
|
|
Backwards Compatibility
|
Backwards Compatibility
|
=======================
|
=======================
|
|
|
To allow a single malloc package to be used in a given application,
|
To allow a single malloc package to be used in a given application,
|
provision is made for the traditional `malloc', `realloc', and `free'
|
provision is made for the traditional `malloc', `realloc', and `free'
|
functions to be implemented as special cases of the `mmalloc'
|
functions to be implemented as special cases of the `mmalloc'
|
functions. In particular, if any of the functions that expect malloc
|
functions. In particular, if any of the functions that expect malloc
|
descriptors are called with a `NULL' pointer rather than a valid malloc
|
descriptors are called with a `NULL' pointer rather than a valid malloc
|
descriptor, then they default to using an `sbrk' managed region. The
|
descriptor, then they default to using an `sbrk' managed region. The
|
`mmalloc' package provides compatible `malloc', `realloc', and `free'
|
`mmalloc' package provides compatible `malloc', `realloc', and `free'
|
functions using this mechanism internally. Applications can avoid this
|
functions using this mechanism internally. Applications can avoid this
|
extra interface layer by simply including the following defines:
|
extra interface layer by simply including the following defines:
|
|
|
#define malloc(size) mmalloc ((void *)0, (size))
|
#define malloc(size) mmalloc ((void *)0, (size))
|
#define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size));
|
#define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size));
|
#define free(ptr) mfree ((void *)0, (ptr))
|
#define free(ptr) mfree ((void *)0, (ptr))
|
|
|
or replace the existing `malloc', `realloc', and `free' calls with the
|
or replace the existing `malloc', `realloc', and `free' calls with the
|
above patterns if using `#define' causes problems.
|
above patterns if using `#define' causes problems.
|
|
|
|
|
File: mmalloc.info, Node: Functions, Prev: Compatibility, Up: Implementation
|
File: mmalloc.info, Node: Functions, Prev: Compatibility, Up: Implementation
|
|
|
Function Descriptions
|
Function Descriptions
|
=====================
|
=====================
|
|
|
These are the details on the functions that make up the `mmalloc'
|
These are the details on the functions that make up the `mmalloc'
|
package.
|
package.
|
|
|
`void *mmalloc_attach (int FD, void *BASEADDR);'
|
`void *mmalloc_attach (int FD, void *BASEADDR);'
|
Initialize access to a `mmalloc' managed region.
|
Initialize access to a `mmalloc' managed region.
|
|
|
If FD is a valid file descriptor for an open file, then data for
|
If FD is a valid file descriptor for an open file, then data for
|
the `mmalloc' managed region is mapped to that file. Otherwise
|
the `mmalloc' managed region is mapped to that file. Otherwise
|
`/dev/zero' is used and the data will not exist in any filesystem
|
`/dev/zero' is used and the data will not exist in any filesystem
|
object.
|
object.
|
|
|
If the open file corresponding to FD is from a previous use of
|
If the open file corresponding to FD is from a previous use of
|
`mmalloc' and passes some basic sanity checks to ensure that it is
|
`mmalloc' and passes some basic sanity checks to ensure that it is
|
compatible with the current `mmalloc' package, then its data is
|
compatible with the current `mmalloc' package, then its data is
|
mapped in and is immediately accessible at the same addresses in
|
mapped in and is immediately accessible at the same addresses in
|
the current process as the process that created the file.
|
the current process as the process that created the file.
|
|
|
If BASEADDR is not `NULL', the mapping is established starting at
|
If BASEADDR is not `NULL', the mapping is established starting at
|
the specified address in the process address space. If BASEADDR
|
the specified address in the process address space. If BASEADDR
|
is `NULL', the `mmalloc' package chooses a suitable address at
|
is `NULL', the `mmalloc' package chooses a suitable address at
|
which to start the mapped region, which will be the value of the
|
which to start the mapped region, which will be the value of the
|
previous mapping if opening an existing file which was previously
|
previous mapping if opening an existing file which was previously
|
built by `mmalloc', or for new files will be a value chosen by
|
built by `mmalloc', or for new files will be a value chosen by
|
`mmap'.
|
`mmap'.
|
|
|
Specifying BASEADDR provides more control over where the regions
|
Specifying BASEADDR provides more control over where the regions
|
start and how big they can be before bumping into existing mapped
|
start and how big they can be before bumping into existing mapped
|
regions or future mapped regions.
|
regions or future mapped regions.
|
|
|
On success, returns a malloc descriptor which is used in subsequent
|
On success, returns a malloc descriptor which is used in subsequent
|
calls to other `mmalloc' package functions. It is explicitly
|
calls to other `mmalloc' package functions. It is explicitly
|
`void *' (`char *' for systems that don't fully support `void') so
|
`void *' (`char *' for systems that don't fully support `void') so
|
that users of the package don't have to worry about the actual
|
that users of the package don't have to worry about the actual
|
implementation details.
|
implementation details.
|
|
|
On failure returns `NULL'.
|
On failure returns `NULL'.
|
|
|
`void *mmalloc_detach (void *MD);'
|
`void *mmalloc_detach (void *MD);'
|
Terminate access to a `mmalloc' managed region identified by the
|
Terminate access to a `mmalloc' managed region identified by the
|
descriptor MD, by closing the base file and unmapping all memory
|
descriptor MD, by closing the base file and unmapping all memory
|
pages associated with the region.
|
pages associated with the region.
|
|
|
Returns `NULL' on success.
|
Returns `NULL' on success.
|
|
|
Returns the malloc descriptor on failure, which can subsequently
|
Returns the malloc descriptor on failure, which can subsequently
|
be used for further action (such as obtaining more information
|
be used for further action (such as obtaining more information
|
about the nature of the failure).
|
about the nature of the failure).
|
|
|
`void *mmalloc (void *MD, size_t SIZE);'
|
`void *mmalloc (void *MD, size_t SIZE);'
|
Given an `mmalloc' descriptor MD, allocate additional memory of
|
Given an `mmalloc' descriptor MD, allocate additional memory of
|
SIZE bytes in the associated mapped region.
|
SIZE bytes in the associated mapped region.
|
|
|
`*mrealloc (void *MD, void *PTR, size_t SIZE);'
|
`*mrealloc (void *MD, void *PTR, size_t SIZE);'
|
Given an `mmalloc' descriptor MD and a pointer to memory
|
Given an `mmalloc' descriptor MD and a pointer to memory
|
previously allocated by `mmalloc' in PTR, reallocate the memory to
|
previously allocated by `mmalloc' in PTR, reallocate the memory to
|
be SIZE bytes long, possibly moving the existing contents of
|
be SIZE bytes long, possibly moving the existing contents of
|
memory if necessary.
|
memory if necessary.
|
|
|
`void *mvalloc (void *MD, size_t SIZE);'
|
`void *mvalloc (void *MD, size_t SIZE);'
|
Like `mmalloc' but the resulting memory is aligned on a page
|
Like `mmalloc' but the resulting memory is aligned on a page
|
boundary.
|
boundary.
|
|
|
`void mfree (void *MD, void *PTR);'
|
`void mfree (void *MD, void *PTR);'
|
Given an `mmalloc' descriptor MD and a pointer to memory previously
|
Given an `mmalloc' descriptor MD and a pointer to memory previously
|
allocated by `mmalloc' in PTR, free the previously allocated
|
allocated by `mmalloc' in PTR, free the previously allocated
|
memory.
|
memory.
|
|
|
`int mmalloc_errno (void *MD);'
|
`int mmalloc_errno (void *MD);'
|
Given a `mmalloc' descriptor, if the last `mmalloc' operation
|
Given a `mmalloc' descriptor, if the last `mmalloc' operation
|
failed for some reason due to a system call failure, then returns
|
failed for some reason due to a system call failure, then returns
|
the associated `errno'. Returns 0 otherwise. (This function is
|
the associated `errno'. Returns 0 otherwise. (This function is
|
not yet implemented).
|
not yet implemented).
|
|
|
|
|
|
|
Tag Table:
|
Tag Table:
|
Node: Top937
|
Node: Top937
|
Node: Overview1373
|
Node: Overview1373
|
Node: Implementation2401
|
Node: Implementation2401
|
Node: Compatibility3794
|
Node: Compatibility3794
|
Node: Functions4868
|
Node: Functions4868
|
|
|
End Tag Table
|
End Tag Table
|
|
|
