1 \input texinfo @c -*- Texinfo -*-
2 @setfilename mmalloc.info
7 * Mmalloc: (mmalloc). The GNU mapped-malloc package.
11 This file documents the GNU mmalloc (mapped-malloc) package, written by
12 fnf@@cygnus.com, based on GNU malloc written by mike@@ai.mit.edu.
14 Copyright (C) 1992 Free Software Foundation, Inc.
16 Permission is granted to make and distribute verbatim copies of
17 this manual provided the copyright notice and this permission notice
18 are preserved on all copies.
21 Permission is granted to process this file through Tex and print the
22 results, provided the printed document carries copying permission
23 notice identical to this one except for the removal of this paragraph
24 (this paragraph not being relevant to the printed manual).
27 Permission is granted to copy and distribute modified versions of this
28 manual under the conditions for verbatim copying, provided also that the
29 entire resulting derived work is distributed under the terms of a
30 permission notice identical to this one.
32 Permission is granted to copy and distribute translations of this manual
33 into another language, under the above conditions for modified versions.
37 @setchapternewpage odd
38 @settitle MMALLOC, the GNU memory-mapped malloc package
41 @subtitle The GNU memory-mapped malloc package
43 @author Cygnus Support
45 @author Free Software Foundation
49 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
50 \xdef\manvers{\$Revision: 1.1 $} % For use in headers, footers too
52 \hfill Cygnus Support\par
53 \hfill fnf\@cygnus.com\par
54 \hfill {\it MMALLOC, the GNU memory-mapped malloc package}, \manvers\par
55 \hfill \TeX{}info \texinfoversion\par
59 @vskip 0pt plus 1filll
60 Copyright @copyright{} 1992 Free Software Foundation, Inc.
62 Permission is granted to make and distribute verbatim copies of
63 this manual provided the copyright notice and this permission notice
64 are preserved on all copies.
66 Permission is granted to copy and distribute modified versions of this
67 manual under the conditions for verbatim copying, provided also that
68 the entire resulting derived work is distributed under the terms of a
69 permission notice identical to this one.
71 Permission is granted to copy and distribute translations of this manual
72 into another language, under the above conditions for modified versions.
77 @node Top, Overview, (dir), (dir)
79 This file documents the GNU memory-mapped malloc package mmalloc.
82 * Overview:: Overall Description
83 * Implementation:: Implementation
85 --- The Detailed Node Listing ---
89 * Compatibility:: Backwards Compatibility
90 * Functions:: Function Descriptions
95 @node Overview, Implementation, Top, Top
96 @chapter Overall Description
98 This is a heavily modified version of GNU @code{malloc}. It uses
99 @code{mmap} as the basic mechanism for obtaining memory from the
100 system, rather than @code{sbrk}. This gives it several advantages over the
101 more traditional malloc:
105 Several different heaps can be used, each of them growing
106 or shinking under control of @code{mmap}, with the @code{mmalloc} functions
107 using a specific heap on a call by call basis.
110 By using @code{mmap}, it is easy to create heaps which are intended to
111 be persistent and exist as a filesystem object after the creating
112 process has gone away.
115 Because multiple heaps can be managed, data used for a
116 specific purpose can be allocated into its own heap, making
117 it easier to allow applications to ``dump'' and ``restore'' initialized
118 malloc-managed memory regions. For example, the ``unexec'' hack popularized
119 by GNU Emacs could potentially go away.
122 @node Implementation, , Overview, Top
123 @chapter Implementation
125 The @code{mmalloc} functions contain no internal static state. All
126 @code{mmalloc} internal data is allocated in the mapped in region, along
127 with the user data that it manages. This allows it to manage multiple
128 such regions and to ``pick up where it left off'' when such regions are
129 later dynamically mapped back in.
131 In some sense, malloc has been ``purified'' to contain no internal state
132 information and generalized to use multiple memory regions rather than a
133 single region managed by @code{sbrk}. However the new routines now need an
134 extra parameter which informs @code{mmalloc} which memory region it is dealing
135 with (along with other information). This parameter is called the
136 @dfn{malloc descriptor}.
138 The functions initially provided by @code{mmalloc} are:
141 void *mmalloc_attach (int fd, void *baseaddr);
142 void *mmalloc_detach (void *md);
143 int mmalloc_errno (void *md);
144 int mmalloc_setkey (void *md, int keynum, void *key);
145 void *mmalloc_getkey (void *md, int keynum);
147 void *mmalloc (void *md, size_t size);
148 void *mrealloc (void *md, void *ptr, size_t size);
149 void *mvalloc (void *md, size_t size);
150 void mfree (void *md, void *ptr);
154 * Compatibility:: Backwards Compatibility
155 * Functions:: Function Descriptions
158 @node Compatibility, Functions, Implementation, Implementation
159 @section Backwards Compatibility
161 To allow a single malloc package to be used in a given application,
162 provision is made for the traditional @code{malloc}, @code{realloc}, and
163 @code{free} functions to be implemented as special cases of the
164 @code{mmalloc} functions. In particular, if any of the functions that
165 expect malloc descriptors are called with a @code{NULL} pointer rather than a
166 valid malloc descriptor, then they default to using an @code{sbrk} managed
168 The @code{mmalloc} package provides compatible @code{malloc}, @code{realloc},
169 and @code{free} functions using this mechanism internally.
170 Applications can avoid this extra interface layer by simply including the
174 #define malloc(size) mmalloc ((void *)0, (size))
175 #define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size));
176 #define free(ptr) mfree ((void *)0, (ptr))
180 or replace the existing @code{malloc}, @code{realloc}, and @code{free}
181 calls with the above patterns if using @code{#define} causes problems.
183 @node Functions, , Compatibility, Implementation
184 @section Function Descriptions
186 These are the details on the functions that make up the @code{mmalloc}
190 @item void *mmalloc_attach (int @var{fd}, void *@var{baseaddr});
191 Initialize access to a @code{mmalloc} managed region.
193 If @var{fd} is a valid file descriptor for an open file, then data for the
194 @code{mmalloc} managed region is mapped to that file. Otherwise
195 @file{/dev/zero} is used and the data will not exist in any filesystem object.
197 If the open file corresponding to @var{fd} is from a previous use of
198 @code{mmalloc} and passes some basic sanity checks to ensure that it is
199 compatible with the current @code{mmalloc} package, then its data is
200 mapped in and is immediately accessible at the same addresses in
201 the current process as the process that created the file.
203 If @var{baseaddr} is not @code{NULL}, the mapping is established
204 starting at the specified address in the process address space. If
205 @var{baseaddr} is @code{NULL}, the @code{mmalloc} package chooses a
206 suitable address at which to start the mapped region, which will be the
207 value of the previous mapping if opening an existing file which was
208 previously built by @code{mmalloc}, or for new files will be a value
209 chosen by @code{mmap}.
211 Specifying @var{baseaddr} provides more control over where the regions
212 start and how big they can be before bumping into existing mapped
213 regions or future mapped regions.
215 On success, returns a malloc descriptor which is used in subsequent
216 calls to other @code{mmalloc} package functions. It is explicitly
217 @samp{void *} (@samp{char *} for systems that don't fully support
218 @code{void}) so that users of the package don't have to worry about the
219 actual implementation details.
221 On failure returns @code{NULL}.
223 @item void *mmalloc_detach (void *@var{md});
224 Terminate access to a @code{mmalloc} managed region identified by the
225 descriptor @var{md}, by closing the base file and unmapping all memory
226 pages associated with the region.
228 Returns @code{NULL} on success.
230 Returns the malloc descriptor on failure, which can subsequently
231 be used for further action (such as obtaining more information about
232 the nature of the failure).
234 @item void *mmalloc (void *@var{md}, size_t @var{size});
235 Given an @code{mmalloc} descriptor @var{md}, allocate additional memory of
236 @var{size} bytes in the associated mapped region.
238 @item *mrealloc (void *@var{md}, void *@var{ptr}, size_t @var{size});
239 Given an @code{mmalloc} descriptor @var{md} and a pointer to memory
240 previously allocated by @code{mmalloc} in @var{ptr}, reallocate the
241 memory to be @var{size} bytes long, possibly moving the existing
242 contents of memory if necessary.
244 @item void *mvalloc (void *@var{md}, size_t @var{size});
245 Like @code{mmalloc} but the resulting memory is aligned on a page boundary.
247 @item void mfree (void *@var{md}, void *@var{ptr});
248 Given an @code{mmalloc} descriptor @var{md} and a pointer to memory previously
249 allocated by @code{mmalloc} in @var{ptr}, free the previously allocated memory.
251 @item int mmalloc_errno (void *@var{md});
252 Given a @code{mmalloc} descriptor, if the last @code{mmalloc} operation
253 failed for some reason due to a system call failure, then
254 returns the associated @code{errno}. Returns 0 otherwise.
255 (This function is not yet implemented).