Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PMEMBLK_CREATE(3)	   PMDK	Programmer's Manual	     PMEMBLK_CREATE(3)

       pmemblk_create(),  pmemblk_open(),  pmemblk_close(),  pmemblk_check() -
       create, open, close and validate	block pool

	      #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);

       The pmemblk_create() function creates a block memory pool with the giv-
       en  total poolsize, divided into	as many	elements of size bsize 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	poolsize/bsize,	and is made  available
       to  the caller via the pmemblk_nblock(3)	function.  Given the specifics
       of the implementation, the number of available blocks for the user can-
       not be less than	256.  This translates to at least 512 internal blocks.
       path specifies the name of the memory pool file to  be  created.	  mode
       specifies  the  permissions to use when creating	the file, as described
       by creat(2).  The memory	pool file is fully allocated to	the size pool-
       size using posix_fallocate(3).  The caller may choose to	take responsi-
       bility for creating the memory pool file	by creating it before  calling
       pmemblk_create(),  and  then specifying poolsize	as zero.  In this case
       pmemblk_create()	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 mini-
       mum net pool size allowed by the	library	for a block pool is defined in
       <libpmemblk.h>  as  PMEMBLK_MIN_POOL.  bsize can	be any non-zero	value;
       however,	libpmemblk will	silently round up  the	given  size  to	 PMEM-
       BLK_MIN_BLK, as defined in <libpmemblk.h>.

       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 lim-
       ited by the capacity of a single	memory device.	 libpmemblk(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 pool set may be stored	on a different
       memory device or	pmem-aware filesystem.

       Creation	of all the parts of the	pool set can be	done with pmemblk_cre-
       ate(); however, the recommended method for creating pool	sets is	by us-
       ing the pmempool(1) utility.

       When creating a pool set	consisting of multiple files, the  path	 argu-
       ment passed to pmemblk_create() must point to the special set file that
       defines the pool	layout and the location	of all the parts of  the  pool
       set.   The  poolsize argument must be 0.	 The meaning of	the mode argu-
       ment does not change, except that the same mode is used for creation of
       all the parts of	the pool set.

       For more	information on pool set	format,	see poolset(5).

       The  pmemblk_open()  function  opens an existing	block memory pool.  As
       with pmemblk_create(), path must	identify either	an existing block mem-
       ory pool	file, or the set file used to create a pool set.  The applica-
       tion must have permission to open the file and memory map the  file  or
       pool  set  with	read/write  permissions.   If bsize is non-zero, pmem-
       blk_open() will verify that the given block size	matches	the block size
       used  when  the	pool was created.  Otherwise, pmemblk_open() will open
       the pool	without	verifying the block size.  The bsize can be determined
       using the pmemblk_bsize(3) function.

       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 pmempool-feature(1).

       The  pmemblk_close()  function  closes the memory pool indicated	by pbp
       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 pmemblk_open() as described above.

       The pmemblk_check() function performs a consistency check of  the  file
       indicated by path, and returns 1	if the memory pool is found to be con-
       sistent.	 If the	pool is	found not to be	consistent, further use	of the
       file with libpmemblk will result	in undefined behavior.	The debug ver-
       sion of libpmemblk will provide additional details  on  inconsistencies
       when PMEMBLK_LOG_LEVEL is at least 1, as	described in the DEBUGGING AND
       ERROR HANDLING section in  libpmemblk(7).   pmemblk_check()  opens  the
       given  path  read-only so it never makes	any changes to the file.  This
       function	is not supported on Device DAX.

       On success, pmemblk_create() returns a PMEMblkpool* handle to the block
       memory pool.  On	error, it returns NULL and sets	errno appropriately.

       On  success,  pmemblk_open()  returns a PMEMblkpool* handle that	can be
       used with most of the functions in libpmemblk(7).  On error, it returns
       NULL and	sets errno appropriately.  Possible errors include:

       o failure to open path

       o path  specifies  a  set  file and any of the pool set files cannot be

       o path specifies	a set file and the actual size of any  file  does  not
	 match the corresponding part size defined in the set file

       o bsize	is  non-zero  and does not match the block size	given when the
	 pool was created.  errno is set to EINVAL in this case.

       The pmemblk_close() function returns no value.

       pmemblk_check() returns 1 if the	memory pool is found to	be consistent.
       If  the check is	successfully performed but the pool is found to	be in-
       consistent, pmemblk_check() returns 0.  This includes  the  case	 where
       bsize is	non-zero and does not match the	block size given when the pool
       was created.  If	the  consistency  check	 cannot	 be  performed,	 pmem-
       blk_check() returns -1 and sets errno appropriately.

       Not all file systems support posix_fallocate(3).	 pmemblk_create() will
       fail if the underlying file system does not support posix_fallocate(3).

       pmempool(1),    creat(2),    pmemblk_nblock(3),	   posix_fallocate(3),
       poolset(5), libpmemblk(7) and <>

PMDK - pmemblk API version 1.1	  2019-07-10		     PMEMBLK_CREATE(3)


Want to link to this manual page? Use this URL:

home | help