.. _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_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 values in
/etc/nvme/hostnqn and /etc/nvme/hostid and attaches it to **r**.
**Return**
:c:type:`nvme_host_t` object
.. 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_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
**Return**
File descriptor associated with **n** or -1
.. 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
**Return**
File descriptor associated with **c** or -1
.. 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:: 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 an 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:: 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:: 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:: 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_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:: 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