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

NAME

6       pmemlog_create(),  pmemlog_open(),  pmemlog_close(),  pmemlog_check() -
7       create, open, close and validate persistent memory resident log file
8

SYNOPSIS

10              #include <libpmemlog.h>
11
12              PMEMlogpool *pmemlog_open(const char *path);
13              PMEMlogpool *pmemlog_create(const char *path, size_t poolsize, mode_t mode);
14              void pmemlog_close(PMEMlogpool *plp);
15              int pmemlog_check(const char *path);
16

DESCRIPTION

18       The pmemlog_create() function creates a log memory pool with the  given
19       total  poolsize.   Since  the transactional nature of a log memory pool
20       requires some space overhead in the memory pool, the  resulting  avail‐
21       able log size is less than poolsize, and is made available to the call‐
22       er via the pmemlog_nbyte(3) function.  path specifies the name  of  the
23       memory  pool file to be created.  mode specifies the permissions to use
24       when creating the file as described by creat(2).  The memory pool  file
25       is  fully allocated to the size poolsize using posix_fallocate(3).  The
26       caller may choose to take responsibility for creating the  memory  pool
27       file by creating it before calling pmemlog_create() and then specifying
28       poolsize as zero.  In this case pmemlog_create()  will  take  the  pool
29       size  from  the size of the existing file and will verify that the file
30       appears to be empty by searching for any  non-zero  data  in  the  pool
31       header  at the beginning of the file.  The net pool size of a pool file
32       is equal to the file size.  The minimum net pool size  allowed  by  the
33       library   for  a  log  pool  is  defined  in  <libpmemlog.h>  as  PMEM‐
34       LOG_MIN_POOL.
35
36       Depending on the  configuration  of  the  system,  the  available  non-
37       volatile  memory space may be divided into multiple memory devices.  In
38       such case, the maximum size of the pmemlog memory pool could be limited
39       by the capacity of a single memory device.  libpmemlog(7) allows build‐
40       ing persistent memory resident logs spanning multiple memory devices by
41       creation of persistent memory pools consisting of multiple files, where
42       each part of such a pool set may be stored on a different memory device
43       or pmem-aware filesystem.
44
45       Creation of all the parts of the pool set can be done with pmemlog_cre‐
46       ate(); however, the recommended method for creating pool sets  is  with
47       the pmempool(1) utility.
48
49       When  creating  a pool set consisting of multiple files, the path argu‐
50       ment passed to pmemlog_create() must point to the special set file that
51       defines  the  pool layout and the location of all the parts of the pool
52       set.  The poolsize argument must be 0.  The meaning of the  mode  argu‐
53       ment does not change, except that the same mode is used for creation of
54       all the parts of the pool set.
55
56       The set file is a plain text file, the structure of which is  described
57       in poolset(5).
58
59       The pmemlog_open() function opens an existing log memory pool.  Similar
60       to pmemlog_create(), path must identify either an existing  log  memory
61       pool  file, or the set file used to create a pool set.  The application
62       must have permission to open the file and memory map the file  or  pool
63       set with read/write permissions.
64
65       Be  aware  that  if the pool contains bad blocks inside, opening can be
66       aborted by the SIGBUS signal, because currently the pool is not checked
67       against  bad blocks during opening.  It can be turned on by setting the
68       CHECK_BAD_BLOCKS compat feature.  For details see description  of  this
69       feature in pmempool-feature(1).
70
71       The  pmemlog_close()  function  closes the memory pool indicated by plp
72       and deletes the memory pool handle.  The log memory pool  itself  lives
73       on  in  the  file that contains it and may be re-opened at a later time
74       using pmemlog_open() as described above.
75
76       The pmemlog_check() function performs a consistency check of  the  file
77       indicated  by  path.  pmemlog_check() opens the given path read-only so
78       it never makes any changes to the file.  This function is not supported
79       on Device DAX.
80

RETURN VALUE

82       On success, pmemlog_create() returns a PMEMlogpool* handle to the memo‐
83       ry pool that is used with most of the functions from libpmemlog(7).  If
84       an  error prevents any of the pool set files from being created, it re‐
85       turns NULL and sets errno appropriately.
86
87       On success, pmemlog_open() returns a PMEMlogpool* handle to the  memory
88       pool that is used with most of the functions from libpmemlog(7).  If an
89       error prevents the pool from being opened,  or  a  pool  set  is  being
90       opened and the actual size of any file does not match the corresponding
91       part size defined in the set file, pmemlog_open() returns NULL and sets
92       errno appropriately.
93
94       The pmemlog_close() function returns no value.
95
96       The  pmemlog_check()  function returns 1 if the persistent memory resi‐
97       dent log file is found to  be  consistent.   Any  inconsistencies  will
98       cause  pmemlog_check()  to  return 0, in which case the use of the file
99       with libpmemlog will result in undefined behavior.  The  debug  version
100       of  libpmemlog  will provide additional details on inconsistencies when
101       PMEMLOG_LOG_LEVEL is at least 1, as described in the DEBUGGING AND  ER‐
102       ROR  HANDLING section in libpmemlog(7).  pmemlog_check() will return -1
103       and set errno if it cannot perform the consistency check due  to  other
104       errors.
105

CAVEATS

107       Not all file systems support posix_fallocate(3).  pmemlog_create() will
108       fail if the underlying file system does not support posix_fallocate(3).
109

SEE ALSO

111       pmempool(1),    creat(2),     posix_fallocate(3),     pmemlog_nbyte(3),
112       poolset(5), libpmemlog(7) and <https://pmem.io>
113
114
115
116PMDK - pmemlog API version 1.1    2021-07-22                 PMEMLOG_CREATE(3)
Impressum