1LIBPMEMOBJ(7) PMDK Programmer's Manual LIBPMEMOBJ(7)
2
3
4
6 libpmemobj - persistent memory transactional object store
7
9 #include <libpmemobj.h>
10 cc -std=gnu99 ... -lpmemobj -lpmem
11
12 Library API versioning:
13 const char *pmemobj_check_version(
14 unsigned major_required,
15 unsigned minor_required);
16
17 Managing library behavior:
18 void pmemobj_set_funcs(
19 void *(*malloc_func)(size_t size),
20 void (*free_func)(void *ptr),
21 void *(*realloc_func)(void *ptr, size_t size),
22 char *(*strdup_func)(const char *s));
23
24 Error handling:
25 const char *pmemobj_errormsg(void);
26
27 Other library functions:
28 A description of other libpmemobj functions can be found on the follow‐
29 ing manual pages:
30
31 • control and statistics: pmemobj_ctl_get(3)
32
33 • create, open, close and validate: pmemobj_open(3)
34
35 • low-level memory manipulation: pmemobj_memcpy_persist(3)
36
37 • locking: pmemobj_mutex_zero(3)
38
39 • persistent object identifier: OID_IS_NULL(3)
40
41 • type-safety: TOID_DECLARE(3)
42
43 • layout declaration: POBJ_LAYOUT_BEGIN(3)
44
45 • non-transactional atomic allocations: pmemobj_alloc(3)
46
47 • root object management: pmemobj_root(3)
48
49 • object containers: pmemobj_first(3)
50
51 • non-transactional persistent atomic circular doubly-linked list:
52 pmemobj_list_insert(3), POBJ_LIST_HEAD(3)
53
54 • transactional object manipulation: pmemobj_tx_begin(3), pmemo‐
55 bj_tx_add_range(3), pmemobj_tx_alloc(3)
56
57 • delayed atomicity actions: pmemobj_action(3) (EXPERIMENTAL)
58
60 libpmemobj provides a transactional object store in persistent memory
61 (pmem) for applications that require transactions and persistent memory
62 management using direct access storage (DAX), which is storage that
63 supports load/store access without paging blocks from a block storage
64 device. Some types of non-volatile memory DIMMs (NVDIMMs) provide this
65 type of byte addressable access to storage. A persistent memory aware
66 file system is typically used to expose the direct access to applica‐
67 tions. Memory mapping a file from this type of file system results in
68 load/store, non-paged access to pmem. libpmemobj builds on this type
69 of memory mapped file using the low-level pmem support provided by
70 libpmem(7), handling the transactional updates, flushing changes to
71 persistence, and managing recovery for the application.
72
73 libpmemobj requires the -std=gnu99 compilation flag to build properly.
74
75 libpmemobj is one of a collection of persistent memory libraries avail‐
76 able. The others are:
77
78 • libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks
79 with atomic updates.
80
81 • libpmemlog(7), providing a pmem-resident log file.
82
83 • libpmem(7), low-level persistent memory support.
84
85 Under normal usage, libpmemobj will never print messages or intention‐
86 ally cause the process to exit. The only exception to this is the de‐
87 bugging information, when enabled, as described under DEBUGGING AND ER‐
88 ROR HANDLING, below.
89
91 This section describes how the library API is versioned, allowing ap‐
92 plications to work with an evolving API.
93
94 The pmemobj_check_version() function is used to see if the installed
95 libpmemobj supports the version of the library API required by an ap‐
96 plication. The easiest way to do this is for the application to supply
97 the compile-time version information, supplied by defines in <libpmemo‐
98 bj.h>, like this:
99
100 reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION,
101 PMEMOBJ_MINOR_VERSION);
102 if (reason != NULL) {
103 /* version check failed, reason string tells you why */
104 }
105
106 Any mismatch in the major version number is considered a failure, but a
107 library with a newer minor version number will pass this check since
108 increasing minor versions imply backwards compatibility.
109
110 An application can also check specifically for the existence of an in‐
111 terface by checking for the version where that interface was intro‐
112 duced. These versions are documented in this man page as follows: un‐
113 less otherwise specified, all interfaces described here are available
114 in version 1.0 of the library. Interfaces added after version 1.0 will
115 contain the text introduced in version x.y in the section of this manu‐
116 al describing the feature.
117
118 On success, pmemobj_check_version() returns NULL. Otherwise, the re‐
119 turn value is a static string describing the reason the version check
120 failed. The string returned by pmemobj_check_version() must not be
121 modified or freed.
122
124 The pmemobj_set_funcs() function allows an application to override mem‐
125 ory allocation calls used internally by libpmemobj. Passing in NULL
126 for any of the handlers will cause the libpmemobj default function to
127 be used. The library does not make heavy use of the system malloc
128 functions, but it does allocate approximately 4-8 kilobytes for each
129 memory pool in use.
130
131 By default, libpmemobj supports up to 1024 parallel transactions/allo‐
132 cations. For debugging purposes it is possible to decrease this value
133 by setting the PMEMOBJ_NLANES environment variable to the desired lim‐
134 it.
135
137 If an error is detected during the call to a libpmemobj function, the
138 application may retrieve an error message describing the reason for the
139 failure from pmemobj_errormsg(). This function returns a pointer to a
140 static buffer containing the last error message logged for the current
141 thread. If errno was set, the error message may include a description
142 of the corresponding error code as returned by strerror(3). The error
143 message buffer is thread-local; errors encountered in one thread do not
144 affect its value in other threads. The buffer is never cleared by any
145 library function; its content is significant only when the return value
146 of the immediately preceding call to a libpmemobj function indicated an
147 error, or if errno was set. The application must not modify or free
148 the error message string, but it may be modified by subsequent calls to
149 other library functions.
150
151 Two versions of libpmemobj are typically available on a development
152 system. The normal version, accessed when a program is linked using
153 the -lpmemobj option, is optimized for performance. That version skips
154 checks that impact performance and never logs any trace information or
155 performs any run-time assertions.
156
157 A second version of libpmemobj, accessed when a program uses the li‐
158 braries under /usr/lib/pmdk_debug, contains run-time assertions and
159 trace points. The typical way to access the debug version is to set
160 the environment variable LD_LIBRARY_PATH to /usr/lib/pmdk_debug or
161 /usr/lib64/pmdk_debug, as appropriate. Debugging output is controlled
162 using the following environment variables. These variables have no ef‐
163 fect on the non-debug version of the library.
164
165 • PMEMOBJ_LOG_LEVEL
166
167 The value of PMEMOBJ_LOG_LEVEL enables trace points in the debug ver‐
168 sion of the library, as follows:
169
170 • 0 - This is the default level when PMEMOBJ_LOG_LEVEL is not set. No
171 log messages are emitted at this level.
172
173 • 1 - Additional details on any errors detected are logged, in addition
174 to returning the errno-based errors as usual. The same information
175 may be retrieved using pmemobj_errormsg().
176
177 • 2 - A trace of basic operations is logged.
178
179 • 3 - Enables a very verbose amount of function call tracing in the li‐
180 brary.
181
182 • 4 - Enables voluminous and fairly obscure tracing information that is
183 likely only useful to the libpmemobj developers.
184
185 Unless PMEMOBJ_LOG_FILE is set, debugging output is written to stderr.
186
187 • PMEMOBJ_LOG_FILE
188
189 Specifies the name of a file where all logging information should be
190 written. If the last character in the name is “-”, the PID of the cur‐
191 rent process will be appended to the file name when the log file is
192 created. If PMEMOBJ_LOG_FILE is not set, logging output is written to
193 stderr.
194
195 See also libpmem(7) to get information about other environment vari‐
196 ables affecting libpmemobj behavior.
197
199 See <https://pmem.io/pmdk/libpmemobj> for examples using the libpmemobj
200 API.
201
203 libpmemobj builds on the persistent memory programming model recommend‐
204 ed by the SNIA NVM Programming Technical Work Group:
205 <https://snia.org/nvmp>
206
208 OID_IS_NULL(3), pmemobj_alloc(3), pmemobj_ctl_exec(3), pmemo‐
209 bj_ctl_get(3), pmemobj_ctl_set(3), pmemobj_first(3), pmemobj_list_in‐
210 sert(3), pmemobj_memcpy_persist(3), pmemobj_mutex_zero(3), pmemo‐
211 bj_open(3), pmemobj_root(3), pmemobj_tx_add_range(3), pmemobj_tx_al‐
212 loc(3), pmemobj_tx_begin(3), POBJ_LAYOUT_BEGIN(3), POBJ_LIST_HEAD(3),
213 strerror(3), TOID_DECLARE(3), libpmem(7), libpmemblk(7), libpmemlog(7)
214 and <https://pmem.io>
215
216
217
218PMDK - pmemobj API version 2.3 2020-10-28 LIBPMEMOBJ(7)