1LIBPMEM(7) PMDK Programmer's Manual LIBPMEM(7)
2
6 libpmem -- persistent memory support library
7
9 #include <libpmem.h>
10 cc ... -lpmem
11 Library API versioning:
13 const char *pmem_check_version(
14 unsigned major_required,
15 unsigned minor_required);
16 Error handling:
18 const char *pmem_errormsg(void);
19 Other library functions:
21 A description of other libpmem functions can be found on the following
22 manual pages:
23 · most commonly used functions: pmem_is_pmem(3)
25 · partial flushing operations: pmem_flush(3)
27 · copying to persistent memory: pmem_memmove_persist(3)
29
31 libpmem provides low-level persistent memory (pmem) support for appli‐
32 cations using direct access storage (DAX), which is storage that sup‐
33 ports load/store access without paging blocks from a block storage de‐
34 vice. Some types of non-volatile memory DIMMs (NVDIMMs) provide this
35 type of byte addressable access to storage. A persistent memory aware
36 file system is typically used to expose the direct access to applica‐
37 tions. Memory mapping a file from this type of file system results in
38 the load/store, non-paged access to pmem.
39 This library is for applications that use persistent memory directly,
41 without the help of any library-supplied transactions or memory alloca‐
42 tion. Higher-level libraries that build on libpmem are available and
43 are recommended for most applications, see:
44 · libpmemobj(7), a general use persistent memory API, providing memory
46 allocation and transactional operations on variable-sized objects.
47 · libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks
49 with atomic updates.
50 · libpmemlog(7), providing a pmem-resident log file.
52 Under normal usage, libpmem will never print messages or intentionally
54 cause the process to exit. The only exception to this is the debugging
55 information, when enabled, as described under DEBUGGING AND ERROR HAN‐
56 DLING below.
57
59 libpmem relies on the library destructor being called from the main
60 thread. For this reason, all functions that might trigger destruction
61 (e.g. dlclose(3)) should be called in the main thread. Otherwise some
62 of the resources associated with that thread might not be cleaned up
63 properly.
64
66 This section describes how the library API is versioned, allowing ap‐
67 plications to work with an evolving API.
68 The pmem_check_version() function is used to determine whether the in‐
70 stalled libpmem supports the version of the library API required by an
71 application. The easiest way to do this is for the application to sup‐
72 ply the compile-time version information, supplied by defines in <libp‐
73 mem.h>, like this:
74 reason = pmem_check_version(PMEM_MAJOR_VERSION,
76 PMEM_MINOR_VERSION);
77 if (reason != NULL) {
78 /* version check failed, reason string tells you why */
79 }
80 Any mismatch in the major version number is considered a failure, but a
82 library with a newer minor version number will pass this check since
83 increasing minor versions imply backwards compatibility.
84 An application can also check specifically for the existence of an in‐
86 terface by checking for the version where that interface was intro‐
87 duced. These versions are documented in this man page as follows: un‐
88 less otherwise specified, all interfaces described here are available
89 in version 1.0 of the library. Interfaces added after version 1.0 will
90 contain the text introduced in version x.y in the section of this manu‐
91 al describing the feature.
92 When the version check performed by pmem_check_version() is successful,
94 the return value is NULL. Otherwise the return value is a static
95 string describing the reason for failing the version check. The string
96 returned by pmem_check_version() must not be modified or freed.
97
99 libpmem can change its default behavior based on the following environ‐
100 ment variables. These are largely intended for testing and are not
101 normally required.
102 · PMEM_IS_PMEM_FORCE=val
104 If val is 0 (zero), then pmem_is_pmem(3) will always return false.
106 Setting val to 1 causes pmem_is_pmem(3) to always return true. This
107 variable is mostly used for testing but can be used to force pmem be‐
108 havior on a system where a range of pmem is not detectable as pmem for
109 some reason.
110 NOTE: Unlike the other variables, the value of
112 PMEM_IS_PMEM_FORCE is not queried (and cached) at library ini‐
113 tialization time, but on the first call to pmem_is_pmem(3).
114 This means that in case of libpmemlog(7), libpmemblk(7), and
115 libpmemobj(7), PMEM_IS_PMEM_FORCE may still be set or modified
116 by the program until the first attempt to create or open the
117 persistent memory pool.
118 · PMEM_NO_CLWB=1
120 Setting this environment variable to 1 forces libpmem to never issue
122 the CLWB instruction on Intel hardware, falling back to other cache
123 flush instructions instead (CLFLUSHOPT or CLFLUSH on Intel hardware).
124 Without this environment variable, libpmem will always use the CLWB in‐
125 struction for flushing processor caches on platforms that support the
126 instruction. This variable is intended for use during library testing
127 but may be required for some rare cases where using CLWB has a negative
128 impact on performance.
129 · PMEM_NO_CLFLUSHOPT=1
131 Setting this environment variable to 1 forces libpmem to never issue
133 the CLFLUSHOPT instruction on Intel hardware, falling back to the
134 CLFLUSH instructions instead. Without this environment variable, libp‐
135 mem will always use the CLFLUSHOPT instruction for flushing processor
136 caches on platforms that support the instruction, but where CLWB is not
137 available. This variable is intended for use during library testing.
138 · PMEM_NO_FLUSH=1
140 Setting this environment variable to 1 forces most libpmem functions to
142 never issue any of CLFLUSH, CLFLUSHOPT or CLWB instructions on Intel
143 hardware. The only exceptions are pmem_deep_flush(3) and
144 pmem_deep_persist(3) functions.
145 · PMEM_NO_FLUSH=0
147 Setting this environment variable to 0 forces to always flush CPU
149 caches using one of CLFLUSH, CLFLUSHOPT or CLWB instructions even if
150 pmem_has_auto_flush(3) function returns true and eADR is supported.
151 · PMEM_NO_MOVNT=1
153 Setting this environment variable to 1 forces libpmem to never use the
155 non-temporal move instructions on Intel hardware. Without this envi‐
156 ronment variable, libpmem will use the non-temporal instructions for
157 copying larger ranges to persistent memory on platforms that support
158 the instructions. This variable is intended for use during library
159 testing.
160 · PMEM_MOVNT_THRESHOLD=val
162 This environment variable allows overriding the minimum length of the
164 pmem_memmove_persist(3) operations, for which libpmem uses non-temporal
165 move instructions. Setting this environment variable to 0 forces libp‐
166 mem to always use the non-temporal move instructions if available. It
167 has no effect if PMEM_NO_MOVNT is set to 1. This variable is intended
168 for use during library testing.
169 · PMEM_MMAP_HINT=val
171 This environment variable allows overriding the hint address used by
173 pmem_map_file(). If set, it also disables mapping address randomiza‐
174 tion. This variable is intended for use during library testing and de‐
175 bugging. Setting it to some fairly large value (i.e. 0x10000000000)
176 will very likely result in mapping the file at the specified address
177 (if not used) or at the first unused region above given address, with‐
178 out adding any random offset. When debugging, this makes it easier to
179 calculate the actual address of the persistent memory block, based on
180 its offset in the file. In case of libpmemobj it simplifies conversion
181 of a persistent object identifier (OID) into a direct pointer to the
182 object.
183 NOTE: Setting this environment variable affects all the PMDK li‐
185 braries, disabling mapping address randomization and causing the
186 specified address to be used as a hint about where to place the
187 mapping.
188
190 If an error is detected during the call to a libpmem function, the ap‐
191 plication may retrieve an error message describing the reason for the
192 failure from pmem_errormsg(). This function returns a pointer to a
193 static buffer containing the last error message logged for the current
194 thread. If errno was set, the error message may include a description
195 of the corresponding error code as returned by strerror(3). The error
196 message buffer is thread-local; errors encountered in one thread do not
197 affect its value in other threads. The buffer is never cleared by any
198 library function; its content is significant only when the return value
199 of the immediately preceding call to a libpmem function indicated an
200 error, or if errno was set. The application must not modify or free
201 the error message string, but it may be modified by subsequent calls to
202 other library functions.
203 Two versions of libpmem are typically available on a development sys‐
205 tem. The normal version, accessed when a program is linked using the
206 -lpmem option, is optimized for performance. That version skips checks
207 that impact performance and never logs any trace information or per‐
208 forms any run-time assertions.
209 A second version of libpmem, accessed when a program uses the libraries
211 under /usr/lib/pmdk_debug, contains run-time assertions and trace
212 points. The typical way to access the debug version is to set the en‐
213 vironment variable LD_LIBRARY_PATH to /usr/lib/pmdk_debug or
214 /usr/lib64/pmdk_debug, as appropriate. Debugging output is controlled
215 using the following environment variables. These variables have no ef‐
216 fect on the non-debug version of the library.
217 · PMEM_LOG_LEVEL
219 The value of PMEM_LOG_LEVEL enables trace points in the debug version
221 of the library, as follows:
222 · 0 - This is the default level when PMEM_LOG_LEVEL is not set. No log
224 messages are emitted at this level.
225 · 1 - Additional details on any errors detected are logged, in addition
227 to returning the errno-based errors as usual. The same information
228 may be retrieved using pmem_errormsg().
229 · 2 - A trace of basic operations is logged.
231 · 3 - Enables a very verbose amount of function call tracing in the li‐
233 brary.
234 · 4 - Enables voluminous and fairly obscure tracing information that is
236 likely only useful to the libpmem developers.
237 Unless PMEM_LOG_FILE is set, debugging output is written to stderr.
239 · PMEM_LOG_FILE
241 Specifies the name of a file where all logging information should be
243 written. If the last character in the name is "-", the PID of the cur‐
244 rent process will be appended to the file name when the log file is
245 created. If PMEM_LOG_FILE is not set, output is written to stderr.
246
248 The following example uses libpmem to flush changes made to raw, memo‐
249 ry-mapped persistent memory.
250 WARNING: There is nothing transactional about the pmem_per‐
252 sist(3) or pmem_msync(3) calls in this example. Interrupting
253 the program may result in a partial write to pmem. Use a trans‐
254 actional library such as libpmemobj(7) to avoid torn updates.
255 #include <sys/types.h>
257 #include <sys/stat.h>
258 #include <fcntl.h>
259 #include <stdio.h>
260 #include <errno.h>
261 #include <stdlib.h>
262 #include <unistd.h>
263 #include <string.h>
264 #include <libpmem.h>
265 /* using 4k of pmem for this example */
267 #define PMEM_LEN 4096
268 #define PATH "/pmem-fs/myfile"
270 int
272 main(int argc, char *argv[])
273 {
274 char *pmemaddr;
275 size_t mapped_len;
276 int is_pmem;
277 /* create a pmem file and memory map it */
279 if ((pmemaddr = pmem_map_file(PATH, PMEM_LEN, PMEM_FILE_CREATE,
281 0666, &mapped_len, &is_pmem)) == NULL) {
282 perror("pmem_map_file");
283 exit(1);
284 }
285 /* store a string to the persistent memory */
287 strcpy(pmemaddr, "hello, persistent memory");
288 /* flush above strcpy to persistence */
290 if (is_pmem)
291 pmem_persist(pmemaddr, mapped_len);
292 else
293 pmem_msync(pmemaddr, mapped_len);
294 /*
296 * Delete the mappings. The region is also
297 * automatically unmapped when the process is
298 * terminated.
299 */
300 pmem_unmap(pmemaddr, mapped_len);
301 }
302 See <http://pmem.io/pmdk/libpmem> for more examples using the libpmem
304 API.
305
307 libpmem builds on the persistent memory programming model recommended
308 by the SNIA NVM Programming Technical Work Group:
309 <http://snia.org/nvmp>
310
312 dlclose(3), pmem_flush(3), pmem_is_pmem(3), pmem_memmove_persist(3),
313 pmem_msync(3), pmem_persist(3), strerror(3), libpmemblk(7), libpmemc‐
314 to(7), libpmemlog(7), libpmemobj(7) and <http://pmem.io>
315PMDK - pmem API version 1.1 2018-03-13 LIBPMEM(7)