GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LIBUSB (3)

NAME

libusb - USB access library

CONTENTS

Library
Synopsis
Description
Library Initialisation / Deinitialisation
Usb Descriptors
Usb Asynchronous I/o
Usb Synchronous I/o
Usb Events
Libusb Version 0.1 Compatibility
See Also
History

LIBRARY

USB access library (libusb, -lusb)

SYNOPSIS


.In 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.

int libusb_get_port_numbers libusb_device *dev uint8_t *buf uint8_t bufsize Stores, in the buffer buf of size bufsize, the list of all port numbers from root for the device dev.

int libusb_get_port_path libusb_context *ctx libusb_device *dev uint8_t *buf uint8_t bufsize Deprecated function equivalent to libusb_get_port_numbers.

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.

int libusb_get_max_iso_packet_size libusb_device *dev unsigned char endpoint Returns the packet size multiplied by the packet multiplier 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 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 libusb_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 libusb_device_handle *devh uint8_t desc_idx uint16_t langid unsigned char *data int length Retrieve a string descriptor in raw format. Returns the number of bytes actually transferred on success or a negative LIBUSB_ERROR code on failure.

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.

int libusb_parse_ss_endpoint_comp const void *buf int len libusb_ss_endpoint_companion_descriptor **ep_comp This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by buf and having a length of len. Typically these arguments are the extra and extra_length fields of the endpoint descriptor. On success the pointer to resulting descriptor is stored at the location given by ep_comp. Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed USB 3.0 endpoint companion descriptor must be freed using the libusb_free_ss_endpoint_comp function.

void libusb_free_ss_endpoint_comp libusb_ss_endpoint_companion_descriptor *ep_comp This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor.

int libusb_parse_bos_descriptor const void *buf int len libusb_bos_descriptor **bos This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by buf and having a length of len. On success the pointer to resulting descriptor is stored at the location given by bos. Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed BOS descriptor must be freed using the libusb_free_bos_descriptor function.

void libusb_free_bos_descriptor libusb_bos_descriptor *bos This function is NULL safe and frees a parsed BOS descriptor.

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 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 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_completed libusb_context *ctx struct timeval *tv int *completed Handle any pending events by checking if timeouts have expired and by checking the set of file descriptors for activity. If the completed argument is not equal to NULL, this function will loop until a transfer completion callback sets the variable pointed to by the completed argument to non-zero. If the tv argument is not equal to NULL, this function will return LIBUSB_ERROR_TIMEOUT after the given timeout. Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout.

int libusb_handle_events_completed libusb_context *ctx int *completed Handle any pending events by checking the set of file descriptors for activity. If the completed argument is not equal to NULL, this function will loop until a transfer completion callback sets the variable pointed to by the completed argument to non-zero. Returns 0 on success, or a LIBUSB_ERROR code on failure.

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 or timeout.

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 descriptors, 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 or timeout.

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
.Fx 8.0 .
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.