nvme_admin_passthru(2)

💖 nvme_admin_passthru — bestie's guide to yeeting an admin command at your NVMe 💖

okay so this is a page from the libnvme API manual — section 2, the syscall-ish zone — and it's all about nvme_admin_passthru. yes it's a mouthful. no we're not renaming it. she's iconic, she's lowercase, and she's about to hand-roll an NVMe command for you. sit down, grab a strawberry 🍓, let's go.

---

✨ NAME ✨

nvme_admin_passthru — submit an NVMe passthrough command. that's it, that's the whole name section, no notes. 💅

---

🦋 SYNOPSIS 🦋

int nvme_admin_passthru (int fd , __u8 opcode , __u8 flags , __u16 rsvd
, __u32 nsid , __u32 cdw2 , __u32 cdw3 , __u32 cdw10 , __u32 cdw11 ,
__u32 cdw12 , __u32 cdw13 , __u32 cdw14 , __u32 cdw15 , __u32 data_len ,
void *data , __u32 metadata_len , void *metadata , __u32 timeout_ms ,
__u32 *result );

like, that's a LOT of parameters, bestie. it's giving "the function that knows everybody". but honestly every single one of them is doing a job and we're gonna be so normal about it. 😌

---

🌸 ARGUMENTS 🌸

• fd — file descriptor of the NVMe device. your ticket in. 🎟️
• opcode — the nvme io command you're sending. the "what am i even doing here" field.
• flags — NVMe command flags. and here's the tea: they're not used. reserved, ignored, sitting in the corner being decorative. 🙈
• rsvd — reserved for future use. it's a maybe-baby. don't touch, don't expect anything.
• nsid — namespace identifier. which namespace are we talking to, bestie?
• cdw2 — command dword 2.
• cdw3 — command dword 3.
• cdw10 — command dword 10.
• cdw11 — command dword 11.
• cdw12 — command dword 12.
• cdw13 — command dword 13.
• cdw14 — command dword 14.
• cdw15 — command dword 15.

(and yes, the list literally jumps from cdw3 to cdw10 — that is not a typo, that is just how the NVMe spec does dwords, we do not question it, we respect it. 🫶)

• data_len — length of the data transferred in this command, in bytes. 📏
• data — pointer to the user address of the data buffer.
• metadata_len — length of metadata transferred in this command.
• metadata — pointer to the user address of the metadata buffer.
• timeout_ms — how long the kernel waits for the command to complete. patience: measured. ⏳
• result — optional field to return the result from the CQE dword 0. optional!! so it can be a little ✨nothing✨ and that's valid.

---

💜 DESCRIPTION 💜

so basically this is the parameterized form of nvme_submit_admin_passthru. same energy, but you're handing over every single piece yourself instead of pointing at a struct.

what she does under the hood: sets up and submits a struct nvme_passthru_cmd. one struct, fully dressed, ready for the kernel runway. 💃

and if you're wondering "okay but what are the valid opcode values??" — the known values for opcode are defined in enum nvme_admin_opcode. go look, it's all there. iykyk. 👑

---

🔥 RETURN 🔥

two possible endings, choose your fighter:

• the nvme command status if a response was received — check enum nvme_status_field for what the number is actually saying. it's giving fortune cookie but in hex.
• -1 with errno set otherwise. classic. the universal "something went sideways, check errno bestie" 💀

---

real talk: if you get back a status, read the status. don't just stare at it. enum nvme_status_field is literally right there waiting for you. 🌈

---

that's the whole page, no crumbs left. written with love, submitted with struct nvme_passthru_cmd, and signed off from the libnvme API manual, section nvme_admin_passthru(2), dated July 2026. periodt. 👑✨💖