1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "PMEMBLK_CREATE" "3" "2018-10-12" "PMDK - pmemblk API version 1.1" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2018, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" * Neither the name of the copyright holder nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH NAME
.PP
\f[B]pmemblk_create\f[](), \f[B]pmemblk_open\f[](),
\f[B]pmemblk_close\f[](), \f[B]pmemblk_check\f[]() \- create, open,
close and validate block pool
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemblk.h>
PMEMblkpool\ *pmemblk_create(const\ char\ *path,\ size_t\ bsize,
\ \ \ \ \ \ \ \ size_t\ poolsize,\ mode_t\ mode);
PMEMblkpool\ *pmemblk_open(const\ char\ *path,\ size_t\ bsize);
void\ pmemblk_close(PMEMblkpool\ *pbp);
int\ pmemblk_check(const\ char\ *path,\ size_t\ bsize);
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmemblk_create\f[]() function creates a block memory pool with
the given total \f[I]poolsize\f[], divided into as many elements of size
\f[I]bsize\f[] as will fit in the pool.
Since the transactional nature of a block memory pool requires some
space overhead in the memory pool, the resulting number of available
blocks is less than \f[I]poolsize\f[]/\f[I]bsize\f[], and is made
available to the caller via the \f[B]pmemblk_nblock\f[](3) function.
Given the specifics of the implementation, the number of available
blocks for the user cannot be less than 256.
This translates to at least 512 internal blocks.
\f[I]path\f[] specifies the name of the memory pool file to be created.
\f[I]mode\f[] specifies the permissions to use when creating the file,
as described by \f[B]creat\f[](2).
The memory pool file is fully allocated to the size \f[I]poolsize\f[]
using \f[B]posix_fallocate\f[](3).
The caller may choose to take responsibility for creating the memory
pool file by creating it before calling \f[B]pmemblk_create\f[](), and
then specifying \f[I]poolsize\f[] as zero.
In this case \f[B]pmemblk_create\f[]() 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 block pool is
defined in \f[B]<libpmemblk.h>\f[] as \f[B]PMEMBLK_MIN_POOL\f[].
\f[I]bsize\f[] can be any non\-zero value; however, \f[B]libpmemblk\f[]
will silently round up the given size to \f[B]PMEMBLK_MIN_BLK\f[], as
defined in \f[B]<libpmemblk.h>\f[].
.PP
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 pmemblk memory pool could be
limited by the capacity of a single memory device.
\f[B]libpmemblk\f[](7) allows building a persistent memory resident
array spanning multiple memory devices by creation of persistent memory
pools consisting of multiple files, where each part of such a \f[I]pool
set\f[] may be stored on a different memory device or pmem\-aware
filesystem.
.PP
Creation of all the parts of the pool set can be done with
\f[B]pmemblk_create\f[](); however, the recommended method for creating
pool sets is by using the \f[B]pmempool\f[](1) utility.
.PP
When creating a pool set consisting of multiple files, the \f[I]path\f[]
argument passed to \f[B]pmemblk_create\f[]() must point to the special
\f[I]set\f[] file that defines the pool layout and the location of all
the parts of the pool set.
The \f[I]poolsize\f[] argument must be 0.
The meaning of the \f[I]mode\f[] argument does not change, except that
the same \f[I]mode\f[] is used for creation of all the parts of the pool
set.
.PP
For more information on pool set format, see \f[B]poolset\f[](5).
.PP
The \f[B]pmemblk_open\f[]() function opens an existing block memory
pool.
As with \f[B]pmemblk_create\f[](), \f[I]path\f[] must identify either an
existing block memory pool file, or the \f[I]set\f[] 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.
If \f[I]bsize\f[] is non\-zero, \f[B]pmemblk_open\f[]() will verify that
the given block size matches the block size used when the pool was
created.
Otherwise, \f[B]pmemblk_open\f[]() will open the pool without verifying
the block size.
The \f[I]bsize\f[] can be determined using the \f[B]pmemblk_bsize\f[](3)
function.
.PP
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
\f[B]pmempool\-feature\f[](1).
.PP
The \f[B]pmemblk_close\f[]() function closes the memory pool indicated
by \f[I]pbp\f[] and deletes the memory pool handle.
The block memory pool itself lives on in the file that contains it and
may be re\-opened at a later time using \f[B]pmemblk_open\f[]() as
described above.
.PP
The \f[B]pmemblk_check\f[]() function performs a consistency check of
the file indicated by \f[I]path\f[], 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
\f[B]libpmemblk\f[] will result in undefined behavior.
The debug version of \f[B]libpmemblk\f[] will provide additional details
on inconsistencies when \f[B]PMEMBLK_LOG_LEVEL\f[] is at least 1, as
described in the \f[B]DEBUGGING AND ERROR HANDLING\f[] section in
\f[B]libpmemblk\f[](7).
\f[B]pmemblk_check\f[]() opens the given \f[I]path\f[] read\-only so it
never makes any changes to the file.
This function is not supported on Device DAX.
.SH RETURN VALUE
.PP
On success, \f[B]pmemblk_create\f[]() returns a \f[I]PMEMblkpool*\f[]
handle to the block memory pool.
On error, it returns NULL and sets \f[I]errno\f[] appropriately.
.PP
On success, \f[B]pmemblk_open\f[]() returns a \f[I]PMEMblkpool*\f[]
handle that can be used with most of the functions in
\f[B]libpmemblk\f[](7).
On error, it returns NULL and sets \f[I]errno\f[] appropriately.
Possible errors include:
.IP \[bu] 2
failure to open \f[I]path\f[]
.IP \[bu] 2
\f[I]path\f[] specifies a \f[I]set\f[] file and any of the pool set
files cannot be opened
.IP \[bu] 2
\f[I]path\f[] specifies a \f[I]set\f[] file and the actual size of any
file does not match the corresponding part size defined in the
\f[I]set\f[] file
.IP \[bu] 2
\f[I]bsize\f[] is non\-zero and does not match the block size given when
the pool was created.
\f[I]errno\f[] is set to \f[B]EINVAL\f[] in this case.
.PP
The \f[B]pmemblk_close\f[]() function returns no value.
.PP
\f[B]pmemblk_check\f[]() 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, \f[B]pmemblk_check\f[]() returns 0.
This includes the case where \f[I]bsize\f[] is non\-zero and does not
match the block size given when the pool was created.
If the consistency check cannot be performed, \f[B]pmemblk_check\f[]()
returns \-1 and sets \f[I]errno\f[] appropriately.
.SH CAVEATS
.PP
Not all file systems support \f[B]posix_fallocate\f[](3).
\f[B]pmemblk_create\f[]() will fail if the underlying file system does
not support \f[B]posix_fallocate\f[](3).
.SH SEE ALSO
.PP
\f[B]pmempool\f[](1), \f[B]creat\f[](2), \f[B]pmemblk_nblock\f[](3),
\f[B]posix_fallocate\f[](3), \f[B]poolset\f[](5), \f[B]libpmemblk\f[](7)
and \f[B]<http://pmem.io>\f[]
|
