usb_poison_urb(9)

💅 usb_poison_urb(9) — the Kernel API Manual, but make it make sense 🎀

okay so bestie, welcome to usb_poison_urb(9), the one where we reliably kill a transfer and prevent further use of an URB. yes. that's the whole vibe. it's giving "we're done here" energy and honestly? iconic. ✨

---

✨ SYNOPSIS ✨

void usb_poison_urb (struct urb *urb);

that's it. that's the whole call. one (1) pointer, no return value, maximum chaos potential. 🦋

---

🌸 ARGUMENTS 🌸

• urb — pointer to the URB describing a request you already submitted, and guess what: it may be NULL. fr fr, that's allowed. 🫶

---

💜 DESCRIPTION 💜

So what does this thing actually do? It cancels an in-progress request, and it does it hard. Like, guaranteed hard. 💀

When this routine returns, you have my word: all completion handlers will have finished, and the URB will be totally idle and cannot be reused. Not "shouldn't", not "probably won't" — cannot. That's the whole point, and it's exactly why this is the ideal way to stop I/O in a disconnect callback. 👑

And here's the tea 🍓: if the request hasn't already finished or been unlinked, the completion handler is gonna see this:

urb->status == -ENOENT

yes bestie, -ENOENT. that's the signal. 😭

Now, after this routine runs — and honestly while it's running too — any attempt to resubmit the URB will fail with error -EPERM. so even if the URB's completion handler is that one friend who always tries to resubmit… it will not succeed, and the URB will become idle. no cap. the door is locked. 🚪🔒

⚠️ BIG IMPORTANT ONE, do not skip this: The URB must not be deallocated while this routine is running. In particular, when a driver calls this routine, it must insure that the completion handler cannot deallocate the URB. like, you literally cannot let that happen. it's not a vibe. it's a crash. 💀

⚠️ Also: This routine may not be used in an interrupt context (such as a bottom half or a completion handler), or when holding a spinlock, or in other situations where the caller can't schedule. so if you can't schedule, you can't call this. periodt. ✋

⚠️ And one more: This routine should not be called by a driver after its disconnect method has returned. like, that window's closed, bestie. the store is shut. 🙈

---

🌈 SEE ALSO 🌈

Kernel file ./drivers/usb/core/urb.c — go read it, it's the source of truth 💖 — plus this whole friend group right here:

• usb_init_urb(9)
• usb_alloc_urb(9)
• usb_free_urb(9)
• usb_get_urb(9)
• usb_anchor_urb(9)
• usb_unanchor_urb(9)
• usb_pipe_type_check(9)
• usb_urb_ep_type_check(9)
• usb_submit_urb(9)
• usb_unlink_urb(9)
• usb_kill_urb(9)
• usb_block_urb(9)
• usb_kill_anchored_urbs(9)
• usb_poison_anchored_urbs(9)
• usb_unpoison_anchored_urbs(9)
• usb_anchor_suspend_wakeups(9)
• usb_anchor_resume_wakeups(9)
• usb_wait_anchor_empty_timeout(9)
• usb_get_from_anchor(9)
• usb_scuttle_anchored_urbs(9)
• usb_anchor_empty(9)

---

and that's the page! 🧚‍♀️

cute lil sign-off moment: this one lives in ./drivers/usb/core, dated October 2026, and the whole thing is usb_poison_urb(9) — you're welcome, go poison some URBs responsibly 💅🎀🦋