path: root/doc/rst/util.rst

.. _util.h:

**util.h**


libnvme utility functions



.. c:enum:: nvme_connect_err

   nvme connect error codes

**Constants**

``ENVME_CONNECT_RESOLVE``
  failed to resolve host

``ENVME_CONNECT_ADDRFAM``
  unrecognized address family

``ENVME_CONNECT_TRADDR``
  failed to get traddr

``ENVME_CONNECT_TARG``
  need a transport (-t) argument

``ENVME_CONNECT_AARG``
  need a address (-a) argument

``ENVME_CONNECT_OPEN``
  failed to open nvme-fabrics device

``ENVME_CONNECT_WRITE``
  failed to write to nvme-fabrics device

``ENVME_CONNECT_READ``
  failed to read from nvme-fabrics device

``ENVME_CONNECT_PARSE``
  failed to parse ctrl info

``ENVME_CONNECT_INVAL_TR``
  invalid transport type

``ENVME_CONNECT_LOOKUP_SUBSYS_NAME``
  failed to lookup subsystem name

``ENVME_CONNECT_LOOKUP_SUBSYS``
  failed to lookup subsystem

``ENVME_CONNECT_ALREADY``
  the connect attempt failed, already connected

``ENVME_CONNECT_INVAL``
  invalid arguments/configuration

``ENVME_CONNECT_ADDRINUSE``
  hostnqn already in use

``ENVME_CONNECT_NODEV``
  invalid interface

``ENVME_CONNECT_OPNOTSUPP``
  not supported

``ENVME_CONNECT_CONNREFUSED``
  connection refused

``ENVME_CONNECT_ADDRNOTAVAIL``
  cannot assign requested address

``ENVME_CONNECT_IGNORED``
  connect attempt is ignored due to configuration


.. c:function:: __u8 nvme_status_to_errno (int status, bool fabrics)

   Converts nvme return status to errno

**Parameters**

``int status``
  Return status from an nvme passthrough command

``bool fabrics``
  Set to true if :c:type:`status` is to a fabrics target.

**Return**

An errno representing the nvme status if it is an nvme status field,
or unchanged status is < 0 since errno is already set.


.. c:function:: const char * nvme_status_to_string (int status, bool fabrics)

   Returns string describing nvme return status.

**Parameters**

``int status``
  Return status from an nvme passthrough command

``bool fabrics``
  Set to true if :c:type:`status` is to a fabrics target.

**Return**

String representation of the nvme status if it is an nvme status field,
or a standard errno string if status is < 0.


.. c:function:: const char * nvme_errno_to_string (int err)

   Returns string describing nvme connect failures

**Parameters**

``int err``
  Returned error code from nvme_add_ctrl()

**Return**

String representation of the nvme connect error codes


.. c:function:: void nvme_init_ctrl_list (struct nvme_ctrl_list *cntlist, __u16 num_ctrls, __u16 *ctrlist)

   Initialize an nvme_ctrl_list structure from an array.

**Parameters**

``struct nvme_ctrl_list *cntlist``
  The controller list structure to initialize

``__u16 num_ctrls``
  The number of controllers in the array, :c:type:`ctrlist`.

``__u16 *ctrlist``
  An array of controller identifiers in CPU native endian.

**Description**

This is intended to be used with any command that takes a controller list
argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().


.. c:function:: void nvme_init_dsm_range (struct nvme_dsm_range *dsm, __u32 *ctx_attrs, __u32 *llbas, __u64 *slbas, __u16 nr_ranges)

   Constructs a data set range structure

**Parameters**

``struct nvme_dsm_range *dsm``
  DSM range array

``__u32 *ctx_attrs``
  Array of context attributes

``__u32 *llbas``
  Array of length in logical blocks

``__u64 *slbas``
  Array of starting logical blocks

``__u16 nr_ranges``
  The size of the dsm arrays

**Description**

Each array must be the same size of size 'nr_ranges'. This is intended to be
used with constructing a payload for nvme_dsm().

**Return**

The nvme command status if a response was received or -errno
otherwise.


.. c:function:: void nvme_init_copy_range (struct nvme_copy_range *copy, __u16 *nlbs, __u64 *slbas, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

   Constructs a copy range structure

**Parameters**

``struct nvme_copy_range *copy``
  Copy range array

``__u16 *nlbs``
  Number of logical blocks

``__u64 *slbas``
  Starting LBA

``__u32 *eilbrts``
  Expected initial logical block reference tag

``__u32 *elbatms``
  Expected logical block application tag mask

``__u32 *elbats``
  Expected logical block application tag

``__u16 nr``
  Number of descriptors to construct


.. c:function:: void nvme_init_copy_range_f1 (struct nvme_copy_range_f1 *copy, __u16 *nlbs, __u64 *slbas, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

   Constructs a copy range f1 structure

**Parameters**

``struct nvme_copy_range_f1 *copy``
  Copy range array

``__u16 *nlbs``
  Number of logical blocks

``__u64 *slbas``
  Starting LBA

``__u64 *eilbrts``
  Expected initial logical block reference tag

``__u32 *elbatms``
  Expected logical block application tag mask

``__u32 *elbats``
  Expected logical block application tag

``__u16 nr``
  Number of descriptors to construct


.. c:function:: void nvme_init_copy_range_f2 (struct nvme_copy_range_f2 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

   Constructs a copy range f2 structure

**Parameters**

``struct nvme_copy_range_f2 *copy``
  Copy range array

``__u32 *snsids``
  Source namespace identifier

``__u16 *nlbs``
  Number of logical blocks

``__u64 *slbas``
  Starting LBA

``__u16 *sopts``
  Source options

``__u32 *eilbrts``
  Expected initial logical block reference tag

``__u32 *elbatms``
  Expected logical block application tag mask

``__u32 *elbats``
  Expected logical block application tag

``__u16 nr``
  Number of descriptors to construct


.. c:function:: void nvme_init_copy_range_f3 (struct nvme_copy_range_f3 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

   Constructs a copy range f3 structure

**Parameters**

``struct nvme_copy_range_f3 *copy``
  Copy range array

``__u32 *snsids``
  Source namespace identifier

``__u16 *nlbs``
  Number of logical blocks

``__u64 *slbas``
  Starting LBA

``__u16 *sopts``
  Source options

``__u64 *eilbrts``
  Expected initial logical block reference tag

``__u32 *elbatms``
  Expected logical block application tag mask

``__u32 *elbats``
  Expected logical block application tag

``__u16 nr``
  Number of descriptors to construct


.. c:function:: int nvme_get_feature_length (int fid, __u32 cdw11, __u32 *len)

   Retreive the command payload length for a specific feature identifier

**Parameters**

``int fid``
  Feature identifier, see :c:type:`enum nvme_features_id <nvme_features_id>`.

``__u32 cdw11``
  The cdw11 value may affect the transfer (only known fid is
  ``NVME_FEAT_FID_HOST_ID``)

``__u32 *len``
  On success, set to this features payload length in bytes.

**Return**

0 on success, -1 with errno set to EINVAL if the function did not
recognize :c:type:`fid`.


.. c:function:: int nvme_get_feature_length2 (int fid, __u32 cdw11, enum nvme_data_tfr dir, __u32 *len)

   Retreive the command payload length for a specific feature identifier

**Parameters**

``int fid``
  Feature identifier, see :c:type:`enum nvme_features_id <nvme_features_id>`.

``__u32 cdw11``
  The cdw11 value may affect the transfer (only known fid is
  ``NVME_FEAT_FID_HOST_ID``)

``enum nvme_data_tfr dir``
  Data transfer direction: false - host to controller, true -
  controller to host may affect the transfer (only known fid is
  ``NVME_FEAT_FID_HOST_MEM_BUF``).

``__u32 *len``
  On success, set to this features payload length in bytes.

**Return**

0 on success, -1 with errno set to EINVAL if the function did not
recognize :c:type:`fid`.


.. c:function:: int nvme_get_directive_receive_length (enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len)

   Get directive receive length

**Parameters**

``enum nvme_directive_dtype dtype``
  Directive type, see :c:type:`enum nvme_directive_dtype <nvme_directive_dtype>`

``enum nvme_directive_receive_doper doper``
  Directive receive operation, see :c:type:`enum nvme_directive_receive_doper <nvme_directive_receive_doper>`

``__u32 *len``
  On success, set to this directives payload length in bytes.

**Return**

0 on success, -1 with errno set to EINVAL if the function did not
recognize :c:type:`dtype` or :c:type:`doper`.


.. c:function:: size_t get_entity_name (char *buffer, size_t bufsz)

   Get Entity Name (ENAME).

**Parameters**

``char *buffer``
  The buffer where the ENAME will be saved as an ASCII string.

``size_t bufsz``
  The size of **buffer**.

**Description**

Per TP8010, ENAME is defined as the name associated with the host (i.e.
hostname).

**Return**

Number of characters copied to **buffer**.


.. c:function:: size_t get_entity_version (char *buffer, size_t bufsz)

   Get Entity Version (EVER).

**Parameters**

``char *buffer``
  The buffer where the EVER will be saved as an ASCII string.

``size_t bufsz``
  The size of **buffer**.

**Description**

EVER is defined as the operating system name and version as an ASCII
string. This function reads different files from the file system and
builds a string as follows: [os type] [os release] [distro release]

    E.g. "Linux 5.17.0-rc1 SLES 15.4"

**Return**

Number of characters copied to **buffer**.


.. c:function:: char * kv_strip (char *kv)

   Strip blanks from key value string

**Parameters**

``char *kv``
  The key-value string to strip

**Description**

Strip leading/trailing blanks as well as trailing comments from the
Key=Value string pointed to by **kv**.

**Return**

A pointer to the stripped string. Note that the original string,
**kv**, gets modified.


.. c:function:: char * kv_keymatch (const char *kv, const char *key)

   Look for key in key value string

**Parameters**

``const char *kv``
  The key=value string to search for the presence of **key**

``const char *key``
  The key to look for

**Description**

Look for **key** in the Key=Value pair pointed to by **k** and return a
pointer to the Value if **key** is found.

Check if **kv** starts with **key**. If it does then make sure that we
have a whole-word match on the **key**, and if we do, return a pointer
to the first character of value (i.e. skip leading spaces, tabs,
and equal sign)

**Return**

A pointer to the first character of "value" if a match is found.
NULL otherwise.


.. c:function:: char * startswith (const char *s, const char *prefix)

   Checks that a string starts with a given prefix.

**Parameters**

``const char *s``
  The string to check

``const char *prefix``
  A string that **s** could be starting with

**Return**

If **s** starts with **prefix**, then return a pointer within **s** at
the first character after the matched **prefix**. NULL otherwise.


.. c:macro:: round_up

``round_up (val, mult)``

   Round a value **val** to the next multiple specified by **mult**.

**Parameters**

``val``
  Value to round

``mult``
  Multiple to round to.

**Description**

usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16


.. c:function:: __u16 nvmf_exat_len (size_t val_len)

   Return length rounded up by 4

**Parameters**

``size_t val_len``
  Value length

**Description**

Return the size in bytes, rounded to a multiple of 4 (e.g., size of
__u32), of the buffer needed to hold the exat value of size
**val_len**.

**Return**

Length rounded up by 4


.. c:function:: __u16 nvmf_exat_size (size_t val_len)

   Return min aligned size to hold value

**Parameters**

``size_t val_len``
  This is the length of the data to be copied to the "exatval"
  field of a "struct nvmf_ext_attr".

**Description**

Return the size of the "struct nvmf_ext_attr" needed to hold
a value of size **val_len**.

**Return**

The size in bytes, rounded to a multiple of 4 (i.e. size of
__u32), of the "struct nvmf_ext_attr" required to hold a string of
length **val_len**.


.. c:function:: struct nvmf_ext_attr * nvmf_exat_ptr_next (struct nvmf_ext_attr *p)

   Increment **p** to the next element in the array.

**Parameters**

``struct nvmf_ext_attr *p``
  Pointer to an element of an array of "struct nvmf_ext_attr".

**Description**

Extended attributes are saved to an array of "struct nvmf_ext_attr"
where each element of the array is of variable size. In order to
move to the next element in the array one must increment the
pointer to the current element (**p**) by the size of the current
element.

**Return**

Pointer to the next element in the array.




.. c:enum:: nvme_version

   Selector for version to be returned by **nvme_get_version**

**Constants**

``NVME_VERSION_PROJECT``
  Project release version

``NVME_VERSION_GIT``
  Git reference


.. c:function:: const char * nvme_get_version (enum nvme_version type)

   Return version libnvme string

**Parameters**

``enum nvme_version type``
  Selects which version type (see **struct** nvme_version)

**Return**

Returns version string for known types or else "n/a"


.. c:function:: int nvme_uuid_to_string (unsigned char uuid[NVME_UUID_LEN], char *str)

   Return string represenation of encoded UUID

**Parameters**

``unsigned char uuid[NVME_UUID_LEN]``
  Binary encoded input UUID

``char *str``
  Output string represenation of UUID

**Return**

Returns error code if type conversion fails.


.. c:function:: int nvme_uuid_from_string (const char *str, unsigned char uuid[NVME_UUID_LEN])

   Return encoded UUID represenation of string UUID

**Parameters**

``const char *str``
  Output string represenation of UUID

``unsigned char uuid[NVME_UUID_LEN]``
  Binary encoded input UUID

**Return**

Returns error code if type conversion fails.


.. c:function:: int nvme_uuid_random (unsigned char uuid[NVME_UUID_LEN])

   Generate random UUID

**Parameters**

``unsigned char uuid[NVME_UUID_LEN]``
  Generated random UUID

**Description**

Generate random number according
https://www.rfc-editor.org/rfc/rfc4122#section-4.4

**Return**

Returns error code if generating of random number fails.


.. c:function:: int nvme_uuid_find (struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN])

   Find UUID position on UUID list

**Parameters**

``struct nvme_id_uuid_list *uuid_list``
  UUID list returned by identify UUID

``const unsigned char uuid[NVME_UUID_LEN]``
  Binary encoded input UUID

**Return**

The array position where given UUID is present, or -1 on failure with errno set.


.. c:function:: bool nvme_ipaddrs_eq (const char *addr1, const char *addr2)

   Check if 2 IP addresses are equal.

**Parameters**

``const char *addr1``
  IP address (can be IPv4 or IPv6)

``const char *addr2``
  IP address (can be IPv4 or IPv6)

**Return**

true if addr1 == addr2. false otherwise.


.. c:function:: const char * nvme_iface_matching_addr (const struct ifaddrs *iface_list, const char *addr)

   Get interface matching **addr**

**Parameters**

``const struct ifaddrs *iface_list``
  Interface list returned by getifaddrs()

``const char *addr``
  Address to match

**Description**

Parse the interface list pointed to by **iface_list** looking
for the interface that has **addr** as one of its assigned
addresses.

**Return**

The name of the interface that owns **addr** or NULL.


.. c:function:: bool nvme_iface_primary_addr_matches (const struct ifaddrs *iface_list, const char *iface, const char *addr)

   Check that interface's primary address matches

**Parameters**

``const struct ifaddrs *iface_list``
  Interface list returned by getifaddrs()

``const char *iface``
  Interface to match

``const char *addr``
  Address to match

**Description**

Parse the interface list pointed to by **iface_list** and looking for
interface **iface**. The get its primary address and check if it matches
**addr**.

**Return**

true if a match is found, false otherwise.