libpmempool(7)

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

NAME

6       libpmempool - persistent memory pool management library
7

SYNOPSIS

9              #include <libpmempool.h>
10              cc -std=gnu99 ... -lpmempool -lpmem
11
12   Library API versioning:
13              const char *pmempool_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17   Error handling:
18              const char *pmempool_errormsg(void);
19
20   Other library functions:
21       A  description  of other libpmempool functions can be found on the fol‐
22       lowing manual pages:
23
24       • health check functions: pmempool_check_init(3)
25
26       • pool set synchronization and transformation: pmempool_sync(3)
27
28       • pool set management functions: pmempool_rm(3)
29
30       • toggle or query pool set features: pmempool_feature_query(3)
31

DESCRIPTION

33       libpmempool provides a set of utilities for off-line analysis  and  ma‐
34       nipulation  of  a  pool.   A pool in this manpage means a pmemobj pool,
35       pmemblk pool, pmemlog pool or BTT layout, independent of the underlying
36       storage.   Some  libpmempool functions are required to work without any
37       impact on the pool but some may create a  new  or  modify  an  existing
38       pool.
39
40       libpmempool  is for applications that need high reliability or built-in
41       troubleshooting.  It may be useful for testing and  debugging  purposes
42       also.
43
44       libpmempool introduces functionality of pool set health check, synchro‐
45       nization, transformation and removal.
46

CAVEATS

48       libpmempool relies on the library destructor being called from the main
49       thread.   For this reason, all functions that might trigger destruction
50       (e.g.  dlclose(3)) should be called in the main thread.  Otherwise some
51       of  the  resources  associated with that thread might not be cleaned up
52       properly.
53
54       libpmempool requires the -std=gnu99 compilation flag to build properly.
55

LIBRARY API VERSIONING

57       This section describes how the library API is versioned,  allowing  ap‐
58       plications to work with an evolving API.
59
60       The  pmempool_check_version()  function is used to see if the installed
61       libpmempool supports the version of the library API required by an  ap‐
62       plication.  The easiest way to do this for the application is to supply
63       the compile-time version information, supplied by defines in  <libpmem‐
64       pool.h>, like this:
65
66              reason = pmempool_check_version(PMEMPOOL_MAJOR_VERSION,
67                                              PMEMPOOL_MINOR_VERSION);
68              if (reason != NULL) {
69                  /* version check failed, reason string tells you why */
70              }
71
72       Any mismatch in the major version number is considered a failure, but a
73       library with a newer minor version number will pass  this  check  since
74       increasing minor versions imply backwards compatibility.
75
76       An  application can also check specifically for the existence of an in‐
77       terface by checking for the version where  that  interface  was  intro‐
78       duced.   These versions are documented in this man page as follows: un‐
79       less otherwise specified, all interfaces described here  are  available
80       in version 1.0 of the library.  Interfaces added after version 1.0 will
81       contain the text introduced in version x.y in the section of this manu‐
82       al describing the feature.
83
84       When  the  version  check performed by pmempool_check_version() is suc‐
85       cessful, the return value is NULL.  Otherwise the  return  value  is  a
86       static string describing the reason for failing the version check.  The
87       string returned by pmempool_check_version() must  not  be  modified  or
88       freed.
89

DEBUGGING AND ERROR HANDLING

91       If  an error is detected during the call to a libpmempool function, the
92       application may retrieve an error message describing the reason for the
93       failure from pmempool_errormsg().  This function returns a pointer to a
94       static buffer containing the last error message logged for the  current
95       thread.   If errno was set, the error message may include a description
96       of the corresponding error code as returned by strerror(3).  The  error
97       message buffer is thread-local; errors encountered in one thread do not
98       affect its value in other threads.  The buffer is never cleared by  any
99       library function; its content is significant only when the return value
100       of the immediately preceding call to a libpmempool  function  indicated
101       an error, or if errno was set.  The application must not modify or free
102       the error message string, but it may be modified by subsequent calls to
103       other library functions.
104
105       Two  versions  of  libpmempool are typically available on a development
106       system.  The normal version, accessed when a program  is  linked  using
107       the  -lpmempool  option,  is  optimized  for performance.  That version
108       skips checks that impact performance and never logs any trace  informa‐
109       tion or performs any run-time assertions.
110
111       A  second  version of libpmempool, accessed when a program uses the li‐
112       braries under /usr/lib/pmdk_debug,  contains  run-time  assertions  and
113       trace  points.   The  typical way to access the debug version is to set
114       the environment  variable  LD_LIBRARY_PATH  to  /usr/lib/pmdk_debug  or
115       /usr/lib64/pmdk_debug,  as appropriate.  Debugging output is controlled
116       using the following environment variables.  These variables have no ef‐
117       fect on the non-debug version of the library.
118
119       • PMEMPOOL_LOG_LEVEL
120
121       The  value of PMEMPOOL_LOG_LEVEL enables trace points in the debug ver‐
122       sion of the library, as follows:
123
124       • 0 - This is the default level when PMEMPOOL_LOG_LEVEL is not set.  No
125         log messages are emitted at this level.
126
127       • 1 - Additional details on any errors detected are logged (in addition
128         to returning the errno-based errors as usual).  The same  information
129         may be retrieved using pmempool_errormsg().
130
131       • 2 - A trace of basic operations is logged.
132
133       • 3 - Enables a very verbose amount of function call tracing in the li‐
134         brary.
135
136       • 4 - Enables voluminous and fairly obscure tracing information that is
137         likely only useful to the libpmempool developers.
138
139       Unless PMEMPOOL_LOG_FILE is set, debugging output is written to stderr.
140
141       • PMEMPOOL_LOG_FILE
142
143       Specifies  the  name  of a file where all logging information should be
144       written.  If the last character in the name is “-”, the PID of the cur‐
145       rent  process  will  be  appended to the file name when the log file is
146       created.  If PMEMPOOL_LOG_FILE is not set, output is written to stderr.
147

EXAMPLE

149       The following example illustrates how the libpmempool API is used.  The
150       program  detects  the  type  and  checks consistency of given pool.  If
151       there are any issues detected, the pool is automatically repaired.
152
153              #include <stddef.h>
154              #include <unistd.h>
155              #include <stdlib.h>
156              #include <stdio.h>
157              #include <libpmempool.h>
158
159              #define PATH "./pmem-fs/myfile"
160              #define CHECK_FLAGS (PMEMPOOL_CHECK_FORMAT_STR|PMEMPOOL_CHECK_REPAIR|\
161                                   PMEMPOOL_CHECK_VERBOSE)
162
163              int
164              main(int argc, char *argv[])
165              {
166                  PMEMpoolcheck *ppc;
167                  struct pmempool_check_status *status;
168                  enum pmempool_check_result ret;
169
170                  /* arguments for check */
171                  struct pmempool_check_args args = {
172                      .path       = PATH,
173                      .backup_path    = NULL,
174                      .pool_type  = PMEMPOOL_POOL_TYPE_DETECT,
175                      .flags      = CHECK_FLAGS
176                  };
177
178                  /* initialize check context */
179                  if ((ppc = pmempool_check_init(&args, sizeof(args))) == NULL) {
180                      perror("pmempool_check_init");
181                      exit(EXIT_FAILURE);
182                  }
183
184                  /* perform check and repair, answer 'yes' for each question */
185                  while ((status = pmempool_check(ppc)) != NULL) {
186                      switch (status->type) {
187                      case PMEMPOOL_CHECK_MSG_TYPE_ERROR:
188                          printf("%s\n", status->str.msg);
189                          break;
190                      case PMEMPOOL_CHECK_MSG_TYPE_INFO:
191                          printf("%s\n", status->str.msg);
192                          break;
193                      case PMEMPOOL_CHECK_MSG_TYPE_QUESTION:
194                          printf("%s\n", status->str.msg);
195                          status->str.answer = "yes";
196                          break;
197                      default:
198                          pmempool_check_end(ppc);
199                          exit(EXIT_FAILURE);
200                      }
201                  }
202
203                  /* finalize the check and get the result */
204                  ret = pmempool_check_end(ppc);
205                  switch (ret) {
206                      case PMEMPOOL_CHECK_RESULT_CONSISTENT:
207                      case PMEMPOOL_CHECK_RESULT_REPAIRED:
208                          return 0;
209                      default:
210                          return 1;
211                  }
212              }
213
214       See <https://pmem.io/pmdk/libpmempool>  for  more  examples  using  the
215       libpmempool API.
216

ACKNOWLEDGEMENTS

218       libpmempool  builds  on  the persistent memory programming model recom‐
219       mended  by   the   SNIA   NVM   Programming   Technical   Work   Group:
220       <https://snia.org/nvmp>
221