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
       defined  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 responsibility for creating the  memory
       pool  file by creating it before calling pmemcto_create(), and then specifying poolsize as
       zero.  In this case pmemcto_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 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, 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 pmemcto_open() function opens an existing close-to-open persistence memory pool.  path
       must  be an existing 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 permission  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 later 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 opening 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  provide  additional  details  on
       inconsistencies  when  PMEMCTO_LOG_LEVEL  is at least 1, as described in the DEBUGGING 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 system 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>