pmemcto_create(3)

1PMEMCTO_OPEN(3)            PMDK Programmer's Manual            PMEMCTO_OPEN(3)
2
3
4

NAME

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

SYNOPSIS

10              #include <libpmemcto.h>
11
12              PMEMctopool *pmemcto_create(const char *path, const char *layout,
13                      size_t poolsize, mode_t mode);
14              PMEMctopool *pmemcto_open(const char *path, const char *layout);
15              void pmemcto_close(PMEMctopool *pcp);
16              int pmemcto_check(const char *path, const char *layout);
17

DESCRIPTION

19       The pmemcto_create() function creates a close-to-open persistence  pool
20       with  the  given  total poolsize.  The resulting pool is then used with
21       functions like pmemcto_malloc(3) and pmemcto_free(3) to provide the fa‐
22       miliar  malloc-like programming model for the memory pool.  path speci‐
23       fies the name of the memory pool file to be created.  layout  specifies
24       the application's layout type in the form of a string.  The layout name
25       is not interpreted by libpmemcto(7), but may be used as  a  check  when
26       pmemcto_open()  is  called.  The layout name, including the terminating
27       null byte (`\0'), cannot be longer than PMEMCTO_MAX_LAYOUT  as  defined
28       in  <libpmemcto.h>.   A  NULL  layout  is  equivalent to using an empty
29       string as a layout name.  mode specifies the permissions  to  use  when
30       creating  the  file, as described by creat(2).  The memory pool file is
31       fully allocated to the size  poolsize  using  posix_fallocate(3).   The
32       caller  may  choose to take responsibility for creating the memory pool
33       file by creating it before calling pmemcto_create(), and then  specify‐
34       ing poolsize as zero.  In this case pmemcto_create() will take the pool
35       size from the size of the existing file and will verify that  the  file
36       appears  to  be  empty  by  searching for any non-zero data in the pool
37       header at the beginning of the file.  The minimum net pool size allowed
38       by the library for a local close-to-open persistence pool is defined in
39       <libpmemcto.h> as PMEMCTO_MIN_POOL.
40
41       Depending  on  the  configuration  of   the   system,   the   available
42       non-volatile  memory space may be divided into multiple memory devices.
43       In such case, the maximum size of the pmemcto memory pool could be lim‐
44       ited  by  the capacity of a single memory device.  libpmemcto(7) allows
45       building a close-to-open persistence pool spanning multiple memory  de‐
46       vices  by  creation  of  persistent memory pools consisting of multiple
47       files, where each part of such a pool set may be stored on a  different
48       memory device or pmem-aware filesystem.
49
50       Creation of all the parts of the pool set can be done with pmemcto_cre‐
51       ate(); however, the recommended method for creating pool sets is by us‐
52       ing the pmempool(1) utility.
53
54       When  creating  a pool set consisting of multiple files, the path argu‐
55       ment passed to pmemcto_create() must point to the special set file that
56       defines  the  pool layout and the location of all the parts of the pool
57       set.  The poolsize argument must be 0.  The meaning of the  layout  and
58       mode  arguments  does not change, except that the same mode is used for
59       creation of all the parts of the pool set.
60
61       For more information on pool set format, see poolset(5).
62
63       The pmemcto_open() function opens an existing close-to-open persistence
64       memory pool.  path must be an existing file containing a pmemcto memory
65       pool as created by pmemcto_create().  If layout is non-NULL, it is com‐
66       pared to the layout name provided to pmemcto_create() when the pool was
67       first created.  This can be used to verify that the layout of the  pool
68       matches  what  was  expected.   The application must have permission to
69       open the file and memory map it with read/write permissions.
70
71       The pmemcto_close() function closes the memory pool  indicated  by  pcp
72       and  deletes the memory pool handle.  The close-to-open memory pool it‐
73       self lives on in the file that contains it and may be  re-opened  at  a
74       later  time  using  pmemcto_open() as described above.  If the pool was
75       not closed gracefully due to  abnormal  program  termination  or  power
76       failure,  the  pool is in an inconsistent state causing subsequent pool
77       opening to fail.
78
79       The pmemcto_check() function performs a consistency check of  the  file
80       indicated by path, and returns 1 if the memory pool is found to be con‐
81       sistent.  If the pool is found not to be consistent, further use of the
82       file  with  libpmemcto(7) will result in undefined behavior.  The debug
83       version of libpmemcto(7) will provide additional details  on  inconsis‐
84       tencies  when  PMEMCTO_LOG_LEVEL is at least 1, as described in the DE‐
85       BUGGING AND ERROR HANDLING section of  libpmemcto(7).   pmemcto_check()
86       will return -1 and set errno if it cannot perform the consistency check
87       due to other errors.  pmemcto_check() opens the given path read-only so
88       it never makes any changes to the file.  This function is not supported
89       on Device DAX.
90

RETURN VALUE

92       On success, pmemcto_create()  returns  a  PMEMctopool*  handle  to  the
93       close-to-open  persistence  memory pool.  On error, it returns NULL and
94       sets errno appropriately.
95
96       On success, pmemcto_open() returns a PMEMctopool* handle  that  can  be
97       used with most of the functions in libpmemcto(7).  On error, it returns
98       NULL and sets errno appropriately.
99
100       The pmemcto_close() function returns no value.
101
102       pmemcto_check() returns 1 if the memory pool is found to be consistent.
103       If  the check is successfully performed but the pool is found to be in‐
104       consistent, pmemcto_check() returns 0.  If the consistency check cannot
105       be  performed, pmemcto_check() returns -1 and sets errno appropriately.
106       This includes the case where layout is non-NULL and does not match  the
107       layout string given when the pool was created.
108

ERRORS

110       EINVAL “layout” string does not match the layout stored in pool header.
111
112       EINVAL “layout” string is longer than PMEMCTO_MAX_LAYOUT.
113
114       EINVAL poolsize is less than PMEMCTO_MIN_POOL.
115
116       EINVAL Invalid format of the pool set file.
117
118       EINVAL Invalid pool header.
119
120       EEXIST  path  passed to pmemcto_create() points to a pool set file, but
121       poolsize is not zero.
122
123       EEXIST path passed to pmemcto_create() points to an existing file,  but
124       poolsize is not zero.
125
126       EEXIST  path  passed  to  pmemcto_create()  points to an existing file,
127       which is not-empty.
128
129       EAGAIN The pmemcto pool pointed by path is already open.
130
131       EACCES No write access permission to the pool file(s).
132
133       ENOMEM The pool cannot be mapped at the address it was created.
134

CAVEATS

136       Not all file systems support posix_fallocate(3).  pmemcto_create() will
137       fail if the underlying file system does not support posix_fallocate(3).
138

BUGS

140       Unlike  libpmemobj(7),  data  replication is not supported in libpmemc‐
141       to(7).  Thus, it is not allowed to specify replica sections in pool set
142       files.
143