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 
-SONAME   = libpsm.so.0
-VERSION  = 0.1.9
-LIBPSM	 = libpsm.so.$(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 %.in,%,$(wildcard *.[1-9].in))
+TEST      = teststore testbuddy testalloc testrecovery zallocevil \
+	    test_mmap ftrunctest 
+SONAME    = libpsm.so.0
+VERSION   = 0.1.9
+LIBPSM	  = libpsm.so.$(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 %.in,%,$(wildcard *.1.in))
+MAN3PAGES = $(patsubst %.in,%,$(wildcard *.3.in))
+MAN7PAGES = $(patsubst %.in,%,$(wildcard *.7.in))
+MANPAGES  = $(MAN3PAGES) $(MAN7PAGES)
 
 CC	 = gcc
 ifndef DEBUG
@@ -74,12 +77,13 @@ install: all
 	cd $(INSTALLROOT)$(libdir) && ln -sf libpsm.so.$(VERSION) $(SONAME)
 	cd $(INSTALLROOT)$(libdir) && ln -sf libpsm.so.$(VERSION) libpsm.so
 	$(INSTALL) lpsm.h    $(INSTALLROOT)$(includedir)
-	$(INSTALL) $(MANPAGES) $(INSTALLROOT)$(man3dir)
+	$(INSTALL) $(MAN3PAGES) $(INSTALLROOT)$(man3dir)
 	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
+	$(INSTALL) $(MAN7PAGES) $(INSTALLROOT)$(man7dir)
 	ldconfig
 
 %.o: %.c
diff --git a/lpsm.7.in b/lpsm.7.in
new file mode 100644
index 0000000..683fa5e
--- /dev/null
+++ b/lpsm.7.in
@@ -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"
+.SH "NAME"
+lpsm \- A persistent memory library for Linux
+.SH "DESCRIPTION"
+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
+checkpoint.
+.SH "USAGE"
+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.
+.PP
+In
+.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
+by
+.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
+.B MAP_SHARED
+and
+.B MAP_PRIVATE
+options to
+.BR mmap() .
+.PP
+In
+.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.
+.PP
+It is expected that most applications will use managed mode.
+.SH "FUNCTIONS USED IN UNMANAGED 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.
+.SH "FUNCTIONS USED IN MANAGED MODE"
+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() ,
+and
+.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.
+.SH "SEE ALSO"
+.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).