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>