.\" 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 2019-2021, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_source_from_fd\f[R](), \f[B]pmem2_source_from_handle\f[R](),
\f[B]pmem2_source_delete\f[R]() - creates or deletes an instance of
persistent memory data source
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
On Linux the \f[B]pmem2_source_from_fd\f[R]() function validates the
file descriptor and instantiates a new *struct pmem2_source** object
describing the data source.
.PP
On Windows the \f[B]pmem2_source_from_fd\f[R]() function converts a file
descriptor to a file handle (using **_get_osfhandle\f[B]()), and passes
it to \f[R]pmem2_source_from_handle\f[B](). By default
\f[R]_get_osfhandle\f[B]() calls abort() in case of invalid file
descriptor, but this behavior can be suppressed by
\f[R]_set_abort_behavior\f[B]() and \f[R]SetErrorMode**() functions.
Please check MSDN documentation for more information about Windows CRT
error handling.
.PP
\f[I]fd\f[R] must be opened with \f[I]O_RDONLY\f[R] or \f[I]O_RDWR\f[R]
mode, but on Windows it is not validated.
.PP
If \f[I]fd\f[R] is invalid, then the function fails.
.PP
The \f[B]pmem2_source_from_handle\f[R]() function validates the handle
and instantiates a new *struct pmem2_source\f[B] object describing the
data source. If \f[BI]handle\f[B] is \f[BI]INVALID_HANDLE_VALUE\f[B],
then the function fails. The handle has to be created with an access
mode of \f[BI]GENERIC_READ\f[B] or \f[BI](GENERIC_READ |
GENERIC_WRITE)\f[B]. For details please see the \f[R]CreateFile**()
documentation.
.PP
The \f[B]pmem2_source_delete\f[R]() function frees \f[I]*src\f[R]
returned by \f[B]pmem2_source_from_fd\f[R]() or
\f[B]pmem2_source_from_handle\f[R]() and sets \f[I]*src\f[R] to NULL.
If \f[I]*src\f[R] is NULL, no operation is performed.
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_from_fd\f[R]() and
\f[B]pmem2_source_from_handle\f[R]() functions return 0 on success or a
negative error code on failure.
.PP
The \f[B]pmem2_source_delete\f[R]() function always returns 0.
.SH ERRORS
.PP
The
\f[B]pmem2_source_from_fd\f[R]()/\f[B]pmem2_source_from_handle\f[R]()
functions can fail with the following errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[R] - \f[I]fd\f[R] is not an open and
valid file descriptor.
On Windows the function can \f[B]abort\f[R]() on this failure based on
CRT\[cq]s abort() behavior.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[R] - \f[I]fd\f[R] is opened in
O_WRONLY mode.
.PP
On Linux:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[R] - \f[I]fd\f[R] points to a
directory, block device, pipe, or socket.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[R] - \f[I]fd\f[R] points to a character
device other than Device DAX.
.PP
On Windows:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[R] - \f[I]handle\f[R] points to a
resource that is not a regular file.
.PP
On Windows \f[B]pmem2_source_from_fd\f[R]() can return all errors from
the underlying \f[B]pmem2_source_from_handle\f[R]() function.
.PP
The \f[B]pmem2_source_from_handle\f[R]() can return the following
errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[R] - \f[I]handle\f[R] points to a
resource that is not a file.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[R] - \f[I]handle\f[R] points to a
directory.
.PP
The \f[B]pmem2_source_from_fd\f[R]() and
\f[B]pmem2_source_from_handle\f[R]() functions can also return
\f[B]-ENOMEM\f[R] in case of insufficient memory to allocate an instance
of \f[I]struct pmem2_source\f[R].
.SH CAVEATS
.PP
On non-DAX Windows volumes, \f[I]fd\f[R]/\f[I]handle\f[R] must remain
open while the mapping is in use.
.SH SEE ALSO
.PP
\f[B]errno\f[R](3), \f[B]pmem2_map_new\f[R](3), \f[B]libpmem2\f[R](7)
and \f[B]<https://pmem.io>\f[R]