.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "USB_UNLINK_URB" "9" "09 October 2005" "" ""

.SH NAME
usb_unlink_urb \- abort/cancel a transfer request for an endpoint
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
int usb_unlink_urb  (struct urb * \fIurb\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIurb\fB\fR
pointer to urb describing a previously submitted request,
may be NULL
.SH "DESCRIPTION"
.PP
This routine cancels an in-progress request.  URBs complete only
once per submission, and may be canceled only once per submission.
Successful cancellation means the requests's completion handler will
be called with a status code indicating that the request has been
canceled (rather than any other code) and will quickly be removed
from host controller data structures.
.PP
In the past, clearing the URB_ASYNC_UNLINK transfer flag for the
URB indicated that the request was synchronous.  This usage is now
deprecated; if the flag is clear the call will be forwarded to
\fBusb_kill_urb\fR and the return value will be 0.  In the future, drivers
should call \fBusb_kill_urb\fR directly for synchronous unlinking.
.PP
When the URB_ASYNC_UNLINK transfer flag for the URB is set, this
request is asynchronous.  Success is indicated by returning -EINPROGRESS,
at which time the URB will normally have been unlinked but not yet
given back to the device driver.  When it is called, the completion
function will see urb->status == -ECONNRESET.  Failure is indicated
by any other return value.  Unlinking will fail when the 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.
.SH "UNLINKING AND ENDPOINT QUEUES"
.PP
.PP
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 stops, at least until that URB's completion routine
returns.  It is guaranteed that the 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.  Normally the same behavior and guarantees
apply when an URB terminates because it was unlinked; however if an
URB is unlinked before the hardware has started to execute it, then
its queue is not guaranteed to stop until all the preceding URBs have
completed.
.PP
This means that USB device drivers can safely build deep queues for
large or complex transfers, and clean them up reliably after any sort
of aborted transfer by unlinking all pending URBs at the first fault.
.PP
Note that an URB terminating early because a short packet was received
will count as an error if and only if the URB_SHORT_NOT_OK flag is set.
Also, that all unlinks performed in any URB completion handler must
be asynchronous.
.PP
Queues for isochronous endpoints are treated differently, because they
advance at fixed rates.  Such queues do not stop when an URB is unlinked.
An unlinked URB may leave a gap in the stream of packets.  It is undefined
whether such gaps can be filled in.
.PP
When a control URB terminates with an error, it is likely that the
status stage of the transfer will not take place, even if it is merely
a soft error resulting from a short-packet with URB_SHORT_NOT_OK set.