diff options
Diffstat (limited to 'lib/libusb')
-rw-r--r-- | lib/libusb/libusb.3 | 301 |
1 files changed, 118 insertions, 183 deletions
diff --git a/lib/libusb/libusb.3 b/lib/libusb/libusb.3 index 885b066..780c1f6 100644 --- a/lib/libusb/libusb.3 +++ b/lib/libusb/libusb.3 @@ -31,165 +31,123 @@ .Os .Sh NAME .Nm libusb -. .Nd "USB access library" -. -. .Sh LIBRARY -. -. USB access library (libusb -lusb) -. -. .Sh SYNOPSIS -. -. .In libusb.h -. -. .Sh DESCRIPTION The .Nm library contains interfaces for directly managing a usb device. The current implementation supports v1.0 of the libusb API. -. -. .Sh LIBRARY INITIALISATION / DEINITIALISATION -. .Pp -. .Ft int .Fn 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 +This function initialises libusb. +Must be called at the beginning +of the program. +This function returns 0 on success or LIBUSB_ERROR on failure. -. .Pp -. .Ft void .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 -. .Ft const char * .Fn libusb_strerror "int code" Get ASCII representation of the error given by the .Fa code argument. -. -. .Pp -. .Ft void .Fn libusb_set_debug "libusb_context *ctx" "int level" Set debug to the .Fa level level. -. .Pp -. .Ft ssize_t .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" Fill into -.Fa 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 +.Fa 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_ERROR code. -. .Pp -. .Ft void .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 is set to 1 all devices are unref one time. -. .Pp -. .Ft uint8_t .Fn libusb_get_bus_number "libusb_device *dev" Returns the number of the bus contained by the device .Fa dev. -. .Pp -. .Ft uint8_t .Fn libusb_get_device_address "libusb_device *dev" Returns the device_address contained by the device .Fa dev. -. .Pp -. .Ft enum libusb_speed .Fn 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. -. .Pp -. .Ft int .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. -. .Pp -. .Ft libusb_device * .Fn libusb_ref_device "libusb_device *dev" Increment the reference counter of the device .Fa dev. -. .Pp -. .Ft void .Fn libusb_unref_device "libusb_device *dev" Decrement the reference counter of the device .Fa dev. -. .Pp -. .Ft int .Fn 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 problem, LIBUSB_ERROR_ACCESS -on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been +Open a device and obtain a device_handle. +Returns 0 on success, +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. -. .Pp -. .Ft libusb_device_handle * .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" -Convenience function to open a device with is -.Fa vid -and +Convenience function to open a device with is +.Fa vid +and .Fa pid. Returns NULL on error. -. .Pp -. .Ft void .Fn libusb_close "libusb_device_handle *devh" Close a device handle. -. .Pp -. .Ft libusb_device * .Fn libusb_get_device "libusb_device_handle *devh" Get the device contained by devh. Returns NULL on error. -. .Pp -. .Ft int .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" -Returns the bConfiguration value of the current configuration. Returns 0 -on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected +Returns the bConfiguration 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. -. .Pp -. .Ft int .Fn libusb_set_configuration "libusb_device_handle *devh" "int config" Set the active configuration @@ -197,73 +155,66 @@ Set the active configuration for the device contained by .Fa 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 +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. -. .Pp -. .Ft int .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" Claim an interface in a given libusb_handle .Fa devh. -This is a non-blocking function. It returns 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 +This is a non-blocking function. +It returns 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. -. .Pp -. .Ft int .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" -This function release an interface. All the claimed interface must be released -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 +This function release an interface. +All the claimed interface must be released +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. -. .Pp -. .Ft int .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, -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 +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 LIBUSB_ERROR code on failure. -. .Pp -. .Ft int .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 -if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been +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. -. .Pp -. .Ft int .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 been disconnected and a LIBUSB_ERROR code on failure. -. .Pp -. .Ft int .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 code on failure. -. .Pp -. .Ft int .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 -is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE +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, +returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and returns a LIBUSB_ERROR code on failure. -. .Pp -. .Ft int .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" or @@ -284,9 +235,7 @@ This function is non-portable. The buffer pointed to by .Fa name is only zero terminated on success. -. .Pp -. .Ft int .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" or @@ -295,69 +244,66 @@ or 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_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 -. .Ft int .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" -Re-attach an interface kernel driver 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 disconnect, LIBUSB_ERROR_BUSY if the driver cannot be -attached because the interface is claimed by a program or driver and a +Re-attach an interface kernel driver 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 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. -. .Pp -. .Sh USB DESCRIPTORS -. .Pp -. .Ft int .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" Get the USB device descriptor for the device .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. -. .Pp -.Ft int +.Ft int .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 -success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state +Get the USB configuration descriptor for the active configuration. +Returns 0 on +success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state and returns another LIBUSB_ERROR code on error. -. .Pp -.Ft int +.Ft int .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. -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. -. .Pp .Ft int .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 -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 +Get a USB configuration 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. -. .Pp .Ft void .Fn libusb_free_config_descriptor "libusb_config_descriptor *config" Free a configuration descriptor. -. .Pp .Ft int .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. -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 -. .Sh USB ASYNCHRONOUS I/O -. .Pp .Ft struct libusb_transfer * .Fn libusb_alloc_transfer "int iso_packets" @@ -365,28 +311,24 @@ Allocate a transfer with .Fa iso_packets numbers of isochronous packet descriptors. Returns NULL on error. -. .Pp .Ft void .Fn libusb_free_transfer "struct libusb_transfer *tr" Free a transfer. -. .Pp .Ft int .Fn 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 +Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if +the device has been disconnected and LIBUSB_ERROR code on other failure. -. .Pp .Ft int .Fn libusb_cancel_transfer "struct libusb_transfer *tr" This function asynchronously cancel a transfer. Returns 0 on success and LIBUSB_ERROR code on failure. -. .Pp .Sh USB SYNCHRONOUS I/O -. .Pp .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" @@ -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 device has been disconnected or another LIBUSB_ERROR code on other failures. The libusb error codes are always negative. -. .Pp .Ft int .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. 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 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 +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. -. .Pp .Ft int .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. 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 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 +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. -. .Pp .Sh USB EVENTS -. .Pp .Ft int .Fn 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. -. .Pp .Ft void .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 .Ft void .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(). -. .Pp .Ft int .Fn 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 +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. -. .Pp .Ft int .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. -. .Pp .Ft void .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 thread is event handling so calling libusb_handle_events() is not allowed. -. .Pp .Ft void .Fn libusb_unlock_event_waiters "libusb_context *ctx" Release the event_waiters lock. -. .Pp -.Ft int +.Ft int .Fn 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 +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 +the event handling lock through libusb_unlock_events(). +Returns 0 after a transfer completes or another thread stops event handling, returns 1 if the timeout expired. -. .Pp .Ft int .Fn 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 +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. -. .Pp .Ft int .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. -. .Pp .Ft int .Fn 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. -. +another threads are already doing so. +Must be called with the event lock held. .Pp .Ft int .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 code on failure. -. .Pp .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" 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. -. .Pp .Ft const struct libusb_pollfd ** .Fn 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. -. +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. .Sh LIBUSB VERSION 0.1 COMPATIBILITY .Pp 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_get_driver_np .Fn usb_detach_kernel_driver_np -. .Sh SEE ALSO .Xr libusb20 3 , .Xr usb 4 , .Xr usbconfig 8 .Pp .Pa http://libusb.sourceforge.net/ -. .Sh HISTORY -. .Nm support first appeared in .Fx 8.0 . |