.\" Automatically generated by Pandoc 2.0.6 .\" .TH "RPMEM_CREATE" "3" "2022-08-25" "PMDK - rpmem API version 1.3" "PMDK Programmer's Manual" .hy .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright 2017-2022, Intel Corporation .SH NAME .PP \f[B]rpmem_create\f[]()(DEPRECATED), \f[B]rpmem_open\f[]()(DEPRECATED), \f[B]rpmem_set_attr\f[]()(DEPRECATED), \f[B]rpmem_close\f[]()(DEPRECATED), \f[B]rpmem_remove\f[]()(DEPRECATED), \- most commonly used functions for remote access to \f[I]persistent memory\f[] .SH SYNOPSIS .IP .nf \f[C] #include\ RPMEMpool\ *rpmem_create(const\ char\ *target,\ const\ char\ *pool_set_name, \ \ \ \ void\ *pool_addr,\ size_t\ pool_size,\ unsigned\ *nlanes, \ \ \ \ const\ struct\ rpmem_pool_attr\ *create_attr); RPMEMpool\ *rpmem_open(const\ char\ *target,\ const\ char\ *pool_set_name, \ \ \ \ void\ *pool_addr,\ size_t\ pool_size,\ unsigned\ *nlanes, \ \ \ \ struct\ rpmem_pool_attr\ *open_attr); int\ rpmem_set_attr(RPMEMpool\ *rpp,\ const\ struct\ rpmem_pool_attr\ *attr); int\ rpmem_close(RPMEMpool\ *rpp); int\ rpmem_remove(const\ char\ *target,\ const\ char\ *pool_set_name,\ int\ flags); \f[] .fi .SH DESCRIPTION .PP The \f[B]rpmem_create\f[]() function creates a remote pool on a given \f[I]target\f[] node, using pool \f[I]set\f[] file \f[I]pool_set_name\f[] to map the remote pool. \f[I]pool_set_name\f[] is a relative path in the root config directory on the \f[I]target\f[] node. For pool set file format and options see \f[B]poolset\f[](5). \f[I]pool_addr\f[] is a pointer to the associated local memory pool with size \f[I]pool_size\f[]. Both \f[I]pool_addr\f[] and \f[I]pool_size\f[] must be aligned to the system's page size (see \f[B]sysconf\f[](3)). The size of the remote pool must be at least \f[I]pool_size\f[]. See \f[B]REMOTE POOL SIZE\f[], below, for details. \f[I]nlanes\f[] points to the maximum number of lanes which the caller is requesting. Upon successful creation of the remote pool, *\f[I]nlanes\f[] is set to the maximum number of lanes supported by both the local and remote nodes. See \f[B]LANES\f[], below, for details. The \f[I]create_attr\f[] structure contains the attributes used for creating the remote pool. If the \f[I]create_attr\f[] structure is not NULL, a pool with internal metadata is created. The metadata is stored in the first 4096 bytes of the pool and can be read when opening the remote pool with \f[B]rpmem_open\f[](). To prevent user from overwriting the pool metadata, this region is not accessible to the user via \f[B]rpmem_persist\f[](). If \f[I]create_attr\f[] is NULL or zeroed, remote pool set file must contain the \f[I]NOHDRS\f[] option. In that case the remote pool is created without internal metadata in it and the entire pool space is available to the user. See \f[B]rpmem_persist\f[](3) for details. .PP The \f[B]rpmem_open\f[]() function opens the existing remote pool with \f[I]set\f[] file \f[I]pool_set_name\f[] on remote node \f[I]target\f[]. \f[I]pool_set_name\f[] is a relative path in the root config directory on the \f[I]target\f[] node. \f[I]pool_addr\f[] is a pointer to the associated local memory pool of size \f[I]pool_size\f[]. Both \f[I]pool_addr\f[] and \f[I]pool_size\f[] must be aligned to the system's page size (see \f[B]sysconf\f[](3)). The size of the remote pool must be at least \f[I]pool_size\f[]. See \f[B]REMOTE POOL SIZE\f[], below, for details. \f[I]nlanes\f[] points to the maximum number of lanes which the caller is requesting. Upon successful opening of the remote pool, *\f[I]nlanes\f[] is set to the maximum number of lanes supported by both the local and remote nodes. See \f[B]LANES\f[], below, for details. .PP The \f[B]rpmem_set_attr\f[]() function overwrites the pool's attributes. The \f[I]attr\f[] structure contains the attributes used for overwriting the remote pool attributes that were passed to \f[B]rpmem_create\f[]() at pool creation. If \f[I]attr\f[] is NULL, a zeroed structure with attributes will be used. New attributes are stored in the pool's metadata. .PP The \f[B]rpmem_close\f[]() function closes the remote pool \f[I]rpp\f[]. All resources are released on both the local and remote nodes. The remote pool itself persists on the remote node and may be re\-opened at a later time using \f[B]rpmem_open\f[](). .PP The \f[B]rpmem_remove\f[]() function removes the remote pool with \f[I]set\f[] file name \f[I]pool_set_name\f[] from node \f[I]target\f[]. The \f[I]pool_set_name\f[] is a relative path in the root config directory on the \f[I]target\f[] node. By default only the pool part files are removed; the pool \f[I]set\f[] file is left untouched. If the pool is not consistent, the \f[B]rpmem_remove\f[]() function fails. The \f[I]flags\f[] argument determines the behavior of \f[B]rpmem_remove\f[](). \f[I]flags\f[] may be either 0 or the bitwise OR of one or more of the following flags: .IP \[bu] 2 \f[B]RPMEM_REMOVE_FORCE\f[] \- Ignore errors when opening an inconsistent pool. The pool \f[I]set\f[] file must still be in appropriate format for the pool to be removed. .IP \[bu] 2 \f[B]RPMEM_REMOVE_POOL_SET\f[] \- Remove the pool \f[I]set\f[] file after removing the pool described by this pool set. .SH RETURN VALUE .PP On success, \f[B]rpmem_create\f[]() returns an opaque handle to the remote pool for use in subsequent \f[B]librpmem\f[] calls. If any error prevents the remote pool from being created, \f[B]rpmem_create\f[]() returns NULL and sets \f[I]errno\f[] appropriately. .PP On success, \f[B]rpmem_open\f[]() returns an opaque handle to the remote pool for subsequent \f[B]librpmem\f[] calls. If the \f[I]open_attr\f[] argument is not NULL, the remote pool attributes are returned in the provided structure. If the remote pool was created without internal metadata, zeroes are returned in the \f[I]open_attr\f[] structure on successful call to \f[B]rpmem_open\f[](). If any error prevents the remote pool from being opened, \f[B]rpmem_open\f[]() returns NULL and sets \f[I]errno\f[] appropriately. .PP On success, \f[B]rpmem_set_attr\f[]() returns 0. On error, it returns \-1 and sets \f[I]errno\f[] appropriately. .PP On success, \f[B]rpmem_close\f[]() returns 0. On error, it returns a non\-zero value and sets \f[I]errno\f[] appropriately. .PP On success, \f[B]rpmem_remove\f[]() returns 0. On error, it returns a non\-zero value and sets \f[I]errno\f[] appropriately. .SH NOTES .SS REMOTE POOL SIZE .PP The size of a remote pool depends on the configuration in the pool set file on the remote node (see \f[B]poolset\f[](5)). If no pool set options is used in the remote pool set file, the remote pool size is the sum of the sizes of all part files, decreased by 4096 bytes per part file. 4096 bytes of each part file are utilized for storing internal metadata. If the \f[I]SINGLEHDR\f[] option is used in the remote pool set file, the remote pool size is the sum of sizes of all part files, decreased once by 4096 bytes. In this case only the first part contains internal metadata. If a remote pool set file contains the \f[I]NOHDRS\f[] option, the remote pool size is the sum of sizes of all its part files. In this case none of the parts contains internal metadata. For other consequences of using the \f[I]SINGLEHDR\f[] and \f[I]NOHDRS\f[] options see \f[B]rpmem_persist\f[](3). \f[B]RPMEM_MIN_PART\f[] and \f[B]RPMEM_MIN_POOL\f[] in \f[B]\f[] define the minimum size allowed by \f[B]librpmem\f[] for a part file and a remote pool, respectively. .SS LANES .PP The term \f[I]lane\f[] means an isolated path of execution. The underlying hardware utilized by both local and remote nodes may have limited resources that restrict the maximum number of parallel \f[B]rpmem_persist\f[](3) operations. The maximum number of supported lanes is returned by the \f[B]rpmem_open\f[]() and \f[B]rpmem_create\f[]() function calls. The caller passes the maximum number of lanes requested in *\f[I]nlanes\f[]. If the pool is successfully created or opened, *\f[I]nlanes\f[] is updated to reflect the minimum of the number of lanes requested by the caller and the maximum number of lanes supported by underlying hardware. The application is obligated to use at most the returned number of lanes in parallel. .PP \f[B]rpmem_persist\f[](3) does not provide any locking mechanism; thus any serialization of calls must be performed by the application if required. .PP Each lane requires a separate connection, represented by a file descriptor. If the system runs out of free file descriptors during \f[B]rpmem_create\f[]() or \f[B]rpmem_open\f[](), these functions will fail. See \f[B]nofile\f[] in \f[B]limits.conf\f[](5) for more details. .SH SEE ALSO .PP \f[B]rpmem_persist\f[](3), \f[B]sysconf\f[](3), \f[B]limits.conf\f[](5), \f[B]libpmemobj\f[](7), \f[B]librpmem\f[](7) and \f[B]\f[]