.\" Automatically generated by Pandoc 2.10.1
.\"
.TH "PMEMPOOL-CREATE" "1" "2020-10-28" "PMDK - pmem Tools version 1.4" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2016-2019, Intel Corporation
.SH NAME
.PP
\f[B]pmempool-create\f[R] - create a persistent memory pool
.SH SYNOPSIS
.IP
.nf
\f[C]
$ pmempool create [<options>] [<type>] [<bsize>] <file>
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmempool\f[R] invoked with \f[I]create\f[R] command creates a
pool file of specified type.
Depending on a pool type it is possible to provide more properties of
pool.
.PP
Valid pool types are: \f[B]blk\f[R], \f[B]log\f[R] and \f[B]obj\f[R]
which stands for \f[I]pmemblk\f[R], \f[I]pmemlog\f[R] and
\f[I]pmemobj\f[R] pools respectively.
By default the pool file is created with \f[I]minimum\f[R] allowed size
for specified pool type.
The minimum sizes for \f[B]blk\f[R], \f[B]log\f[R] and \f[B]obj\f[R]
pool types are \f[B]PMEMBLK_MIN_POOL\f[R], \f[B]PMEMLOG_MIN_POOL\f[R]
and \f[B]PMEMOBJ_MIN_POOL\f[R] respectively.
See \f[B]libpmemblk\f[R](7), \f[B]libpmemlog\f[R](7) and
\f[B]libpmemobj\f[R](7) for details.
.PP
For \f[I]pmemblk\f[R] pool type block size \f[I]<bsize>\f[R] is a
required argument.
.PP
In order to set custom size of pool use \f[B]-s\f[R] option, or use
\f[B]-M\f[R] option to create a pool of maximum available size on
underlying file system.
.PP
The \f[I]size\f[R] argument may be passed in format that permits only
the upper-case character for byte - B as specified in IEC 80000-13, IEEE
1541 and the Metric Interchange Format.
Standards accept SI units with obligatory B - kB, MB, GB, \&... which
means multiplier by 1000 and IEC units with optional \[lq]iB\[rq] - KiB,
MiB, GiB, \&..., K, M, G, \&... - which means multiplier by 1024.
.SS Available options:
.PP
\f[C]-s, --size <size>\f[R]
.PP
Size of pool file.
.PP
\f[C]-M, --max-size\f[R]
.PP
Set size of pool to available space of underlying file system.
.PP
\f[C]-m, --mode <octal>\f[R]
.PP
Set permissions to (the default is 0664) when creating the files.
If the file already exist the permissions are not changed.
.PP
\f[C]-i, --inherit <file>\f[R]
.PP
Create a new pool of the same size and other properties as
\f[I]<file>\f[R].
.PP
\f[C]-b, --clear-bad-blocks\f[R]
.PP
Clear bad blocks in existing files.
.PP
\f[C]-f, --force\f[R]
.PP
Remove the pool before creating.
.PP
\f[C]-v, --verbose\f[R]
.PP
Increase verbosity level.
.PP
\f[C]-h, --help\f[R]
.PP
Display help message and exit.
.SS Options for PMEMBLK:
.PP
By default when creating a pmem \f[B]blk\f[R] pool, the \f[B]BTT\f[R]
layout is \f[I]not\f[R] written until the first \f[I]write
operation\f[R] of block entry is performed.
Using \f[B]-w\f[R] option you can force writing the \f[B]BTT\f[R] layout
by writing zero data to specified block number.
By default the \f[I]write operation\f[R] is performed to block number 0.
Please refer to \f[B]libpmemblk\f[R](7) for details.
.PP
\f[C]-w, --write-layout\f[R]
.PP
Force writing the \f[B]BTT\f[R] layout by performing \f[I]write
operation\f[R] to block number zero.
.SS Options for PMEMOBJ:
.PP
By default when creating a pmem \f[B]obj\f[R] pool, the layout name
provided to the \f[B]libpmemobj\f[R] library is an empty string.
Please refer to \f[B]libpmemobj\f[R](7) for details.
.PP
\f[C]-l, --layout <layout>\f[R]
.PP
Layout name of the \f[B]pmemobj\f[R] pool.
.SH EXAMPLE
.IP
.nf
\f[C]
$ pmempool create blk 512 pool.blk
\f[R]
.fi
.PP
Create a blk pool file of minimum allowed size and block size 512 bytes
.IP
.nf
\f[C]
$ pmempool create log -M pool.log
\f[R]
.fi
.PP
Create a log pool file of maximum allowed size
.IP
.nf
\f[C]
$ pmempool create blk --size=4G --write-layout 1K pool.blk
\f[R]
.fi
.PP
Create a blk pool file of size 4G, block size 1K and write the BTT
layout
.IP
.nf
\f[C]
$ pmempool create --layout my_layout obj pool.obj
\f[R]
.fi
.PP
Create an obj pool file of minimum allowed size and layout
\[lq]my_layout\[rq]
.IP
.nf
\f[C]
$ pmempool create --inherit=pool.log new_pool.log
\f[R]
.fi
.PP
Create a pool file based on pool.log file
.SH SEE ALSO
.PP
\f[B]pmempool\f[R](1), \f[B]libpmemblk\f[R](7), \f[B]libpmemlog\f[R](7),
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]