NAME

       pmemobj_open(),         pmemobj_create(),         pmemobj_close(),         pmemobj_check()
       pmemobj_set_user_data(),  pmemobj_get_user_data()  -  create,  open,  close  and  validate
       persistent memory transactional object store

SYNOPSIS

              #include <libpmemobj.h>

              PMEMobjpool *pmemobj_open(const char *path, const char *layout);
              PMEMobjpool *pmemobj_create(const char *path, const char *layout,
                  size_t poolsize, mode_t mode);
              void pmemobj_close(PMEMobjpool *pop);
              int pmemobj_check(const char *path, const char *layout);

              void pmemobj_set_user_data(PMEMobjpool *pop, void *data);
              void *pmemobj_get_user_data(PMEMobjpool *pop);

DESCRIPTION

       To  use  the  pmem-resident transactional object store provided by libpmemobj(7), a memory
       pool must first be created with the pmemobj_create() function described  below.   Existing
       pools may be opened with the pmemobj_open() function.

       As  of  libpmemobj  1.11,  these  functions are thread-safe; be careful if you have to use
       earlier versions of the library.

       Once created, the memory pool is represented by an opaque handle,  of  type  PMEMobjpool*,
       which  is  passed to most of the other libpmemobj(7) functions.  Internally, libpmemobj(7)
       will use either pmem_persist(3) or msync(2) when it needs to flush changes,  depending  on
       whether  the  memory  pool  appears  to  be  persistent  memory or a regular file (see the
       pmem_is_pmem(3) function in libpmem(7) for  more  information).   There  is  no  need  for
       applications  to  flush  changes  directly  when  using  the object memory API provided by
       libpmemobj(7).

       The pmemobj_create() function creates a transactional object store with  the  given  total
       poolsize.   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  libpmemobj(7),  but may be used as a check when pmemobj_open() is called.
       The layout name, including the  terminating  null  byte  (`\0'),  cannot  be  longer  than
       PMEMOBJ_MAX_LAYOUT  as defined in <libpmemobj.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 pmemobj_create(), and then
       specifying poolsize as zero.  In this case pmemobj_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 transactional object store is
       defined in <libpmemobj.h> as PMEMOBJ_MIN_POOL.  For remote replicas the minimum file  size
       is defined in <librpmem.h> as RPMEM_MIN_PART.

       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  pmemobj
       memory  pool  could  be  limited by the capacity of a single memory device.  libpmemobj(7)
       allows building persistent memory resident object store 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 pmemobj_create(); however,  the
       recommended method for creating pool sets is with the pmempool(1) utility.

       When  creating  a  pool  set  consisting  of  multiple  files, the path argument passed to
       pmemobj_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.

       The set file is a plain text file, the structure of which is described in poolset(5).

       The  pmemobj_open()  function  opens  an  existing  object  store memory pool.  Similar to
       pmemobj_create(), path must identify either an existing obj memory pool file, or  the  set
       file  used to create a pool set.  If layout is non-NULL, it is compared to the layout name
       provided to pmemobj_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.

       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  pmemobj_close()  function  closes  the  memory  pool indicated by pop and deletes the
       memory pool handle.  The object store itself lives on in the file that contains it and may
       be re-opened at a later time using pmemobj_open() as described above.

       The  pmemobj_check()  function performs a consistency check of the file indicated by path.
       pmemobj_check() opens the given path read-only so it never makes any changes to the  file.
       This function is not supported on Device DAX.

       The  pmemobj_set_user_data()  function  associates  custom  volatile state, represented by
       pointer data, with  the  given  pool  pop.   This  state  can  later  be  retrieved  using
       pmemobj_get_user_data()   function.    This   state  does  not  survive  pool  close.   If
       pmemobj_set_user_data() was not called for  a  given  pool,  pmemobj_get_user_data()  will
       return NULL.

RETURN VALUE

       The  pmemobj_create()  function  returns  a memory pool handle to be used with most of the
       functions in libpmemobj(7).  On error it returns NULL and sets errno appropriately.

       The pmemobj_open() function returns a memory pool handle to  be  used  with  most  of  the
       functions  in  libpmemobj(7).   If an error prevents the pool from being opened, or if the
       given layout does not match the pool's layout, pmemobj_open() returns NULL and sets  errno
       appropriately.

       The pmemobj_close() function returns no value.

       The  pmemobj_check() function returns 1 if the memory pool is found to be consistent.  Any
       inconsistencies found will cause pmemobj_check() to return 0, in which case the use of the
       file  with  libpmemobj(7)  will  result  in  undefined  behavior.   The  debug  version of
       libpmemobj(7) will provide additional details on inconsistencies when PMEMOBJ_LOG_LEVEL is
       at  least  1,  as  described in the DEBUGGING AND ERROR HANDLING section in libpmemobj(7).
       pmemobj_check() returns -1 and sets errno if it cannot perform the consistency  check  due
       to other errors.

CAVEATS

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

SEE ALSO

       creat(2),  msync(2),  pmem_is_pmem(3),  pmem_persist(3),  posix_fallocate(3),  libpmem(7),
       libpmemobj(7) and <https://pmem.io>