d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Whitespace corrections for LibUSB manual page (1/2).

Browse Source 
MFC after:	1 week
Approved by:	re (kib)
PR:		docs/159898
This commit is contained in:
Hans Petter Selasky 2011-08-22 21:05:39 +00:00
parent 15523cf799
commit c8c1f2ec4d
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=225090
1 changed files with 118 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

301
lib/libusb/libusb.3
View File

@ -31,165 +31,123 @@
.Os .Os
.Sh NAME .Sh NAME
.Nm libusb .Nm libusb
.
.Nd "USB access library" .Nd "USB access library"
.
.
.Sh LIBRARY .Sh LIBRARY
.
.
USB access library (libusb -lusb) USB access library (libusb -lusb)
.
.
.Sh SYNOPSIS .Sh SYNOPSIS
.
.
.In libusb.h .In libusb.h
.
.
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
library contains interfaces for directly managing a usb device. library contains interfaces for directly managing a usb device.
The current implementation supports v1.0 of the libusb API. The current implementation supports v1.0 of the libusb API.
.
.
.Sh LIBRARY INITIALISATION / DEINITIALISATION .Sh LIBRARY INITIALISATION / DEINITIALISATION
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_init libusb_context **ctx .Fn libusb_init libusb_context **ctx
This function initialises libusb. Must be called at the beginning This function initialises libusb.
of the program. This function returns 0 on success or LIBUSB_ERROR on Must be called at the beginning
of the program.
This function returns 0 on success or LIBUSB_ERROR on
failure. failure.
.
.Pp .Pp
.
.Ft void .Ft void
.Fn libusb_exit "libusb_context *ctx" .Fn libusb_exit "libusb_context *ctx"
Deinitialise libusb. Must be called at the end of the application. Deinitialise libusb.
. Must be called at the end of the application.
.Pp .Pp
.
.Ft const char * .Ft const char *
.Fn libusb_strerror "int code" .Fn libusb_strerror "int code"
Get ASCII representation of the error given by the Get ASCII representation of the error given by the
.Fa code .Fa code
argument. argument.
.
.
.Pp .Pp
.
.Ft void .Ft void
.Fn libusb_set_debug "libusb_context *ctx" "int level" .Fn libusb_set_debug "libusb_context *ctx" "int level"
Set debug to the Set debug to the
.Fa level .Fa level
level. level.
.
.Pp .Pp
.
.Ft ssize_t .Ft ssize_t
.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
Fill into Fill into
.Fa list .Fa list
the list of usb device available. All the device created by this the list of usb device available.
function must be unref and free when you are done with them. This 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_ERROR code. function returns the number of devices in list or a LIBUSB_ERROR code.
.
.Pp .Pp
.
.Ft void .Ft void
.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
Free the list of devices discovered by libusb_get_device_list. If Free the list of devices discovered by libusb_get_device_list.
If
.Fa unref_device .Fa unref_device
is set to 1 all devices are unref one time. is set to 1 all devices are unref one time.
.
.Pp .Pp
.
.Ft uint8_t .Ft uint8_t
.Fn libusb_get_bus_number "libusb_device *dev" .Fn libusb_get_bus_number "libusb_device *dev"
Returns the number of the bus contained by the device Returns the number of the bus contained by the device
.Fa dev. .Fa dev.
.
.Pp .Pp
.
.Ft uint8_t .Ft uint8_t
.Fn libusb_get_device_address "libusb_device *dev" .Fn libusb_get_device_address "libusb_device *dev"
Returns the device_address contained by the device Returns the device_address contained by the device
.Fa dev. .Fa dev.
.
.Pp .Pp
.
.Ft enum libusb_speed .Ft enum libusb_speed
.Fn libusb_get_device_speed "libusb_device *dev" .Fn libusb_get_device_speed "libusb_device *dev"
Returns the wire speed at which the device is connected. Returns the wire speed at which the device is connected.
See the LIBUSB_SPEED_XXX enums for more information. See the LIBUSB_SPEED_XXX enums for more information.
LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed. LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
.
.Pp .Pp
.
.Ft libusb_device * .Ft libusb_device *
.Fn libusb_ref_device "libusb_device *dev" .Fn libusb_ref_device "libusb_device *dev"
Increment the reference counter of the device Increment the reference counter of the device
.Fa dev. .Fa dev.
.
.Pp .Pp
.
.Ft void .Ft void
.Fn libusb_unref_device "libusb_device *dev" .Fn libusb_unref_device "libusb_device *dev"
Decrement the reference counter of the device Decrement the reference counter of the device
.Fa dev. .Fa dev.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
Open a device and obtain a device_handle. Returns 0 on success, Open a device and obtain a device_handle.
LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS Returns 0 on success,
on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS
on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been
disconnected and a LIBUSB_ERROR code on error. disconnected and a LIBUSB_ERROR code on error.
.
.Pp .Pp
.
.Ft libusb_device_handle * .Ft libusb_device_handle *
.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
Convenience function to open a device with is Convenience function to open a device with is
.Fa vid .Fa vid
and and
.Fa pid. .Fa pid.
Returns NULL on error. Returns NULL on error.
.
.Pp .Pp
.
.Ft void .Ft void
.Fn libusb_close "libusb_device_handle *devh" .Fn libusb_close "libusb_device_handle *devh"
Close a device handle. Close a device handle.
.
.Pp .Pp
.
.Ft libusb_device * .Ft libusb_device *
.Fn libusb_get_device "libusb_device_handle *devh" .Fn libusb_get_device "libusb_device_handle *devh"
Get the device contained by devh. Get the device contained by devh.
Returns NULL on error. Returns NULL on error.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
Returns the bConfiguration value of the current configuration. Returns 0 Returns the bConfiguration value of the current configuration.
on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected Returns 0
on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
and a LIBUSB_ERROR code on error. and a LIBUSB_ERROR code on error.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
Set the active configuration Set the active configuration
@ -197,73 +155,66 @@ Set the active configuration
for the device contained by for the device contained by
.Fa devh. .Fa devh.
This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested 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 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 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
LIBUSB_ERROR code on failure. LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
Claim an interface in a given libusb_handle Claim an interface in a given libusb_handle
.Fa devh. .Fa devh.
This is a non-blocking function. It returns 0 success, LIBUSB_ERROR_NOT_FOUND This is a non-blocking function.
if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or It returns 0 success, LIBUSB_ERROR_NOT_FOUND
driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has 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. been disconnected and a LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
This function release an interface. All the claimed interface must be released This function release an interface.
before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the All the claimed interface must be released
interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been before closing a 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. disconnected and LIBUSB_ERROR on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" .Fn 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, Activate an alternate setting for an interface.
LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested Returns 0 on success,
setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 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 LIBUSB_ERROR code on failure. disconnected and LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" .Fn 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 Clear an halt/stall for a endpoint.
if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 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. disconnected and a LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_reset_device "libusb_device_handle *devh" .Fn libusb_reset_device "libusb_device_handle *devh"
Perform an USB port reset for an usb device. Returns 0 on success, 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 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
been disconnected and a LIBUSB_ERROR code on failure. been disconnected and a LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_check_connected "libusb_device_handle *devh" .Fn libusb_check_connected "libusb_device_handle *devh"
Test if USB device is still connected. Returns 0 on success, Test if USB device is still connected.
Returns 0 on success,
LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR
code on failure. code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" .Fn 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 Determine if a driver is active on a interface.
is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE Returns 0 if no kernel driver
is active, returns 1 if a kernel driver is active,
returns LIBUSB_ERROR_NO_DEVICE
if the device has been disconnected and returns a LIBUSB_ERROR code on failure. if the device has been disconnected and returns a LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
or or
@ -284,9 +235,7 @@ This function is non-portable.
The buffer pointed to by The buffer pointed to by
.Fa name .Fa name
is only zero terminated on success. is only zero terminated on success.
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
or or
@ -295,69 +244,66 @@ or
Detach a kernel driver from an interface. Detach a kernel driver from an interface.
This is needed to claim an interface required by a kernel driver. 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, 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. 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.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
Re-attach an interface kernel driver previously detached. Returns 0 on success, Re-attach an interface kernel driver previously detached.
LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE Returns 0 on success,
if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
attached because the interface is claimed by a program or driver and a 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. LIBUSB_ERROR code on failure.
.
.Pp .Pp
.
.Sh USB DESCRIPTORS .Sh USB DESCRIPTORS
.
.Pp .Pp
.
.Ft int .Ft int
.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
Get the USB device descriptor for the device Get the USB device descriptor for the device
.Fa dev. .Fa dev.
This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on This is a non-blocking function.
Returns 0 on success and a LIBUSB_ERROR code on
failure. failure.
.
.Pp .Pp
.Ft int .Ft int
.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" .Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
Get the USB configuration descriptor for the active configuration. Returns 0 on Get the USB configuration descriptor for the active configuration.
success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state Returns 0 on
success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state
and returns another LIBUSB_ERROR code on error. and returns another LIBUSB_ERROR code on error.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
Get USB configuration descriptor based on its index Get USB configuration descriptor based on its index
.Fa idx. .Fa idx.
Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
and returns another LIBUSB_ERROR code on error. and returns another LIBUSB_ERROR code on error.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" .Fn 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 Get a USB configuration descriptor with a specific bConfigurationValue.
a non-blocking function which does not send request through the device. Returns 0 This is
on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another 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. LIBUSB_ERROR code on failure.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
Free a configuration descriptor. Free a configuration descriptor.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" .Fn 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. Retrieve a string descriptor in C style ascii.
Returns a positive number of bytes in the resulting ASCII string on success and a LIBUSB_ERROR code on failure. Returns a positive number of bytes in the resulting ASCII string
. on success and a LIBUSB_ERROR code on failure.
.Pp .Pp
.
.Sh USB ASYNCHRONOUS I/O .Sh USB ASYNCHRONOUS I/O
.
.Pp .Pp
.Ft struct libusb_transfer * .Ft struct libusb_transfer *
.Fn libusb_alloc_transfer "int iso_packets" .Fn libusb_alloc_transfer "int iso_packets"
@ -365,28 +311,24 @@ Allocate a transfer with
.Fa iso_packets .Fa iso_packets
numbers of isochronous packet descriptors. numbers of isochronous packet descriptors.
Returns NULL on error. Returns NULL on error.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_free_transfer "struct libusb_transfer *tr" .Fn libusb_free_transfer "struct libusb_transfer *tr"
Free a transfer. Free a transfer.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_submit_transfer "struct libusb_transfer *tr" .Fn libusb_submit_transfer "struct libusb_transfer *tr"
This function will submit a transfer and returns immediately. This function will submit a transfer and returns immediately.
Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
the device has been disconnected and
LIBUSB_ERROR code on other failure. LIBUSB_ERROR code on other failure.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_cancel_transfer "struct libusb_transfer *tr" .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
This function asynchronously cancel a transfer. This function asynchronously cancel a transfer.
Returns 0 on success and LIBUSB_ERROR code on failure. Returns 0 on success and LIBUSB_ERROR code on failure.
.
.Pp .Pp
.Sh USB SYNCHRONOUS I/O .Sh USB SYNCHRONOUS I/O
.
.Pp .Pp
.Ft int .Ft int
.Fn 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" .Fn 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"
@ -400,125 +342,121 @@ LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the
control request was not supported, LIBUSB_ERROR_NO_DEVICE if the control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
device has been disconnected or another LIBUSB_ERROR code on other failures. device has been disconnected or another LIBUSB_ERROR code on other failures.
The libusb error codes are always negative. The libusb error codes are always negative.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" .Fn 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. Perform an USB bulk transfer.
A timeout value of zero means no timeout. A timeout value of zero means no timeout.
The timeout value is given in milliseconds. The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
LIBUSB_ERROR code on other failure. LIBUSB_ERROR code on other failure.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" .Fn 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. Perform an USB Interrupt transfer.
A timeout value of zero means no timeout. A timeout value of zero means no timeout.
The timeout value is given in milliseconds. The timeout value is given in milliseconds.
Returns 0 on success, LIBUSB_ERROR_TIMEOUT Returns 0 on success, LIBUSB_ERROR_TIMEOUT
if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not
supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
LIBUSB_ERROR code on other failure. LIBUSB_ERROR code on other failure.
.
.Pp .Pp
.Sh USB EVENTS .Sh USB EVENTS
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_try_lock_events "libusb_context *ctx" .Fn libusb_try_lock_events "libusb_context *ctx"
Try to acquire the event handling lock. Try to acquire the event handling lock.
Returns 0 if the lock was obtained and 1 if not. Returns 0 if the lock was obtained and 1 if not.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_lock_events "libusb_context *ctx" .Fn libusb_lock_events "libusb_context *ctx"
Acquire the event handling lock. This function is blocking. Acquire the event handling lock.
. This function is blocking.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_unlock_events "libusb_context *ctx" .Fn libusb_unlock_events "libusb_context *ctx"
Release the event handling lock. This will wake up any thread blocked Release the event handling lock.
This will wake up any thread blocked
on libusb_wait_for_event(). on libusb_wait_for_event().
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_event_handling_ok "libusb_context *ctx" .Fn libusb_event_handling_ok "libusb_context *ctx"
Determine if it still OK for this thread to be doing event handling. Returns 1 Determine if it still OK for this thread to be doing event handling.
if event handling can start or continue. Returns 0 if this thread must give up Returns 1
if event handling can start or continue.
Returns 0 if this thread must give up
the events lock. the events lock.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_event_handler_active "libusb_context *ctx" .Fn libusb_event_handler_active "libusb_context *ctx"
Determine if an active thread is handling events. Returns 1 if yes and 0 if there Determine if an active thread is handling events.
Returns 1 if yes and 0 if there
are no threads currently handling events. are no threads currently handling events.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_lock_event_waiters "libusb_context *ctx" .Fn libusb_lock_event_waiters "libusb_context *ctx"
Acquire the event_waiters lock. This lock is designed to be obtained under the Acquire the event_waiters lock.
This lock is designed to be obtained under the
situation where you want to be aware when events are completed, but some other 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. thread is event handling so calling libusb_handle_events() is not allowed.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_unlock_event_waiters "libusb_context *ctx" .Fn libusb_unlock_event_waiters "libusb_context *ctx"
Release the event_waiters lock. Release the event_waiters lock.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
Wait for another thread to signal completion of an event. Must be called Wait for another thread to signal completion of an event.
with the event waiters lock held, see libusb_lock_event_waiters(). This will 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 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 the event handling lock through libusb_unlock_events().
Returns 0 after a
transfer completes or another thread stops event handling, returns 1 if the transfer completes or another thread stops event handling, returns 1 if the
timeout expired. timeout expired.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
Handle any pending events by checking if timeouts have expired and by 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 checking the set of file descriptors for activity.
Returns 0 on success, or a
LIBUSB_ERROR code on failure. LIBUSB_ERROR code on failure.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_handle_events "libusb_context *ctx" .Fn libusb_handle_events "libusb_context *ctx"
Handle any pending events in blocking mode with a sensible timeout. Returns 0 Handle any pending events in blocking mode with a sensible timeout.
Returns 0
on success, returns a LIBUSB_ERROR code on failure. on success, returns a LIBUSB_ERROR code on failure.
.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
Handle any pending events by polling file desciptors, without checking if 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. another threads are already doing so.
. Must be called with the event lock held.
.Pp .Pp
.Ft int .Ft int
.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
Determine the next internal timeout that libusb needs to handle. Returns 0 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 LIBUSB_ERROR if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR
code on failure. code on failure.
.
.Pp .Pp
.Ft void .Ft void
.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" .Fn 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. Register notification functions for file descriptor additions/removals.
These functions will be invoked for every new or removed file descriptor These functions will be invoked for every new or removed file descriptor
that libusb uses as an event source. that libusb uses as an event source.
.
.Pp .Pp
.Ft const struct libusb_pollfd ** .Ft const struct libusb_pollfd **
.Fn libusb_get_pollfds "libusb_context *ctx" .Fn libusb_get_pollfds "libusb_context *ctx"
Retrive a list of file descriptors that should be polled by your main loop as 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 event sources.
. Returns a NULL-terminated list on success or NULL on failure.
.Sh LIBUSB VERSION 0.1 COMPATIBILITY .Sh LIBUSB VERSION 0.1 COMPATIBILITY
.Pp .Pp
The library is also compliant with LibUSB version 0.1.12. The library is also compliant with LibUSB version 0.1.12.
@ -555,16 +493,13 @@ The library is also compliant with LibUSB version 0.1.12.
.Fn usb_check_connected .Fn usb_check_connected
.Fn usb_get_driver_np .Fn usb_get_driver_np
.Fn usb_detach_kernel_driver_np .Fn usb_detach_kernel_driver_np
.
.Sh SEE ALSO .Sh SEE ALSO
.Xr libusb20 3 , .Xr libusb20 3 ,
.Xr usb 4 , .Xr usb 4 ,
.Xr usbconfig 8 .Xr usbconfig 8
.Pp .Pp
.Pa http://libusb.sourceforge.net/ .Pa http://libusb.sourceforge.net/
.
.Sh HISTORY .Sh HISTORY
.
.Nm .Nm
support first appeared in support first appeared in
.Fx 8.0 . .Fx 8.0 .