1 This is ./mmalloc.info, produced by makeinfo version 4.6 from
5 * Mmalloc: (mmalloc). The GNU mapped-malloc package.
8 This file documents the GNU mmalloc (mapped-malloc) package, written
9 by fnf@cygnus.com, based on GNU malloc written by mike@ai.mit.edu.
11 Copyright (C) 1992 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided also
19 that the entire resulting derived work is distributed under the terms
20 of a permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
27 File: mmalloc.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
32 This file documents the GNU memory-mapped malloc package mmalloc.
36 * Overview:: Overall Description
37 * Implementation:: Implementation
39 --- The Detailed Node Listing ---
43 * Compatibility:: Backwards Compatibility
44 * Functions:: Function Descriptions
47 File: mmalloc.info, Node: Overview, Next: Implementation, Prev: Top, Up: Top
52 This is a heavily modified version of GNU `malloc'. It uses `mmap' as
53 the basic mechanism for obtaining memory from the system, rather than
54 `sbrk'. This gives it several advantages over the more traditional
57 * Several different heaps can be used, each of them growing or
58 shinking under control of `mmap', with the `mmalloc' functions
59 using a specific heap on a call by call basis.
61 * By using `mmap', it is easy to create heaps which are intended to
62 be persistent and exist as a filesystem object after the creating
63 process has gone away.
65 * Because multiple heaps can be managed, data used for a specific
66 purpose can be allocated into its own heap, making it easier to
67 allow applications to "dump" and "restore" initialized
68 malloc-managed memory regions. For example, the "unexec" hack
69 popularized by GNU Emacs could potentially go away.
72 File: mmalloc.info, Node: Implementation, Prev: Overview, Up: Top
77 The `mmalloc' functions contain no internal static state. All
78 `mmalloc' internal data is allocated in the mapped in region, along
79 with the user data that it manages. This allows it to manage multiple
80 such regions and to "pick up where it left off" when such regions are
81 later dynamically mapped back in.
83 In some sense, malloc has been "purified" to contain no internal
84 state information and generalized to use multiple memory regions rather
85 than a single region managed by `sbrk'. However the new routines now
86 need an extra parameter which informs `mmalloc' which memory region it
87 is dealing with (along with other information). This parameter is
88 called the "malloc descriptor".
90 The functions initially provided by `mmalloc' are:
92 void *mmalloc_attach (int fd, void *baseaddr);
93 void *mmalloc_detach (void *md);
94 int mmalloc_errno (void *md);
95 int mmalloc_setkey (void *md, int keynum, void *key);
96 void *mmalloc_getkey (void *md, int keynum);
98 void *mmalloc (void *md, size_t size);
99 void *mrealloc (void *md, void *ptr, size_t size);
100 void *mvalloc (void *md, size_t size);
101 void mfree (void *md, void *ptr);
105 * Compatibility:: Backwards Compatibility
106 * Functions:: Function Descriptions
109 File: mmalloc.info, Node: Compatibility, Next: Functions, Prev: Implementation, Up: Implementation
111 Backwards Compatibility
112 =======================
114 To allow a single malloc package to be used in a given application,
115 provision is made for the traditional `malloc', `realloc', and `free'
116 functions to be implemented as special cases of the `mmalloc'
117 functions. In particular, if any of the functions that expect malloc
118 descriptors are called with a `NULL' pointer rather than a valid malloc
119 descriptor, then they default to using an `sbrk' managed region. The
120 `mmalloc' package provides compatible `malloc', `realloc', and `free'
121 functions using this mechanism internally. Applications can avoid this
122 extra interface layer by simply including the following defines:
124 #define malloc(size) mmalloc ((void *)0, (size))
125 #define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size));
126 #define free(ptr) mfree ((void *)0, (ptr))
128 or replace the existing `malloc', `realloc', and `free' calls with the
129 above patterns if using `#define' causes problems.
132 File: mmalloc.info, Node: Functions, Prev: Compatibility, Up: Implementation
134 Function Descriptions
135 =====================
137 These are the details on the functions that make up the `mmalloc'
140 `void *mmalloc_attach (int FD, void *BASEADDR);'
141 Initialize access to a `mmalloc' managed region.
143 If FD is a valid file descriptor for an open file, then data for
144 the `mmalloc' managed region is mapped to that file. Otherwise
145 `/dev/zero' is used and the data will not exist in any filesystem
148 If the open file corresponding to FD is from a previous use of
149 `mmalloc' and passes some basic sanity checks to ensure that it is
150 compatible with the current `mmalloc' package, then its data is
151 mapped in and is immediately accessible at the same addresses in
152 the current process as the process that created the file.
154 If BASEADDR is not `NULL', the mapping is established starting at
155 the specified address in the process address space. If BASEADDR
156 is `NULL', the `mmalloc' package chooses a suitable address at
157 which to start the mapped region, which will be the value of the
158 previous mapping if opening an existing file which was previously
159 built by `mmalloc', or for new files will be a value chosen by
162 Specifying BASEADDR provides more control over where the regions
163 start and how big they can be before bumping into existing mapped
164 regions or future mapped regions.
166 On success, returns a malloc descriptor which is used in subsequent
167 calls to other `mmalloc' package functions. It is explicitly
168 `void *' (`char *' for systems that don't fully support `void') so
169 that users of the package don't have to worry about the actual
170 implementation details.
172 On failure returns `NULL'.
174 `void *mmalloc_detach (void *MD);'
175 Terminate access to a `mmalloc' managed region identified by the
176 descriptor MD, by closing the base file and unmapping all memory
177 pages associated with the region.
179 Returns `NULL' on success.
181 Returns the malloc descriptor on failure, which can subsequently
182 be used for further action (such as obtaining more information
183 about the nature of the failure).
185 `void *mmalloc (void *MD, size_t SIZE);'
186 Given an `mmalloc' descriptor MD, allocate additional memory of
187 SIZE bytes in the associated mapped region.
189 `*mrealloc (void *MD, void *PTR, size_t SIZE);'
190 Given an `mmalloc' descriptor MD and a pointer to memory
191 previously allocated by `mmalloc' in PTR, reallocate the memory to
192 be SIZE bytes long, possibly moving the existing contents of
195 `void *mvalloc (void *MD, size_t SIZE);'
196 Like `mmalloc' but the resulting memory is aligned on a page
199 `void mfree (void *MD, void *PTR);'
200 Given an `mmalloc' descriptor MD and a pointer to memory previously
201 allocated by `mmalloc' in PTR, free the previously allocated
204 `int mmalloc_errno (void *MD);'
205 Given a `mmalloc' descriptor, if the last `mmalloc' operation
206 failed for some reason due to a system call failure, then returns
207 the associated `errno'. Returns 0 otherwise. (This function is
208 not yet implemented).
214 Node: Overview
\7f1370
215 Node: Implementation
\7f2395
216 Node: Compatibility
\7f3785
217 Node: Functions
\7f4856