.\" Automatically generated by Pandoc 2.9.2.1 .\" .TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual" .hy .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright 2017-2022, Intel Corporation .SH NAME .PP \f[B]pmemobj_open\f[R](), \f[B]pmemobj_create\f[R](), \f[B]pmemobj_close\f[R](), \f[B]pmemobj_check\f[R]() \f[B]pmemobj_set_user_data\f[R](), \f[B]pmemobj_get_user_data\f[R]() - create, open, close and validate persistent memory transactional object store .SH SYNOPSIS .IP .nf \f[C] #include PMEMobjpool *pmemobj_open(const char *path, const char *layout); PMEMobjpool *pmemobj_create(const char *path, const char *layout, size_t poolsize, mode_t mode); void pmemobj_close(PMEMobjpool *pop); int pmemobj_check(const char *path, const char *layout); void pmemobj_set_user_data(PMEMobjpool *pop, void *data); void *pmemobj_get_user_data(PMEMobjpool *pop); \f[R] .fi .SH DESCRIPTION .PP To use the pmem-resident transactional object store provided by \f[B]libpmemobj\f[R](7), a \f[I]memory pool\f[R] must first be created with the \f[B]pmemobj_create\f[R]() function described below. Existing pools may be opened with the \f[B]pmemobj_open\f[R]() function. .PP As of \f[B]libpmemobj\f[R] \f[B]1.11\f[R], these functions are thread-safe; be careful if you have to use earlier versions of the library. .PP Once created, the memory pool is represented by an opaque handle, of type \f[I]PMEMobjpool*\f[R], which is passed to most of the other \f[B]libpmemobj\f[R](7) functions. Internally, \f[B]libpmemobj\f[R](7) will use either \f[B]pmem_persist\f[R](3) or \f[B]msync\f[R](2) when it needs to flush changes, depending on whether the memory pool appears to be persistent memory or a regular file (see the \f[B]pmem_is_pmem\f[R](3) function in \f[B]libpmem\f[R](7) for more information). There is no need for applications to flush changes directly when using the object memory API provided by \f[B]libpmemobj\f[R](7). .PP The \f[B]pmemobj_create\f[R]() function creates a transactional object store with the given total \f[I]poolsize\f[R]. \f[I]path\f[R] specifies the name of the memory pool file to be created. \f[I]layout\f[R] specifies the application\[cq]s layout type in the form of a string. The layout name is not interpreted by \f[B]libpmemobj\f[R](7), but may be used as a check when \f[B]pmemobj_open\f[R]() is called. The layout name, including the terminating null byte (`\[rs]0'), cannot be longer than \f[B]PMEMOBJ_MAX_LAYOUT\f[R] as defined in \f[B]\f[R]. A NULL \f[I]layout\f[R] is equivalent to using an empty string as a layout name. \f[I]mode\f[R] specifies the permissions to use when creating the file, as described by \f[B]creat\f[R](2). The memory pool file is fully allocated to the size \f[I]poolsize\f[R] using \f[B]posix_fallocate\f[R](3). The caller may choose to take responsibility for creating the memory pool file by creating it before calling \f[B]pmemobj_create\f[R](), and then specifying \f[I]poolsize\f[R] as zero. In this case \f[B]pmemobj_create\f[R]() 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 minimum net pool size allowed by the library for a local transactional object store is defined in \f[B]\f[R] as \f[B]PMEMOBJ_MIN_POOL\f[R]. .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 pmemobj memory pool could be limited by the capacity of a single memory device. \f[B]libpmemobj\f[R](7) allows building persistent memory resident object store 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[R] 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]pmemobj_create\f[R](); however, the recommended method for creating pool sets is with the \f[B]pmempool\f[R](1) utility. .PP When creating a pool set consisting of multiple files, the \f[I]path\f[R] argument passed to \f[B]pmemobj_create\f[R]() must point to the special \f[I]set\f[R] file that defines the pool layout and the location of all the parts of the pool set. The \f[I]poolsize\f[R] argument must be 0. The meaning of the \f[I]layout\f[R] and \f[I]mode\f[R] arguments does not change, except that the same \f[I]mode\f[R] is used for creation of all the parts of the pool set. .PP The \f[I]set\f[R] file is a plain text file, the structure of which is described in \f[B]poolset\f[R](5). .PP The \f[B]pmemobj_open\f[R]() function opens an existing object store memory pool. Similar to \f[B]pmemobj_create\f[R](), \f[I]path\f[R] must identify either an existing obj memory pool file, or the \f[I]set\f[R] file used to create a pool set. If \f[I]layout\f[R] is non-NULL, it is compared to the layout name provided to \f[B]pmemobj_create\f[R]() when the pool was first created. This can be used to verify that the layout of the pool matches what was expected. The application must have permission to open the file and memory map it with read/write permissions. .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[R](1). .PP The \f[B]pmemobj_close\f[R]() function closes the memory pool indicated by \f[I]pop\f[R] and deletes the memory pool handle. The object store itself lives on in the file that contains it and may be re-opened at a later time using \f[B]pmemobj_open\f[R]() as described above. .PP The \f[B]pmemobj_check\f[R]() function performs a consistency check of the file indicated by \f[I]path\f[R]. \f[B]pmemobj_check\f[R]() opens the given \f[I]path\f[R] read-only so it never makes any changes to the file. This function is not supported on Device DAX. .PP The \f[B]pmemobj_set_user_data\f[R]() function associates custom volatile state, represented by pointer \f[I]data\f[R], with the given pool \f[I]pop\f[R]. This state can later be retrieved using \f[B]pmemobj_get_user_data\f[R]() function. This state does not survive pool close. If \f[B]pmemobj_set_user_data\f[R]() was not called for a given pool, \f[B]pmemobj_get_user_data\f[R]() will return NULL. .SH RETURN VALUE .PP The \f[B]pmemobj_create\f[R]() function returns a memory pool handle to be used with most of the functions in \f[B]libpmemobj\f[R](7). On error it returns NULL and sets \f[I]errno\f[R] appropriately. .PP The \f[B]pmemobj_open\f[R]() function returns a memory pool handle to be used with most of the functions in \f[B]libpmemobj\f[R](7). If an error prevents the pool from being opened, or if the given \f[I]layout\f[R] does not match the pool\[cq]s layout, \f[B]pmemobj_open\f[R]() returns NULL and sets \f[I]errno\f[R] appropriately. .PP The \f[B]pmemobj_close\f[R]() function returns no value. .PP The \f[B]pmemobj_check\f[R]() function returns 1 if the memory pool is found to be consistent. Any inconsistencies found will cause \f[B]pmemobj_check\f[R]() to return 0, in which case the use of the file with \f[B]libpmemobj\f[R](7) will result in undefined behavior. The debug version of \f[B]libpmemobj\f[R](7) will provide additional details on inconsistencies when \f[B]PMEMOBJ_LOG_LEVEL\f[R] is at least 1, as described in the \f[B]DEBUGGING AND ERROR HANDLING\f[R] section in \f[B]libpmemobj\f[R](7). \f[B]pmemobj_check\f[R]() returns -1 and sets \f[I]errno\f[R] if it cannot perform the consistency check due to other errors. .SH CAVEATS .PP Not all file systems support \f[B]posix_fallocate\f[R](3). \f[B]pmemobj_create\f[R]() will fail if the underlying file system does not support \f[B]posix_fallocate\f[R](3). .SH SEE ALSO .PP \f[B]creat\f[R](2), \f[B]msync\f[R](2), \f[B]pmem_is_pmem\f[R](3), \f[B]pmem_persist\f[R](3), \f[B]posix_fallocate\f[R](3), \f[B]libpmem\f[R](7), \f[B]libpmemobj\f[R](7) and \f[B]\f[R]