NAME

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

SYNOPSIS

              #include <libpmemblk.h>

              PMEMblkpool *pmemblk_create(const char *path, size_t bsize,
                      size_t poolsize, mode_t mode);
              PMEMblkpool *pmemblk_open(const char *path, size_t bsize);
              void pmemblk_close(PMEMblkpool *pbp);
              int pmemblk_check(const char *path, size_t bsize);

DESCRIPTION

       The pmemblk_create() function creates a block memory pool with the given total poolsize, divided into  as
       many  elements  of  size bsize as will fit in the pool.  Since the transactional nature of a block memory
       pool requires some space overhead in the memory pool, the resulting number of available  blocks  is  less
       than  poolsize/bsize,  and is made available to the caller via the pmemblk_nblock(3) function.  Given the
       specifics of the implementation, the number of available blocks for the user cannot  be  less  than  256.
       This  translates  to at least 512 internal blocks.  path specifies the name of the memory pool file to be
       created.  mode specifies the permissions to use when creating the file, as described  by  creat(2).   The
       memory pool file is fully allocated to the size poolsize using posix_fallocate(3).  The caller may choose
       to take responsibility for creating the memory pool file by creating it before calling  pmemblk_create(),
       and  then  specifying  poolsize  as zero.  In this case pmemblk_create() will take the pool size from the
       size of the existing file, and will verify that the file  appears  to  be  empty  by  searching  for  any
       non-zero data in the pool header at the beginning of the file.  The net pool size of a pool file is equal
       to the file size.  The minimum net pool size allowed by the library  for  a  block  pool  is  defined  in
       <libpmemblk.h>  as  PMEMBLK_MIN_POOL.  bsize can be any non-zero value; however, libpmemblk will silently
       round up the given size to PMEMBLK_MIN_BLK, as defined in <libpmemblk.h>.

       Depending on the configuration of the system, the available non-volatile memory space may be divided into
       multiple  memory  devices.  In such case, the maximum size of the pmemblk memory pool could be limited by
       the capacity of a single memory device.  libpmemblk(7) allows building a persistent memory resident array
       spanning  multiple  memory  devices  by creation of persistent memory pools consisting of multiple files,
       where each part of such a pool set may be stored on a different memory device or pmem-aware filesystem.

       Creation of all the parts of the pool set can be done with  pmemblk_create();  however,  the  recommended
       method for creating pool sets is by using the pmempool(1) utility.

       When  creating a pool set consisting of multiple files, the path argument passed to pmemblk_create() must
       point to the special set file that defines the pool layout and the location of all the parts of the  pool
       set.  The poolsize argument must be 0.  The meaning of the mode argument does not change, except that the
       same mode is used for creation of all the parts of the pool set.

       For more information on pool set format, see poolset(5).

       The pmemblk_open() function opens an existing block memory pool.  As  with  pmemblk_create(),  path  must
       identify  either  an  existing  block  memory  pool file, or the set file used to create a pool set.  The
       application must have permission to open the file and memory map the file or  pool  set  with  read/write
       permissions.   If  bsize  is  non-zero,  pmemblk_open() will verify that the given block size matches the
       block size used when the pool  was  created.   Otherwise,  pmemblk_open()  will  open  the  pool  without
       verifying the block size.  The bsize can be determined using the pmemblk_bsize(3) function.

       Be  aware  that  if  the  pool  contains  bad blocks inside, opening can be aborted by the SIGBUS signal,
       because currently the pool is not checked against bad blocks during opening.  It  can  be  turned  on  by
       setting   the  CHECK_BAD_BLOCKS  compat  feature.   For  details  see  description  of  this  feature  in
       pmempool-feature(1).

       The pmemblk_close() function closes the memory pool indicated by pbp and deletes the memory pool  handle.
       The  block  memory pool itself lives on in the file that contains it and may be re-opened at a later time
       using pmemblk_open() as described above.

       The pmemblk_check() function performs a consistency check of the file indicated by path, and returns 1 if
       the memory pool is found to be consistent.  If the pool is found not to be consistent, further use of the
       file with libpmemblk will result in undefined behavior.  The debug version  of  libpmemblk  will  provide
       additional details on inconsistencies when PMEMBLK_LOG_LEVEL is at least 1, as described in the DEBUGGING
       AND ERROR HANDLING section in libpmemblk(7).  pmemblk_check() opens the given path read-only so it  never
       makes any changes to the file.  This function is not supported on Device DAX.

RETURN VALUE

       On  success,  pmemblk_create()  returns  a  PMEMblkpool*  handle  to the block memory pool.  On error, it
       returns NULL and sets errno appropriately.

       On success, pmemblk_open() returns a PMEMblkpool* handle that can be used with most of the  functions  in
       libpmemblk(7).  On error, it returns NULL and sets errno appropriately.  Possible errors include:

       • failure to open path

       • path specifies a set file and any of the pool set files cannot be opened

       • path  specifies  a  set file and the actual size of any file does not match the corresponding part size
         defined in the set file

       • bsize is non-zero and does not match the block size given when the pool was created.  errno is  set  to
         EINVAL in this case.

       The pmemblk_close() function returns no value.

       pmemblk_check()  returns  1  if  the memory pool is found to be consistent.  If the check is successfully
       performed but the pool is found to be inconsistent, pmemblk_check() returns 0.  This  includes  the  case
       where  bsize  is  non-zero  and  does  not  match the block size given when the pool was created.  If the
       consistency check cannot be performed, pmemblk_check() returns -1 and sets errno appropriately.

CAVEATS

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

SEE ALSO

       pmempool(1),    creat(2),    pmemblk_nblock(3),   posix_fallocate(3),   poolset(5),   libpmemblk(7)   and
       <https://pmem.io>