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

FreeBSD Manual Pages

  
 
  

home | help
LIBUSB(3)		 BSD 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.
     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.

     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_ER-
     ROR 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 de-
     vice_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_ER-
     ROR_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_ER-
     ROR_NO_MEM	on memory allocation problem, LIBUSB_ERROR_ACCESS on permis-
     sion problem, LIBUSB_ERROR_NO_DEVICE if the device	has been disconnected
     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) Re-
     turn 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 in-
     terface must be released before closing a device. Returns 0 on success,
     LIBUSB_ERROR_NOT_FOUND if the interafce was not claimed, LIBUSB_ER-
     ROR_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 in-
     terface was not claimed or	the requested setting does not exist,
     LIBUSB_ERROR_NO_DEVICE if the device has been disconnected	and LIBUSB_ER-
     ROR 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
     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_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, re-
     turns LIBUSB_ERROR_NO_DEVICE if the device	has been disconnected and re-
     turn a LIBUSB_ERROR code on failure.

     int libusb_detach_kernel_driver(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_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.

     int libusb_attach_kernel_driver(libusb_device_handle *devh, int
     interface)	Re-attach an interface kernel driver previously	detached. Re-
     turns 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 de-
     vice 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,
     libusb_device_descriptor **config)	Get the	USB configuration descriptor
     for the active configuration. Returns 0 on	success, returns LIBUSB_ER-
     ROR_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_ER-
     ROR_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 de-
     scriptor 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_ER-
     ROR 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, uint16_t wIndex, unsigned char *data, uint16_t wLength,
     unsigned int timeout) Perform a USB control transfer. Returns 0 on	suc-
     cess, LIBUSB_ERROR_TIMEOUT	if the transfer	timeout, LIBUSB_ERROR_PIPE if
     the control request was not supported, LIBUSB_ERROR_NO_DEVICE if the de-
     vice has been disconnected	and LIBUSB_ERROR code on other failure.

     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_ER-
     ROR_TIMEOUT if the	transfer timeout, LIBUSB_ERROR_PIPE if the control re-
     quest 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.

     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 ac-
     tive 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 al-
     lowed.

     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 re-
     leases the	event handling lock through libusb_unlock_events(). Returns 0
     after a transfer completes	or another thread stops	event handling,	re-
     turns 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) De-
     termine 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) 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_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()

SEE ALSO
     libusb20(3), usb(4), usbconfig(8)

     http://libusb.sourceforge.net/

HISTORY
     libusb support first appeared in FreeBSD 8.0.

BSD				 June 22, 2009				   BSD

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&sektion=3&manpath=FreeBSD+8.1-RELEASE>

home | help