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

DESCRIPTION

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

CAVEATS

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

LIBRARY API VERSIONING

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

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

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

ACKNOWLEDGEMENTS

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