diff options
authorH. Peter Anvin <>2001-10-26 02:32:56 (GMT)
committerH. Peter Anvin <>2001-10-26 02:32:56 (GMT)
commitd5cfcf4d16630bd5961157fb66f6a9d9d288c063 (patch)
parentaf538c1a2aa168d1c66e6e1c1fa3a3fb3e5b00b6 (diff)
Add overall man page lpsm(7)
2 files changed, 130 insertions, 12 deletions
diff --git a/Makefile b/Makefile
index ebada37..7cb659c 100644
--- a/Makefile
+++ b/Makefile
@@ -11,17 +11,20 @@
## -----------------------------------------------------------------------
-TEST = teststore testbuddy testalloc testrecovery zallocevil \
- test_mmap ftrunctest
-VERSION = 0.1.9
-LIBPSM =$(VERSION) libpsm.a
-CFILES = arena.c bitops.c \
- mgmt.c malloc.c free.c realloc.c zalloc.c calloc.c stats.c
-OSOBJ = $(patsubst %.c,%.o,$(CFILES))
-OSPICOBJ = $(patsubst %.c,%.pic.o,$(CFILES))
-MANPAGES = $(patsubst,%,$(wildcard *.[1-9].in))
+TEST = teststore testbuddy testalloc testrecovery zallocevil \
+ test_mmap ftrunctest
+VERSION = 0.1.9
+LIBPSM =$(VERSION) libpsm.a
+CFILES = arena.c bitops.c \
+ mgmt.c malloc.c free.c realloc.c zalloc.c calloc.c stats.c
+OSOBJ = $(patsubst %.c,%.o,$(CFILES))
+OSPICOBJ = $(patsubst %.c,%.pic.o,$(CFILES))
+# MAN1PAGES = $(patsubst,%,$(wildcard *
+MAN3PAGES = $(patsubst,%,$(wildcard *
+MAN7PAGES = $(patsubst,%,$(wildcard *
CC = gcc
ifndef DEBUG
@@ -74,12 +77,13 @@ install: all
cd $(INSTALLROOT)$(libdir) && ln -sf$(VERSION) $(SONAME)
cd $(INSTALLROOT)$(libdir) && ln -sf$(VERSION)
$(INSTALL) lpsm.h $(INSTALLROOT)$(includedir)
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_checkpoint.3 lpsm_need_checkpoint.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_free.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_realloc.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_zalloc.3
cd $(INSTALLROOT)$(man3dir) && ln -sf lpsm_malloc.3 lpsm_calloc.3
%.o: %.c
diff --git a/ b/
new file mode 100644
index 0000000..683fa5e
--- /dev/null
+++ b/
@@ -0,0 +1,114 @@
+.\" -*- nroff -*- ---------------------------------------------------------
+.\" Copyright 2001 H. Peter Anvin - All Rights Reserved
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU Lesser General Public License as
+.\" published by the Free Software Foundation, Inc.,
+.\" 59 Temple Place Ste 330, Bostom MA 02111-1307, USA; version 2.1,
+.\" incorporated herein by reference.
+.\" -----------------------------------------------------------------------
+.\" $Id$
+.TH LPSM 7 "25 October 2001" "@@VERSION@@" "Linux Persistent Memory"
+lpsm \- A persistent memory library for Linux
+LPSM is a C library with a simple interface that manages a segment of
+memory backed by a persistent file. LPSM differs from ordinary
+.B mmap()
+in two ways: it can optionally offer heap management
+(malloc/free/realloc) within the arena, and, more importantly, a
+transaction log is used to ensure the consistency of the persistent
+representation. The application notifies LPSM whenever the arena is in
+a consistent state, suitable for checkpointing. If the application or
+system crashes, the arena will always be recovered to a consistent
+An LPSM database consists of two files, the
+.IR datafile ,
+which contains the bulk storage, and the
+.IR logfile ,
+which contains the recent changes. The logfile is constructed in such
+a way that data loss is unlikely.
+.IR "unmanaged mode" ,
+the contents of the mapped memory is simply the contents of the
+datafile, quite similarly to the way a file can be mapped into memory
+.BR mmap() .
+However, unlike
+.BR mmap() ,
+the application can use
+.B lpsm_checkpoint()
+to control when it is safe for data to get written back to the data
+store. In that way, it provides a combination of the semantics
+offered by the
+options to
+.BR mmap() .
+.IR "managed mode" ,
+the contents of the data store is managed in a way very similar to the
+way conventional memory is managed by
+.B malloc()
+and its associated functions.
+It is expected that most applications will use managed mode.
+In unmanaged mode, a data store is opened with
+.BR lpsm_arena_init() .
+The function
+.B lpsm_checkpoint()
+is called to checkpoint,
+.B lpsm_extend()
+to increase the size of the memory arena, and
+.B lpsm_shutdown()
+to close the data store. The function
+.B lpsm_recover()
+can be called to do offline log recovery, i.e. bring the
+.I datafile
+fully up to date with the contents of the data store and truncate the
+.I logfile
+to its minimum size.
+In managed mode, a data store is opened with
+.BR lpsm_init() .
+The functions
+.BR lpsm_malloc() ,
+.BR lpsm_free() ,
+.BR lpsm_realloc() ,
+.BR lpsm_zalloc() ,
+.B lpsm_calloc()
+provide memory management very similar to the equivalent conventional
+memory functions
+.RB ( lpsm_zalloc()
+is similar to
+.B calloc()
+but with a different interface.)
+The function
+.B lpsm_alloc_stats()
+provide extended statistics on the memory allocation.
+As in unmanaged mode,
+.B lpsm_checkpoint()
+is used to checkpoint the data store, and
+.B lpsm_shutdown()
+to close. As with unmanaged mode,
+.B lpsm_recover()
+can be used to do offline log recovery.
+.BR lpsm_init (3),
+.BR lpsm_malloc (3),
+.BR lpsm_alloc_stats (3),
+.BR lpsm_arena_init (3),
+.BR lpsm_extend (3),
+.BR lpsm_checkpoint (3),
+.BR lpsm_shutdown (3),
+.BR lpsm_recover (3),
+.BR mmap (2),
+.BR malloc (3).