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

RETURN VALUE

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

CAVEATS

138       Not all file systems support posix_fallocate(3).  pmemobj_create() will
139       fail if the underlying file system does not support posix_fallocate(3).
140

SEE ALSO

142       creat(2),   msync(2),  pmem_is_pmem(3),  pmem_persist(3),  posix_fallo‐
143       cate(3), libpmem(7), libpmemobj(7) and <https://pmem.io>
144
145
146
147PMDK - pmemobj API version 2.3    2021-07-22                   PMEMOBJ_OPEN(3)
Impressum