NAME

       pmemlog_create()(DEPRECATED),   pmemlog_open()(DEPRECATED),   pmemlog_close()(DEPRECATED),
       pmemlog_check()(DEPRECATED) - create, open, close and validate persistent memory  resident
       log file

SYNOPSIS

              #include <libpmemlog.h>

              PMEMlogpool *pmemlog_open(const char *path);
              PMEMlogpool *pmemlog_create(const char *path, size_t poolsize, mode_t mode);
              void pmemlog_close(PMEMlogpool *plp);
              int pmemlog_check(const char *path);

DESCRIPTION

       The  pmemlog_create()  function  creates  a log memory pool with the given total poolsize.
       Since the transactional nature of a log memory pool requires some space  overhead  in  the
       memory pool, the resulting available log size is less than poolsize, and is made available
       to the caller via the pmemlog_nbyte(3) function.  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 pmemlog_create() and then specifying  poolsize  as
       zero.  In this case pmemlog_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  log  pool
       is defined in <libpmemlog.h> as PMEMLOG_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  pmemlog
       memory  pool  could  be  limited by the capacity of a single memory device.  libpmemlog(7)
       allows building persistent memory  resident  logs  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 pmemlog_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
       pmemlog_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.

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

       The   pmemlog_open()   function   opens   an   existing   log  memory  pool.   Similar  to
       pmemlog_create(), path must identify either an existing log 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.

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

       The  pmemlog_check()  function performs a consistency check of the file indicated by path.
       pmemlog_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, pmemlog_create() returns a PMEMlogpool* handle to the memory pool that is used
       with most of the functions from libpmemlog(7).  If an error prevents any of the  pool  set
       files from being created, it returns NULL and sets errno appropriately.

       On  success,  pmemlog_open() returns a PMEMlogpool* handle to the memory pool that is used
       with most of the functions from libpmemlog(7).  If an error prevents the pool  from  being
       opened,  or  a pool set is being opened and the actual size of any file does not match the
       corresponding part size defined in the set file,  pmemlog_open()  returns  NULL  and  sets
       errno appropriately.

       The pmemlog_close() function returns no value.

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

CAVEATS

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

SEE ALSO

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