1PMEMLOG_CREATE(3) PMDK Programmer's Manual PMEMLOG_CREATE(3)
2
6 pmemlog_create(), pmemlog_open(), pmemlog_close(), pmemlog_check() -
7 create, open, close and validate persistent memory resident log file
8
10 #include <libpmemlog.h>
11 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
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 Depending on the configuration of the system, the available
37 non-volatile memory space may be divided into multiple memory devices.
38 In such case, the maximum size of the pmemlog memory pool could be lim‐
39 ited by the capacity of a single memory device. libpmemlog(7) allows
40 building persistent memory resident logs spanning multiple memory de‐
41 vices by creation of persistent memory pools consisting of multiple
42 files, where each part of such a pool set may be stored on a different
43 memory device or pmem-aware filesystem.
44 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 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 The set file is a plain text file, the structure of which is described
57 in poolset(5).
58 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 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 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 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
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 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 The pmemlog_close() function returns no value.
95 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
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
111 pmempool(1), creat(2), posix_fallocate(3), pmemlog_nbyte(3),
112 poolset(5), libpmemlog(7) and <https://pmem.io>
113PMDK - pmemlog API version 1.1 2021-09-24 PMEMLOG_CREATE(3)