From 8d8dea49f2c0cc7ab063be580feba033c3446b61 Mon Sep 17 00:00:00 2001
From: Weronika Lewandowska <weronika.lewandowska@intel.com>
Date: Tue, 13 Oct 2020 11:55:20 +0200
Subject: [PATCH] doc: add pmem2_source_get_fd/handle mans

---
 doc/Makefile                              |  4 +-
 doc/libpmem2/.gitignore                   |  2 +
 doc/libpmem2/pmem2_source_get_fd.3.md     | 57 +++++++++++++++++++++
 doc/libpmem2/pmem2_source_get_handle.3.md | 62 +++++++++++++++++++++++
 4 files changed, 124 insertions(+), 1 deletion(-)
 create mode 100644 doc/libpmem2/pmem2_source_get_fd.3.md
 create mode 100644 doc/libpmem2/pmem2_source_get_handle.3.md

diff --git a/doc/Makefile b/doc/Makefile
index c635dceb2..1ab350594 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 8118753d6..6c2dd66a5 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 000000000..982d829e7
--- /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 000000000..0156d1e7b
--- /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>**
-- 
GitLab