1LIBPMEMBLK(7)              PMDK Programmer's Manual              LIBPMEMBLK(7)
2
3
4

NAME

6       libpmemblk -- persistent memory resident array of blocks
7

SYNOPSIS

9              #include <libpmemblk.h>
10              cc ... -lpmemblk -lpmem
11
12   Library API versioning:
13              const char *pmemblk_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17   Managing library behavior:
18              void pmemblk_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 *pmemblk_errormsg(void);
26
27   Other library functions:
28       A description of other libpmemblk functions can be found on the follow‐
29       ing manual pages:
30
31       pmemblk_create(3), pmemblk_bsize(3),  pmemblk_read(3),  pmemblk_set_ze‐
32       ro(3)
33

DESCRIPTION

35       libpmemblk provides an array of blocks in persistent memory (pmem) such
36       that updates to a single block are atomic.  This  library  is  intended
37       for  applications  using  direct access storage (DAX), which is storage
38       that supports load/store access without  paging  blocks  from  a  block
39       storage device.  Some types of non-volatile memory DIMMs (NVDIMMs) pro‐
40       vide this type of byte addressable access  to  storage.   A  persistent
41       memory  aware file system is typically used to expose the direct access
42       to applications.  Memory mapping a file from this type of  file  system
43       results in the load/store, non-paged access to pmem.  libpmemblk builds
44       on this type of memory mapped file.
45
46       This library is for applications that need a potentially large array of
47       blocks,  all the same size, where any given block is updated atomically
48       (the update cannot be torn by program interruption such as power  fail‐
49       ures).   This  library builds on the low-level pmem support provided by
50       libpmem(3), handling the transactional update of the  blocks,  flushing
51       to persistence, and recovery for the application.  libpmemblk is one of
52       a collection of persistent memory libraries available, the others are:
53
54       · libpmemobj(7), a general use persistent memory API, providing  memory
55         allocation and transactional operations on variable-sized objects.
56
57       · libpmemlog(7), providing a pmem-resident log file.
58
59       · libpmemcto(7), providing close-to-open persistence.
60
61       · libpmem(7), low-level persistent memory support.
62
63       Under  normal usage, libpmemblk will never print messages or intention‐
64       ally cause the process to exit.  The only exception to this is the  de‐
65       bugging information, when enabled, as described under DEBUGGING AND ER‐
66       ROR HANDLING below.
67
68       To use the atomic block arrays supplied by libpmemblk, a memory pool is
69       first  created  using  the pmemblk_create() function described in pmem‐
70       blk_create(3).  The other libpmemblk functions operate on the resulting
71       block  memory  pool using the opaque handle, of type PMEMblkpool*, that
72       is returned by pmemblk_create() or pmemblk_open().   Internally,  libp‐
73       memblk  will  use  either  pmem_persist(3) or msync(2) when it needs to
74       flush changes, depending on whether the memory pool appears to be  per‐
75       sistent  memory  or a regular file (see the pmem_is_pmem(3) function in
76       libpmem(7) for more information).  There is no need for applications to
77       flush  changes  directly  when  using  the block memory API provided by
78       libpmemblk.
79

CAVEATS

81       libpmemblk relies on the library destructor being called from the  main
82       thread.   For this reason, all functions that might trigger destruction
83       (e.g.  dlclose(3)) should be called in the main thread.  Otherwise some
84       of  the  resources  associated with that thread might not be cleaned up
85       properly.
86

LIBRARY API VERSIONING

88       This section describes how the library API is versioned,  allowing  ap‐
89       plications to work with an evolving API.
90
91       The  pmemblk_check_version()  function is used to determine whether the
92       installed libpmemblk supports the version of the library  API  required
93       by  an  application.  The easiest way to do this is for the application
94       to supply the compile-time version information, supplied by defines  in
95       <ibpmemblk.h>, like this:
96
97              reason = pmemblk_check_version(PMEMBLK_MAJOR_VERSION,
98                                             PMEMBLK_MINOR_VERSION);
99              if (reason != NULL) {
100                  /* version check failed, reason string tells you why */
101              }
102
103       Any mismatch in the major version number is considered a failure, but a
104       library with a newer minor version number will pass  this  check  since
105       increasing minor versions imply backwards compatibility.
106
107       An  application can also check specifically for the existence of an in‐
108       terface by checking for the version where  that  interface  was  intro‐
109       duced.   These versions are documented in this man page as follows: un‐
110       less otherwise specified, all interfaces described here  are  available
111       in version 1.0 of the library.  Interfaces added after version 1.0 will
112       contain the text introduced in version x.y in the section of this manu‐
113       al describing the feature.
114
115       When the version check performed by pmemblk_check_version() is success‐
116       ful, the return value is NULL.  Otherwise the return value is a  static
117       string describing the reason for failing the version check.  The string
118       returned by pmemblk_check_version() must not be modified or freed.
119

MANAGING LIBRARY BEHAVIOR

121       The pmemblk_set_funcs() function allows an application to override mem‐
122       ory  allocation  calls  used internally by libpmemblk.  Passing in NULL
123       for any of the handlers will cause the libpmemblk default  function  to
124       be  used.   The  library  does  not make heavy use of the system malloc
125       functions, but it does allocate approximately 4-8  kilobytes  for  each
126       memory pool in use.
127

DEBUGGING AND ERROR HANDLING

129       The  pmemblk_errormsg()  function  returns a pointer to a static buffer
130       containing the last error message logged for the  current  thread.   If
131       errno  was set, the error message may include a description of the cor‐
132       responding error code, as returned by strerror(3).  The  error  message
133       buffer  is thread-local; errors encountered in one thread do not affect
134       its value in other threads.  The buffer is never cleared by any library
135       function;  its content is significant only when the return value of the
136       immediately preceding call to a libpmemblk function indicated an error,
137       or if errno was set.  The application must not modify or free the error
138       message string, but it may be modified by subsequent calls to other li‐
139       brary functions.
140
141       Two  versions  of  libpmemblk  are typically available on a development
142       system.  The normal version, accessed when a program  is  linked  using
143       the -lpmemblk option, is optimized for performance.  That version skips
144       checks that impact performance and never logs any trace information  or
145       performs any run-time assertions.  If an error is detected in a call to
146       libpmemblk, the error message describing the failure may  be  retrieved
147       with pmemblk_errormsg() as described above.
148
149       A  second  version  of libpmemblk, accessed when a program uses the li‐
150       braries under /usr/lib/pmdk_debug,  contains  run-time  assertions  and
151       trace  points.   The  typical way to access the debug version is to set
152       the LD_LIBRARY_PATH  environment  variable  to  /usr/lib/pmdk_debug  or
153       /usr/lib64/pmdk_debug,  as appropriate.  Debugging output is controlled
154       using the following environment variables.  These variables have no ef‐
155       fect on the non-debug version of the library.
156
157       · PMEMBLK_LOG_LEVEL
158
159       The  value  of PMEMBLK_LOG_LEVEL enables trace points in the debug ver‐
160       sion of the library, as follows:
161
162       · 0 - This is the default level when PMEMBLK_LOG_LEVEL is not set.   No
163         log messages are emitted at this level.
164
165       · 1 - Additional details on any errors detected are logged, in addition
166         to returning the errno-based errors as usual.  The  same  information
167         may be retrieved using pmemblk_errormsg().
168
169       · 2 - A trace of basic operations is logged.
170
171       · 3 - Enables a very verbose amount of function call tracing in the li‐
172         brary.
173
174       · 4 - Enables voluminous and fairly obscure tracing information that is
175         likely only useful to the libpmemblk developers.
176
177       Unless PMEMBLK_LOG_FILE is set, debugging output is written to stderr.
178
179       · PMEMBLK_LOG_FILE
180
181       Specifies  the  name  of a file where all logging information should be
182       written.  If the last character in the name is "-", the PID of the cur‐
183       rent  process  will  be  appended to the file name when the log file is
184       created.  If PMEMBLK_LOG_FILE is not set, the logging output is written
185       to stderr.
186
187       See also libpmem(7) for information on other environment variables that
188       may affect libpmemblk behavior.
189

EXAMPLE

191       The following example illustrates how the libpmemblk API is used.
192
193              #include <fcntl.h>
194              #include <errno.h>
195              #include <stdlib.h>
196              #include <unistd.h>
197              #include <string.h>
198              #include <libpmemblk.h>
199
200              /* size of the pmemblk pool -- 1 GB */
201              #define POOL_SIZE ((size_t)(1 << 30))
202
203              /* size of each element in the pmem pool */
204              #define ELEMENT_SIZE 1024
205
206              int
207              main(int argc, char *argv[])
208              {
209                  const char path[] = "/pmem-fs/myfile";
210                  PMEMblkpool *pbp;
211                  size_t nelements;
212                  char buf[ELEMENT_SIZE];
213
214                  /* create the pmemblk pool or open it if it already exists */
215                  pbp = pmemblk_create(path, ELEMENT_SIZE, POOL_SIZE, 0666);
216
217                  if (pbp == NULL)
218                      pbp = pmemblk_open(path, ELEMENT_SIZE);
219
220                  if (pbp == NULL) {
221                      perror(path);
222                      exit(1);
223                  }
224
225                  /* how many elements fit into the file? */
226                  nelements = pmemblk_nblock(pbp);
227                  printf("file holds %zu elements", nelements);
228
229                  /* store a block at index 5 */
230                  strcpy(buf, "hello, world");
231                  if (pmemblk_write(pbp, buf, 5) < 0) {
232                      perror("pmemblk_write");
233                      exit(1);
234                  }
235
236                  /* read the block at index 10 (reads as zeros initially) */
237                  if (pmemblk_read(pbp, buf, 10) < 0) {
238                      perror("pmemblk_read");
239                      exit(1);
240                  }
241
242                  /* zero out the block at index 5 */
243                  if (pmemblk_set_zero(pbp, 5) < 0) {
244                      perror("pmemblk_set_zero");
245                      exit(1);
246                  }
247
248                  /* ... */
249
250                  pmemblk_close(pbp);
251              }
252
253       See <http://pmem.io/pmdk/libpmemblk> for more examples using the  libp‐
254       memblk API.
255

BUGS

257       Unlike  libpmemobj(7), data replication is not supported in libpmemblk.
258       Thus, specifying replica sections in pool set files is not allowed.
259

ACKNOWLEDGEMENTS

261       libpmemblk builds on the persistent memory programming model recommend‐
262       ed    by    the    SNIA   NVM   Programming   Technical   Work   Group:
263       <http://snia.org/nvmp>
264

SEE ALSO

266       msync(2),  dlclose(3),   pmemblk_bsize(3),   pmemblk_create(3),   pmem‐
267       blk_read(3),   pmemblk_set_zero(3),  pmem_is_pmem(3),  pmem_persist(3),
268       strerror(3), libpmem(7),  libpmemcto(7),  libpmemlog(7),  libpmemobj(7)
269       and <http://pmem.io>
270
271
272
273PMDK - pmemblk API version 1.1    2018-03-13                     LIBPMEMBLK(7)
Impressum