libnvme(9)

💖 libnvme(9) — bestie edition 💖

okay so you're reading the libnvme API manual, section 9, and we're about to get SO cozy with one very specific struct. buckle up, this is gonna be a whole vibe 🦋

---

✨ NAME ✨

struct nvme_io_args — the lil argument bag you hand over when you wanna run NVMe I/O commands 💅

---

✨ SYNOPSIS ✨

struct nvme_io_args {
    __u64 slba;
    __u64 storage_tag;
    __u32 *result;
    void *data;
    void *metadata;
    int args_size;
    int fd;
    __u32 timeout;
    __u32 nsid;
    __u32 reftag;
    __u32 data_len;
    __u32 metadata_len;
    __u16 nlb;
    __u16 control;
    __u16 apptag;
    __u16 appmask;
    __u16 dspec;
    __u8 dsm;
    __u8 rsvd1[1];
    __u64 reftag_u64;
    __u8 sts;
    __u8 pif;
 };

like, look at her. twenty-one fields. every single one of them matters. no skipping. 👑

---

✨ Members ✨

the whole roster, one by one 🎀

• slba — the starting logical block. that's it, that's the field. your launch point, bestie 🚀
• storage_tag — this field specifies the Variable Sized Expected Logical Block Storage Tag (ELBST) or the Logical Block Storage Tag (LBST). two acronyms, one field, iconic behavior honestly.
• result — the command completion result, straight outta CQE dword0. this is where the answer lands.
• data — a pointer to the user address of the data buffer. where your actual bytes live 🫶
• metadata — a pointer to the user address of the metadata buffer. the data buffer's little sibling 💜
• args_size — the size of struct nvme_io_args. yes she knows her own size, self-aware queen.
• fd — the file descriptor of the nvme device. your ticket in 🎟️
• timeout — timeout in ms. milliseconds. tick tock ⏳
• nsid — Namespace ID. which namespace are we even talking to, bestie?
• reftag — this field specifies the variable sized Expected Initial Logical Block Reference Tag (EILBRT) or the Initial Logical Block Reference Tag (ILBRT). it's only used if the namespace is formatted to use end-to-end protection information. read that again. only then. fr fr.
• data_len — the length of the user buffer, data, in bytes. count them, don't guess 😭
• metadata_len — the length of the user buffer, metadata, in bytes. same energy, different buffer.
• nlb — number of logical blocks to send. and yes it's a 0's based value, so be normal about the math.
• control — command control flags, see enum nvme_io_control_flags. go look, iykyk.
• apptag — this field specifies the Application Tag Mask expected value. used only if the namespace is formatted to use end-to-end protection information. yep, another one of those.
• appmask — this field specifies the Application Tag expected value. used only if the namespace is formatted to use end-to-end protection information. (and yes, the doc really does describe apptag as the mask and appmask as the expected value — we don't make the rules, we just report them 💀)
• dspec — directive specific value. short name, big responsibility.
• dsm — data set management attributes, see enum nvme_io_dsm_flags.
• rsvd1 — Reserved. she's just sitting there. leave her alone. 🙈
• reftag_u64 — this field specifies the variable sized Expected Initial Logical Block Reference Tag (EILBRT) or the Initial Logical Block Reference Tag (ILBRT). it's the 8 byte version required for enhanced protection information. used only if the namespace is formatted to use end-to-end protection information. so basically reftag's glow-up ✨
• sts — storage tag size in bits, set by the namespace Extended LBA Format. set by the namespace, not by you. let her cook.
• pif — protection information format. it determines how the variable sized storage_tag and reftag get put into dwords 2, 3, and 14. set by the namespace Extended LBA Format. so if your tags look weird in those dwords, this field is the one who did it 🧚

---

🌸 quick vibe check: a whole bunch of these fields — reftag, reftag_u64, apptag, appmask — are only in play when the namespace is formatted for end-to-end protection information. and sts + pif get set by the namespace's Extended LBA Format. you don't get to freelance those. periodt.

---

and that's the page!! 💖 this was struct nvme_io_args from the libnvme API Manual, section libnvme(9), dated August 2026. slay, go write some I/O 🔥👑