1PMEMOBJ_OPEN(3)            PMDK Programmer's Manual            PMEMOBJ_OPEN(3)
2
3
4

NAME

6       pmemobj_open(),   pmemobj_create(),   pmemobj_close(),  pmemobj_check()
7       pmemobj_set_user_data(), pmemobj_get_user_data() - create, open,  close
8       and validate persistent memory transactional object store
9

SYNOPSIS

11              #include <libpmemobj.h>
12
13              PMEMobjpool *pmemobj_open(const char *path, const char *layout);
14              PMEMobjpool *pmemobj_create(const char *path, const char *layout,
15                  size_t poolsize, mode_t mode);
16              void pmemobj_close(PMEMobjpool *pop);
17              int pmemobj_check(const char *path, const char *layout);
18
19              void pmemobj_set_user_data(PMEMobjpool *pop, void *data);
20              void *pmemobj_get_user_data(PMEMobjpool *pop);
21

DESCRIPTION

23       To  use  the pmem-resident transactional object store provided by libp‐
24       memobj(7), a memory pool must first be created  with  the  pmemobj_cre‐
25       ate()  function described below.  Existing pools may be opened with the
26       pmemobj_open() function.
27
28       None of the three functions described below are  thread-safe  with  re‐
29       spect to any other libpmemobj(7) function.  In other words, when creat‐
30       ing, opening or deleting a pool, nothing else in the library can happen
31       in  parallel,  and  therefore these functions should be called from the
32       main thread.
33
34       Once created, the memory pool is represented by an  opaque  handle,  of
35       type  PMEMobjpool*,  which is passed to most of the other libpmemobj(7)
36       functions.  Internally, libpmemobj(7) will use  either  pmem_persist(3)
37       or  msync(2)  when  it needs to flush changes, depending on whether the
38       memory pool appears to be persistent memory or a regular file (see  the
39       pmem_is_pmem(3) function in libpmem(7) for more information).  There is
40       no need for applications to flush changes directly when using  the  ob‐
41       ject memory API provided by libpmemobj(7).
42
43       The pmemobj_create() function creates a transactional object store with
44       the given total poolsize.  path specifies the name of the  memory  pool
45       file  to be created.  layout specifies the application's layout type in
46       the form of a string.  The layout name is not interpreted by  libpmemo‐
47       bj(7),  but  may be used as a check when pmemobj_open() is called.  The
48       layout name, including the terminating  null  byte  (`\0'),  cannot  be
49       longer  than  PMEMOBJ_MAX_LAYOUT  as defined in <libpmemobj.h>.  A NULL
50       layout is equivalent to using an empty string as a layout  name.   mode
51       specifies  the  permissions to use when creating the file, as described
52       by creat(2).  The memory pool file is fully allocated to the size pool‐
53       size using posix_fallocate(3).  The caller may choose to take responsi‐
54       bility for creating the memory pool file by creating it before  calling
55       pmemobj_create(),  and  then specifying poolsize as zero.  In this case
56       pmemobj_create() will take the pool size from the size of the  existing
57       file and will verify that the file appears to be empty by searching for
58       any non-zero data in the pool header at the beginning of the file.  The
59       minimum  net pool size allowed by the library for a local transactional
60       object store is defined in <libpmemobj.h> as PMEMOBJ_MIN_POOL.  For re‐
61       mote  replicas  the minimum file size is defined in <librpmem.h> as RP‐
62       MEM_MIN_PART.
63
64       Depending  on  the  configuration  of   the   system,   the   available
65       non-volatile  memory space may be divided into multiple memory devices.
66       In such case, the maximum size of the pmemobj memory pool could be lim‐
67       ited  by  the capacity of a single memory device.  libpmemobj(7) allows
68       building persistent memory resident object store spanning multiple mem‐
69       ory devices by creation of persistent memory pools consisting of multi‐
70       ple files, where each part of such a pool set may be stored on  a  dif‐
71       ferent memory device or pmem-aware filesystem.
72
73       Creation of all the parts of the pool set can be done with pmemobj_cre‐
74       ate(); however, the recommended method for creating pool sets  is  with
75       the pmempool(1) utility.
76
77       When  creating  a pool set consisting of multiple files, the path argu‐
78       ment passed to pmemobj_create() must point to the special set file that
79       defines  the  pool layout and the location of all the parts of the pool
80       set.  The poolsize argument must be 0.  The meaning of the  layout  and
81       mode  arguments  does not change, except that the same mode is used for
82       creation of all the parts of the pool set.
83
84       The set file is a plain text file, the structure of which is  described
85       in poolset(5).
86
87       The pmemobj_open() function opens an existing object store memory pool.
88       Similar to pmemobj_create(), path must identify either an existing  obj
89       memory pool file, or the set file used to create a pool set.  If layout
90       is non-NULL, it is compared to the layout name provided to pmemobj_cre‐
91       ate() when the pool was first created.  This can be used to verify that
92       the layout of the pool matches what was expected.  The application must
93       have permission to open the file and memory map it with read/write per‐
94       missions.
95
96       Be aware that if the pool contains bad blocks inside,  opening  can  be
97       aborted by the SIGBUS signal, because currently the pool is not checked
98       against bad blocks during opening.  It can be turned on by setting  the
99       CHECK_BAD_BLOCKS  compat  feature.  For details see description of this
100       feature in pmempool-feature(1).
101
102       The pmemobj_close() function closes the memory pool  indicated  by  pop
103       and  deletes  the memory pool handle.  The object store itself lives on
104       in the file that contains it and may be re-opened at a later time using
105       pmemobj_open() as described above.
106
107       The  pmemobj_check()  function performs a consistency check of the file
108       indicated by path.  pmemobj_check() opens the given path  read-only  so
109       it never makes any changes to the file.  This function is not supported
110       on Device DAX.
111
112       The pmemobj_set_user_data() function associates custom volatile  state,
113       represented  by  pointer data, with the given pool pop.  This state can
114       later be retrieved using pmemobj_get_user_data() function.  This  state
115       does not survive pool close.  If pmemobj_set_user_data() was not called
116       for a given pool, pmemobj_get_user_data() will return NULL.
117

RETURN VALUE

119       The pmemobj_create() function returns a memory pool handle to  be  used
120       with  most of the functions in libpmemobj(7).  On error it returns NULL
121       and sets errno appropriately.
122
123       The pmemobj_open() function returns a memory pool  handle  to  be  used
124       with  most of the functions in libpmemobj(7).  If an error prevents the
125       pool from being opened, or if the  given  layout  does  not  match  the
126       pool's  layout, pmemobj_open() returns NULL and sets errno appropriate‐
127       ly.
128
129       The pmemobj_close() function returns no value.
130
131       The pmemobj_check() function returns 1 if the memory pool is  found  to
132       be consistent.  Any inconsistencies found will cause pmemobj_check() to
133       return 0, in which case the use of the file with libpmemobj(7) will re‐
134       sult  in  undefined  behavior.  The debug version of libpmemobj(7) will
135       provide additional details on inconsistencies when PMEMOBJ_LOG_LEVEL is
136       at least 1, as described in the DEBUGGING AND ERROR HANDLING section in
137       libpmemobj(7).  pmemobj_check() returns -1 and sets errno if it  cannot
138       perform the consistency check due to other errors.
139

CAVEATS

141       Not all file systems support posix_fallocate(3).  pmemobj_create() will
142       fail if the underlying file system does not support posix_fallocate(3).
143

SEE ALSO

145       creat(2),  msync(2),  pmem_is_pmem(3),  pmem_persist(3),   posix_fallo‐
146       cate(3), libpmem(7), libpmemobj(7) and <https://pmem.io>
147
148
149
150PMDK - pmemobj API version 2.3    2020-01-31                   PMEMOBJ_OPEN(3)
Impressum