.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "PMEMOBJ_OPEN" "3" "2017-12-22" "PMDK - pmemobj API version 2.2" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2017, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" * Neither the name of the copyright holder nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH NAME
.PP
\f[B]pmemobj_open\f[](), \f[B]pmemobj_create\f[](),
\f[B]pmemobj_close\f[](), \f[B]pmemobj_check\f[]() \-\- create, open,
close and validate persistent memory transactional object store
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>
PMEMobjpool\ *pmemobj_open(const\ char\ *path,\ const\ char\ *layout);
PMEMobjpool\ *pmemobj_create(const\ char\ *path,\ const\ char\ *layout,
\ \ \ \ size_t\ poolsize,\ mode_t\ mode);
void\ pmemobj_close(PMEMobjpool\ *pop);
int\ pmemobj_check(const\ char\ *path,\ const\ char\ *layout);
\f[]
.fi
.SH DESCRIPTION
.PP
To use the pmem\-resident transactional object store provided by
\f[B]libpmemobj\f[](7), a \f[I]memory pool\f[] must first be created
with the \f[B]pmemobj_create\f[]() function described below.
Existing pools may be opened with the \f[B]pmemobj_open\f[]() function.
.PP
None of the three functions described below is thread\-safe with respect
to any other \f[B]libpmemobj\f[](7) functions.
In other words, when creating, opening or deleting a pool, nothing else
in the library can happen in parallel, and therefore these functions
should be called from the main thread.
.PP
Once created, the memory pool is represented by an opaque handle, of
type \f[I]PMEMobjpool*\f[], which is passed to most of the other
\f[B]libpmemobj\f[](7) functions.
Internally, \f[B]libpmemobj\f[](7) will use either
\f[B]pmem_persist\f[](3) or \f[B]msync\f[](2) when it needs to flush
changes, depending on whether the memory pool appears to be persistent
memory or a regular file (see the \f[B]pmem_is_pmem\f[](3) function in
\f[B]libpmem\f[](7) for more information).
There is no need for applications to flush changes directly when using
the object memory API provided by \f[B]libpmemobj\f[](7).
.PP
The \f[B]pmemobj_create\f[]() function creates a transactional object
store with the given total \f[I]poolsize\f[].
\f[I]path\f[] specifies the name of the memory pool file to be created.
\f[I]layout\f[] specifies the application\[aq]s layout type in the form
of a string.
The layout name is not interpreted by \f[B]libpmemobj\f[](7), but may be
used as a check when \f[B]pmemobj_open\f[]() is called.
The layout name, including the terminating null byte (\[aq]\[aq]),
cannot be longer than \f[B]PMEMOBJ_MAX_LAYOUT\f[] as defined in
\f[B]<libpmemobj.h>\f[].
A NULL \f[I]layout\f[] is equivalent to using an empty string as a
layout name.
\f[I]mode\f[] specifies the permissions to use when creating the file,
as described by \f[B]creat\f[](2).
The memory pool file is fully allocated to the size \f[I]poolsize\f[]
using \f[B]posix_fallocate\f[](3).
The caller may choose to take responsibility for creating the memory
pool file by creating it before calling \f[B]pmemobj_create\f[](), and
then specifying \f[I]poolsize\f[] as zero.
In this case \f[B]pmemobj_create\f[]() will take the pool size from the
size of the existing file and will verify that the file appears to be
empty by searching for any non\-zero data in the pool header at the
beginning of the file.
The minimum net pool size allowed by the library for a local
transactional object store is defined in \f[B]<libpmemobj.h>\f[] as
\f[B]PMEMOBJ_MIN_POOL\f[].
For remote replicas the minimum file size is defined in
\f[B]<librpmem.h>\f[] as \f[B]RPMEM_MIN_PART\f[].
.PP
The \f[B]pmemobj_open\f[]() function opens an existing object store
memory pool.
\f[I]path\f[] must be an existing file containing a pmemobj memory pool
as created by \f[B]pmemobj_create\f[]().
If \f[I]layout\f[] is non\-NULL, it is compared to the layout name
provided to \f[B]pmemobj_create\f[]() when the pool was first created.
This can be used to verify that the layout of the pool matches what was
expected.
The application must have permission to open the file and memory map it
with read/write permissions.
.PP
The \f[B]pmemobj_close\f[]() function closes the memory pool indicated
by \f[I]pop\f[] and deletes the memory pool handle.
The object store itself lives on in the file that contains it and may be
re\-opened at a later time using \f[B]pmemobj_open\f[]() as described
above.
.PP
The \f[B]pmemobj_check\f[]() function performs a consistency check of
the file indicated by \f[I]path\f[].
\f[B]pmemobj_check\f[]() opens the given \f[I]path\f[] read\-only so it
never makes any changes to the file.
This function is not supported on Device DAX.
.SH RETURN VALUE
.PP
The \f[B]pmemobj_create\f[]() function returns a memory pool handle to
be used with most of the functions in \f[B]libpmemobj\f[](7).
On error it returns NULL and sets \f[I]errno\f[] appropriately.
.PP
The \f[B]pmemobj_open\f[]() function returns a memory pool handle to be
used with most of the functions in \f[B]libpmemobj\f[](7).
If an error prevents the pool from being opened, or if the given
\f[I]layout\f[] does not match the pool\[aq]s layout,
\f[B]pmemobj_open\f[]() returns NULL and sets \f[I]errno\f[]
appropriately.
.PP
The \f[B]pmemobj_close\f[]() function returns no value.
.PP
The \f[B]pmemobj_check\f[]() function returns 1 if the memory pool is
found to be consistent.
Any inconsistencies found will cause \f[B]pmemobj_check\f[]() to return
0, in which case the use of the file with \f[B]libpmemobj\f[](7) will
result in undefined behavior.
The debug version of \f[B]libpmemobj\f[](7) will provide additional
details on inconsistencies when \f[B]PMEMOBJ_LOG_LEVEL\f[] is at least
1, asdescribed in the \f[B]DEBUGGING AND ERROR HANDLING\f[] section in
\f[B]libpmemobj\f[](7).
\f[B]pmemobj_check\f[]() returns \-1 and sets \f[I]errno\f[] if it
cannot perform the consistency check due to other errors.
.SH CAVEATS
.PP
Not all file systems support \f[B]posix_fallocate\f[](3).
\f[B]pmemobj_create\f[]() will fail if the underlying file system does
not support \f[B]posix_fallocate\f[](3).
.SH SEE ALSO
.PP
\f[B]creat\f[](2), \f[B]msync\f[](2), \f[B]pmem_is_pmem\f[](3),
\f[B]pmem_persist\f[](3), \f[B]posix_fallocate\f[](3),
\f[B]libpmem\f[](7), \f[B]libpmemobj\f[](7) and
\f[B]<http://pmem.io>\f[]