.\" 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_usc\f[R]() - returns the \f[I]unsafe shutdown
counter\f[R] value of a device
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_source;
int pmem2_source_device_usc(const struct pmem2_source *source, uint64_t *usc);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_source_device_usc\f[R]() function retrieves the sum of
the \f[I]unsafe shutdown count\f[R](\f[B]USC\f[R]) values of all
hardware devices backing the data source and stores it in
\f[I]*usc\f[R].
.PP
Please refer to \f[B]libpmem2_unsafe_shutdown\f[R](7) for detailed
description on how to properly consume this information.
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_device_usc\f[R]() function returns 0 on success.
If the function fails, the \f[I]*usc\f[R] variable content is left
unmodified and a negative error code is returned.
.SH ERRORS
.PP
The \f[B]pmem2_source_device_usc\f[R]() can fail with the following
errors:
.PP
On all systems:
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[R] - the underlying platform does not expose
unsafe shutdown count information.
.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 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.
.IP \[bu] 2
-\f[B]errno\f[R] set by failing
\f[B]ndctl_dimm_get_dirty_shutdown\f[R](), while trying to obtain DIMM
\f[B]USC\f[R] value.
.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]