.\" -*- 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_ARENA_INIT 3  "25 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
.SH NAME
lpsm_arena_init \- Open persistent memory in unmanaged mode
.SH SYNOPSIS
.nf
.B #include <lpsm.h>
.sp
.BI "void *lpsm_arena_init(const char " "*datafile" ", const char " "*logfile" ", size_t *" "arena_size" ", void *" "arena_base" ");"
.fi
.SH DESCRIPTION
This function opens an LPSM persistent memory arena in unmanaged mode.
It provides an in-memory snapshot of the
.I datafile
with commit semantics, using the
.I logfile
to implement the commit semantics. This function is not compatible
with the use of
.B lpsm_malloc()
and its related functions.
.PP
.B lpsm_arena_init()
opens the persistent memory arena that consists of the two
files
.I datafile
and
.IR logfile .
If these files don't exist, they are created.  The argument
.I arena_size
contains the minimum size of the arena (if smaller, it will be resized
to this size.)  On exit, it contains the actual size of the arena.
.PP
It returns a pointer to the arena, or
.B NULL
on error.
.PP
If
.I arena_base
is set, try to map the arena at that particular
base address.  If arena_base is
.IR NULL ,
use an architecture-specific default value.  Only one arena can be
opened at any one time.
.SH "RETURN VALUES"
.B lpsm_arena_init()
returns the pointer to the arena, or
.B NULL
on failure.
.SH "ERRORS"
On failure,
.B lpsm_arena_init()
will set
.I errno
to the appropriate value for the error that occurred.
.SH "SEE ALSO"
.BR lpsm_init (3),
.BR lpsm_checkpoint (3),
.BR lpsm_extend (3),
.BR lpsm_shutdown (3),
.BR lpsm_recover (3),
.BR lpsm (7).
.SH BUGS
The persistent memory system is not currently thread-safe.