LIBUSB(3) BSD Library Functions Manual LIBUSB(3)NAMElibusb — 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.
Must be called at the beginning of the program. 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.
const char * libusb_strerror(int code) Get ASCII representation of the
error given by the code argument.
void libusb_set_debug(libusb_context *ctx, int level) Set debug to the
level level.
ssize_t libusb_get_device_list(libusb_context *ctx, libusb_device
***list) Fill into list the list of usb device available. All the device
created by this function must be unref and free when you are done with
them. This function returns the number of devices in 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 are unref one time.
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) Return the
device_address contained by the device dev.
int libusb_get_max_packet_size(libusb_device *dev, unsigned char
endpoint) Return 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 ref‐
erence 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. Return 0 on success,
LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS on
permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been discon‐
nected and a LIBUSB_ERROR code on error.
libusb_device_handle * libusb_open_device_with_vid_pid(libusb_context
*ctx, uint16_t vid, uint16_t pid) Conveniance function to open a device
with is vid and pid. Return 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. Return NULL on error.
int libusb_get_configuration(libusb_device_handle *devh, int *config)
Return the bConfiguration value of the current configuration. return 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 config for the device contained by devh. This
function return 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 discon‐
nected 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 return 0 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 release an interface. All the claimed
interface must be released before closing a device. Returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if the interafce 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
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 USB device
is still connected. Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if 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, returns 1 if a kernel driver is active,
returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
return 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) Gets the name of the
driver attached to the given device and interface into the buffer given
by name and 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 func‐
tion is non-portable. The buffer pointed to by name is only zero termi‐
nated 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 required 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 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 disconnect,
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, returns
LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state and return
another LIBUSB_ERROR code on error.
int libusb_get_config_descriptor(libusb_device *dev, uint8_t
config_index, libusb_config_descriptor **config) Get USB configuration
descriptor based on its index idx. Returns 0 on success,
LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and returns
another LIBUSB_ERROR code on error.
int libusb_get_config_descriptor_by_value(libusb_device *dev, uint8
bConfigurationValue, libusb_config_descriptor **config) Get a USB config‐
uration descriptor with a specific bConfigurationValue. This is a non-
blocking function which does not send request through the device. Returns
0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
and another 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 a number of byte 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 iso_packets numbers of isochronous packet descriptors.
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
LIBUSB_ERROR code on other failure.
int libusb_cancel_transfer(struct libusb_transfer *tr) This function
asynchronously cancel a transfer. Returns 0 on success and 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 until and including On error
a libusb error code is returned, for example LIBUSB_ERROR_TIMEOUT if the
transfer timeout, LIBUSB_ERROR_PIPE if the control request was not sup‐
ported, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected or
another LIBUSB_ERROR code on other failures. The libusb error codes are
always 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. Returns 0 on success,
LIBUSB_ERROR_TIMEOUT if the transfer timeout, 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 discon‐
nected and 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. Returns 0 on
success, LIBUSB_ERROR_TIMEOUT if the transfer timeout, 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 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 libusb_wait_for_event().
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 han‐
dling 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 yes 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 under the situa‐
tion 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,
returns 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, returns 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 threads are 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
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 addi‐
tions/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()SEE ALSOlibusb20(3), usb(4), usbconfig(8)
http://libusb.sourceforge.net/
HISTORYlibusb support first appeared in FreeBSD 8.0.
BSD November 18, 2010 BSD
