summaryrefslogtreecommitdiffstats
path: root/doc/rst/tree.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rst/tree.rst')
-rw-r--r--doc/rst/tree.rst2108
1 files changed, 2108 insertions, 0 deletions
diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst
new file mode 100644
index 0000000..2334464
--- /dev/null
+++ b/doc/rst/tree.rst
@@ -0,0 +1,2108 @@
+.. _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:: 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, uuid_t out)
+
+ UUID of a namespace
+
+**Parameters**
+
+``nvme_ns_t n``
+ Namespace instance
+
+``uuid_t out``
+ 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_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:: 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
+
+