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

NAME

6       pmem2_source_device_id() - returns the unique identifier of a device
7

SYNOPSIS

9              #include <libpmem2.h>
10
11              struct pmem2_source;
12              int pmem2_source_device_id(const struct pmem2_source *source, char *id, size_t *len);
13

DESCRIPTION

15       The  pmem2_source_device_id() function retrieves a unique identifier of
16       all NVDIMMs backing the data source.  This function has  two  operating
17       modes:
18
19       • if  *id  is NULL the function calculates a buffer length required for
20         storing the identifier of the *source device and puts this length  in
21         *len  The  more hardware devices back the data source, the longer the
22         length is.
23
24       • if *id is not NULL it must point to a buffer of length *len  provided
25         by  the previous call to this function.  On success, pmem2_source_de‐
26         vice_id() will store a unique  identifier  of  all  hardware  devices
27         backing the data source.
28
29       For  details  on how to use the unique identifier for detecting the un‐
30       safe shutdown please refer to libpmem2_unsafe_shutdown(7) manual page.
31

RETURN VALUE

33       The pmem2_source_device_id() function returns 0  on  success.   If  the
34       function fails, the *id and *len variables contents are left unmodified
35       and a negative error code is returned.
36

ERRORS

38       The pmem2_source_device_id() can fail with the following errors:
39
40       On all systems:
41
42       • PMEM2_E_BUFFER_TOO_SMALL - the provided buffer of length *len is  too
43         small to store the full identifier of the backing devices.
44
45       • PMEM2_E_NOSUPP  -  the  underlying  platform does not expose hardware
46         identification.
47
48       On Windows:
49
50       • -errno equivalent of return code set by  failing  GetFinalPathNameBy‐
51         HandleW(), while trying to resolve the volume path from the file han‐
52         dle.
53
54       • -errno set by failing malloc(3), while trying to  allocate  a  buffer
55         for storing volume path.
56
57       • -errno  equivalent of return code set by failing CreateFileW(), while
58         trying to obtain a handle to the volume.
59
60       • -errno equivalent of return code set  by  failing  DeviceIoControl(),
61         while trying to obtain volume USC value.
62
63       On Linux:
64
65       • -errno set by failing fstat(2), while trying to validate the file de‐
66         scriptor.
67
68       • -errno set by failing ndctl_new(), while trying to initiate a new ND‐
69         CTL library context.
70

SEE ALSO

72       fstat(2),   errno(3),   malloc(3),   libpmem2_unsafe_shutdown(7),   and
73       <https://pmem.io>
74
75
76
77PMDK -                            2023-06-05                                ()
Impressum