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

FreeBSD Manual Pages

  
 
  

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 de-
       vice.  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  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_ER-
       ROR_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_ER-
       ROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS  on  per-
       missions	 problems,  LIBUSB_ERROR_NO_DEVICE if the device has been dis-
       connected 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 de-
       vice 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_ER-
       ROR_NOT_FOUND if	the requested interface	 does  not  exist,  LIBUSB_ER-
       ROR_BUSY	 if  a program or driver has claimed the interface, LIBUSB_ER-
       ROR_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.  Re-
       turns 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_ER-
       ROR_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_DE-
       VICE 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_IN-
       VALID_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 de-
       tached.	Returns	0 on success, LIBUSB_ERROR_INVALID_PARAM if the	inter-
       face does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been dis-
       connected, 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_ER-
       ROR_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 configura-
       tion  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 con-
       figuration 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	 fail-
       ure.

       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 suc-
       cess 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 end-
       point 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 func-
       tion is NULL safe and frees a parsed BOS	descriptor.

USB ASYNCHRONOUS I/O
       struct libusb_transfer *	libusb_alloc_transfer(int  iso_packets)	 Allo-
       cate a transfer with the	number of isochronous packet descriptors spec-
       ified 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_ER-
       ROR_OVERFLOW if the device offered more data, LIBUSB_ERROR_NO_DEVICE if
       the device has been disconnected	and a LIBUSB_ERROR code	on other fail-
       ure.

       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 han-
       dling   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 there is	a thread  han-
       dling 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	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 han-
       dling, 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.   Re-
       turns  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  suc-
       cess 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	9.2			April 12, 2012			     LIBUSB(3)

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

home | help