home | help
LIBUSB(3)		     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 rou-
     tines  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 af-
     ter 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 de-
     vices 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  decre-
     mented 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  de-
     vice_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 end-
     point) Returns the packet size multiplied by the packet multiplier on  suc-
     cess,  LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and LIBUSB_ER-
     ROR_OTHERS on other failure.

     libusb_device * libusb_ref_device(libusb_device *dev) Increment the  refer-
     ence 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 de-
     vice 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_ER-
     ROR 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 ven-
     dor 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  de-
     vice contained by devh.  Returns NULL on error.

     int  libusb_get_configuration(libusb_device_handle  *devh, int *config) Re-
     turns the value of  the  current  configuration.	Returns  0  on	success,
     LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ER-
     ROR 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 con-
     figuration  does  not  exist,  LIBUSB_ERROR_BUSY if the interfaces are cur-
     rently 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_num-
     ber) 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  dri-
     ver  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_num-
     ber) 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_ER-
     ROR_NO_DEVICE if the device has been disconnected and LIBUSB_ERROR on fail-
     ure.

     int  libusb_set_interface_alt_setting(libusb_device_handle *dev, int inter-
     face_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_ER-
     ROR_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_ER-
     ROR_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 re-
     set 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 de-
     vice 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  at-
     tached  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  in-
     terface) 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_IN-
     VALID_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_ER-
     ROR_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_descrip-
     tor  *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  con-
     figuration does not exist and a LIBUSB_ERROR code on error.

     int  libusb_get_config_descriptor_by_value(libusb_device  *dev, uint8 bCon-
     figurationValue, 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.

     int  libusb_parse_ss_endpoint_comp(const void *buf, int len, libusb_ss_end-
     point_companion_descriptor **ep_comp) This function parses the USB 3.0 end-
     point companion descriptor in host endian format pointed to by buf and hav-
     ing a length of len.  Typically these  arguments  are  the  extra	and  ex-
     tra_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_de-
     scriptor **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_ER-
     ROR code on other failure.

     int libusb_cancel_transfer(struct libusb_transfer *tr) This function  asyn-
     chronously  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  bmRequest-
     Type,  uint8_t  bRequest,	uint16_t  wValue, uint16_t wIndex, unsigned char
     *data, uint16_t wLength, unsigned int timeout) Perform a USB control trans-
     fer.  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 sup-
     ported, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and  an-
     other  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 suc-
     cess, 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  discon-
     nected 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_ER-
     ROR_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_wait-
     ers  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) Deter-
     mine  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_ER-
     ROR 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)  Re-
     trive 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_de-
     scriptor_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_in-
     terrupt_write() usb_interrupt_read()  usb_control_msg()  usb_set_configura-
     tion() 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_ker-
     nel_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 8.4-stable		 April 12, 2012 		       LIBUSB(3)

home | help