.\" 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 2020, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_source_device_id\f[R]() - returns the unique identifier of a
device
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_source;
int pmem2_source_device_id(const struct pmem2_source *source, char *id, size_t *len);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_source_device_id\f[R]() function retrieves a unique
identifier of all NVDIMMs backing the data source.
This function has two operating modes:
.IP \[bu] 2
if \f[I]*id\f[R] is NULL the function calculates a buffer length
required for storing the identifier of the \f[I]*source\f[R] device and
puts this length in \f[I]*len\f[R] The more hardware devices back the
data source, the longer the length is.
.IP \[bu] 2
if \f[I]*id\f[R] is not NULL it must point to a buffer of length
\f[I]*len\f[R] provided by the previous call to this function.
On success, \f[B]pmem2_source_device_id\f[R]() will store a unique
identifier of all hardware devices backing the data source.
.PP
For details on how to use the unique identifier for detecting \f[I]the
unsafe shutdown\f[R] please refer to
\f[B]libpmem2_unsafe_shutdown\f[R](7) manual page.
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_device_id\f[R]() function returns 0 on success.
If the function fails, the \f[I]*id\f[R] and \f[I]*len\f[R] variables
contents are left unmodified and a negative error code is returned.
.SH ERRORS
.PP
The \f[B]pmem2_source_device_id\f[R]() can fail with the following
errors:
.PP
On all systems:
.IP \[bu] 2
\f[B]PMEM2_E_BUFFER_TOO_SMALL\f[R] - the provided buffer of length
\f[I]*len\f[R] is too small to store the full identifier of the backing
devices.
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[R] - the underlying platform does not expose
hardware identification.
.PP
On Windows:
.IP \[bu] 2
-\f[B]errno\f[R] equivalent of return code set by failing
\f[B]GetFinalPathNameByHandleW\f[R](), while trying to resolve the
volume path from the file handle.
.IP \[bu] 2
-\f[B]errno\f[R] set by failing \f[B]malloc\f[R](3), while trying to
allocate a buffer for storing volume path.
.IP \[bu] 2
-\f[B]errno\f[R] equivalent of return code set by failing
\f[B]CreateFileW\f[R](), while trying to obtain a handle to the volume.
.IP \[bu] 2
-\f[B]errno\f[R] equivalent of return code set by failing
\f[B]DeviceIoControl\f[R](), while trying to obtain volume \f[B]USC\f[R]
value.
.PP
On Linux:
.IP \[bu] 2
-\f[B]errno\f[R] set by failing \f[B]fstat\f[R](2), while trying to
validate the file descriptor.
.IP \[bu] 2
-\f[B]errno\f[R] set by failing \f[B]ndctl_new\f[R](), while trying to
initiate a new NDCTL library context.
.SH SEE ALSO
.PP
\f[B]fstat\f[R](2), \f[B]errno\f[R](3), \f[B]malloc\f[R](3),
\f[B]libpmem2_unsafe_shutdown\f[R](7), and \f[B]<https://pmem.io>\f[R]