summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorhselasky <hselasky@FreeBSD.org>2011-08-22 21:05:39 +0000
committerhselasky <hselasky@FreeBSD.org>2011-08-22 21:05:39 +0000
commit0100d506101561ecfdd08119987b11360f93731a (patch)
tree60f7bf4e8cc0fcdb8561866e980928d1549224b7
parent97e23a4cb5e2725a418698d113638d2c921fd9e0 (diff)
downloadFreeBSD-src-0100d506101561ecfdd08119987b11360f93731a.zip
FreeBSD-src-0100d506101561ecfdd08119987b11360f93731a.tar.gz
Whitespace corrections for LibUSB manual page (1/2).
MFC after: 1 week Approved by: re (kib) PR: docs/159898
-rw-r--r--lib/libusb/libusb.3301
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 .
OpenPOWER on IntegriCloud