1PMEMOBJ_OPEN(3) PMDK Programmer's Manual PMEMOBJ_OPEN(3)
2
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
11 #include <libpmemobj.h>
12 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 void pmemobj_set_user_data(PMEMobjpool *pop, void *data);
20 void *pmemobj_get_user_data(PMEMobjpool *pop);
21
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 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 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 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 Depending on the configuration of the system, the available non-
65 volatile memory space may be divided into multiple memory devices. In
66 such case, the maximum size of the pmemobj memory pool could be limited
67 by the capacity of a single memory device. libpmemobj(7) allows build‐
68 ing persistent memory resident object store spanning multiple memory
69 devices by creation of persistent memory pools consisting of multiple
70 files, where each part of such a pool set may be stored on a different
71 memory device or pmem-aware filesystem.
72 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 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 The set file is a plain text file, the structure of which is described
85 in poolset(5).
86 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 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 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 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 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
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 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 The pmemobj_close() function returns no value.
130 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
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
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>
147PMDK - pmemobj API version 2.3 2020-10-28 PMEMOBJ_OPEN(3)