NAME

       pmemcto_create(),  pmemcto_open(),  pmemcto_close(),  pmemcto_check()  - create, open, close and validate
       close-to-open persistence pool

SYNOPSIS

              #include <libpmemcto.h>

              PMEMctopool *pmemcto_create(const char *path, const char *layout,
                      size_t poolsize, mode_t mode);
              PMEMctopool *pmemcto_open(const char *path, const char *layout);
              void pmemcto_close(PMEMctopool *pcp);
              int pmemcto_check(const char *path, const char *layout);

DESCRIPTION

       The pmemcto_create() function creates a close-to-open persistence pool with  the  given  total  poolsize.
       The  resulting pool is then used with functions like pmemcto_malloc(3) and pmemcto_free(3) to provide the
       familiar malloc-like programming model for the memory pool.  path specifies the name of the  memory  pool
       file  to be created.  layout specifies the application's layout type in the form of a string.  The layout
       name is not interpreted by libpmemcto(7), but may be used as a check when pmemcto_open() is called.   The
       layout  name, including the terminating null byte (`\0'), cannot be longer than PMEMCTO_MAX_LAYOUT as de‐
       fined in <libpmemcto.h>.  A NULL layout is equivalent to using an empty string as a  layout  name.   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  respon‐
       sibility for creating the memory pool file by creating it before calling pmemcto_create(), and then spec‐
       ifying  poolsize as zero.  In this case pmemcto_create() will take the pool size from the size of the ex‐
       isting 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 minimum net pool size allowed by the library for a local
       close-to-open persistence pool is defined in <libpmemcto.h> as PMEMCTO_MIN_POOL.

       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 pmemcto memory pool could be  limited  by
       the  capacity  of a single memory device.  libpmemcto(7) allows building a close-to-open persistence pool
       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 pmemcto_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 pmemcto_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 layout and mode arguments does not change, ex‐
       cept 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 pmemcto_open() function opens an existing close-to-open persistence memory pool.  path must be an ex‐
       isting file containing a pmemcto memory pool as created by pmemcto_create().  If layout is  non-NULL,  it
       is compared to the layout name provided to pmemcto_create() when the pool was first created.  This can be
       used  to verify that the layout of the pool matches what was expected.  The application must have permis‐
       sion to open the file and memory map it with read/write permissions.

       The pmemcto_close() function closes the memory pool indicated by pcp and deletes the memory pool  handle.
       The close-to-open memory pool itself lives on in the file that contains it and may be re-opened at a lat‐
       er  time  using pmemcto_open() as described above.  If the pool was not closed gracefully due to abnormal
       program termination or power failure, the pool is in an inconsistent state causing subsequent pool  open‐
       ing to fail.

       The pmemcto_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 libpmemcto(7) will result in undefined behavior.  The debug version of libpmemcto(7) will pro‐
       vide additional details on inconsistencies when PMEMCTO_LOG_LEVEL is at least 1, as described in the  DE‐
       BUGGING  AND ERROR HANDLING section of libpmemcto(7).  pmemcto_check() will return -1 and set errno if it
       cannot perform the consistency check due to other errors.  pmemcto_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, pmemcto_create() returns a PMEMctopool* handle to the close-to-open persistence memory  pool.
       On error, it returns NULL and sets errno appropriately.

       On  success,  pmemcto_open() returns a PMEMctopool* handle that can be used with most of the functions in
       libpmemcto(7).  On error, it returns NULL and sets errno appropriately.

       The pmemcto_close() function returns no value.

       pmemcto_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, pmemcto_check() returns 0.  If the consistency check
       cannot be performed, pmemcto_check() returns -1 and sets errno appropriately.   This  includes  the  case
       where layout is non-NULL and does not match the layout string given when the pool was created.

ERRORS

       EINVAL “layout” string does not match the layout stored in pool header.

       EINVAL “layout” string is longer than PMEMCTO_MAX_LAYOUT.

       EINVAL poolsize is less than PMEMCTO_MIN_POOL.

       EINVAL Invalid format of the pool set file.

       EINVAL Invalid pool header.

       EEXIST path passed to pmemcto_create() points to a pool set file, but poolsize is not zero.

       EEXIST path passed to pmemcto_create() points to an existing file, but poolsize is not zero.

       EEXIST path passed to pmemcto_create() points to an existing file, which is not-empty.

       EAGAIN The pmemcto pool pointed by path is already open.

       EACCES No write access permission to the pool file(s).

       ENOMEM The pool cannot be mapped at the address it was created.

CAVEATS

       Not  all file systems support posix_fallocate(3).  pmemcto_create() will fail if the underlying file sys‐
       tem does not support posix_fallocate(3).

BUGS

       Unlike libpmemobj(7), data replication is not supported in libpmemcto(7).  Thus, it  is  not  allowed  to
       specify replica sections in pool set files.

SEE ALSO

       ndctl-create-namespace(1),  pmempool-create(1), jemalloc(3), poolset(5), libpmemcto(7), libpmemobj(7) and
       <http://pmem.io>

PMDK - libpmemcto API version 1.0                  2018-05-21                                    PMEMCTO_OPEN(3)