.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_SOURCE_DEVICE_ID" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_source_device_id\f[]() 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[] is NULL the function calculates a buffer length required
for storing the identifier of the \f[I]*source\f[] device and puts this
length in \f[I]*len\f[] The more hardware devices back the data source,
the longer the length is.
.IP \[bu] 2
if \f[I]*id\f[] is not NULL it must point to a buffer of length
\f[I]*len\f[] provided by the previous call to this function.
On success, \f[B]pmem2_source_device_id\f[]() 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[] please refer to \f[B]libpmem2_unsafe_shutdown\f[](7)
manual page.
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_device_id\f[]() function returns 0 on success.
If the function fails, the \f[I]*id\f[] and \f[I]*len\f[] variables
contents are left unmodified and a negative error code is returned.
.SH ERRORS
.PP
The \f[B]pmem2_source_device_id\f[]() can fail with the following
errors:
.PP
On all systems:
.IP \[bu] 2
\f[B]PMEM2_E_BUFFER_TOO_SMALL\f[] \- the provided buffer of length
\f[I]*len\f[] is too small to store the full identifier of the backing
devices.
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[] \- the underlying platform does not expose
hardware identification.
.PP
On Windows:
.IP \[bu] 2
\-\f[B]errno\f[] equivalent of return code set by failing
\f[B]GetFinalPathNameByHandleW\f[](), while trying to resolve the volume
path from the file handle.
.IP \[bu] 2
\-\f[B]errno\f[] set by failing \f[B]malloc\f[](3), while trying to
allocate a buffer for storing volume path.
.IP \[bu] 2
\-\f[B]errno\f[] equivalent of return code set by failing
\f[B]CreateFileW\f[](), while trying to obtain a handle to the volume.
.IP \[bu] 2
\-\f[B]errno\f[] equivalent of return code set by failing
\f[B]DeviceIoControl\f[](), while trying to obtain volume \f[B]USC\f[]
value.
.PP
On Linux:
.IP \[bu] 2
\-\f[B]errno\f[] set by failing \f[B]fstat\f[](2), while trying to
validate the file descriptor.
.IP \[bu] 2
\-\f[B]errno\f[] set by failing \f[B]ndctl_new\f[](), while trying to
initiate a new NDCTL library context.
.SH SEE ALSO
.PP
\f[B]fstat\f[](2), \f[B]errno\f[](3), \f[B]malloc\f[](3),
\f[B]libpmem2_unsafe_shutdown\f[](7), and \f[B]<https://pmem.io>\f[]