Attachment #117768 for bug #159898

View | Details | Raw Unified | Return to bug 159898
Collapse All | Expand All




.Nm libusb
.Nd "USB access library"
.Sh LIBRARY
USB access library
.Pq libusb, -lusb
.Sh SYNOPSIS
.In libusb.h
.Sh DESCRIPTION

.Ft int
.Fn libusb_init libusb_context **ctx
This function initialises libusb.
It must be called at the beginning
of the program, before other libusb routines are used.
This function returns 0 on success or LIBUSB_ERROR on
failure.
.Pp

.Fn libusb_exit "libusb_context *ctx"
Deinitialise libusb.
Must be called at the end of the application.
Other libusb routines may not be called after this function.
.Pp
.Ft const char *
.Fn libusb_strerror "int code"
Get the ASCII representation of the error given by the
.Fa code
argument.
.Pp
.Ft void
.Fn libusb_set_debug "libusb_context *ctx" "int level"
Set the debug level to
.Fa level .
level.
.Pp
.Ft ssize_t
.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
Populate
.Fa list
with the list of usb devices available, adding a reference to each
device in the list.
All the list entries created by this
function must have their reference counter
decremented when you are done with them,
and the list itself must be freed.
This
function returns the number of devices in the list or a LIBUSB_ERROR code.
.Pp
.Ft void
.Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
Free the list of devices discovered by libusb_get_device_list.
If
.Fa unref_device
is set to 1 all devices in the list have their reference
counter decremented once.
.Pp
.Ft uint8_t
.Fn libusb_get_bus_number "libusb_device *dev"

.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
Open a device and obtain a device_handle.
Returns 0 on success,
LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on other errors.
.Pp
.Ft libusb_device_handle *
.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
A convenience function to open a device with vendor and producd IDs
.Fa vid
and
.Fa pid.

.Pp
.Ft int
.Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
Set the active configuration to
.Fa config
for the device contained by
.Fa devh.

Claim an interface in a given libusb_handle
.Fa devh.
This is a non-blocking function.
It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
been disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
This function releases an interface.
All the claimed interfaces on a device must be released
before closing the device.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and LIBUSB_ERROR on failure.

Returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"

.Pp
.Ft int
.Fn libusb_check_connected "libusb_device_handle *devh"
Test if the USB device is still connected.
Returns 0 on success,
LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
code on failure.
.Pp
.Ft int
.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
Determine if a driver is active on a interface.
Returns 0 if no kernel driver
is active, 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
if the device has been disconnected and a LIBUSB_ERROR code on failure.
if the device has been disconnected and returns a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
or
.Ft int
.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
Copy the name of the driver attached to the given
.Fa device
and
.Fa interface
into the buffer
.Fa name
of length
.Fa namelen .
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does

.Ft int
.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
Detach a kernel driver from an interface.
This is needed to claim an interface already claimed by a kernel driver.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected

.Pp
.Ft int
.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
Re-attach an interface kernel driver that was previously detached.
Returns 0 on success,
LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
LIBUSB_ERROR_NO_DEVICE
if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
attached because the interface is claimed by a program or driver and a
LIBUSB_ERROR code on failure.
.Pp

.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
Get the USB configuration descriptor for the active configuration.
Returns 0 on
success, LIBUSB_ERROR_NOT_FOUND if the device is in
an unconfigured state
and a LIBUSB_ERROR code on error.
.Pp
.Ft int
.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
Get a USB configuration descriptor based on its index
.Fa idx.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
and a LIBUSB_ERROR code on error.
.Pp
.Ft int
.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
Get a USB configuration descriptor with a specific bConfigurationValue.
This is
a non-blocking function which does not send a request through the device.
Returns 0
on success, LIBUSB_ERROR_NOT_FOUND if the configuration
does not exist and a
LIBUSB_ERROR code on failure.
.Pp
.Ft void

.Pp
.Ft int
.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
Retrieve a string descriptor in C style ASCII.
Returns the positive number of bytes in the resulting ASCII string
on success and a LIBUSB_ERROR code on failure.
.Pp
.Sh USB ASYNCHRONOUS I/O
.Pp
.Ft struct libusb_transfer *
.Fn libusb_alloc_transfer "int iso_packets"
Allocate a transfer with the number of isochronous packet descriptors
specified by
.Fa iso_packets .
Returns NULL on error.
.Pp
.Ft void

.Fn libusb_submit_transfer "struct libusb_transfer *tr"
This function will submit a transfer and returns immediately.
Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
the device has been disconnected and a
LIBUSB_ERROR code on other failure.
.Pp
.Ft int
.Fn libusb_cancel_transfer "struct libusb_transfer *tr"
This function asynchronously cancels a transfer.
Returns 0 on success and a LIBUSB_ERROR code on failure.
.Pp
.Sh USB SYNCHRONOUS I/O
.Pp

.Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint8_t bRequest" "uint16_t wValue" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout"
Perform a USB control transfer.
Returns the actual number of bytes
transferred on success, in the range from and including zero up to and
including
.Fa wLength .
On error a LIBUSB_ERROR code is returned, for example
LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
device has been disconnected and another LIBUSB_ERROR code on other failures.
The LIBUSB_ERROR codes are all negative.
.Pp
.Ft int
.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"

A timeout value of zero means no timeout.
The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
a LIBUSB_ERROR code on other failure.
.Pp
.Ft int
.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"

A timeout value of zero means no timeout.
The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
a LIBUSB_ERROR code on other failure.
.Pp
.Sh USB EVENTS
.Pp

.Fn libusb_unlock_events "libusb_context *ctx"
Release the event handling lock.
This will wake up any thread blocked
on
.B libusb_wait_for_event() .
.Pp
.Ft int
.Fn libusb_event_handling_ok "libusb_context *ctx"

.Ft int
.Fn libusb_event_handler_active "libusb_context *ctx"
Determine if an active thread is handling events.
Returns 1 if there is a thread handling events and 0 if there
are no threads currently handling events.
.Pp
.Ft void
.Fn libusb_lock_event_waiters "libusb_context *ctx"
Acquire the event_waiters lock.
This lock is designed to be obtained in the
situation where you want to be aware when events are completed, but some other
thread is event handling so calling libusb_handle_events() is not allowed.
.Pp

block until the timeout expires or a transfer completes or a thread releases
the event handling lock through libusb_unlock_events().
Returns 0 after a
transfer completes or another thread stops event handling, and 1 if the
timeout expired.
.Pp
.Ft int

.Fn libusb_handle_events "libusb_context *ctx"
Handle any pending events in blocking mode with a sensible timeout.
Returns 0
on success and a LIBUSB_ERROR code on failure.
.Pp
.Ft int
.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
Handle any pending events by polling file desciptors, without checking if
another thread is already doing so.
Must be called with the event lock held.
.Pp
.Ft int
.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
Determine the next internal timeout that libusb needs to handle.
Returns 0
if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
code on failure.
.Pp
.Ft void

Return to bug 159898