1() PMDK Programmer's Manual ()
2
6 pmemblk_create()(DEPRECATED), pmemblk_open()(DEPRECATED), pmem‐
7 blk_close()(DEPRECATED), pmemblk_check()(DEPRECATED) - create, open,
8 close and validate block pool
9
11 #include <libpmemblk.h>
12 PMEMblkpool *pmemblk_create(const char *path, size_t bsize,
14 size_t poolsize, mode_t mode);
15 PMEMblkpool *pmemblk_open(const char *path, size_t bsize);
16 void pmemblk_close(PMEMblkpool *pbp);
17 int pmemblk_check(const char *path, size_t bsize);
18
20 The pmemblk_create() function creates a block memory pool with the giv‐
21 en total poolsize, divided into as many elements of size bsize as will
22 fit in the pool. Since the transactional nature of a block memory pool
23 requires some space overhead in the memory pool, the resulting number
24 of available blocks is less than poolsize/bsize, and is made available
25 to the caller via the pmemblk_nblock(3) function. Given the specifics
26 of the implementation, the number of available blocks for the user can‐
27 not be less than 256. This translates to at least 512 internal blocks.
28 path specifies the name of the memory pool file to be created. mode
29 specifies the permissions to use when creating the file, as described
30 by creat(2). The memory pool file is fully allocated to the size pool‐
31 size using posix_fallocate(3). The caller may choose to take responsi‐
32 bility for creating the memory pool file by creating it before calling
33 pmemblk_create(), and then specifying poolsize as zero. In this case
34 pmemblk_create() will take the pool size from the size of the existing
35 file, and will verify that the file appears to be empty by searching
36 for any non-zero data in the pool header at the beginning of the file.
37 The net pool size of a pool file is equal to the file size. The mini‐
38 mum net pool size allowed by the library for a block pool is defined in
39 <libpmemblk.h> as PMEMBLK_MIN_POOL. bsize can be any non-zero value;
40 however, libpmemblk will silently round up the given size to PMEM‐
41 BLK_MIN_BLK, as defined in <libpmemblk.h>.
42 Depending on the configuration of the system, the available non-
44 volatile memory space may be divided into multiple memory devices. In
45 such case, the maximum size of the pmemblk memory pool could be limited
46 by the capacity of a single memory device. libpmemblk(7) allows build‐
47 ing a persistent memory resident array spanning multiple memory devices
48 by creation of persistent memory pools consisting of multiple files,
49 where each part of such a pool set may be stored on a different memory
50 device or pmem-aware filesystem.
51 Creation of all the parts of the pool set can be done with pmemblk_cre‐
53 ate(); however, the recommended method for creating pool sets is by us‐
54 ing the pmempool(1) utility.
55 When creating a pool set consisting of multiple files, the path argu‐
57 ment passed to pmemblk_create() must point to the special set file that
58 defines the pool layout and the location of all the parts of the pool
59 set. The poolsize argument must be 0. The meaning of the mode argu‐
60 ment does not change, except that the same mode is used for creation of
61 all the parts of the pool set.
62 For more information on pool set format, see poolset(5).
64 The pmemblk_open() function opens an existing block memory pool. As
66 with pmemblk_create(), path must identify either an existing block mem‐
67 ory pool file, or the set file used to create a pool set. The applica‐
68 tion must have permission to open the file and memory map the file or
69 pool set with read/write permissions. If bsize is non-zero, pmem‐
70 blk_open() will verify that the given block size matches the block size
71 used when the pool was created. Otherwise, pmemblk_open() will open
72 the pool without verifying the block size. The bsize can be determined
73 using the pmemblk_bsize(3) function.
74 Be aware that if the pool contains bad blocks inside, opening can be
76 aborted by the SIGBUS signal, because currently the pool is not checked
77 against bad blocks during opening. It can be turned on by setting the
78 CHECK_BAD_BLOCKS compat feature. For details see description of this
79 feature in pmempool-feature(1).
80 The pmemblk_close() function closes the memory pool indicated by pbp
82 and deletes the memory pool handle. The block memory pool itself lives
83 on in the file that contains it and may be re-opened at a later time
84 using pmemblk_open() as described above.
85 The pmemblk_check() function performs a consistency check of the file
87 indicated by path, and returns 1 if the memory pool is found to be con‐
88 sistent. If the pool is found not to be consistent, further use of the
89 file with libpmemblk will result in undefined behavior. The debug ver‐
90 sion of libpmemblk will provide additional details on inconsistencies
91 when PMEMBLK_LOG_LEVEL is at least 1, as described in the DEBUGGING AND
92 ERROR HANDLING section in libpmemblk(7). pmemblk_check() opens the
93 given path read-only so it never makes any changes to the file. This
94 function is not supported on Device DAX.
95
97 On success, pmemblk_create() returns a PMEMblkpool* handle to the block
98 memory pool. On error, it returns NULL and sets errno appropriately.
99 On success, pmemblk_open() returns a PMEMblkpool* handle that can be
101 used with most of the functions in libpmemblk(7). On error, it returns
102 NULL and sets errno appropriately. Possible errors include:
103 • failure to open path
105 • path specifies a set file and any of the pool set files cannot be
107 opened
108 • path specifies a set file and the actual size of any file does not
110 match the corresponding part size defined in the set file
111 • bsize is non-zero and does not match the block size given when the
113 pool was created. errno is set to EINVAL in this case.
114 The pmemblk_close() function returns no value.
116 pmemblk_check() returns 1 if the memory pool is found to be consistent.
118 If the check is successfully performed but the pool is found to be in‐
119 consistent, pmemblk_check() returns 0. This includes the case where
120 bsize is non-zero and does not match the block size given when the pool
121 was created. If the consistency check cannot be performed, pmem‐
122 blk_check() returns -1 and sets errno appropriately.
123
125 Not all file systems support posix_fallocate(3). pmemblk_create() will
126 fail if the underlying file system does not support posix_fallocate(3).
127
129 pmempool(1), creat(2), pmemblk_nblock(3), posix_fallocate(3),
130 poolset(5), libpmemblk(7) and <https://pmem.io>
131PMDK - 2023-06-05 ()