diff --git a/doc/Makefile b/doc/Makefile index c635dceb266e9cae9c9e0b782306d45078b8c9a8..1ab350594717d2a7c43862d8791fde51415749ec 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -108,7 +108,9 @@ MANPAGES_3_MD_PMEM2 = libpmem2/pmem2_errormsg.3.md libpmem2/pmem2_config_new.3.m libpmem2/pmem2_badblock_clear.3.md libpmem2/pmem2_config_set_protection.3.md \ libpmem2/pmem2_deep_flush.3.md libpmem2/pmem2_source_from_anon.3.md \ libpmem2/pmem2_source_device_id.3.md libpmem2/pmem2_source_device_usc.3.md \ - libpmem2/pmem2_map_from_existing.3.md + libpmem2/pmem2_map_from_existing.3.md libpmem2/pmem2_source_get_fd.3.md \ + libpmem2/pmem2_source_get_handle.3.md + MANPAGES_1_MD_PMEM2 = ifeq ($(PMEM2_INSTALL),y) MANPAGES_3_DUMMY += libpmem2/pmem2_config_delete.3 libpmem2/pmem2_source_from_handle.3 libpmem2/pmem2_source_delete.3 \ diff --git a/doc/libpmem2/.gitignore b/doc/libpmem2/.gitignore index 8118753d62d16e6ececfaa30885bec97519ff3f2..6c2dd66a535390ca3358f4de8dfd16f91943d2ab 100644 --- a/doc/libpmem2/.gitignore +++ b/doc/libpmem2/.gitignore @@ -25,6 +25,8 @@ pmem2_map_get_store_granularity.3 pmem2_source_alignment.3 pmem2_source_from_fd.3 pmem2_source_from_anon.3 +pmem2_source_get_fd.3 +pmem2_source_get_handle.3 pmem2_source_size.3 pmem2_source_device_id.3 pmem2_source_device_usc.3 diff --git a/doc/libpmem2/pmem2_source_get_fd.3.md b/doc/libpmem2/pmem2_source_get_fd.3.md new file mode 100644 index 0000000000000000000000000000000000000000..982d829e77f36032bf3405c089a4ba298b3505cc --- /dev/null +++ b/doc/libpmem2/pmem2_source_get_fd.3.md @@ -0,0 +1,57 @@ +--- +layout: manual +Content-Style: 'text/css' +title: _MP(PMEM2_SOURCE_GET_FD, 3) +collection: libpmem2 +header: PMDK +date: pmem2 API version 1.0 +... + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_source_get_fd.3 -- man page for pmem2_source_get_fd + +[NAME](#name)<br /> +[SYNOPSIS](#synopsis)<br /> +[DESCRIPTION](#description)<br /> +[RETURN VALUE](#return-value)<br /> +[ERRORS](#errors)<br /> +[SEE ALSO](#see-also)<br /> + +# NAME # + +**pmem2_source_get_fd**() - reads file descriptor of the data source + +# SYNOPSIS # + +```c +#include <libpmem2.h> + +int pmem2_source_get_fd(const struct pmem2_source *src, int *fd); +``` + +# DESCRIPTION # + +The **pmem2_source_get_fd**() function reads the file descriptor of +*struct pmem2_source** object describing the data source and returns it +by *fd* parameter. + +This function is Linux only, on Windows use **pmem2_source_get_handle**(3). + +# RETURN VALUE # + +The **pmem2_source_get_fd**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_source_get_fd**() can fail with the following errors: + +* **PMEM2_E_FILE_DESCRIPTOR_NOT_SET** - in case of an instance of +*struct pmem2_source* that does not come from source type that +support file descriptors, eg. anonymous data source. + +# SEE ALSO # + +**pmem2_source_get_handle**(3), **libpmem2**(7) and **<http://pmem.io>** diff --git a/doc/libpmem2/pmem2_source_get_handle.3.md b/doc/libpmem2/pmem2_source_get_handle.3.md new file mode 100644 index 0000000000000000000000000000000000000000..0156d1e7b5eaaf0a34b48de72432e372b8f6d48e --- /dev/null +++ b/doc/libpmem2/pmem2_source_get_handle.3.md @@ -0,0 +1,62 @@ +--- +layout: manual +Content-Style: 'text/css' +title: _MP(PMEM2_SOURCE_GET_HANDLE, 3) +collection: libpmem2 +header: PMDK +date: pmem2 API version 1.0 +... + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_source_get_handsle.3 -- man page for pmem2_source_get_handle + +[NAME](#name)<br /> +[SYNOPSIS](#synopsis)<br /> +[DESCRIPTION](#description)<br /> +[RETURN VALUE](#return-value)<br /> +[ERRORS](#errors)<br /> +[SEE ALSO](#see-also)<br /> + +# NAME # + +**pmem2_source_get_handle**() - reads file handler of the data source + +# SYNOPSIS # + +```c +#include <libpmem2.h> + +int pmem2_source_get_handle(const struct pmem2_source *src, HANDLE *h); +``` + +# DESCRIPTION # + +The **pmem2_source_get_handle**() function reads the file handler of +*struct pmem2_source** object describing the data source and returns +it by *h* parameter. + +This function is Windows only, on Linux use **pmem2_source_get_fd**(3). +If the source was created using **pmem2_source_from_fd**(3) then +**pmem2_source_get_handle**() is also valid function to read handler, because +file descriptor is converted to file handle during source creation. + +However, there are limitations to what you can do with a handle created from a file descriptor. +For details refer to **DESCRIPTION** section in the **pmem2_source_from_fd**(3) manpage. + +# ERRORS # + +The **pmem2_source_get_handle**() can fail with the following errors: + +* **PMEM2_E_FILE_HANDLE_NOT_SET** - in case of an instance of +*struct pmem2_source* that does not come from source type that +support file handles, eg. anonymous data source. + +# RETURN VALUE # + +The **pmem2_source_get_handle**() returns a file handle of data source. + +# SEE ALSO # + +**pmem2_source_from_fd**(3), **pmem2_source_get_fd**(3), **libpmem2**(7) and **<http://pmem.io>**