Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
LIBUSB(3)              FreeBSD Library Functions Manual              LIBUSB(3)

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.

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

     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.

FreeBSD 11.0-PRERELEASE          June 7, 2013          FreeBSD 11.0-PRERELEASE

NAME | 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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libusb&manpath=FreeBSD+10.0-RELEASE>

home | help