1() PMDK Programmer's Manual ()
2
6 libpmemblk - persistent memory resident array of blocks (DEPRECATED)
7 NOTE: Support for Windows and FreeBSD deprecated since PMDK
9 1.13.0 release and will be removed in the PMDK 1.14.0 release.
10
12 #include <libpmemblk.h>
13 cc ... -lpmemblk -lpmem
14 Library API versioning:
16 const char *pmemblk_check_version(
17 unsigned major_required,
18 unsigned minor_required);
19 Managing library behavior:
21 void pmemblk_set_funcs(
22 void *(*malloc_func)(size_t size),
23 void (*free_func)(void *ptr),
24 void *(*realloc_func)(void *ptr, size_t size),
25 char *(*strdup_func)(const char *s));
26 Error handling:
28 const char *pmemblk_errormsg(void);
29 Other library functions:
31 A description of other libpmemblk functions can be found on the follow‐
32 ing manual pages:
33 pmemblk_bsize(3), pmemblk_create(3), pmemblk_ctl_exec(3), pmem‐
35 blk_ctl_get(3), pmemblk_ctl_set(3), pmemblk_read(3), pmemblk_set_ze‐
36 ro(3),
37
39 libpmemblk provides an array of blocks in persistent memory (pmem) such
40 that updates to a single block are atomic. This library is intended
41 for applications using direct access storage (DAX), which is storage
42 that supports load/store access without paging blocks from a block
43 storage device. Some types of non-volatile memory DIMMs (NVDIMMs) pro‐
44 vide this type of byte addressable access to storage. A persistent
45 memory aware file system is typically used to expose the direct access
46 to applications. Memory mapping a file from this type of file system
47 results in the load/store, non-paged access to pmem. libpmemblk builds
48 on this type of memory mapped file.
49 This library is for applications that need a potentially large array of
51 blocks, all the same size, where any given block is updated atomically
52 (the update cannot be torn by program interruption such as power fail‐
53 ures). This library builds on the low-level pmem support provided by
54 libpmem(7), handling the transactional update of the blocks, flushing
55 to persistence, and recovery for the application. libpmemblk is one of
56 a collection of persistent memory libraries available, the others are:
57 • libpmemobj(7), a general use persistent memory API, providing memory
59 allocation and transactional operations on variable-sized objects.
60 • libpmemlog(7), providing a pmem-resident log file.
62 • libpmem(7), low-level persistent memory support.
64 Under normal usage, libpmemblk will never print messages or intention‐
66 ally cause the process to exit. The only exception to this is the de‐
67 bugging information, when enabled, as described under DEBUGGING AND ER‐
68 ROR HANDLING below.
69 To use the atomic block arrays supplied by libpmemblk, a memory pool is
71 first created using the pmemblk_create() function described in pmem‐
72 blk_create(3). The other libpmemblk functions operate on the resulting
73 block memory pool using the opaque handle, of type PMEMblkpool*, that
74 is returned by pmemblk_create() or pmemblk_open(). Internally, libp‐
75 memblk will use either pmem_persist(3) or msync(2) when it needs to
76 flush changes, depending on whether the memory pool appears to be per‐
77 sistent memory or a regular file (see the pmem_is_pmem(3) function in
78 libpmem(7) for more information). There is no need for applications to
79 flush changes directly when using the block memory API provided by
80 libpmemblk.
81
83 libpmemblk relies on the library destructor being called from the main
84 thread. For this reason, all functions that might trigger destruction
85 (e.g. dlclose(3)) should be called in the main thread. Otherwise some
86 of the resources associated with that thread might not be cleaned up
87 properly.
88
90 This section describes how the library API is versioned, allowing ap‐
91 plications to work with an evolving API.
92 The pmemblk_check_version() function is used to determine whether the
94 installed libpmemblk supports the version of the library API required
95 by an application. The easiest way to do this is for the application
96 to supply the compile-time version information, supplied by defines in
97 <libpmemblk.h>, like this:
98 reason = pmemblk_check_version(PMEMBLK_MAJOR_VERSION,
100 PMEMBLK_MINOR_VERSION);
101 if (reason != NULL) {
102 /* version check failed, reason string tells you why */
103 }
104 Any mismatch in the major version number is considered a failure, but a
106 library with a newer minor version number will pass this check since
107 increasing minor versions imply backwards compatibility.
108 An application can also check specifically for the existence of an in‐
110 terface by checking for the version where that interface was intro‐
111 duced. These versions are documented in this man page as follows: un‐
112 less otherwise specified, all interfaces described here are available
113 in version 1.0 of the library. Interfaces added after version 1.0 will
114 contain the text introduced in version x.y in the section of this manu‐
115 al describing the feature.
116 When the version check performed by pmemblk_check_version() is success‐
118 ful, the return value is NULL. Otherwise the return value is a static
119 string describing the reason for failing the version check. The string
120 returned by pmemblk_check_version() must not be modified or freed.
121
123 The pmemblk_set_funcs() function allows an application to override mem‐
124 ory allocation calls used internally by libpmemblk. Passing in NULL
125 for any of the handlers will cause the libpmemblk default function to
126 be used. The library does not make heavy use of the system malloc
127 functions, but it does allocate approximately 4-8 kilobytes for each
128 memory pool in use.
129
131 The pmemblk_errormsg() function returns a pointer to a static buffer
132 containing the last error message logged for the current thread. If
133 errno was set, the error message may include a description of the cor‐
134 responding error code, as returned by strerror(3). The error message
135 buffer is thread-local; errors encountered in one thread do not affect
136 its value in other threads. The buffer is never cleared by any library
137 function; its content is significant only when the return value of the
138 immediately preceding call to a libpmemblk function indicated an error,
139 or if errno was set. The application must not modify or free the error
140 message string, but it may be modified by subsequent calls to other li‐
141 brary functions.
142 Two versions of libpmemblk are typically available on a development
144 system. The normal version, accessed when a program is linked using
145 the -lpmemblk option, is optimized for performance. That version skips
146 checks that impact performance and never logs any trace information or
147 performs any run-time assertions. If an error is detected in a call to
148 libpmemblk, the error message describing the failure may be retrieved
149 with pmemblk_errormsg() as described above.
150 A second version of libpmemblk, accessed when a program uses the li‐
152 braries under /usr/lib/pmdk_debug, contains run-time assertions and
153 trace points. The typical way to access the debug version is to set
154 the LD_LIBRARY_PATH environment variable to /usr/lib/pmdk_debug or
155 /usr/lib64/pmdk_debug, as appropriate. Debugging output is controlled
156 using the following environment variables. These variables have no ef‐
157 fect on the non-debug version of the library.
158 • PMEMBLK_LOG_LEVEL
160 The value of PMEMBLK_LOG_LEVEL enables trace points in the debug ver‐
162 sion of the library, as follows:
163 • 0 - This is the default level when PMEMBLK_LOG_LEVEL is not set. No
165 log messages are emitted at this level.
166 • 1 - Additional details on any errors detected are logged, in addition
168 to returning the errno-based errors as usual. The same information
169 may be retrieved using pmemblk_errormsg().
170 • 2 - A trace of basic operations is logged.
172 • 3 - Enables a very verbose amount of function call tracing in the li‐
174 brary.
175 • 4 - Enables voluminous and fairly obscure tracing information that is
177 likely only useful to the libpmemblk developers.
178 Unless PMEMBLK_LOG_FILE is set, debugging output is written to stderr.
180 • PMEMBLK_LOG_FILE
182 Specifies the name of a file where all logging information should be
184 written. If the last character in the name is “-”, the PID of the cur‐
185 rent process will be appended to the file name when the log file is
186 created. If PMEMBLK_LOG_FILE is not set, the logging output is written
187 to stderr.
188 See also libpmem(7) for information on other environment variables that
190 may affect libpmemblk behavior.
191
193 The following example illustrates how the libpmemblk API is used.
194 #include <fcntl.h>
196 #include <errno.h>
197 #include <stdlib.h>
198 #include <unistd.h>
199 #include <string.h>
200 #include <libpmemblk.h>
201 /* size of the pmemblk pool -- 1 GB */
203 #define POOL_SIZE ((size_t)(1 << 30))
204 /* size of each element in the pmem pool */
206 #define ELEMENT_SIZE 1024
207 int
209 main(int argc, char *argv[])
210 {
211 const char path[] = "/pmem-fs/myfile";
212 PMEMblkpool *pbp;
213 size_t nelements;
214 char buf[ELEMENT_SIZE];
215 /* create the pmemblk pool or open it if it already exists */
217 pbp = pmemblk_create(path, ELEMENT_SIZE, POOL_SIZE, 0666);
218 if (pbp == NULL)
220 pbp = pmemblk_open(path, ELEMENT_SIZE);
221 if (pbp == NULL) {
223 perror(path);
224 exit(1);
225 }
226 /* how many elements fit into the file? */
228 nelements = pmemblk_nblock(pbp);
229 printf("file holds %zu elements", nelements);
230 /* store a block at index 5 */
232 strcpy(buf, "hello, world");
233 if (pmemblk_write(pbp, buf, 5) < 0) {
234 perror("pmemblk_write");
235 exit(1);
236 }
237 /* read the block at index 10 (reads as zeros initially) */
239 if (pmemblk_read(pbp, buf, 10) < 0) {
240 perror("pmemblk_read");
241 exit(1);
242 }
243 /* zero out the block at index 5 */
245 if (pmemblk_set_zero(pbp, 5) < 0) {
246 perror("pmemblk_set_zero");
247 exit(1);
248 }
249 /* ... */
251 pmemblk_close(pbp);
253 }
254 See <https://pmem.io/pmdk/libpmemblk> for more examples using the libp‐
256 memblk API.
257
259 Unlike libpmemobj(7), data replication is not supported in libpmemblk.
260 Thus, specifying replica sections in pool set files is not allowed.
261
263 NOTICE: The libpmemblk library is deprecated since PMDK 1.13.0
264 release and will be removed in the PMDK 1.14.0 release.
265
267 libpmemblk builds on the persistent memory programming model recommend‐
268 ed by the SNIA NVM Programming Technical Work Group:
269 <https://snia.org/nvmp>
270
272 msync(2), dlclose(3), pmemblk_bsize(3), pmemblk_create(3), pmem‐
273 blk_ctl_exec(3), pmemblk_ctl_get(3), pmemblk_ctl_set(3), pmem‐
274 blk_read(3), pmemblk_set_zero(3), pmem_is_pmem(3), pmem_persist(3),
275 strerror(3), libpmem(7), libpmemlog(7), libpmemobj(7) and
276 <https://pmem.io>
277PMDK - 2023-06-05 ()