.. _tree.h:

**tree.h**


libnvme tree object interface

.. c:function:: nvme_root_t nvme_create_root (FILE *fp, int log_level)

   Initialize root object

**Parameters**

``FILE *fp``
  File descriptor for logging messages

``int log_level``
  Logging level to use

**Return**

Initialized :c:type:`nvme_root_t` object


.. c:function:: void nvme_root_set_application (nvme_root_t r, const char *a)

   Specify managing application

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

``const char *a``
  Application string

**Description**

Sets the managing application string for **r**.


.. c:function:: const char * nvme_root_get_application (nvme_root_t r)

   Get managing application

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Description**

Returns the managing application string for **r** or NULL if not set.


.. c:function:: void nvme_root_skip_namespaces (nvme_root_t r)

   Skip namespace scanning

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Description**

Sets a flag to skip namespaces during scanning.


.. c:function:: void nvme_root_release_fds (nvme_root_t r)

   Close all opened file descriptors in the tree

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Description**

Controller and Namespace objects cache the file descriptors
of opened nvme devices. This API can be used to close and
clear all cached fds in the tree.


.. c:function:: void nvme_free_tree (nvme_root_t r)

   Free root object

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Description**

Free an :c:type:`nvme_root_t` object and all attached objects


.. c:function:: nvme_host_t nvme_first_host (nvme_root_t r)

   Start host iterator

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Return**

First :c:type:`nvme_host_t` object in an iterator


.. c:function:: nvme_host_t nvme_next_host (nvme_root_t r, nvme_host_t h)

   Next host iterator

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

``nvme_host_t h``
  Previous :c:type:`nvme_host_t` iterator

**Return**

Next :c:type:`nvme_host_t` object in an iterator


.. c:function:: nvme_root_t nvme_host_get_root (nvme_host_t h)

   Returns nvme_root_t object

**Parameters**

``nvme_host_t h``
  :c:type:`nvme_host_t` object

**Return**

:c:type:`nvme_root_t` object from **h**


.. c:function:: nvme_host_t nvme_lookup_host (nvme_root_t r, const char *hostnqn, const char *hostid)

   Lookup nvme_host_t object

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

``const char *hostnqn``
  Host NQN

``const char *hostid``
  Host ID

**Description**

Lookup a nvme_host_t object based on **hostnqn** and **hostid**
or create one if not found.

**Return**

:c:type:`nvme_host_t` object


.. c:function:: const char * nvme_host_get_dhchap_key (nvme_host_t h)

   Return host key

**Parameters**

``nvme_host_t h``
  Host for which the key should be returned

**Return**

DH-HMAC-CHAP host key or NULL if not set


.. c:function:: void nvme_host_set_dhchap_key (nvme_host_t h, const char *key)

   set host key

**Parameters**

``nvme_host_t h``
  Host for which the key should be set

``const char *key``
  DH-HMAC-CHAP Key to set or NULL to clear existing key


.. c:function:: void nvme_host_set_pdc_enabled (nvme_host_t h, bool enabled)

   Set Persistent Discovery Controller flag

**Parameters**

``nvme_host_t h``
  Host for which the falg should be set

``bool enabled``
  The bool to set the enabled flag

**Description**

When nvme_host_set_pdc_enabled() is not used to set the PDC flag,
nvme_host_is_pdc_enabled() will return the default value which was
passed into the function and not the undefined flag value.


.. c:function:: bool nvme_host_is_pdc_enabled (nvme_host_t h, bool fallback)

   Is Persistenct Discovery Controller enabled

**Parameters**

``nvme_host_t h``
  Host which to check if PDC is enabled

``bool fallback``
  The fallback default value of the flag when
  **nvme_host_set_pdc_enabled** has not be used
  to set the flag.

**Return**

true if PDC is enabled for **h**, else false


.. c:function:: nvme_host_t nvme_default_host (nvme_root_t r)

   Initializes the default host

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

**Description**

Initializes the default host object based on the hostnqn/hostid
values returned by nvme_host_get_ids() and attaches it to **r**.

**Return**

:c:type:`nvme_host_t` object


.. c:function:: int nvme_host_get_ids (nvme_root_t r, char *hostnqn_arg, char *hostid_arg, char **hostnqn, char **hostid)

   Retrieve host ids from various sources

**Parameters**

``nvme_root_t r``
  :c:type:`nvme_root_t` object

``char *hostnqn_arg``
  Input hostnqn (command line) argument

``char *hostid_arg``
  Input hostid (command line) argument

``char **hostnqn``
  Output hostnqn

``char **hostid``
  Output hostid

**Description**

nvme_host_get_ids figures out which hostnqn/hostid is to be used.
There are several sources where this information can be retrieved.

The order is:

 - Start with informartion from DMI or device-tree
 - Override hostnqn and hostid from /etc/nvme files
 - Override hostnqn or hostid with values from JSON
   configuration file. The first host entry in the file is
   considered the default host.
 - Override hostnqn or hostid with values from the command line
   (**hostnqn_arg**, **hostid_arg**).

 If the IDs are still NULL after the lookup algorithm, the function
 will generate random IDs.

 The function also verifies that hostnqn and hostid matches. The Linux
 NVMe implementation expects a 1:1 matching between the IDs.

**Return**

0 on success (**hostnqn** and **hostid** contain valid strings
 which the caller needs to free), -1 otherwise and errno is set.


.. c:function:: nvme_subsystem_t nvme_first_subsystem (nvme_host_t h)

   Start subsystem iterator

**Parameters**

``nvme_host_t h``
  :c:type:`nvme_host_t` object

**Return**

first :c:type:`nvme_subsystem_t` object in an iterator


.. c:function:: nvme_subsystem_t nvme_next_subsystem (nvme_host_t h, nvme_subsystem_t s)

   Next subsystem iterator

**Parameters**

``nvme_host_t h``
  :c:type:`nvme_host_t` object

``nvme_subsystem_t s``
  Previous :c:type:`nvme_subsystem_t` iterator

**Return**

next :c:type:`nvme_subsystem_t` object in an iterator


.. c:function:: nvme_subsystem_t nvme_lookup_subsystem (struct nvme_host *h, const char *name, const char *subsysnqn)

   Lookup nvme_subsystem_t object

**Parameters**

``struct nvme_host *h``
  :c:type:`nvme_host_t` object

``const char *name``
  Name of the subsystem (may be NULL)

``const char *subsysnqn``
  Subsystem NQN

**Description**

Lookup a :c:type:`nvme_subsystem_t` object in **h** base on **name** (if present)
and **subsysnqn** or create one if not found.

**Return**

nvme_subsystem_t object


.. c:function:: void nvme_free_subsystem (struct nvme_subsystem *s)

   Free a subsystem

**Parameters**

``struct nvme_subsystem *s``
  subsystem

**Description**

Frees **s** and all related objects.


.. c:function:: nvme_host_t nvme_subsystem_get_host (nvme_subsystem_t s)

   Returns nvme_host_t object

**Parameters**

``nvme_subsystem_t s``
  subsystem

**Return**

:c:type:`nvme_host_t` object from **s**


.. c:function:: nvme_ns_t nvme_ctrl_first_ns (nvme_ctrl_t c)

   Start namespace iterator

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

First :c:type:`nvme_ns_t` object of an **c** iterator


.. c:function:: nvme_ns_t nvme_ctrl_next_ns (nvme_ctrl_t c, nvme_ns_t n)

   Next namespace iterator

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``nvme_ns_t n``
  Previous nvme_ns_t iterator

**Return**

Next nvme_ns_t object of an **c** iterator


.. c:function:: nvme_path_t nvme_ctrl_first_path (nvme_ctrl_t c)

   Start path iterator

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

First :c:type:`nvme_path_t` object of an **c** iterator


.. c:function:: nvme_path_t nvme_ctrl_next_path (nvme_ctrl_t c, nvme_path_t p)

   Next path iterator

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``nvme_path_t p``
  Previous :c:type:`nvme_path_t` object of an **c** iterator

**Return**

Next :c:type:`nvme_path_t` object of an **c** iterator


.. c:function:: nvme_ctrl_t nvme_subsystem_first_ctrl (nvme_subsystem_t s)

   First ctrl iterator

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

**Return**

First controller of an **s** iterator


.. c:function:: nvme_ctrl_t nvme_subsystem_next_ctrl (nvme_subsystem_t s, nvme_ctrl_t c)

   Next ctrl iterator

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

``nvme_ctrl_t c``
  Previous controller instance of an **s** iterator

**Return**

Next controller of an **s** iterator


.. c:function:: nvme_path_t nvme_namespace_first_path (nvme_ns_t ns)

   Start path iterator

**Parameters**

``nvme_ns_t ns``
  Namespace instance

**Return**

First :c:type:`nvme_path_t` object of an **ns** iterator


.. c:function:: nvme_path_t nvme_namespace_next_path (nvme_ns_t ns, nvme_path_t p)

   Next path iterator

**Parameters**

``nvme_ns_t ns``
  Namespace instance

``nvme_path_t p``
  Previous :c:type:`nvme_path_t` object of an **ns** iterator

**Return**

Next :c:type:`nvme_path_t` object of an **ns** iterator


.. c:function:: nvme_ctrl_t nvme_lookup_ctrl (nvme_subsystem_t s, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid, nvme_ctrl_t p)

   Lookup nvme_ctrl_t object

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

``const char *transport``
  Transport name

``const char *traddr``
  Transport address

``const char *host_traddr``
  Host transport address

``const char *host_iface``
  Host interface name

``const char *trsvcid``
  Transport service identifier

``nvme_ctrl_t p``
  Previous controller instance

**Description**

Lookup a controller in **s** based on **transport**, **traddr**,
**host_traddr**, **host_iface**, and **trsvcid**. **transport** must be specified,
other fields may be required depending on the transport. A new
object is created if none is found. If **p** is specified the lookup
will start at **p** instead of the first controller.

**Return**

Controller instance


.. c:function:: nvme_ctrl_t nvme_ctrl_find (nvme_subsystem_t s, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)

   Locate an existing controller

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

``const char *transport``
  Transport name

``const char *traddr``
  Transport address

``const char *trsvcid``
  Transport service identifier

``const char *subsysnqn``
  Subsystem NQN

``const char *host_traddr``
  Host transport address

``const char *host_iface``
  Host interface name

**Description**

Lookup a controller in **s** based on **transport**, **traddr**, **trsvcid**,
**subsysnqn**, **host_traddr**, and **host_iface**. **transport** must be specified,
other fields may be required depending on the transport. Parameters set
to NULL will be ignored.

Unlike nvme_lookup_ctrl(), this function does not create a new object if
an existing controller cannot be found.

**Return**

Controller instance on success, NULL otherwise.


.. c:function:: bool nvme_ctrl_config_match (struct nvme_ctrl *c, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)

   Check if ctrl **c** matches config params

**Parameters**

``struct nvme_ctrl *c``
  An existing controller instance

``const char *transport``
  Transport name

``const char *traddr``
  Transport address

``const char *trsvcid``
  Transport service identifier

``const char *subsysnqn``
  Subsystem NQN

``const char *host_traddr``
  Host transport address

``const char *host_iface``
  Host interface name

**Description**

Check that controller **c** matches parameters: **transport**, **traddr**,
**trsvcid**, **subsysnqn**, **host_traddr**, and **host_iface**. Parameters set
to NULL will be ignored.

**Return**

true if there's a match, false otherwise.


.. c:function:: nvme_ctrl_t nvme_create_ctrl (nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid)

   Allocate an unconnected NVMe controller

**Parameters**

``nvme_root_t r``
  NVMe root element

``const char *subsysnqn``
  Subsystem NQN

``const char *transport``
  Transport type

``const char *traddr``
  Transport address

``const char *host_traddr``
  Host transport address

``const char *host_iface``
  Host interface name

``const char *trsvcid``
  Transport service ID

**Description**

Creates an unconnected controller to be used for nvme_add_ctrl().

**Return**

Controller instance


.. c:function:: nvme_ns_t nvme_subsystem_first_ns (nvme_subsystem_t s)

   Start namespace iterator

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

**Return**

First :c:type:`nvme_ns_t` object of an **s** iterator


.. c:function:: nvme_ns_t nvme_subsystem_next_ns (nvme_subsystem_t s, nvme_ns_t n)

   Next namespace iterator

**Parameters**

``nvme_subsystem_t s``
  :c:type:`nvme_subsystem_t` object

``nvme_ns_t n``
  Previous :c:type:`nvme_ns_t` iterator

**Return**

Next :c:type:`nvme_ns_t` object of an **s** iterator


.. c:macro:: nvme_for_each_host_safe

``nvme_for_each_host_safe (r, h, _h)``

   Traverse host list

**Parameters**

``r``
  :c:type:`nvme_root_t` object

``h``
  :c:type:`nvme_host_t` object

``_h``
  Temporary :c:type:`nvme_host_t` object


.. c:macro:: nvme_for_each_host

``nvme_for_each_host (r, h)``

   Traverse host list

**Parameters**

``r``
  :c:type:`nvme_root_t` object

``h``
  :c:type:`nvme_host_t` object


.. c:macro:: nvme_for_each_subsystem_safe

``nvme_for_each_subsystem_safe (h, s, _s)``

   Traverse subsystems

**Parameters**

``h``
  :c:type:`nvme_host_t` object

``s``
  :c:type:`nvme_subsystem_t` object

``_s``
  Temporary :c:type:`nvme_subsystem_t` object


.. c:macro:: nvme_for_each_subsystem

``nvme_for_each_subsystem (h, s)``

   Traverse subsystems

**Parameters**

``h``
  :c:type:`nvme_host_t` object

``s``
  :c:type:`nvme_subsystem_t` object


.. c:macro:: nvme_subsystem_for_each_ctrl_safe

``nvme_subsystem_for_each_ctrl_safe (s, c, _c)``

   Traverse controllers

**Parameters**

``s``
  :c:type:`nvme_subsystem_t` object

``c``
  Controller instance

``_c``
  A :c:type:`nvme_ctrl_t_node` to use as temporary storage


.. c:macro:: nvme_subsystem_for_each_ctrl

``nvme_subsystem_for_each_ctrl (s, c)``

   Traverse controllers

**Parameters**

``s``
  :c:type:`nvme_subsystem_t` object

``c``
  Controller instance


.. c:macro:: nvme_ctrl_for_each_ns_safe

``nvme_ctrl_for_each_ns_safe (c, n, _n)``

   Traverse namespaces

**Parameters**

``c``
  Controller instance

``n``
  :c:type:`nvme_ns_t` object

``_n``
  A :c:type:`nvme_ns_t_node` to use as temporary storage


.. c:macro:: nvme_ctrl_for_each_ns

``nvme_ctrl_for_each_ns (c, n)``

   Traverse namespaces

**Parameters**

``c``
  Controller instance

``n``
  :c:type:`nvme_ns_t` object


.. c:macro:: nvme_ctrl_for_each_path_safe

``nvme_ctrl_for_each_path_safe (c, p, _p)``

   Traverse paths

**Parameters**

``c``
  Controller instance

``p``
  :c:type:`nvme_path_t` object

``_p``
  A :c:type:`nvme_path_t_node` to use as temporary storage


.. c:macro:: nvme_ctrl_for_each_path

``nvme_ctrl_for_each_path (c, p)``

   Traverse paths

**Parameters**

``c``
  Controller instance

``p``
  :c:type:`nvme_path_t` object


.. c:macro:: nvme_subsystem_for_each_ns_safe

``nvme_subsystem_for_each_ns_safe (s, n, _n)``

   Traverse namespaces

**Parameters**

``s``
  :c:type:`nvme_subsystem_t` object

``n``
  :c:type:`nvme_ns_t` object

``_n``
  A :c:type:`nvme_ns_t_node` to use as temporary storage


.. c:macro:: nvme_subsystem_for_each_ns

``nvme_subsystem_for_each_ns (s, n)``

   Traverse namespaces

**Parameters**

``s``
  :c:type:`nvme_subsystem_t` object

``n``
  :c:type:`nvme_ns_t` object


.. c:macro:: nvme_namespace_for_each_path_safe

``nvme_namespace_for_each_path_safe (n, p, _p)``

   Traverse paths

**Parameters**

``n``
  Namespace instance

``p``
  :c:type:`nvme_path_t` object

``_p``
  A :c:type:`nvme_path_t_node` to use as temporary storage


.. c:macro:: nvme_namespace_for_each_path

``nvme_namespace_for_each_path (n, p)``

   Traverse paths

**Parameters**

``n``
  Namespace instance

``p``
  :c:type:`nvme_path_t` object


.. c:function:: int nvme_ns_get_fd (nvme_ns_t n)

   Get associated file descriptor

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Description**

libnvme will open() the file (if not already opened) and keep
an internal copy of the file descriptor. Following calls to
this API retrieve the internal cached copy of the file
descriptor. The file will remain opened and the fd will
remain cached until the ns object is deleted or
nvme_ns_release_fd() is called.

**Return**

File descriptor associated with **n** or -1


.. c:function:: void nvme_ns_release_fd (nvme_ns_t n)

   Close fd and clear fd from ns object

**Parameters**

``nvme_ns_t n``
  Namespace instance


.. c:function:: int nvme_ns_get_nsid (nvme_ns_t n)

   NSID of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

NSID of **n**


.. c:function:: int nvme_ns_get_lba_size (nvme_ns_t n)

   LBA size of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

LBA size of **n**


.. c:function:: int nvme_ns_get_meta_size (nvme_ns_t n)

   Metadata size of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

Metadata size of **n**


.. c:function:: uint64_t nvme_ns_get_lba_count (nvme_ns_t n)

   LBA count of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

LBA count of **n**


.. c:function:: uint64_t nvme_ns_get_lba_util (nvme_ns_t n)

   LBA utilization of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

LBA utilization of **n**


.. c:function:: enum nvme_csi nvme_ns_get_csi (nvme_ns_t n)

   Command set identifier of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

The namespace's command set identifier in use


.. c:function:: const uint8_t * nvme_ns_get_eui64 (nvme_ns_t n)

   64-bit eui of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

A pointer to the 64-bit eui


.. c:function:: const uint8_t * nvme_ns_get_nguid (nvme_ns_t n)

   128-bit nguid of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

A pointer to the 128-bit nguid


.. c:function:: void nvme_ns_get_uuid (nvme_ns_t n, unsigned char out[NVME_UUID_LEN])

   UUID of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``unsigned char out[NVME_UUID_LEN]``
  buffer for the UUID

**Description**

Copies the namespace's uuid into **out**


.. c:function:: const char * nvme_ns_get_sysfs_dir (nvme_ns_t n)

   sysfs directory of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

sysfs directory name of **n**


.. c:function:: const char * nvme_ns_get_name (nvme_ns_t n)

   sysfs name of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

sysfs name of **n**


.. c:function:: const char * nvme_ns_get_generic_name (nvme_ns_t n)

   Returns name of generic namespace chardev.

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

Name of generic namespace chardev


.. c:function:: const char * nvme_ns_get_firmware (nvme_ns_t n)

   Firmware string of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

Firmware string of **n**


.. c:function:: const char * nvme_ns_get_serial (nvme_ns_t n)

   Serial number of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

Serial number string of **n**


.. c:function:: const char * nvme_ns_get_model (nvme_ns_t n)

   Model of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

Model string of **n**


.. c:function:: nvme_subsystem_t nvme_ns_get_subsystem (nvme_ns_t n)

   :c:type:`nvme_subsystem_t` of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

nvme_subsystem_t object of **n**


.. c:function:: nvme_ctrl_t nvme_ns_get_ctrl (nvme_ns_t n)

   :c:type:`nvme_ctrl_t` of a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Description**

nvme_ctrl_t object may be NULL for a multipathed namespace

**Return**

nvme_ctrl_t object of **n** if present


.. c:function:: void nvme_free_ns (struct nvme_ns *n)

   Free a namespace object

**Parameters**

``struct nvme_ns *n``
  Namespace instance


.. c:function:: int nvme_ns_read (nvme_ns_t n, void *buf, off_t offset, size_t count)

   Read from a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``void *buf``
  Buffer into which the data will be transferred

``off_t offset``
  LBA offset of **n**

``size_t count``
  Number of sectors in **buf**

**Return**

Number of sectors read or -1 on error.


.. c:function:: int nvme_ns_write (nvme_ns_t n, void *buf, off_t offset, size_t count)

   Write to a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``void *buf``
  Buffer with data to be written

``off_t offset``
  LBA offset of **n**

``size_t count``
  Number of sectors in **buf**

**Return**

Number of sectors written or -1 on error


.. c:function:: int nvme_ns_verify (nvme_ns_t n, off_t offset, size_t count)

   Verify data on a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``off_t offset``
  LBA offset of **n**

``size_t count``
  Number of sectors to be verified

**Return**

Number of sectors verified


.. c:function:: int nvme_ns_compare (nvme_ns_t n, void *buf, off_t offset, size_t count)

   Compare data on a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``void *buf``
  Buffer with data to be compared

``off_t offset``
  LBA offset of **n**

``size_t count``
  Number of sectors in **buf**

**Return**

Number of sectors compared


.. c:function:: int nvme_ns_write_zeros (nvme_ns_t n, off_t offset, size_t count)

   Write zeros to a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

``off_t offset``
  LBA offset in **n**

``size_t count``
  Number of sectors to be written

**Return**

Number of sectors written


.. c:function:: int nvme_ns_write_uncorrectable (nvme_ns_t n, off_t offset, size_t count)

   Issus a 'write uncorrectable' command

**Parameters**

``nvme_ns_t n``
  Namespace instance

``off_t offset``
  LBA offset in **n**

``size_t count``
  Number of sectors to be written

**Return**

Number of sectors written


.. c:function:: int nvme_ns_flush (nvme_ns_t n)

   Flush data to a namespace

**Parameters**

``nvme_ns_t n``
  Namespace instance

**Return**

0 on success, -1 on error.


.. c:function:: int nvme_ns_identify (nvme_ns_t n, struct nvme_id_ns *ns)

   Issue an 'identify namespace' command

**Parameters**

``nvme_ns_t n``
  Namespace instance

``struct nvme_id_ns *ns``
  :c:type:`nvme_id_ns` buffer

**Description**

Writes the data returned by the 'identify namespace' command
into **ns**.

**Return**

0 on success, -1 on error.


.. c:function:: int nvme_ns_identify_descs (nvme_ns_t n, struct nvme_ns_id_desc *descs)

   Issue an 'identify descriptors' command

**Parameters**

``nvme_ns_t n``
  Namespace instance

``struct nvme_ns_id_desc *descs``
  List of identify descriptors

**Description**

Writes the data returned by the 'identify descriptors' command
into **descs**.

**Return**

0 on success, -1 on error.


.. c:function:: const char * nvme_path_get_name (nvme_path_t p)

   sysfs name of an :c:type:`nvme_path_t` object

**Parameters**

``nvme_path_t p``
  :c:type:`nvme_path_t` object

**Return**

sysfs name of **p**


.. c:function:: const char * nvme_path_get_sysfs_dir (nvme_path_t p)

   sysfs directory of an nvme_path_t object

**Parameters**

``nvme_path_t p``
  :c:type:`nvme_path_t` object

**Return**

sysfs directory of **p**


.. c:function:: const char * nvme_path_get_ana_state (nvme_path_t p)

   ANA state of an nvme_path_t object

**Parameters**

``nvme_path_t p``
  :c:type:`nvme_path_t` object

**Return**

ANA (Asynchronous Namespace Access) state of **p**


.. c:function:: nvme_ctrl_t nvme_path_get_ctrl (nvme_path_t p)

   Parent controller of an nvme_path_t object

**Parameters**

``nvme_path_t p``
  :c:type:`nvme_path_t` object

**Return**

Parent controller if present


.. c:function:: nvme_ns_t nvme_path_get_ns (nvme_path_t p)

   Parent namespace of an nvme_path_t object

**Parameters**

``nvme_path_t p``
  :c:type:`nvme_path_t` object

**Return**

Parent namespace if present


.. c:function:: int nvme_ctrl_get_fd (nvme_ctrl_t c)

   Get associated file descriptor

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Description**

libnvme will open() the file (if not already opened) and keep
an internal copy of the file descriptor. Following calls to
this API retrieve the internal cached copy of the file
descriptor. The file will remain opened and the fd will
remain cached until the controller object is deleted or
nvme_ctrl_release_fd() is called.

**Return**

File descriptor associated with **c** or -1


.. c:function:: void nvme_ctrl_release_fd (nvme_ctrl_t c)

   Close fd and clear fd from controller object

**Parameters**

``nvme_ctrl_t c``
  Controller instance


.. c:function:: const char * nvme_ctrl_get_name (nvme_ctrl_t c)

   sysfs name of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

sysfs name of **c**


.. c:function:: const char * nvme_ctrl_get_sysfs_dir (nvme_ctrl_t c)

   sysfs directory of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

sysfs directory name of **c**


.. c:function:: const char * nvme_ctrl_get_address (nvme_ctrl_t c)

   Address string of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

NVMe-over-Fabrics address string of **c** or empty string
of no address is present.


.. c:function:: char * nvme_ctrl_get_src_addr (nvme_ctrl_t c, char *src_addr, size_t src_addr_len)

   Extract src_addr from the c->address string

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``char *src_addr``
  Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.

``size_t src_addr_len``
  Length of the buffer **src_addr**.

**Return**

Pointer to **src_addr** on success. NULL on failure to extract the src_addr.


.. c:function:: const char * nvme_ctrl_get_phy_slot (nvme_ctrl_t c)

   PCI physical slot number of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

PCI physical slot number of **c** or empty string if slot
number is not present.


.. c:function:: const char * nvme_ctrl_get_firmware (nvme_ctrl_t c)

   Firmware string of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Firmware string of **c**


.. c:function:: const char * nvme_ctrl_get_model (nvme_ctrl_t c)

   Model of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Model string of **c**


.. c:function:: const char * nvme_ctrl_get_state (nvme_ctrl_t c)

   Running state of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

String indicating the running state of **c**


.. c:function:: const char * nvme_ctrl_get_numa_node (nvme_ctrl_t c)

   NUMA node of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

String indicating the NUMA node


.. c:function:: const char * nvme_ctrl_get_queue_count (nvme_ctrl_t c)

   Queue count of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Queue count of **c**


.. c:function:: const char * nvme_ctrl_get_serial (nvme_ctrl_t c)

   Serial number of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Serial number string of **c**


.. c:function:: const char * nvme_ctrl_get_sqsize (nvme_ctrl_t c)

   SQ size of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

SQ size (as string) of **c**


.. c:function:: const char * nvme_ctrl_get_transport (nvme_ctrl_t c)

   Transport type of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Transport type of **c**


.. c:function:: const char * nvme_ctrl_get_subsysnqn (nvme_ctrl_t c)

   Subsystem NQN of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Subsystem NQN of **c**


.. c:function:: nvme_subsystem_t nvme_ctrl_get_subsystem (nvme_ctrl_t c)

   Parent subsystem of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Parent nvme_subsystem_t object


.. c:function:: const char * nvme_ctrl_get_traddr (nvme_ctrl_t c)

   Transport address of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Transport address of **c**


.. c:function:: const char * nvme_ctrl_get_trsvcid (nvme_ctrl_t c)

   Transport service identifier of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Transport service identifier of **c** (if present)


.. c:function:: const char * nvme_ctrl_get_host_traddr (nvme_ctrl_t c)

   Host transport address of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Host transport address of **c** (if present)


.. c:function:: const char * nvme_ctrl_get_host_iface (nvme_ctrl_t c)

   Host interface name of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Host interface name of **c** (if present)


.. c:function:: const char * nvme_ctrl_get_dhchap_host_key (nvme_ctrl_t c)

   Return host key

**Parameters**

``nvme_ctrl_t c``
  Controller to be checked

**Return**

DH-HMAC-CHAP host key or NULL if not set


.. c:function:: const char * nvme_ctrl_get_cntlid (nvme_ctrl_t c)

   Controller id

**Parameters**

``nvme_ctrl_t c``
  Controller to be checked

**Return**

Controller id of **c**


.. c:function:: void nvme_ctrl_set_dhchap_host_key (nvme_ctrl_t c, const char *key)

   Set host key

**Parameters**

``nvme_ctrl_t c``
  Host for which the key should be set

``const char *key``
  DH-HMAC-CHAP Key to set or NULL to clear existing key


.. c:function:: const char * nvme_ctrl_get_dhchap_key (nvme_ctrl_t c)

   Return controller key

**Parameters**

``nvme_ctrl_t c``
  Controller for which the key should be set

**Return**

DH-HMAC-CHAP controller key or NULL if not set


.. c:function:: void nvme_ctrl_set_dhchap_key (nvme_ctrl_t c, const char *key)

   Set controller key

**Parameters**

``nvme_ctrl_t c``
  Controller for which the key should be set

``const char *key``
  DH-HMAC-CHAP Key to set or NULL to clear existing key


.. c:function:: const char * nvme_ctrl_get_keyring (nvme_ctrl_t c)

   Return keyring

**Parameters**

``nvme_ctrl_t c``
  Controller to be used for the lookup

**Return**

Keyring or NULL if not set


.. c:function:: void nvme_ctrl_set_keyring (nvme_ctrl_t c, const char *keyring)

   Set keyring

**Parameters**

``nvme_ctrl_t c``
  Controller for which the keyring should be set

``const char *keyring``
  Keyring name


.. c:function:: const char * nvme_ctrl_get_tls_key_identity (nvme_ctrl_t c)

   Return Derive TLS Identity

**Parameters**

``nvme_ctrl_t c``
  Controller to be used for the lookup

**Return**

Derive TLS Identity or NULL if not set


.. c:function:: void nvme_ctrl_set_tls_key_identity (nvme_ctrl_t c, const char *identity)

   Set Derive TLS Identity

**Parameters**

``nvme_ctrl_t c``
  Controller for which the key should be set

``const char *identity``
  Derive TLS identity or NULL to clear existing key


.. c:function:: const char * nvme_ctrl_get_tls_key (nvme_ctrl_t c)

   Return Derive TLS PSK

**Parameters**

``nvme_ctrl_t c``
  Controller to be used for the lookup

**Return**

Key in PSK interchange format or NULL if not set


.. c:function:: void nvme_ctrl_set_tls_key (nvme_ctrl_t c, const char *key)

   Set Derive TLS PSK

**Parameters**

``nvme_ctrl_t c``
  Controller for which the key should be set

``const char *key``
  Key in interchange format or NULL to clear existing key


.. c:function:: struct nvme_fabrics_config * nvme_ctrl_get_config (nvme_ctrl_t c)

   Fabrics configuration of a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Fabrics configuration of **c**


.. c:function:: void nvme_ctrl_set_discovered (nvme_ctrl_t c, bool discovered)

   Set the 'discovered' flag

**Parameters**

``nvme_ctrl_t c``
  nvme_ctrl_t object

``bool discovered``
  Value of the 'discovered' flag

**Description**

Set the 'discovered' flag of **c** to **discovered**


.. c:function:: bool nvme_ctrl_is_discovered (nvme_ctrl_t c)

   Returns the value of the 'discovered' flag

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Value of the 'discovered' flag of **c**


.. c:function:: void nvme_ctrl_set_persistent (nvme_ctrl_t c, bool persistent)

   Set the 'persistent' flag

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``bool persistent``
  value of the 'persistent' flag

**Description**

Set the 'persistent' flag of **c** to **persistent**


.. c:function:: bool nvme_ctrl_is_persistent (nvme_ctrl_t c)

   Returns the value of the 'persistent' flag

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Return**

Value of the 'persistent' flag of **c**


.. c:function:: void nvme_ctrl_set_discovery_ctrl (nvme_ctrl_t c, bool discovery)

   Set the 'discovery_ctrl' flag

**Parameters**

``nvme_ctrl_t c``
  Controller to be modified

``bool discovery``
  value of the discovery_ctrl flag

**Description**

Sets the 'discovery_ctrl' flag in **c** to specify whether
**c** connects to a discovery subsystem.


.. c:function:: bool nvme_ctrl_is_discovery_ctrl (nvme_ctrl_t c)

   Check the 'discovery_ctrl' flag

**Parameters**

``nvme_ctrl_t c``
  Controller to be checked

**Description**

Returns the value of the 'discovery_ctrl' flag which specifies whether
**c** connects to a discovery subsystem.

**Return**

Value of the 'discover_ctrl' flag


.. c:function:: void nvme_ctrl_set_unique_discovery_ctrl (nvme_ctrl_t c, bool unique)

   Set the 'unique_discovery_ctrl' flag

**Parameters**

``nvme_ctrl_t c``
  Controller to be modified

``bool unique``
  value of the unique_disc_ctrl flag

**Description**

Sets the 'unique_discovery_ctrl' flag in **c** to specify wheter
**c** is a unique discovery controller


.. c:function:: bool nvme_ctrl_is_unique_discovery_ctrl (nvme_ctrl_t c)

   Check the 'unique_discovery_ctrl' flag

**Parameters**

``nvme_ctrl_t c``
  Controller to be checked

**Return**

Value of the 'unique_discovery_ctrl' flag


.. c:function:: int nvme_ctrl_identify (nvme_ctrl_t c, struct nvme_id_ctrl *id)

   Issues an 'identify controller' command

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``struct nvme_id_ctrl *id``
  Identify controller data structure

**Description**

Issues an 'identify controller' command to **c** and copies the
data into **id**.

**Return**

0 on success or -1 on failure.


.. c:function:: int nvme_disconnect_ctrl (nvme_ctrl_t c)

   Disconnect a controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance

**Description**

Issues a 'disconnect' fabrics command to **c**

**Return**

0 on success, -1 on failure.


.. c:function:: nvme_ctrl_t nvme_scan_ctrl (nvme_root_t r, const char *name)

   Scan on a controller

**Parameters**

``nvme_root_t r``
  nvme_root_t object

``const char *name``
  Name of the controller

**Description**

Scans a controller with sysfs name **name** and add it to **r**.

**Return**

nvme_ctrl_t object


.. c:function:: void nvme_rescan_ctrl (nvme_ctrl_t c)

   Rescan an existing controller

**Parameters**

``nvme_ctrl_t c``
  Controller instance


.. c:function:: int nvme_init_ctrl (nvme_host_t h, nvme_ctrl_t c, int instance)

   Initialize nvme_ctrl_t object for an existing controller.

**Parameters**

``nvme_host_t h``
  nvme_host_t object

``nvme_ctrl_t c``
  nvme_ctrl_t object

``int instance``
  Instance number (e.g. 1 for nvme1)

**Return**

The ioctl() return code. Typically 0 on success.


.. c:function:: void nvme_free_ctrl (struct nvme_ctrl *c)

   Free controller

**Parameters**

``struct nvme_ctrl *c``
  Controller instance


.. c:function:: void nvme_unlink_ctrl (struct nvme_ctrl *c)

   Unlink controller

**Parameters**

``struct nvme_ctrl *c``
  Controller instance


.. c:function:: const char * nvme_subsystem_get_nqn (nvme_subsystem_t s)

   Retrieve NQN from subsystem

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

NQN of subsystem


.. c:function:: const char * nvme_subsystem_get_sysfs_dir (nvme_subsystem_t s)

   sysfs directory of an nvme_subsystem_t object

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

sysfs directory name of **s**


.. c:function:: const char * nvme_subsystem_get_name (nvme_subsystem_t s)

   sysfs name of an nvme_subsystem_t object

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

sysfs name of **s**


.. c:function:: const char * nvme_subsystem_get_type (nvme_subsystem_t s)

   Returns the type of a subsystem

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Description**

Returns the subsystem type of **s**.

**Return**

'nvm' or 'discovery'


.. c:function:: const char * nvme_subsystem_get_application (nvme_subsystem_t s)

   Return the application string

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

Managing application string or NULL if not set.


.. c:function:: void nvme_subsystem_set_application (nvme_subsystem_t s, const char *a)

   Set the application string

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

``const char *a``
  application string

**Description**

Sets the managing application string for **s**.


.. c:function:: const char * nvme_subsystem_get_iopolicy (nvme_subsystem_t s)

   Return the IO policy of subsytem

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

IO policy used by current subsystem


.. c:function:: const char * nvme_subsystem_get_model (nvme_subsystem_t s)

   Return the model of subsystem

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

Model of the current subsystem


.. c:function:: const char * nvme_subsystem_get_fw_rev (nvme_subsystem_t s)

   Return the firmware rev of subsystem

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

**Return**

Firmware revision of the current subsystem


.. c:function:: int nvme_scan_topology (nvme_root_t r, nvme_scan_filter_t f, void *f_args)

   Scan NVMe topology and apply filter

**Parameters**

``nvme_root_t r``
  nvme_root_t object

``nvme_scan_filter_t f``
  filter to apply

``void *f_args``
  user-specified argument to **f**

**Description**

Scans the NVMe topology and filters out the resulting elements
by applying **f**.

**Return**

Number of elements scanned


.. c:function:: const char * nvme_host_get_hostnqn (nvme_host_t h)

   Host NQN of an nvme_host_t object

**Parameters**

``nvme_host_t h``
  nvme_host_t object

**Return**

Host NQN of **h**


.. c:function:: const char * nvme_host_get_hostid (nvme_host_t h)

   Host ID of an nvme_host_t object

**Parameters**

``nvme_host_t h``
  nvme_host_t object

**Return**

Host ID of **h**


.. c:function:: void nvme_host_release_fds (struct nvme_host *h)

   Close all opened file descriptors under host

**Parameters**

``struct nvme_host *h``
  nvme_host_t object

**Description**

Controller and Namespace objects cache the file descriptors
of opened nvme devices. This API can be used to close and
clear all cached fds under this host.


.. c:function:: void nvme_free_host (nvme_host_t h)

   Free nvme_host_t object

**Parameters**

``nvme_host_t h``
  nvme_host_t object


.. c:function:: nvme_root_t nvme_scan (const char *config_file)

   Scan NVMe topology

**Parameters**

``const char *config_file``
  Configuration file

**Return**

nvme_root_t object of found elements


.. c:function:: int nvme_read_config (nvme_root_t r, const char *config_file)

   Read NVMe JSON configuration file

**Parameters**

``nvme_root_t r``
  nvme_root_t object

``const char *config_file``
  JSON configuration file

**Description**

Read in the contents of **config_file** and merge them with
the elements in **r**.

**Return**

0 on success, -1 on failure with errno set.


.. c:function:: void nvme_refresh_topology (nvme_root_t r)

   Refresh nvme_root_t object contents

**Parameters**

``nvme_root_t r``
  nvme_root_t object

**Description**

Removes all elements in **r** and rescans the existing topology.


.. c:function:: int nvme_update_config (nvme_root_t r)

   Update JSON configuration

**Parameters**

``nvme_root_t r``
  nvme_root_t object

**Description**

Updates the JSON configuration file with the contents of **r**.

**Return**

0 on success, -1 on failure.


.. c:function:: int nvme_dump_config (nvme_root_t r)

   Print the JSON configuration

**Parameters**

``nvme_root_t r``
  nvme_root_t object

**Description**

Prints the current contents of the JSON configuration
file to stdout.

**Return**

0 on success, -1 on failure.


.. c:function:: int nvme_dump_tree (nvme_root_t r)

   Dump internal object tree

**Parameters**

``nvme_root_t r``
  nvme_root_t object

**Description**

Prints the internal object tree in JSON format
to stdout.

**Return**

0 on success, -1 on failure.


.. c:function:: char * nvme_get_attr (const char *d, const char *attr)

   Read sysfs attribute

**Parameters**

``const char *d``
  sysfs directory

``const char *attr``
  sysfs attribute name

**Return**

String with the contents of **attr** or ``NULL`` in case of an empty value
        or in case of an error (indicated by non-zero errno code).


.. c:function:: char * nvme_get_subsys_attr (nvme_subsystem_t s, const char *attr)

   Read subsystem sysfs attribute

**Parameters**

``nvme_subsystem_t s``
  nvme_subsystem_t object

``const char *attr``
  sysfs attribute name

**Return**

String with the contents of **attr** or ``NULL`` in case of an empty value
        or in case of an error (indicated by non-zero errno code).


.. c:function:: char * nvme_get_ctrl_attr (nvme_ctrl_t c, const char *attr)

   Read controller sysfs attribute

**Parameters**

``nvme_ctrl_t c``
  Controller instance

``const char *attr``
  sysfs attribute name

**Return**

String with the contents of **attr** or ``NULL`` in case of an empty value
        or in case of an error (indicated by non-zero errno code).


.. c:function:: char * nvme_get_ns_attr (nvme_ns_t n, const char *attr)

   Read namespace sysfs attribute

**Parameters**

``nvme_ns_t n``
  nvme_ns_t object

``const char *attr``
  sysfs attribute name

**Return**

String with the contents of **attr** or ``NULL`` in case of an empty value
        or in case of an error (indicated by non-zero errno code).


.. c:function:: nvme_ns_t nvme_subsystem_lookup_namespace (struct nvme_subsystem *s, __u32 nsid)

   lookup namespace by NSID

**Parameters**

``struct nvme_subsystem *s``
  nvme_subsystem_t object

``__u32 nsid``
  Namespace id

**Return**

nvme_ns_t of the namespace with id **nsid** in subsystem **s**


.. c:function:: void nvme_subsystem_release_fds (struct nvme_subsystem *s)

   Close all opened fds under subsystem

**Parameters**

``struct nvme_subsystem *s``
  nvme_subsystem_t object

**Description**

Controller and Namespace objects cache the file descriptors
of opened nvme devices. This API can be used to close and
clear all cached fds under this subsystem.


.. c:function:: char * nvme_get_path_attr (nvme_path_t p, const char *attr)

   Read path sysfs attribute

**Parameters**

``nvme_path_t p``
  nvme_path_t object

``const char *attr``
  sysfs attribute name

**Return**

String with the contents of **attr** or ``NULL`` in case of an empty value
        or in case of an error (indicated by non-zero errno code).


.. c:function:: nvme_ns_t nvme_scan_namespace (const char *name)

   scan namespace based on sysfs name

**Parameters**

``const char *name``
  sysfs name of the namespace to scan

**Return**

nvme_ns_t object or NULL if not found.


.. c:function:: const char * nvme_host_get_hostsymname (nvme_host_t h)

   Get the host's symbolic name

**Parameters**

``nvme_host_t h``
  Host for which the symbolic name should be returned.

**Return**

The symbolic name or NULL if a symbolic name hasn't been
configure.


.. c:function:: void nvme_host_set_hostsymname (nvme_host_t h, const char *hostsymname)

   Set the host's symbolic name

**Parameters**

``nvme_host_t h``
  Host for which the symbolic name should be set.

``const char *hostsymname``
  Symbolic name