1 files changed, 160 insertions, 0 deletions
diff --git a/mmalloc/README b/mmalloc/README
new file mode 100755
index 0000000..fc2e4ec
--- /dev/null
+++ b/mmalloc/README
@@ -0,0 +1,160 @@
+The GNU mmalloc (mapped-malloc) package.	fnf@cygnus.com
+
+
+Description
+-----------
+
+This is a heavily modified version of GNU malloc which has been extended to
+use mmap() as the basic mechanism for for obtaining memory from the system,
+rather than sbrk().  This gives it several advantages over the
+more traditional malloc:
+
+    *	Providing suitable precautions are taken to avoid memory region
+	collisions, 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 malloc/realloc/free.
+
+    *	Several different memory pools can be used, each of them growing
+	or shinking under control of mmap(), with the mmalloc functions
+	using a specific pool on a call by call basis.
+
+    *   By using 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.
+
+    *	Because multiple memory pools can be managed, data used for a 
+	specific purpose can be allocated into it's own memory pool, making
+	it easier to allow applications to "dump" and "restore" initialized
+	malloc-managed memory regions.  I.E., the "unexec" hack popularized
+	by GNU emacs could potentially go away.
+
+
+Implementation
+--------------
+
+The mmalloc functions contain no internal static state.  All of 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 sbrk().  However the new routines now need an
+extra parameter which informs malloc which memory region it is dealing
+with (along with other information).
+
+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
+split it up into separate files.
+
+The functions initially provided by mmalloc are:
+
+    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);
+
+Backwards Compatibility
+-----------------------
+
+To allow a single malloc package to be used in a given application, provision
+is made for the traditional malloc/realloc/free functions to be implemented
+as special cases of the mmalloc functions.  In particular, if any of the
+functions that expect malloc descriptors are called with a NULL pointer rather
+than a valid malloc descriptor, then they default to using an mmap'd region
+starting at the current sbrk() value and mapped to /dev/zero.  Applications
+can simply include the following defines to use the mmalloc versions:
+
+	#define malloc(size)		mmalloc ((void *)0, (size))
+	#define realloc(ptr,size)	mrealloc ((void *)0, (ptr), (size));
+	#define free(ptr)		mfree ((void *)0, (ptr))
+
+or replace the existing malloc/realloc/free calls with the above patterns
+if the #define's cause problems.
+
+Note that this does not prevent calls to malloc/realloc/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.
+
+
+Function Descriptions
+---------------------
+
+    void *mmalloc_attach (int fd, void *baseaddr);
+
+	Initialize access to a mmalloc managed region.
+
+	If FD is a valid file descriptor for an open file then data for the
+	mmalloc managed region is mapped to that file, otherwise "/dev/zero"
+	is used and the data will not exist in any filesystem object.
+
+	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
+	compatible with the current mmalloc package, then it's data is
+	mapped in and is immediately accessible at the same addresses in
+	the current process as the process that created the file.
+
+	If BASEADDR is not NULL, the mapping is established starting at the
+	specified address in the process address space.  If BASEADDR is NULL,
+	the 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 mmalloc, or
+	for new files will be a value chosen by mmap.
+
+	Specifying 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 mmalloc package functions.  It is explicitly "void *"
+	("char *" for systems that don't fully support void) so that users
+	of the package don't have to worry about the actual implementation
+	details.
+
+	On failure returns NULL.
+
+    void *mmalloc_detach (void *md);
+
+	Terminate access to a mmalloc managed region by closing the base
+	file and unmapping all memory pages associated with the region.
+
+	Returns 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).
+
+    void *mmalloc (void *md, size_t size);
+
+	Given an mmalloc descriptor MD, allocate additional memory of
+	SIZE bytes in the associated mapped region.
+
+    void *mrealloc (void *md, void *ptr, size_t size);
+
+	Given an mmalloc descriptor MD and a pointer to memory previously
+	allocated by mmalloc in PTR, reallocate the memory to be SIZE bytes
+	long, possibly moving the existing contents of memory if necessary.
+	
+    void *mvalloc (void *md, size_t size);
+
+	Like mmalloc but the resulting memory is aligned on a page boundary.
+
+    void mfree (void *md, void *ptr);
+
+	Given an mmalloc descriptor MD and a pointer to memory previously
+	allocated by mmalloc in PTR, free the previously allocated memory.
+
+    int mmalloc_errno (void *md);
+
+	Given a mmalloc descriptor, if the last mmalloc operation
+	failed for some reason due to a system call failure, then
+	returns the associated errno.  Returns 0 otherwise.