.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_SOURCE_FROM_FD" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[](), \f[B]pmem2_source_from_handle\f[](),
\f[B]pmem2_source_delete\f[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
On Linux the \f[B]pmem2_source_from_fd\f[]() 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[]() function converts a file
descriptor to a file handle (using **_get_osfhandle\f[B]()), and passes
it to \f[]pmem2_source_from_handle\f[B](). By default
\f[]_get_osfhandle\f[B]() calls abort() in case of invalid file
descriptor, but this behavior can be suppressed by
\f[]_set_abort_behavior\f[B]() and \f[]SetErrorMode**() functions.
Please check MSDN documentation for more information about Windows CRT
error handling.
.PP
\f[I]fd\f[] must be opened with \f[I]O_RDONLY\f[] or \f[I]O_RDWR\f[]
mode, but on Windows it is not validated.
.PP
If \f[I]fd\f[] is invalid, then the function fails.
.PP
The \f[B]pmem2_source_from_handle\f[]() 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[]CreateFile**()
documentation.
.PP
The \f[B]pmem2_source_delete\f[]() function frees \f[I]*src\f[] returned
by \f[B]pmem2_source_from_fd\f[]() or
\f[B]pmem2_source_from_handle\f[]() and sets \f[I]*src\f[] to NULL.
If \f[I]*src\f[] is NULL, no operation is performed.
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_from_fd\f[]() and
\f[B]pmem2_source_from_handle\f[]() functions return 0 on success or a
negative error code on failure.
.PP
The \f[B]pmem2_source_delete\f[]() function always returns 0.
.SH ERRORS
.PP
The \f[B]pmem2_source_from_fd\f[]()/\f[B]pmem2_source_from_handle\f[]()
functions can fail with the following errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[] \- \f[I]fd\f[] is not an open and
valid file descriptor.
On Windows the function can \f[B]abort\f[]() on this failure based on
CRT's abort() behavior.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[] \- \f[I]fd\f[] is opened in
O_WRONLY mode.
.PP
On Linux:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[] \- \f[I]fd\f[] points to a directory,
block device, pipe, or socket.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[] \- \f[I]fd\f[] points to a character
device other than Device DAX.
.PP
On Windows:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[] \- \f[I]handle\f[] points to a
resource that is not a regular file.
.PP
On Windows \f[B]pmem2_source_from_fd\f[]() can return all errors from
the underlying \f[B]pmem2_source_from_handle\f[]() function.
.PP
The \f[B]pmem2_source_from_handle\f[]() can return the following errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_HANDLE\f[] \- \f[I]handle\f[] points to a
resource that is not a file.
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[] \- \f[I]handle\f[] points to a
directory.
.PP
The \f[B]pmem2_source_from_fd\f[]() and
\f[B]pmem2_source_from_handle\f[]() functions can also return
\f[B]\-ENOMEM\f[] in case of insufficient memory to allocate an instance
of \f[I]struct pmem2_source\f[].
.SH CAVEATS
.PP
On non\-DAX Windows volumes, \f[I]fd\f[]/\f[I]handle\f[] must remain
open while the mapping is in use.
.SH SEE ALSO
.PP
\f[B]errno\f[](3), \f[B]pmem2_map_new\f[](3), \f[B]libpmem2\f[](7) and
\f[B]<https://pmem.io>\f[]