Crate libnvme

Expand description

Safe, idiomatic Rust bindings for the Linux libnvme C library.

libnvme is the userspace library that backs nvme-cli. This crate exposes a memory-safe wrapper over its handle tree:

Root → Host → Subsystem → Controller → Namespace

Every handle borrows from the Root via the 'r lifetime, so dropping the Root cascades-frees the entire tree.

§Example

use libnvme::Root;

let root = Root::scan()?;
for host in root.hosts() {
    for subsys in host.subsystems() {
        for ctrl in subsys.controllers() {
            println!("{} {}", ctrl.name()?, ctrl.model()?);
            let id = ctrl.identify()?;
            println!("  NVMe spec: {}", id.nvme_version());
            for ns in ctrl.namespaces() {
                println!("  {} ({} bytes)", ns.name()?, ns.size_bytes());
            }
        }
    }
}

Structs§

Compare: Builder returned by Namespace::compare.
Connect: Builder for an NVMe-oF Connect operation.
Controller: An NVMe controller.
Controllers: Iterator over Controller entries, returned by crate::Subsystem::controllers.
Copy: Builder returned by Namespace::copy.
CopyRange: One source range for the NVMe Copy command (format 0).
DirectiveRecv: Builder returned by Namespace::directive_recv.
DirectiveSend: Builder returned by Namespace::directive_send.
DiscoveryLog: Discovery-log header + entries returned by a discovery controller’s log page (LID 0x70).
DiscoveryLogEntry: One entry from the discovery log page.
Dsm: Builder returned by Namespace::dsm.
DsmAttr: DSM attribute bits (CDW11). Combine with |.
DsmRange: One DSM range entry. NVMe spec: each entry covers up to 4 GiB of LBAs.
ErrorLogEntry: One entry from the Error Information log page (LID 01h).
Features: Get/Set Features accessor for a controller.
FirmwareSlotLog: Firmware Slot Information log page (LID 03h).
Format: Builder for the Format NVM admin command.
GetLbaStatusArgs: Parameters for Get LBA Status (NVMe 1.4+).
Host: A host entry in the libnvme tree.
Hosts: Iterator over Host entries, returned by Root::hosts.
IdentifyController: Decoded Identify Controller (CNS 01h) data structure.
IdentifyNamespace: Decoded Identify Namespace (CNS 00h) data structure.
LbaFormat: One LBA format entry from Identify Namespace.
LockdownArgs: Parameters for the Lockdown admin command (NVMe 2.0+).
Namespace: An NVMe namespace.
Namespaces: Iterator over Namespace entries reachable through a crate::Controller.
NvmeVersion: Decoded NVMe specification version, as reported by the controller’s VER register and the vs field of Identify Controller.
PassthruArgs: Parameters for Controller::admin_passthru / Controller::io_passthru.
Path: A single multipath route to a namespace.
Paths: Iterator over Path entries reachable through a Controller or Namespace.
Read: Builder returned by Namespace::read.
ReservationAcquire: Builder returned by Namespace::reservation_acquire.
ReservationRegister: Builder returned by Namespace::reservation_register.
ReservationRelease: Builder returned by Namespace::reservation_release.
ReservationReport: Builder returned by Namespace::reservation_report.
Root: The owning handle to the libnvme tree.
Sanitize: Builder for the Sanitize NVM admin command.
SmartLog: Decoded SMART / Health Information log page (LID 02h).
Subsystem: An NVMe subsystem.
Subsystems: Iterator over Subsystem entries, returned by crate::Host::subsystems.
Verify: Builder returned by Namespace::verify.
Write: Builder returned by Namespace::write.
WriteUncorrectable: Builder returned by Namespace::write_uncorrectable.
WriteZeroes: Builder returned by Namespace::write_zeroes.
ZnsAppend: Builder returned by Namespace::zns_append.
ZnsMgmtRecv: Builder returned by Namespace::zns_mgmt_recv.
ZnsMgmtSend: Builder returned by Namespace::zns_mgmt_send.

Enums§

DirectiveRecvOp: Directive Receive Operation (doper).
DirectiveSendOp: Directive Send Operation (doper).
DirectiveType: Directive Type (dtype).
Error: Errors returned by this crate.
FeatureSelect: Which “view” of a feature value the Get Features command should return.
FirmwareAction: What the firmware-commit admin command should do with the slot it targets.
MetadataSettings: How metadata is transferred relative to LBA data.
ProtectionInfo: End-to-end Data Protection type to apply when formatting.
ProtectionLocation: Where the PI guard bytes sit within each LBA.
PtplChange: Change-Persist-Through-Power-Loss (cptpl) for Reservation Register.
ReservationAcquireAction: Reservation Acquire action (racqa).
ReservationRegisterAction: Reservation Register action (rrega).
ReservationReleaseAction: Reservation Release action (rrela).
ReservationType: Reservation type (rtype) — sets the access semantics for the reservation holder vs. registered hosts vs. non-registered hosts.
SanitizeAction: Sanitize action — what the Sanitize admin command should do to the drive’s user data area.
SecureErase: How user data should be erased during a Format NVM operation.
SelfTestAction: Self-test action for the Device Self-Test admin command.
Transport: NVMe-oF transport selector. The Other variant is an escape hatch for transports added to libnvme after this crate was released.
ZoneRecvAction: Zone Receive Action (zra).
ZoneReportFilter: Report-zones filter (ZRASF, zone-receive action-specific field).
ZoneSendAction: Zone Send Action (zsa).

Functions§

generate_hostid: Generate a fresh HostID (random UUID, formatted as a hex string).
generate_hostnqn: Generate a fresh HostNQN (NVMe spec format, embeds a freshly-generated UUID). Equivalent to libnvme’s nvmf_hostnqn_generate. Returned string is owned.
hostid_from_file: Read the local HostID from /etc/nvme/hostid if it exists.
hostnqn_from_file: Read the local HostNQN from /etc/nvme/hostnqn if it exists.

Type Aliases§

AutoPst
HostBehavior
HostMemBufAttrs
LbaRangeType
PlmConfig
Result: Result type alias for fallible operations in this crate.
Timestamp

Crate libnvme

Crate libnvme Copy item path

§Example

Structs§

Enums§

Functions§

Type Aliases§

Crate libnvme