pmem2_source_from_handle(3)

1PMEM2_SOURCE_FROM_FD(3)    PMDK Programmer's Manual    PMEM2_SOURCE_FROM_FD(3)
2
3
4

NAME

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

SYNOPSIS

11              #include <libpmem2.h>
12
13              int pmem2_source_from_fd(struct pmem2_source *src, int fd);
14              int pmem2_source_from_handle(struct pmem2_source *src, HANDLE handle); /* Windows only */
15              int pmem2_source_delete(struct pmem2_source **src);
16

DESCRIPTION

18       On  Linux  the  pmem2_source_from_fd()  function validates the file de‐
19       scriptor and instantiates a new *struct pmem2_source** object  describ‐
20       ing the data source.
21
22       On Windows the pmem2_source_from_fd() function converts a file descrip‐
23       tor to a file handle  (using  **_get_osfhandle()),  and  passes  it  to
24       pmem2_source_from_handle().  By  default _get_osfhandle() calls abort()
25       in case of invalid file descriptor, but this behavior can be suppressed
26       by  _set_abort_behavior() and SetErrorMode**() functions.  Please check
27       MSDN documentation for more information about Windows  CRT  error  han‐
28       dling.
29
30       fd  must  be  opened with O_RDONLY or O_RDWR mode, but on Windows it is
31       not validated.
32
33       If fd is invalid, then the function fails.
34
35       The pmem2_source_from_handle() function validates the  handle  and  in‐
36       stantiates  a  new  *struct  pmem2_source  object  describing  the data
37       source. If handle is INVALID_HANDLE_VALUE, then the function fails. The
38       handle has to be created with an access mode of GENERIC_READ or (GENER‐
39       IC_READ | GENERIC_WRITE). For details  please  see  the  CreateFile**()
40       documentation.
41
42       The    pmem2_source_delete()    function   frees   *src   returned   by
43       pmem2_source_from_fd() or pmem2_source_from_handle() and sets  *src  to
44       NULL.  If *src is NULL, no operation is performed.
45

RETURN VALUE

47       The pmem2_source_from_fd() and pmem2_source_from_handle() functions re‐
48       turn 0 on success or a negative error code on failure.
49
50       The pmem2_source_delete() function always returns 0.
51

ERRORS

53       The  pmem2_source_from_fd()/pmem2_source_from_handle()  functions   can
54       fail with the following errors:
55
56       • PMEM2_E_INVALID_FILE_HANDLE  -  fd  is not an open and valid file de‐
57         scriptor.  On Windows the function can abort() on this failure  based
58         on CRT's abort() behavior.
59
60       • PMEM2_E_INVALID_FILE_HANDLE - fd is opened in O_WRONLY mode.
61
62       On Linux:
63
64       • PMEM2_E_INVALID_FILE_TYPE  -  fd points to a directory, block device,
65         pipe, or socket.
66
67       • PMEM2_E_INVALID_FILE_TYPE - fd points to  a  character  device  other
68         than Device DAX.
69
70       On Windows:
71
72       • PMEM2_E_INVALID_FILE_TYPE - handle points to a resource that is not a
73         regular file.
74
75       On Windows pmem2_source_from_fd() can return all errors from the under‐
76       lying pmem2_source_from_handle() function.
77
78       The pmem2_source_from_handle() can return the following errors:
79
80       • PMEM2_E_INVALID_FILE_HANDLE - handle points to a resource that is not
81         a file.
82
83       • PMEM2_E_INVALID_FILE_TYPE - handle points to a directory.
84
85       The pmem2_source_from_fd() and pmem2_source_from_handle() functions can
86       also  return  -ENOMEM in case of insufficient memory to allocate an in‐
87       stance of struct pmem2_source.
88

CAVEATS

90       On non-DAX Windows volumes, fd/handle must remain open while  the  map‐
91       ping is in use.
92

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

CAVEATS

SEE ALSO