1PMEMCTO_OPEN(3) PMDK Programmer's Manual PMEMCTO_OPEN(3)
2
3
4
6 pmemcto_create(), pmemcto_open(), pmemcto_close(), pmemcto_check() --
7 create, open, close and validate close-to-open persistence pool
8
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
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
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
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
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
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
145 ndctl-create-namespace(1), pmempool-create(1), jemalloc(3), poolset(5),
146 libpmemcto(7), libpmemobj(7) and <http://pmem.io>
147
148
149
150PMDK - libpmemcto API version 1.0 2018-03-13 PMEMCTO_OPEN(3)