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

NAME

6       libpmemlog - persistent memory resident log file (DEPRECATED)
7
8              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

SYNOPSIS

12              #include <libpmemlog.h>
13              cc ... -lpmemlog -lpmem
14
15   Library API versioning:
16              const char *pmemlog_check_version(
17                  unsigned major_required,
18                  unsigned minor_required);
19
20   Managing library behavior:
21              void pmemlog_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
27   Error handling:
28              int pmemlog_check(const char *path);
29
30   Other library functions:
31       A description of other libpmemlog functions can be found on the follow‐
32       ing manual pages:
33
34       pmemlog_append(3),    pmemlog_create(3),   pmemlog_ctl_exec(3),   pmem‐
35       log_ctl_get(3), pmemlog_ctl_set(3), pmemlog_nbyte(3), pmemlog_tell(3)
36

DESCRIPTION

38       libpmemlog provides a log file in persistent memory  (pmem)  such  that
39       additions to the log are appended atomically.  This library is intended
40       for applications using direct access storage (DAX),  which  is  storage
41       that  supports  load/store  access  without  paging blocks from a block
42       storage device.  Some types of non-volatile memory DIMMs (NVDIMMs) pro‐
43       vide  this  type  of  byte addressable access to storage.  A persistent
44       memory aware file system is typically used to expose the direct  access
45       to  applications.   Memory mapping a file from this type of file system
46       results in the load/store, non-paged access to pmem.  libpmemlog builds
47       on thistype of memory mapped file.
48
49       This library is for applications that need a persistent log file updat‐
50       ed atomically (the updates cannot be torn by program interruption  such
51       as  power failures).  This library builds on the low-level pmem support
52       provided by libpmem(7), handling the transactional update of  the  log,
53       flushing to persistence, and recovery for the application.
54
55       libpmemlog is one of a collection of persistent memory libraries avail‐
56       able.  The others are:
57
58libpmemobj(7), a general use persistent memory API, providing  memory
59         allocation and transactional operations on variable-sized objects.
60
61libpmemblk(7),  providing  pmem-resident arrays of fixed-sized blocks
62         with atomic updates.
63
64libpmem(7), low-level persistent memory support.
65
66       Under normal usage, libpmemlog will never print messages or  intention‐
67       ally  cause the process to exit.  The only exception to this is the de‐
68       bugging information, when enabled, as described under DEBUGGING AND ER‐
69       ROR HANDLING below.
70
71       To use the pmem-resident log file provided by libpmemlog, a memory pool
72       is first created.  This is done with  the  pmemlog_create(3)  function.
73       The other functions mentioned above in SYNOPSIS section then operate on
74       the resulting log memory pool.
75
76       Once created, the memory pool is represented by an  opaque  handle,  of
77       type  PMEMlogpool*, which is passed to most of the other functions from
78       libpmemlog.  Internally, libpmemlog will use either pmem_persist(3)  or
79       msync(2) when it needs to flush changes, depending on whether the memo‐
80       ry pool appears to be persistent memory or  a  regular  file  (see  the
81       pmem_is_pmem(3) function in libpmem(7) for more information).  There is
82       no need for applications to flush changes directly when using  the  log
83       memory API provided by libpmemlog.
84

CAVEATS

86       libpmemlog  relies on the library destructor being called from the main
87       thread.  For this reason, all functions that might trigger  destruction
88       (e.g.  dlclose(3)) should be called in the main thread.  Otherwise some
89       of the resources associated with that thread might not  be  cleaned  up
90       properly.
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 pmemlog_check_version() function is used to determine  whether  the
97       installed  libpmemlog  supports the version of the library API required
98       by an application.  The easiest way to do this is for  the  application
99       to  supply  the compile-time version information provided by defines in
100       <libpmemlog.h>, like this:
101
102              reason = pmemlog_check_version(PMEMLOG_MAJOR_VERSION,
103                                             PMEMLOG_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, pmemlog_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  pmemlog_check_version()  must  not  be
123       modified or freed.
124

MANAGING LIBRARY BEHAVIOR

126       The pmemlog_set_funcs() function allows an application to override mem‐
127       ory allocation calls used internally by libpmemlog.   Passing  in  NULL
128       for  any  of the handlers will cause the libpmemlog 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

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

194       The following example illustrates how the libpmemlog API is used.
195
196              #include <stdio.h>
197              #include <fcntl.h>
198              #include <errno.h>
199              #include <stdlib.h>
200              #include <unistd.h>
201              #include <string.h>
202              #include <libpmemlog.h>
203
204              /* size of the pmemlog pool -- 1 GB */
205              #define POOL_SIZE ((size_t)(1 << 30))
206
207              /*
208               * printit -- log processing callback for use with pmemlog_walk()
209               */
210              int
211              printit(const void *buf, size_t len, void *arg)
212              {
213                  fwrite(buf, len, 1, stdout);
214                  return 0;
215              }
216
217              int
218              main(int argc, char *argv[])
219              {
220                  const char path[] = "/pmem-fs/myfile";
221                  PMEMlogpool *plp;
222                  size_t nbyte;
223                  char *str;
224
225                  /* create the pmemlog pool or open it if it already exists */
226                  plp = pmemlog_create(path, POOL_SIZE, 0666);
227
228                  if (plp == NULL)
229                      plp = pmemlog_open(path);
230
231                  if (plp == NULL) {
232                      perror(path);
233                      exit(1);
234                  }
235
236                  /* how many bytes does the log hold? */
237                  nbyte = pmemlog_nbyte(plp);
238                  printf("log holds %zu bytes", nbyte);
239
240                  /* append to the log... */
241                  str = "This is the first string appended";
242                  if (pmemlog_append(plp, str, strlen(str)) < 0) {
243                      perror("pmemlog_append");
244                      exit(1);
245                  }
246                  str = "This is the second string appended";
247                  if (pmemlog_append(plp, str, strlen(str)) < 0) {
248                      perror("pmemlog_append");
249                      exit(1);
250                  }
251
252                  /* print the log contents */
253                  printf("log contains:");
254                  pmemlog_walk(plp, 0, printit, NULL);
255
256                  pmemlog_close(plp);
257              }
258
259       See <https://pmem.io/pmdk/libpmemlog> for more examples using the libp‐
260       memlog API.
261

BUGS

263       Unlike libpmemobj(7), data replication is not supported in  libpmemlog.
264       Thus, specifying replica sections in pool set files is not allowed.
265

NOTE

267              NOTICE:  The  libpmemlog library is deprecated since PMDK 1.13.0
268              release and will be removed in the PMDK 1.14.0 release.
269

ACKNOWLEDGEMENTS

271       libpmemlog builds on the persistent memory programming model recommend‐
272       ed    by    the    SNIA   NVM   Programming   Technical   Work   Group:
273       <https://snia.org/nvmp>
274

SEE ALSO

276       msync(2),  pmemlog_append(3),  pmemlog_create(3),  pmemlog_ctl_exec(3),
277       pmemlog_ctl_get(3),    pmemlog_ctl_set(3),    pmemlog_nbyte(3),   pmem‐
278       log_tell(3), strerror(3), libpmem(7), libpmemblk(7), libpmemobj(7)  and
279       <https://pmem.io>
280
281
282
283PMDK -                            2023-06-05                                ()
Impressum