NAME¶
libusb —
USB access library
LIBRARY¶
USB access library (libusb, -lusb)
SYNOPSIS¶
#include <libusb.h>
DESCRIPTION¶
The
libusb library contains interfaces for directly managing a
usb device. The current implementation supports v1.0 of the libusb API.
LIBRARY
INITIALISATION / DEINITIALISATION¶
int
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.
void
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.
const char *
libusb_strerror(
int code) Get the
ASCII representation of the error given by the
code
argument. This function does not return NULL.
const char *
libusb_error_name(
int code) Get the
ASCII representation of the error enum given by the
code
argument. This function does not return NULL.
void
libusb_set_debug(
libusb_context *ctx,
int level) Set the debug level to
level.
ssize_t
libusb_get_device_list(
libusb_context
*ctx,
libusb_device ***list) Populate
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.
void
libusb_free_device_list(
libusb_device
**list,
int unref_devices) Free the list of
devices discovered by libusb_get_device_list. If
unref_device is set to 1 all devices in the list have
their reference counter decremented once.
uint8_t
libusb_get_bus_number(
libusb_device
*dev) Returns the number of the bus contained by the device
dev.
uint8_t
libusb_get_device_address(
libusb_device
*dev) Returns the device_address contained by the device
dev.
enum libusb_speed
libusb_get_device_speed(
libusb_device
*dev) Returns the wire speed at which the device is connected. See the
LIBUSB_SPEED_XXX enums for more information. LIBUSB_SPEED_UNKNOWN is returned
in case of unknown wire speed.
int
libusb_get_max_packet_size(
libusb_device
*dev,
unsigned char endpoint) Returns the
wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the endpoint does
not exist and LIBUSB_ERROR_OTHERS on other failure.
libusb_device *
libusb_ref_device(
libusb_device *dev)
Increment the reference counter of the device
dev.
void
libusb_unref_device(
libusb_device
*dev) Decrement the reference counter of the device
dev.
int
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.
libusb_device_handle *
libusb_open_device_with_vid_pid(
libusb_context
*ctx,
uint16_t vid,
uint16_t
pid) A convenience function to open a device by vendor and product IDs
vid and
pid. Returns NULL on
error.
void
libusb_close(
libusb_device_handle
*devh) Close a device handle.
libusb_device *
libusb_get_device(
libusb_device_handle
*devh) Get the device contained by devh. Returns NULL on error.
int
libusb_get_configuration(
libusb_device_handle
*devh,
int *config) Returns the bConfiguration
value of the current configuration. Returns 0 on success,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR
code on error.
int
libusb_set_configuration(
libusb_device_handle
*devh,
int config) Set the active configuration to
config for the device contained by
devh. This function returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if the requested configuration does not exist,
LIBUSB_ERROR_BUSY if the interfaces are currently claimed,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR
code on failure.
int
libusb_claim_interface(
libusb_device_handle
*devh,
int interface_number) Claim an interface in
a given libusb_handle
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.
int
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.
int
libusb_set_interface_alt_setting(
libusb_device_handle
*dev,
int interface_number,
int
alternate_setting) Activate an alternate setting for an interface.
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.
int
libusb_clear_halt(
libusb_device_handle
*devh,
unsigned char endpoint) Clear an halt/stall
for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the endpoint
does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
a LIBUSB_ERROR code on failure.
int
libusb_reset_device(
libusb_device_handle
*devh) Perform an USB port reset for an usb device. Returns 0 on
success, LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device
has been disconnected and a LIBUSB_ERROR code on failure.
int
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.
int
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 and 1 if a
kernel driver is active, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on failure.
int
libusb_get_driver(
libusb_device_handle
*devh,
int interface,
char
*name,
int namelen) or
int
libusb_get_driver_np(
libusb_device_handle
*devh,
int interface,
char
*name,
int namelen) Copy the name of the driver
attached to the given
device and
interface into the buffer
name of
length
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 not exist. This function
is non-portable. The buffer pointed to by
name is only
zero terminated on success.
int
libusb_detach_kernel_driver(
libusb_device_handle
*devh,
int interface) or
int
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 and a LIBUSB_ERROR
code on failure. This function is non-portable.
int
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.
USB DESCRIPTORS¶
int
libusb_get_device_descriptor(
libusb_device
*dev,
libusb_device_descriptor *desc) Get the USB
device descriptor for the device
dev. This is a
non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on
failure.
int
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.
int
libusb_get_config_descriptor(
libusb_device
*dev,
uint8_t config_index,
libusb_config_descriptor **config) Get a USB
configuration descriptor based on its index
idx. Returns
0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and a
LIBUSB_ERROR code on error.
int
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.
void
libusb_free_config_descriptor(
libusb_config_descriptor
*config) Free a configuration descriptor.
int
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.
USB ASYNCHRONOUS I/O¶
struct libusb_transfer *
libusb_alloc_transfer(
int iso_packets)
Allocate a transfer with the number of isochronous packet descriptors
specified by
iso_packets. Returns NULL on error.
void
libusb_free_transfer(
struct libusb_transfer
*tr) Free a transfer.
int
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.
int
libusb_cancel_transfer(
struct
libusb_transfer *tr) This function asynchronously cancels a transfer.
Returns 0 on success and a LIBUSB_ERROR code on failure.
USB SYNCHRONOUS I/O¶
int
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
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.
int
libusb_bulk_transfer(
struct
libusb_device_handle *devh,
unsigned char
endpoint,
unsigned char *data,
int
length,
int *transferred,
unsigned
int timeout) Perform an USB bulk transfer. 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.
int
libusb_interrupt_transfer(
struct
libusb_device_handle *devh,
unsigned char
endpoint,
unsigned char *data,
int
length,
int *transferred,
unsigned
int timeout) Perform an USB Interrupt transfer. 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.
USB EVENTS¶
int
libusb_try_lock_events(
libusb_context
*ctx) Try to acquire the event handling lock. Returns 0 if the lock was
obtained and 1 if not.
void
libusb_lock_events(
libusb_context
*ctx) Acquire the event handling lock. This function is blocking.
void
libusb_unlock_events(
libusb_context
*ctx) Release the event handling lock. This will wake up any thread
blocked on
int
libusb_event_handling_ok(
libusb_context
*ctx) Determine if it still OK for this thread to be doing event
handling. Returns 1 if event handling can start or continue. Returns 0 if this
thread must give up the events lock.
int
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.
void
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.
void
libusb_unlock_event_waiters(
libusb_context
*ctx) Release the event_waiters lock.
int
libusb_wait_for_event(
libusb_context
*ctx,
struct timeval *tv) Wait for another thread
to signal completion of an event. Must be called with the event waiters lock
held, see libusb_lock_event_waiters(). This will 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.
int
libusb_handle_events_timeout(
libusb_context
*ctx,
struct timeval *tv) Handle any pending
events by checking if timeouts have expired and by checking the set of file
descriptors for activity. Returns 0 on success, or a LIBUSB_ERROR code on
failure.
int
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.
int
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.
int
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.
void
libusb_set_pollfd_notifiers(
libusb_context
*ctx,
libusb_pollfd_added_cb added_cb,
libusb_pollfd_removed_cb remove_cb,
void
*user_data) Register notification functions for file descriptor
additions/removals. These functions will be invoked for every new or removed
file descriptor that libusb uses as an event source.
const struct libusb_pollfd **
libusb_get_pollfds(
libusb_context
*ctx) Retrive a list of file descriptors that should be polled by your
main loop as libusb event sources. Returns a NULL-terminated list on success
or NULL on failure.
LIBUSB VERSION 0.1
COMPATIBILITY¶
The library is also compliant with LibUSB version 0.1.12.
usb_open()
usb_close()
usb_get_string()
usb_get_string_simple()
usb_get_descriptor_by_endpoint()
usb_get_descriptor()
usb_parse_descriptor()
usb_parse_configuration()
usb_destroy_configuration()
usb_fetch_and_parse_descriptors()
usb_bulk_write()
usb_bulk_read()
usb_interrupt_write()
usb_interrupt_read()
usb_control_msg()
usb_set_configuration()
usb_claim_interface()
usb_release_interface()
usb_set_altinterface()
usb_resetep()
usb_clear_halt()
usb_reset()
usb_strerror()
usb_init()
usb_set_debug()
usb_find_busses()
usb_find_devices()
usb_device()
usb_get_busses()
usb_check_connected()
usb_get_driver_np()
usb_detach_kernel_driver_np()
SEE ALSO¶
libusb20(3),
usb(4),
usbconfig(8),
usbdump(8)
http://libusb.sourceforge.net/
HISTORY¶
libusb support first appeared in
FreeBSD
8.0.