nvme_io_passthru(2)

💖 nvme_io_passthru(2) 💖

okay bestie, so this is a page from the libnvme API manual, and it's all about one lil' function that yeets a passthrough command at your NVMe device. let's get into it 🫶

---

✨ NAME ✨

nvme_io_passthru — submit an nvme io passthrough command

like. it sends the thing. to the drive. that's the whole vibe 💅

---

🌸 SYNOPSIS 🌸

int nvme_io_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 );

that is a LOT of arguments, i know 😭 she's high maintenance but she works. count them. i'll wait. 🍓

---

🎀 ARGUMENTS 🎀

here's the full roster, no skips, no cuts, we're doing all of them because every single one matters:

• fd — file descriptor of the nvme device 🦋 your ticket to the drive, basically.
• opcode — the nvme io command you're sending ✨ this is the choice, the main character of the call.
• flags — NVMe command flags (not used) 💀 yes literally not used. it's there. it does nothing. we love a decoration.
• rsvd — reserved for future use 👑 hands off, it's saving that seat for later.
• 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

yes we jumped from cdw3 to cdw10, that's not a typo, that's just how NVMe rolls 🙈 the command dwords are exactly what they say on the tin — the raw dwords of the command.

• data_len — length of the data transferred in this command, in bytes 📏
• data — pointer to user address of the data buffer 💖
• metadata_len — length of metadata transferred in this command
• metadata — pointer to user address of the metadata buffer 🧚
• timeout_ms — how long the kernel waits for the command to complete ⏳ patience is a virtue, and this is the exact amount of it.
• result — optional field to return the result from the CQE dword 0 ⭐ optional bestie!! you can pass nothing if you don't care about the tea.

---

💜 DESCRIPTION 💜

so this is the parameterized form of nvme_submit_io_passthru. the way it works is it sets up and submits a struct nvme_passthru_cmd for you — you bring the params, she brings the struct, teamwork periodt 🤝

known values for opcode are defined in enum nvme_io_opcode. so if you're wondering "what can i even put in opcode", that enum is your answer key, go look at it 👀

---

🔥 RETURN 🔥

what you get back, depending:

• the nvme command status, if a response was received — see enum nvme_status_field for what those mean 🎀
• -1 with errno set, otherwise 😭 aka something went wrong, check errno, you got this.

---

so yeah. that's nvme_io_passthru. feed her your fd, your opcode, all seventeen-ish dwords and buffers, and she'll handle the rest. slay 💅✨

this page dropped July 2026, it's from nvme_io_passthru in the libnvme API manual, and it's filed under section nvme_io_passthru(2) 🩷 ty for reading, mwah 🫶