Merge pull request #5011 from wlemkows/pmem2-source-get-fd-handle

pmem2: source get fd/handle

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 \

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

doc/libpmem2/pmem2_source_get_fd.3.md

+---
+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>**

doc/libpmem2/pmem2_source_get_handle.3.md

+---
+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>**

src/include/libpmem2.h

@@ -70,6 +70,7 @@ extern "C" {
 #define PMEM2_E_NO_ACCESS			(-100032)
 #define PMEM2_E_VM_RESERVATION_NOT_EMPTY	(-100033)
 #define PMEM2_E_MAP_EXISTS			(-100034)
+#define PMEM2_E_FILE_DESCRIPTOR_NOT_SET		(-100035)
 
 /* source setup */
 
@@ -79,6 +80,9 @@ int pmem2_source_from_fd(struct pmem2_source **src, int fd);
 int pmem2_source_from_anon(struct pmem2_source **src, size_t size);
 #ifdef _WIN32
 int pmem2_source_from_handle(struct pmem2_source **src, HANDLE handle);
+int pmem2_source_get_handle(const struct pmem2_source *src, HANDLE *h);
+#else
+int pmem2_source_get_fd(const struct pmem2_source *src, int *fd);
 #endif
 
 int pmem2_source_size(const struct pmem2_source *src, size_t *size);

src/libpmem2/libpmem2.def

@@ -45,6 +45,7 @@ EXPORTS
 	pmem2_source_from_anon
 	pmem2_source_from_fd
 	pmem2_source_from_handle
+	pmem2_source_get_handle
 	pmem2_source_size
 	pmem2_vm_reservation_delete
 	pmem2_vm_reservation_get_address

src/libpmem2/libpmem2.link.in

@@ -40,6 +40,7 @@ LIBPMEM2_1.0 {
 		pmem2_source_from_anon;
 		pmem2_source_from_fd;
 		pmem2_source_from_handle;
+		pmem2_source_get_fd;
 		pmem2_source_size;
 		pmem2_vm_reservation_delete;
 		pmem2_vm_reservation_get_address;

src/libpmem2/source_posix.c

@@ -174,3 +174,23 @@ pmem2_source_alignment(const struct pmem2_source *src, size_t *alignment)
 
 	return 0;
 }
+
+/*
+ * pmem2_source_get_fd -- get file descriptor from provided source
+ */
+int
+pmem2_source_get_fd(const struct pmem2_source *src, int *fd)
+{
+	LOG(3, "src type %d", src->type);
+	PMEM2_ERR_CLR();
+
+	if (src->type == PMEM2_SOURCE_FD) {
+		*fd = src->value.fd;
+	} else {
+		ERR(
+			"File descriptor is not set, source type does not support fd");
+		return PMEM2_E_FILE_DESCRIPTOR_NOT_SET;
+	}
+
+	return 0;
+}

src/libpmem2/source_windows.c

@@ -161,3 +161,23 @@ pmem2_source_alignment(const struct pmem2_source *src, size_t *alignment)
 
 	return 0;
 }
+
+/*
+ * pmem2_source_get_handle -- get file handler from provided source
+ */
+int
+pmem2_source_get_handle(const struct pmem2_source *src, HANDLE *h)
+{
+	LOG(3, "src type %d", src->type);
+	PMEM2_ERR_CLR();
+
+	if (src->type == PMEM2_SOURCE_HANDLE) {
+		*h = src->value.handle;
+	} else {
+		ERR(
+			"File handle is not set, source type does not support file handles");
+		return PMEM2_E_FILE_HANDLE_NOT_SET;
+	}
+
+	return 0;
+}

src/test/pmem2_source/TESTS.py

@@ -94,3 +94,27 @@ class TEST11(PMEM2_SOURCE):
 
     def run(self, ctx):
         ctx.exec('pmem2_source', self.test_case, ctx.testdir)
+
+
+@t.windows_only
+class TEST12(PMEM2_SOURCE):
+    """get handle from the source"""
+    test_case = "test_get_handle"
+
+
+@t.windows_exclude
+class TEST13(PMEM2_SOURCE):
+    """get file descriptor from the source"""
+    test_case = "test_get_fd"
+
+
+@t.windows_only
+class TEST14(PMEM2_SOURCE_NO_DIR):
+    """get handle from the invalid source type"""
+    test_case = "test_get_handle_inval_type"
+
+
+@t.windows_exclude
+class TEST15(PMEM2_SOURCE_NO_DIR):
+    """get file descriptor from the invalid source type"""
+    test_case = "test_get_fd_inval_type"

src/test/pmem2_source/pmem2_source.c

@@ -293,6 +293,54 @@ test_set_mutex_handle(const struct test_case *tc, int argc, char *argv[])
 
 	return 0;
 }
+
+/*
+ * test_get_handle - test getting handle value
+ */
+static int
+test_get_handle(const struct test_case *tc, int argc, char *argv[])
+{
+	if (argc < 1)
+		UT_FATAL("usage: test_get_handle <file>");
+
+	char *file = argv[0];
+	HANDLE h = CreateFile(file, GENERIC_READ | GENERIC_WRITE,
+		0, NULL, OPEN_ALWAYS, 0, NULL);
+	UT_ASSERTne(h, INVALID_HANDLE_VALUE);
+
+	struct pmem2_source *src;
+	int ret = pmem2_source_from_handle(&src, h);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	HANDLE handle_from_pmem2;
+	ret = pmem2_source_get_handle(src, &handle_from_pmem2);
+	UT_ASSERTeq(handle_from_pmem2, h);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	CloseHandle(h);
+	pmem2_source_delete(&src);
+
+	return 1;
+}
+
+/*
+ * test_get_handle_inval_type - test getting handle value from invalid type
+ */
+static int
+test_get_handle_inval_type(const struct test_case *tc, int argc, char *argv[])
+{
+	struct pmem2_source *src;
+	int ret = pmem2_source_from_anon(&src, 0);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	HANDLE handle_from_pmem2;
+	ret = pmem2_source_get_handle(src, &handle_from_pmem2);
+	UT_PMEM2_EXPECT_RETURN(ret, PMEM2_E_FILE_HANDLE_NOT_SET);
+
+	pmem2_source_delete(&src);
+
+	return 0;
+}
 #else
 /*
  * test_set_directory_handle - test setting directory's fd
@@ -315,6 +363,53 @@ test_set_directory_fd(const struct test_case *tc, int argc, char *argv[])
 
 	return 1;
 }
+
+/*
+ * test_get_fd - test getting file descriptor value
+ */
+static int
+test_get_fd(const struct test_case *tc, int argc, char *argv[])
+{
+	if (argc < 1)
+		UT_FATAL("usage: test_get_fd <file>");
+
+	char *file = argv[0];
+	int fd = OPEN(file, O_RDONLY);
+	UT_ASSERTne(fd, -1);
+
+	struct pmem2_source *src;
+	int ret = pmem2_source_from_fd(&src, fd);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	int fd_from_pmem2;
+	ret = pmem2_source_get_fd(src, &fd_from_pmem2);
+	UT_ASSERTeq(fd_from_pmem2, fd);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	CLOSE(fd);
+	pmem2_source_delete(&src);
+
+	return 1;
+}
+
+/*
+ * test_get_fd_inval_type - test getting fd value from invalid type
+ */
+static int
+test_get_fd_inval_type(const struct test_case *tc, int argc, char *argv[])
+{
+	struct pmem2_source *src;
+	int ret = pmem2_source_from_anon(&src, 0);
+	UT_PMEM2_EXPECT_RETURN(ret, 0);
+
+	int fd_from_pmem2;
+	ret = pmem2_source_get_fd(src, &fd_from_pmem2);
+	UT_PMEM2_EXPECT_RETURN(ret, PMEM2_E_FILE_DESCRIPTOR_NOT_SET);
+
+	pmem2_source_delete(&src);
+
+	return 0;
+}
 #endif
 
 /*
@@ -333,8 +428,12 @@ static struct test_case test_cases[] = {
 	TEST_CASE(test_set_invalid_handle),
 	TEST_CASE(test_set_directory_handle),
 	TEST_CASE(test_set_mutex_handle),
+	TEST_CASE(test_get_handle),
+	TEST_CASE(test_get_handle_inval_type),
 #else
 	TEST_CASE(test_set_directory_fd),
+	TEST_CASE(test_get_fd),
+	TEST_CASE(test_get_fd_inval_type),
 #endif
 };
 

src/test/scope/out13.log.match

@@ -31,6 +31,7 @@ pmem2_source_device_id$(nW)
 pmem2_source_device_usc$(nW)
 pmem2_source_from_anon$(nW)
 pmem2_source_from_fd$(nW)
+pmem2_source_get_fd$(nW)
 pmem2_source_size$(nW)
 pmem2_vm_reservation_delete$(nW)
 pmem2_vm_reservation_get_address$(nW)

src/test/scope/out14.log.match

@@ -36,6 +36,7 @@ pmem2_source_device_usc
 pmem2_source_from_anon
 pmem2_source_from_fd
 pmem2_source_from_handle
+pmem2_source_get_handle
 pmem2_source_size
 pmem2_vm_reservation_delete
 pmem2_vm_reservation_get_address