pmemblk_create(3)

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

NAME

6       pmemblk_create(),  pmemblk_open(),  pmemblk_close(),  pmemblk_check() -
7       create, open, close and validate block pool
8

SYNOPSIS

10              #include <libpmemblk.h>
11
12              PMEMblkpool *pmemblk_create(const char *path, size_t bsize,
13                      size_t poolsize, mode_t mode);
14              PMEMblkpool *pmemblk_open(const char *path, size_t bsize);
15              void pmemblk_close(PMEMblkpool *pbp);
16              int pmemblk_check(const char *path, size_t bsize);
17

DESCRIPTION

19       The pmemblk_create() function creates a block memory pool with the giv‐
20       en  total poolsize, divided into as many elements of size bsize as will
21       fit in the pool.  Since the transactional nature of a block memory pool
22       requires  some  space overhead in the memory pool, the resulting number
23       of available blocks is less than poolsize/bsize, and is made  available
24       to  the caller via the pmemblk_nblock(3) function.  Given the specifics
25       of the implementation, the number of available blocks for the user can‐
26       not be less than 256.  This translates to at least 512 internal blocks.
27       path specifies the name of the memory pool file to  be  created.   mode
28       specifies  the  permissions to use when creating the file, as described
29       by creat(2).  The memory pool file is fully allocated to the size pool‐
30       size using posix_fallocate(3).  The caller may choose to take responsi‐
31       bility for creating the memory pool file by creating it before  calling
32       pmemblk_create(),  and  then specifying poolsize as zero.  In this case
33       pmemblk_create() will take the pool size from the size of the  existing
34       file,  and  will  verify that the file appears to be empty by searching
35       for any non-zero data in the pool header at the beginning of the  file.
36       The  net pool size of a pool file is equal to the file size.  The mini‐
37       mum net pool size allowed by the library for a block pool is defined in
38       <libpmemblk.h>  as  PMEMBLK_MIN_POOL.  bsize can be any non-zero value;
39       however, libpmemblk will silently round up  the  given  size  to  PMEM‐
40       BLK_MIN_BLK, as defined in <libpmemblk.h>.
41
42       Depending   on   the   configuration   of  the  system,  the  available
43       non-volatile memory space may be divided into multiple memory  devices.
44       In such case, the maximum size of the pmemblk memory pool could be lim‐
45       ited by the capacity of a single memory device.   libpmemblk(7)  allows
46       building  a  persistent  memory resident array spanning multiple memory
47       devices by creation of persistent memory pools consisting  of  multiple
48       files,  where each part of such a pool set may be stored on a different
49       memory device or pmem-aware filesystem.
50
51       Creation of all the parts of the pool set can be done with pmemblk_cre‐
52       ate(); however, the recommended method for creating pool sets is by us‐
53       ing the pmempool(1) utility.
54
55       When creating a pool set consisting of multiple files, the  path  argu‐
56       ment passed to pmemblk_create() must point to the special set file that
57       defines the pool layout and the location of all the parts of  the  pool
58       set.   The  poolsize argument must be 0.  The meaning of the mode argu‐
59       ment does not change, except that the same mode is used for creation of
60       all the parts of the pool set.
61
62       For more information on pool set format, see poolset(5).
63
64       The  pmemblk_open()  function  opens an existing block memory pool.  As
65       with pmemblk_create(), path must identify either an existing block mem‐
66       ory pool file, or the set file used to create a pool set.  The applica‐
67       tion must have permission to open the file and memory map the  file  or
68       pool  set  with  read/write  permissions.   If bsize is non-zero, pmem‐
69       blk_open() will verify that the given block size matches the block size
70       used  when  the  pool was created.  Otherwise, pmemblk_open() will open
71       the pool without verifying the block size.  The bsize can be determined
72       using the pmemblk_bsize(3) function.
73
74       Be  aware  that  if the pool contains bad blocks inside, opening can be
75       aborted by the SIGBUS signal, because currently the pool is not checked
76       against  bad blocks during opening.  It can be turned on by setting the
77       CHECK_BAD_BLOCKS compat feature.  For details see description  of  this
78       feature in pmempool-feature(1).
79
80       The  pmemblk_close()  function  closes the memory pool indicated by pbp
81       and deletes the memory pool handle.  The block memory pool itself lives
82       on  in  the  file that contains it and may be re-opened at a later time
83       using pmemblk_open() as described above.
84
85       The pmemblk_check() function performs a consistency check of  the  file
86       indicated by path, and returns 1 if the memory pool is found to be con‐
87       sistent.  If the pool is found not to be consistent, further use of the
88       file with libpmemblk will result in undefined behavior.  The debug ver‐
89       sion of libpmemblk will provide additional details  on  inconsistencies
90       when PMEMBLK_LOG_LEVEL is at least 1, as described in the DEBUGGING AND
91       ERROR HANDLING section in  libpmemblk(7).   pmemblk_check()  opens  the
92       given  path  read-only so it never makes any changes to the file.  This
93       function is not supported on Device DAX.
94

RETURN VALUE

96       On success, pmemblk_create() returns a PMEMblkpool* handle to the block
97       memory pool.  On error, it returns NULL and sets errno appropriately.
98
99       On  success,  pmemblk_open()  returns a PMEMblkpool* handle that can be
100       used with most of the functions in libpmemblk(7).  On error, it returns
101       NULL and sets errno appropriately.  Possible errors include:
102
103       · failure to open path
104
105       · path  specifies  a  set  file and any of the pool set files cannot be
106         opened
107
108       · path specifies a set file and the actual size of any  file  does  not
109         match the corresponding part size defined in the set file
110
111       · bsize  is  non-zero  and does not match the block size given when the
112         pool was created.  errno is set to EINVAL in this case.
113
114       The pmemblk_close() function returns no value.
115
116       pmemblk_check() returns 1 if the memory pool is found to be consistent.
117       If  the check is successfully performed but the pool is found to be in‐
118       consistent, pmemblk_check() returns 0.  This includes  the  case  where
119       bsize is non-zero and does not match the block size given when the pool
120       was created.  If the  consistency  check  cannot  be  performed,  pmem‐
121       blk_check() returns -1 and sets errno appropriately.
122

CAVEATS

124       Not all file systems support posix_fallocate(3).  pmemblk_create() will
125       fail if the underlying file system does not support posix_fallocate(3).
126

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAVEATS

SEE ALSO