pmem2 API version 1.0

The PMDK repository on GitHub is the ultimate source of information on PMDK from release 2.0! For all questions and to submit eventual issues please follow to that repository. The PMDK documentation collected here should be valid up to the 1.13.1 release but is maintained only on a best-effort basis and may not reflect the latest state of the art.

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
SEE ALSO

NAME

pmem2_source_device_id() - returns the unique identifier of a device

SYNOPSIS

#include <libpmem2.h>

struct pmem2_source;
int pmem2_source_device_id(const struct pmem2_source *source, char *id, size_t *len);

DESCRIPTION

The pmem2_source_device_id() function retrieves a unique identifier of all NVDIMMs backing the data source. This function has two operating modes:

  • if *id is NULL the function calculates a buffer length required for storing the identifier of the *source device and puts this length in *len The more hardware devices back the data source, the longer the length is.

  • if *id is not NULL it must point to a buffer of length *len provided by the previous call to this function. On success, pmem2_source_device_id() will store a unique identifier of all hardware devices backing the data source.

For details on how to use the unique identifier for detecting the unsafe shutdown please refer to libpmem2_unsafe_shutdown(7) manual page.

RETURN VALUE

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

ERRORS

The pmem2_source_device_id() can fail with the following errors:

On all systems:

  • PMEM2_E_BUFFER_TOO_SMALL - the provided buffer of length *len is too small to store the full identifier of the backing devices.
  • PMEM2_E_NOSUPP - the underlying platform does not expose hardware identification.

On Windows:

  • -errno equivalent of return code set by failing GetFinalPathNameByHandleW(), while trying to resolve the volume path from the file handle.

  • -errno set by failing malloc(3), while trying to allocate a buffer for storing volume path.

  • -errno equivalent of return code set by failing CreateFileW(), while trying to obtain a handle to the volume.

  • -errno equivalent of return code set by failing DeviceIoControl(), while trying to obtain volume USC value.

On Linux:

  • -errno set by failing fstat(2), while trying to validate the file descriptor.

  • -errno set by failing ndctl_new(), while trying to initiate a new NDCTL library context.

SEE ALSO

fstat(2), errno(3), malloc(3), libpmem2_unsafe_shutdown(7), and https://pmem.io

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.