usb_unlink_urb(9)

📦 version 7.3.1, in nixpkgs unstable

okay so bestie, welcome to usb_unlink_urb(9) from the Kernel API Manual — this is the page where we learn how to ✨cancel✨ a transfer request for an endpoint. buckle up 🎀

🌸 NAME 🌸

usb_unlink_urb — abort/cancel a transfer request for an endpoint. periodt.

✨ SYNOPSIS ✨

int usb_unlink_urb (struct urb *urb );

🦋 ARGUMENTS 🦋

  • urb — pointer to a urb describing a request you already submitted. and yes, it may be NULL 💀 (she said "no thoughts, head empty, still a valid argument").

💖 DESCRIPTION 💖

bestie, this routine literally cancels an in-progress request. the rules are giving very strict:

  • URBs complete only once per submission.
  • and they may be canceled only once per submission.

Successful cancellation means termination of urb will be expedited (speedrun 🏃‍♀️) and the completion handler will be called with a status code indicating the request has been canceled — rather than any other code. iconic behavior honestly.

🚨 drivers should not call this routine, or related routines like usb_kill_urb, after their disconnect method has returned. the disconnect function should synchronize with a driver's I/O routines to insure that all URB-related activity has completed before it returns. no cap, do the sync.

This request is asynchronous, however the HCD might call the ->complete callback during unlink. so when drivers call usb_unlink_urb, they must not hold any locks that may be taken by the completion function. like, at all. put the lock down 🙈

Success is indicated by returning -EINPROGRESS, at which time the URB will probably not yet have been given back to the device driver. when it is eventually called, the completion function will see urb->status == -ECONNRESET. 🔥

Failure is indicated by usb_unlink_urb returning any other value. unlinking will fail when urb is not currently "linked" — i.e.:

  • it was never submitted, or
  • it was unlinked before, or
  • the hardware is already finished with it —

even if the completion handler has not yet run. yeah, the vibe check can fail 😭

⚠️ 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. say it with me: no. use. after. free. 💀

💫 Unlinking and Endpoint Queues

[The behaviors and guarantees described below do not apply to virtual root hubs but only to endpoint queues for physical USB devices.] — read that twice, it matters 🫶

Host Controller Drivers (HCDs) place all the URBs for a particular endpoint in a queue. normally the queue advances as the controller hardware processes each request. but when an URB terminates with an error, its queue generally stops (see below) — at least until that URB's completion routine returns.

It is guaranteed that a stopped queue will not restart until all its unlinked URBs have been fully retired, with their completion routines run, even if that's not until some time after the original completion handler returns. the same behavior and guarantee apply when an URB terminates because it was unlinked. slay, consistency 💅

Bulk and interrupt endpoint queues are guaranteed to stop whenever an URB terminates with any sort of error, including -ECONNRESET, -ENOENT, and -EREMOTEIO. Control endpoint queues behave the same way except that they are not guaranteed to stop for -EREMOTEIO errors. 👀

Queues for isochronous endpoints are treated differently, because they must advance at fixed rates. such queues do not stop when an URB encounters an error or is unlinked. an unlinked isochronous URB may leave a gap in the stream of packets; it is undefined whether such gaps can be filled in. so like, don't count on it 🕳️

Note that early termination of an URB because a short packet was received will generate a -EREMOTEIO error if and only if the URB_SHORT_NOT_OK flag is set. by setting this flag, USB device drivers can build deep queues for large or complex bulk transfers and clean them up reliably after any sort of aborted transfer by unlinking all pending URBs at the first fault. big brain energy fr fr 🧠✨

When a control URB terminates with an error other than -EREMOTEIO, it is quite likely that the status stage of the transfer will not take place. just so you know 🌈

👑 RETURN 👑

  • -EINPROGRESS on success. 🎉
  • see description for other values on failure. (she's not gonna spell it out twice, bestie.)

🍓 SEE ALSO 🍓

Kernel file ./drivers/usb/core/urb.c:

💜 and that's the whole page, bestie!! this one came from ./drivers/usb/core and it's dated October 2026 — literally a little time capsule 🎀 go forth and unlink responsibly, mwah 🫶✨💅

📦 where this page comes from