Man page - pmem2_source_from_fd(3)

Packages contains this manual

Package:  libpmem2-dev
apt-get install libpmem2-dev

Manuals in package:
• pmem2_get_memset_fn(3)
• pmem2_map_delete(3)
• pmem2_source_get_fd(3)
• pmem2_vm_reservation_map_find_prev(3)
• pmem2_source_from_handle(3)
• pmem2_vm_reservation_get_address(3)
• pmem2_config_set_vm_reservation(3)
• pmem2_source_device_id(3)
• pmem2_badblock_clear(3)
• pmem2_async(3)
• pmem2_vm_reservation_map_find_first(3)
• pmem2_vm_reservation_map_find_last(3)
• pmem2_map_from_existing(3)
• pmem2_config_new(3)
• pmem2_badblock_context_new(3)
• pmem2_deep_flush(3)
• pmem2_memcpy_async(3)
• pmem2_source_delete(3)
• pmem2_source_pread_mcsafe(3)
• pmem2_vm_reservation_extend(3)
• pmem2_source_alignment(3)
• pmem2_config_set_sharing(3)
• pmem2_badblock_next(3)
• pmem2_badblock_context_delete(3)
• pmem2_source_numa_node(3)
• pmem2_vm_reservation_shrink(3)
• pmem2_config_set_length(3)
• pmem2_source_size(3)
• pmem2_vm_reservation_map_find_next(3)
• pmem2_vm_reservation_new(3)
• pmem2_map_get_size(3)
• pmem2_config_set_required_store_granularity(3)
• pmem2_source_from_fd(3)
• pmem2_get_memmove_fn(3)
• pmem2_get_flush_fn(3)
• pmem2_vm_reservation_get_size(3)
• pmem2_memset_async(3)
• pmem2_map_get_address(3)
• pmem2_get_drain_fn(3)
• pmem2_memmove_async(3)
• pmem2_perror(3)
• pmem2_errormsg(3)
• pmem2_config_set_protection(3)
• pmem2_source_device_usc(3)
• pmem2_config_delete(3)
• pmem2_config_set_vdm(3)
• pmem2_get_persist_fn(3)
• pmem2_vm_reservation_delete(3)
• pmem2_map_new(3)
• pmem2_source_from_anon(3)
• libpmem2_unsafe_shutdown(7)
• pmem2_source_get_handle(3)
• pmem2_vm_reservation_map_find(3)
• pmem2_get_memcpy_fn(3)
• libpmem2(7)
• pmem2_config_set_offset(3)
• pmem2_source_pwrite_mcsafe(3)
• pmem2_map_get_store_granularity(3)
Documentations in package:
• libpmem2-dev

Manual

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
CAVEATS
SEE ALSO

---

NAME

pmem2_source_from_fd (), pmem2_source_from_handle (), pmem2_source_delete () - creates or deletes an instance of persistent memory data source

SYNOPSIS

#include <libpmem2.h>


int pmem2_source_from_fd(struct pmem2_source *src, int fd);
int pmem2_source_from_handle(struct pmem2_source *src, HANDLE handle); /* Windows only */
int pmem2_source_delete(struct pmem2_source **src);

DESCRIPTION

On Linux the pmem2_source_from_fd () function validates the file descriptor and instantiates a new *struct pmem2_source** object describing the data source.

On Windows the pmem2_source_from_fd () function converts a file descriptor to a file handle (using **_get_osfhandle ()), and passes it to pmem2_source_from_handle (). By default _get_osfhandle () calls abort() in case of invalid file descriptor, but this behavior can be suppressed by _set_abort_behavior () and SetErrorMode**() functions. Please check MSDN documentation for more information about Windows CRT error handling.

fd must be opened with O_RDONLY or O_RDWR mode, but on Windows it is not validated.

If fd is invalid, then the function fails.

The pmem2_source_from_handle () function validates the handle and instantiates a new *struct pmem2_source object describing the data source. If handle is INVALID_HANDLE_VALUE , then the function fails. The handle has to be created with an access mode of GENERIC_READ or (GENERIC_READ | GENERIC_WRITE) . For details please see the CreateFile**() documentation.

The pmem2_source_delete () function frees *src returned by pmem2_source_from_fd () or pmem2_source_from_handle () and sets *src to NULL. If *src is NULL, no operation is performed.

RETURN VALUE

The pmem2_source_from_fd () and pmem2_source_from_handle () functions return 0 on success or a negative error code on failure.

The pmem2_source_delete () function always returns 0.

ERRORS

The pmem2_source_from_fd ()/ pmem2_source_from_handle () functions can fail with the following errors:

	•		PMEM2_E_INVALID_FILE_HANDLE - fd is not an open and valid file descriptor. On Windows the function can abort () on this failure based on CRT’s abort() behavior.
	•		PMEM2_E_INVALID_FILE_HANDLE - fd is opened in O_WRONLY mode.

On Linux:

	•		PMEM2_E_INVALID_FILE_TYPE - fd points to a directory, block device, pipe, or socket.
	•		PMEM2_E_INVALID_FILE_TYPE - fd points to a character device other than Device DAX.

On Windows:

•

PMEM2_E_INVALID_FILE_TYPE - handle points to a resource that is not a regular file.

On Windows pmem2_source_from_fd () can return all errors from the underlying pmem2_source_from_handle () function.

The pmem2_source_from_handle () can return the following errors:

	•		PMEM2_E_INVALID_FILE_HANDLE - handle points to a resource that is not a file.
	•		PMEM2_E_INVALID_FILE_TYPE - handle points to a directory.

The pmem2_source_from_fd () and pmem2_source_from_handle () functions can also return -ENOMEM in case of insufficient memory to allocate an instance of struct pmem2_source .

CAVEATS

On non-DAX Windows volumes, fd / handle must remain open while the mapping is in use.

SEE ALSO

errno (3), pmem2_map_new (3), libpmem2 (7) and <https://pmem.io>

---