struct libnvme_global_ctx *libnvme_create_global_ctx(FILE *fp, int log_level)

Initialize global context object

Parameters

FILE *fp

File descriptor for logging messages

int log_level

Logging level to use

Return

Initialized struct libnvme_global_ctx object

void libnvme_free_global_ctx(struct libnvme_global_ctx *ctx)

Free global context object

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

Description

Free an struct libnvme_global_ctx object and all attached objects

void libnvme_set_logging_level(struct libnvme_global_ctx *ctx, int log_level, bool log_pid, bool log_tstamp)

Set current logging level

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

int log_level

Logging level to set

bool log_pid

Boolean to enable logging of the PID

bool log_tstamp

Boolean to enable logging of the timestamp

Description

Sets the current logging level for the global context.

int libnvme_get_logging_level(struct libnvme_global_ctx *ctx, bool *log_pid, bool *log_tstamp)

Get current logging level

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

bool *log_pid

Pointer to store a current value of logging of the PID flag at (optional).

bool *log_tstamp

Pointer to store a current value of logging of the timestamp flag at (optional).

Description

Retrieves current values of logging variables.

Return

current log level value or LIBNVME_DEFAULT_LOGLEVEL if not initialized.

int libnvme_open(struct libnvme_global_ctx *ctx, const char *name, struct libnvme_transport_handle **hdl)

Open an nvme controller or namespace device

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

const char *name

The basename of the device to open

struct libnvme_transport_handle **hdl

Transport handle to return

Description

This will look for the handle in /dev/ and validate the name and filetype match linux conventions.

Return

0 on success, negative error code otherwise.

void libnvme_close(struct libnvme_transport_handle *hdl)

Close transport handle

Parameters

struct libnvme_transport_handle *hdl

Transport handle

libnvme_fd_t libnvme_transport_handle_get_fd(struct libnvme_transport_handle *hdl)

Return file descriptor from the transport handle

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Description

If the device handle is for a ioctl based device, libnvme_transport_handle_get_fd will return a valid file descriptor.

Return

File descriptor for an IOCTL based transport handle, otherwise LIBNVME_INVALID_FD.

struct libnvme_mi_ep *libnvme_transport_handle_get_mi_ep(struct libnvme_transport_handle *hdl)

get the MI endpoint from a transport handle

Parameters

struct libnvme_transport_handle *hdl

transport handle

Description

Retrieve the MI endpoint associated with this transport handle. Only valid for MI-type transport handles (check with libnvme_transport_handle_is_mi first).

Return

the MI endpoint, or NULL if the handle is not an MI handle.

const char *libnvme_transport_handle_get_name(struct libnvme_transport_handle *hdl)

Return name of the device transport handle

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Return

Device file name, otherwise -1.

bool libnvme_transport_handle_is_ctrl(struct libnvme_transport_handle *hdl)

Check if transport handle is a controller device

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Return

Return true if transport handle is a controller device, otherwise false.

bool libnvme_transport_handle_is_direct(struct libnvme_transport_handle *hdl)

Check if transport handle is using IOCTL interface

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Return

Return true if transport handle is using IOCTL interface, otherwise false.

bool libnvme_transport_handle_is_mi(struct libnvme_transport_handle *hdl)

Check if transport handle is a using MI interface

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Return

Return true if transport handle is using MI interface, otherwise false.

bool libnvme_transport_handle_is_ns(struct libnvme_transport_handle *hdl)

Check if transport handle is a namespace device

Parameters

struct libnvme_transport_handle *hdl

Transport handle

Return

Return true if transport handle is a namespace device, otherwise false.

void libnvme_transport_handle_set_submit_entry(struct libnvme_transport_handle *hdl, void *(*submit_entry)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd))

Install a submit-entry callback

Parameters

struct libnvme_transport_handle *hdl

Transport handle to configure

void *(*submit_entry)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd)

Callback invoked immediately before a passthrough command is submitted. The function receives the command about to be issued and may return an opaque pointer representing per-command context. This pointer is later passed unmodified to the submit-exit callback. Implementations typically use this hook for logging, tracing, or allocating per-command state.

Description

Installs a user-defined callback that is invoked at the moment a passthrough command enters the NVMe submission path. Passing NULL removes any previously installed callback.

Return

None.

void libnvme_transport_handle_set_submit_exit(struct libnvme_transport_handle *hdl, void (*submit_exit)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, int err, void *user_data))

Install a submit-exit callback

Parameters

struct libnvme_transport_handle *hdl

Transport handle to configure

void (*submit_exit)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, int err, void *user_data)

Callback invoked after a passthrough command completes. The function receives the command, the completion status err (0 for success, a negative errno, or an NVMe status value), and the user_data pointer returned earlier by the submit-entry callback. Implementations typically use this hook for logging, tracing, or freeing per-command state.

Description

Installs a callback that is invoked when a passthrough command leaves the NVMe submission path. Passing NULL removes any previously installed callback.

Return

None.

void libnvme_transport_handle_set_decide_retry(struct libnvme_transport_handle *hdl, bool (*decide_retry)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, int err))

Install a retry-decision callback

Parameters

struct libnvme_transport_handle *hdl

Transport handle to configure

bool (*decide_retry)(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, int err)

Callback used to determine whether a passthrough command should be retried after an error. The function is called with the command that failed and the error code returned by the kernel or device. The callback should return true if the submission path should retry the command, or false if the error is final.

Description

Installs a user-provided callback to control retry behavior for passthrough commands issued through hdl. This allows transports or higher-level logic to implement custom retry policies, such as retrying on transient conditions like -EAGAIN or device-specific status codes.

Passing NULL clears any previously installed callback and reverts to the default behavior (no retries).

Return

None.

void libnvme_transport_handle_set_timeout(struct libnvme_transport_handle *hdl, __u32 timeout_ms)

Set the default command timeout

Parameters

struct libnvme_transport_handle *hdl

Transport handle to configure

__u32 timeout_ms

Timeout in milliseconds. A value of 0 means use the kernel default (NVME_DEFAULT_IOCTL_TIMEOUT).

Description

Sets a default timeout that is applied to every passthrough command submitted through hdl when the command’s own timeout_ms field is 0. Commands that set a non-zero timeout_ms override this default.

void libnvme_set_probe_enabled(struct libnvme_global_ctx *ctx, bool enabled)

enable/disable the probe for new MI endpoints

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

bool enabled

whether to probe new endpoints

Description

Controls whether newly-created endpoints are probed for quirks on creation. Defaults to enabled, which results in some initial messaging with the endpoint to determine model-specific details.

void libnvme_set_dry_run(struct libnvme_global_ctx *ctx, bool enable)

Set global dry run state

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

bool enable

Enable/disable dry run state

Description

When dry_run is enabled, any IOCTL commands send via the passthru interface won’t be executed.

void libnvme_set_ioctl_probing(struct libnvme_global_ctx *ctx, bool enable)

Enable/disable 64-bit IOCTL probing

Parameters

struct libnvme_global_ctx *ctx

struct libnvme_global_ctx object

bool enable

Enable/disable 64-bit IOCTL probing

Description

When IOCTL probing is enabled, a 64-bit IOCTL command is issued to figure out if the passthru interface supports it.

IOCTL probing is enabled per default.