pmemobj_check_version(3)

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

NAME

6       libpmemobj -- persistent memory transactional object store
7

SYNOPSIS

9              #include <libpmemobj.h>
10              cc -std=gnu99 ... -lpmemobj -lpmem
11
12   Library API versioning:
13              const char *pmemobj_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17   Managing library behavior:
18              void pmemobj_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 *pmemobj_errormsg(void);
26
27   Other library functions:
28       A description of other libpmemobj functions can be found on the follow‐
29       ing manual pages:
30
31       · create, open, close and validate: pmemobj_open(3)
32
33       · low-level memory manipulation: pmemobj_memcpy_persist(3)
34
35       · locking: pmemobj_mutex_zero(3)
36
37       · persistent object identifier: OID_IS_NULL(3)
38
39       · type-safety: TOID_DECLARE(3)
40
41       · layout declaration: POBJ_LAYOUT_BEGIN(3)
42
43       · non-transactional atomic allocations: pmemobj_alloc(3)
44
45       · root object management: pmemobj_root(3)
46
47       · object containers: pmemobj_first(3)
48
49       · non-transactional  persistent  atomic  circular  doubly-linked  list:
50         pmemobj_list_insert(3), POBJ_LIST_HEAD(3)
51
52       · transactional   object   manipulation:   pmemobj_tx_begin(3),  pmemo‐
53         bj_tx_add_range(3), pmemobj_tx_alloc(3)
54
55       · control and statistics: pmemobj_ctl_get(3)
56
57       · delayed atomicity actions: pmemobj_action(3)
58

DESCRIPTION

60       libpmemobj provides a transactional object store in  persistent  memory
61       (pmem) for applications that require transactions and persistent memory
62       management using direct access storage (DAX),  which  is  storage  that
63       supports  load/store  access without paging blocks from a block storage
64       device.  Some types of non-volatile memory DIMMs (NVDIMMs) provide this
65       type  of byte addressable access to storage.  A persistent memory aware
66       file system is typically used to expose the direct access  to  applica‐
67       tions.   Memory mapping a file from this type of file system results in
68       load/store, non-paged access to pmem.  libpmemobj builds on  this  type
69       of  memory  mapped  file  using  the low-level pmem support provided by
70       libpmem(7), handling the transactional  updates,  flushing  changes  to
71       persistence, and managing recovery for the application.
72
73       libpmemobj requires the -std=gnu99 compilation flag to build properly.
74
75       libpmemobj is one of a collection of persistent memory libraries avail‐
76       able.  The others are:
77
78       · libpmemblk(7), providing pmem-resident arrays of  fixed-sized  blocks
79         with atomic updates.
80
81       · libpmemlog(7), providing a pmem-resident log file.
82
83       · libpmemcto(7), providing close-to-open persistence.
84
85       · libpmem(7), low-level persistent memory support.
86
87       Under  normal usage, libpmemobj will never print messages or intention‐
88       ally cause the process to exit.  The only exception to this is the  de‐
89       bugging information, when enabled, as described under DEBUGGING AND ER‐
90       ROR HANDLING, below.
91

LIBRARY API VERSIONING

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

MANAGING LIBRARY BEHAVIOR

126       The pmemobj_set_funcs() function allows an application to override mem‐
127       ory  allocation  calls  used internally by libpmemobj.  Passing in NULL
128       for any of the handlers will cause the libpmemobj default  function  to
129       be  used.   The  library  does  not make heavy use of the system malloc
130       functions, but it does allocate approximately 4-8  kilobytes  for  each
131       memory pool in use.
132
133       By  default, libpmemobj supports up to 1024 parallel transactions/allo‐
134       cations.  For debugging purposes it is possible to decrease this  value
135       by  setting the PMEMOBJ_NLANES environment variable to the desired lim‐
136       it.
137

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

201       See  <http://pmem.io/pmdk/libpmemobj> for examples using the libpmemobj
202       API.
203

ACKNOWLEDGEMENTS

205       libpmemobj builds on the persistent memory programming model recommend‐
206       ed    by    the    SNIA   NVM   Programming   Technical   Work   Group:
207       <http://snia.org/nvmp>
208