.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEMPOOL-CREATE" "1" "2022-08-25" "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[] \- create a persistent memory pool
.SH SYNOPSIS
.IP
.nf
\f[C]
$\ pmempool\ create\ [<options>]\ [<type>]\ [<bsize>]\ <file>
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmempool\f[] invoked with \f[I]create\f[] 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[], \f[B]log\f[] and \f[B]obj\f[] which
stands for \f[I]pmemblk\f[], \f[I]pmemlog\f[] and \f[I]pmemobj\f[] pools
respectively.
By default the pool file is created with \f[I]minimum\f[] allowed size
for specified pool type.
The minimum sizes for \f[B]blk\f[], \f[B]log\f[] and \f[B]obj\f[] pool
types are \f[B]PMEMBLK_MIN_POOL\f[], \f[B]PMEMLOG_MIN_POOL\f[] and
\f[B]PMEMOBJ_MIN_POOL\f[] respectively.
See \f[B]libpmemblk\f[](7), \f[B]libpmemlog\f[](7) and
\f[B]libpmemobj\f[](7) for details.
.PP
For \f[I]pmemblk\f[] pool type block size \f[I]<bsize>\f[] is a required
argument.
.PP
In order to set custom size of pool use \f[B]\-s\f[] option, or use
\f[B]\-M\f[] option to create a pool of maximum available size on
underlying file system.
.PP
The \f[I]size\f[] 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[]
.PP
Size of pool file.
.PP
\f[C]\-M,\ \-\-max\-size\f[]
.PP
Set size of pool to available space of underlying file system.
.PP
\f[C]\-m,\ \-\-mode\ <octal>\f[]
.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[]
.PP
Create a new pool of the same size and other properties as
\f[I]<file>\f[].
.PP
\f[C]\-b,\ \-\-clear\-bad\-blocks\f[]
.PP
Clear bad blocks in existing files.
.PP
\f[C]\-f,\ \-\-force\f[]
.PP
Remove the pool before creating.
.PP
\f[C]\-v,\ \-\-verbose\f[]
.PP
Increase verbosity level.
.PP
\f[C]\-h,\ \-\-help\f[]
.PP
Display help message and exit.
.SS Options for PMEMBLK:
.PP
By default when creating a pmem \f[B]blk\f[] pool, the \f[B]BTT\f[]
layout is \f[I]not\f[] written until the first \f[I]write operation\f[]
of block entry is performed.
Using \f[B]\-w\f[] option you can force writing the \f[B]BTT\f[] layout
by writing zero data to specified block number.
By default the \f[I]write operation\f[] is performed to block number 0.
Please refer to \f[B]libpmemblk\f[](7) for details.
.PP
\f[C]\-w,\ \-\-write\-layout\f[]
.PP
Force writing the \f[B]BTT\f[] layout by performing \f[I]write
operation\f[] to block number zero.
.SS Options for PMEMOBJ:
.PP
By default when creating a pmem \f[B]obj\f[] pool, the layout name
provided to the \f[B]libpmemobj\f[] library is an empty string.
Please refer to \f[B]libpmemobj\f[](7) for details.
.PP
\f[C]\-l,\ \-\-layout\ <layout>\f[]
.PP
Layout name of the \f[B]pmemobj\f[] pool.
.SH EXAMPLE
.IP
.nf
\f[C]
$\ pmempool\ create\ blk\ 512\ pool.blk
\f[]
.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[]
.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[]
.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[]
.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[]
.fi
.PP
Create a pool file based on pool.log file
.SH SEE ALSO
.PP
\f[B]pmempool\f[](1), \f[B]libpmemblk\f[](7), \f[B]libpmemlog\f[](7),
\f[B]libpmemobj\f[](7) and \f[B]<https://pmem.io>\f[]