.\" -*- 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 "IMPORTANT NOTES"
.B "LPSM databases are not portable."
This is pretty much inherent in the fact that the LPSM library does
not attach any meaning to the data it stores.  Therefore it is
imperative that your application allows a way to dump its database
contents in a portable form.
.PP
Currently the persistent memory database is not sharable nor
thread-safe.  I'm hoping to resolve at least the latter condition in
due time.
.PP
Because the persistent memory is mapped into memory at a fixed address
(which varies with architecture) it is not possible to have more than
one LPSM database mapped at any one time.
.PP
The LPSM library installs a handler for the
.B SIGSEGV
signal.
.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).
.SH "VERSION"
This man page is applicable as to version @@VERSION@@ of LPSM.
.SH "AUTHOR"
LPSM was written by H. Peter Anvin, <hpa@zytor.com>.
.SH "COPYRIGHT AND LICENSE"
\(co 2001 H. Peter Anvin \- All Rights Reserved
.PP
LPSM 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.