summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2001-10-26 02:32:56 (GMT)
committerH. Peter Anvin <hpa@zytor.com>2001-10-26 02:32:56 (GMT)
commitd5cfcf4d16630bd5961157fb66f6a9d9d288c063 (patch)
tree3c63d766ced63f9b1d6bc70dd0bdea5aed455336
parentaf538c1a2aa168d1c66e6e1c1fa3a3fb3e5b00b6 (diff)
downloadlpsm-d5cfcf4d16630bd5961157fb66f6a9d9d288c063.zip
lpsm-d5cfcf4d16630bd5961157fb66f6a9d9d288c063.tar.gz
lpsm-d5cfcf4d16630bd5961157fb66f6a9d9d288c063.tar.bz2
lpsm-d5cfcf4d16630bd5961157fb66f6a9d9d288c063.tar.xz
Add overall man page lpsm(7)
-rw-r--r--Makefile28
-rw-r--r--lpsm.7.in114
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).