Bug 159898

Summary:

[patch] libusb.3 whitespace, markup, grammar fixes

Product:

Documentation

Reporter:

Ben Kaduk <kaduk>

Component:

Books & Articles

Assignee:

Hans Petter Selasky <hselasky>

Status:

Closed FIXED

Severity:

Affects Only Me

Priority:

Normal

Version:

Latest

Hardware:

Any

OS:

Any

Attachments:

Description	Flags
file.diff	none
libusb.3.whitespace.diff.txt	none
libusb.3.diff.txt	none

Description Ben Kaduk 2011-08-19 04:30:08 UTC

libusb.3 started out with a lot of long lines, sentences starting in the middle of lines, trailing whitespace, and ignored lines consisting of just '.'.  Mechanical fixes for these issues are in one patch.
There are also many grammar and consistency issues in the man page, which are fixed in a second patch.  I'll attach the grammar patch in the webform and send the whitespace diff as an update to the ticket.  (The grammar patch applies on top of the whitespace patch, though.)

There are several functions whose return values are erroneously described in the man page at this point, but I can't commit enough time for a full audit at this point in time.

Fix: Patch attached with submission follows:

Comment 1 Ben Kaduk 2011-08-19 04:31:56 UTC

On Fri, 19 Aug 2011, Ben Kaduk wrote:

>
>> Description:
> libusb.3 started out with a lot of long lines, sentences starting in the middle of lines, trailing whitespace, and ignored lines consisting of just '.'.  Mechanical fixes for these issues are in one patch.
> There are also many grammar and consistency issues in the man page, which are fixed in a second patch.  I'll attach the grammar patch in the webform and send the whitespace diff as an update to the ticket.  (The grammar patch applies on top of the whitespace patch, though.)

The whitespace patch.
(Note that there was at least one line '. ', if the '.' lines are to be 
kept for some reason.)

-Ben Kaduk

Comment 2 Ben Kaduk 2011-08-19 16:22:08 UTC

(was: Re: Fwd: svn commit: r224917 - head/lib/libusb)

On Fri, 19 Aug 2011, Hans Petter Selasky wrote:

> On Friday 19 August 2011 05:40:46 Benjamin Kaduk wrote:
>> Dear Hans Petter,
>>
>> I saw a couple grammar and style issues as this went by, and ended up
>> going through the whole man page.  Could you take a look at docs/159898
>> and make sure I didn't change anything factually incorrectly?
>>
>> Thanks,
>>
>> Ben Kaduk
>
> Looks good!
>
> One more change I would suggest:
>
> +A convenience function to open a device with vendor and producd IDs
>
> Into:
>
> +A convenience function to open a device by vendor and product IDs
>
> --HPS
>

Updated patch with comments from hps -- thanks for catching it!

-Ben

Comment 3 Hans Petter Selasky 2011-08-20 15:06:05 UTC

On Friday 19 August 2011 17:22:08 Benjamin Kaduk wrote:
> (was: Re: Fwd: svn commit: r224917 - head/lib/libusb)
> 
> On Fri, 19 Aug 2011, Hans Petter Selasky wrote:
> > On Friday 19 August 2011 05:40:46 Benjamin Kaduk wrote:
> >> Dear Hans Petter,
> >> 
> >> I saw a couple grammar and style issues as this went by, and ended up
> >> going through the whole man page.  Could you take a look at docs/159898
> >> and make sure I didn't change anything factually incorrectly?
> >> 
> >> Thanks,
> >> 
> >> Ben Kaduk
> > 
> > Looks good!
> > 
> > One more change I would suggest:
> > 
> > +A convenience function to open a device with vendor and producd IDs
> > 
> > Into:
> > 
> > +A convenience function to open a device by vendor and product IDs
> > 
> > --HPS
> 
> Updated patch with comments from hps -- thanks for catching it!
> 
> -Ben

Looks good. Who will commit it?

--HPS

Comment 4 dfilter service freebsd_committer

2011-08-22 22:05:55 UTC

Author: hselasky
Date: Mon Aug 22 21:05:39 2011
New Revision: 225090
URL: http://svn.freebsd.org/changeset/base/225090

Log:
  Whitespace corrections for LibUSB manual page (1/2).
  
  MFC after:	1 week
  Approved by:	re (kib)
  PR:		docs/159898

Modified:
  head/lib/libusb/libusb.3

Modified: head/lib/libusb/libusb.3
==============================================================================
--- head/lib/libusb/libusb.3	Mon Aug 22 20:44:18 2011	(r225089)
+++ head/lib/libusb/libusb.3	Mon Aug 22 21:05:39 2011	(r225090)
@@ -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 tim
 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 LibUS
 .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 .
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"

Comment 5 dfilter service freebsd_committer

2011-08-22 22:11:05 UTC

Author: hselasky
Date: Mon Aug 22 21:10:50 2011
New Revision: 225091
URL: http://svn.freebsd.org/changeset/base/225091

Log:
  Spelling corrections for LibUSB manual page (2/2).
  
  MFC after:	1 week
  Approved by:	re (kib)
  PR:		docs/159898

Modified:
  head/lib/libusb/libusb.3

Modified: head/lib/libusb/libusb.3
==============================================================================
--- head/lib/libusb/libusb.3	Mon Aug 22 21:05:39 2011	(r225090)
+++ head/lib/libusb/libusb.3	Mon Aug 22 21:10:50 2011	(r225091)
@@ -33,7 +33,8 @@
 .Nm libusb
 .Nd "USB access library"
 .Sh LIBRARY
-USB access library (libusb -lusb)
+USB access library
+.Pq libusb, -lusb
 .Sh SYNOPSIS
 .In libusb.h
 .Sh DESCRIPTION
@@ -46,8 +47,8 @@ The current implementation supports v1.0
 .Ft int
 .Fn libusb_init libusb_context **ctx
 This function initialises libusb.
-Must be called at the beginning
-of the program.
+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.
 .Pp
@@ -55,35 +56,39 @@ failure.
 .Fn 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.
 .Pp
 .Ft const char *
 .Fn libusb_strerror "int code"
-Get ASCII representation of the error given by the
+Get the 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.
+Set the debug level to
+.Fa level .
 .Pp
 .Ft ssize_t
 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
-Fill into
+Populate
 .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.
+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 list or a LIBUSB_ERROR code.
+function returns the number of devices in the 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
 .Fa unref_device
-is set to 1 all devices are unref one time.
+is set to 1 all devices in the list have their reference
+counter decremented once.
 .Pp
 .Ft uint8_t
 .Fn libusb_get_bus_number "libusb_device *dev"
@@ -120,13 +125,13 @@ Decrement the reference counter of the d
 .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
-disconnected and a LIBUSB_ERROR code on error.
+LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
+on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
+disconnected and a LIBUSB_ERROR code on other errors.
 .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
+A convenience function to open a device by vendor and product IDs
 .Fa vid
 and
 .Fa pid.
@@ -150,7 +155,7 @@ and a LIBUSB_ERROR code on error.
 .Pp
 .Ft int
 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
-Set the active configuration
+Set the active configuration to
 .Fa config
 for the device contained by
 .Fa devh.
@@ -164,16 +169,16 @@ LIBUSB_ERROR code on failure.
 Claim an interface in a given libusb_handle
 .Fa devh.
 This is a non-blocking function.
-It returns 0 success, LIBUSB_ERROR_NOT_FOUND
+It returns 0 on 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.
+This function releases an interface.
+All the claimed interfaces on a device must be released
+before closing the 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.
@@ -184,7 +189,7 @@ Activate an alternate setting for an int
 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.
+disconnected and a LIBUSB_ERROR code on failure.
 .Pp
 .Ft int
 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
@@ -202,31 +207,30 @@ been disconnected and a LIBUSB_ERROR cod
 .Pp
 .Ft int
 .Fn libusb_check_connected "libusb_device_handle *devh"
-Test if USB device is still connected.
+Test if the 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 it 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
-if the device has been disconnected and returns a LIBUSB_ERROR code on failure.
+is active, 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
+if the device has been disconnected and a LIBUSB_ERROR code on failure.
 .Pp
 .Ft int
 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
 or
 .Ft int
 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
-Gets the name of the driver attached to the given
+Copy the name of the driver attached to the given
 .Fa device
 and
 .Fa interface
-into the buffer given by
+into the buffer
 .Fa name
-and
+of length
 .Fa namelen .
 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
@@ -242,7 +246,7 @@ or
 .Ft int
 .Fn 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 required by a kernel driver.
+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
@@ -251,11 +255,11 @@ 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.
+Re-attach an interface kernel driver that was 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
+if the device has been disconnected, 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
@@ -273,24 +277,25 @@ failure.
 .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
-and returns another LIBUSB_ERROR code on error.
+success, LIBUSB_ERROR_NOT_FOUND if the device is in
+an unconfigured state
+and a LIBUSB_ERROR code on error.
 .Pp
 .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 a USB configuration descriptor based on its index
 .Fa idx.
 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
-and returns another LIBUSB_ERROR code on error.
+and a 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.
+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 another
+does not exist and a
 LIBUSB_ERROR code on failure.
 .Pp
 .Ft void
@@ -299,17 +304,17 @@ 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
+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 failure.
 .Pp
 .Sh USB ASYNCHRONOUS I/O
 .Pp
 .Ft struct libusb_transfer *
 .Fn libusb_alloc_transfer "int iso_packets"
-Allocate a transfer with
-.Fa iso_packets
-numbers of isochronous packet descriptors.
+Allocate a transfer with the number of isochronous packet descriptors
+specified by
+.Fa iso_packets .
 Returns NULL on error.
 .Pp
 .Ft void
@@ -320,13 +325,13 @@ Free a transfer.
 .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
+the device has been disconnected and a
 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.
+This function asynchronously cancels a transfer.
+Returns 0 on success and a LIBUSB_ERROR code on failure.
 .Pp
 .Sh USB SYNCHRONOUS I/O
 .Pp
@@ -334,14 +339,14 @@ Returns 0 on success and LIBUSB_ERROR co
 .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"
 Perform a USB control transfer.
 Returns the actual number of bytes
-transferred on success in the range from and including zero until and
+transferred on success, in the range from and including zero up to and
 including
 .Fa wLength .
-On error a libusb error code is returned, for example
-LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the
+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 or another LIBUSB_ERROR code on other failures.
-The libusb error codes are always negative.
+device has been disconnected and another LIBUSB_ERROR code on other failures.
+The LIBUSB_ERROR codes are all 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"
@@ -349,10 +354,10 @@ 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
+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
-LIBUSB_ERROR code on other failure.
+a 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"
@@ -360,10 +365,10 @@ 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
+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
-LIBUSB_ERROR code on other failure.
+a LIBUSB_ERROR code on other failure.
 .Pp
 .Sh USB EVENTS
 .Pp
@@ -381,7 +386,8 @@ This function is blocking.
 .Fn libusb_unlock_events "libusb_context *ctx"
 Release the event handling lock.
 This will wake up any thread blocked
-on libusb_wait_for_event().
+on
+.B libusb_wait_for_event() .
 .Pp
 .Ft int
 .Fn libusb_event_handling_ok "libusb_context *ctx"
@@ -394,13 +400,13 @@ the events lock.
 .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
+Returns 1 if there is a thread handling events 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
+This lock is designed to be obtained in 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
@@ -417,7 +423,7 @@ 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 handling, returns 1 if the
+transfer completes or another thread stops event handling, and 1 if the
 timeout expired.
 .Pp
 .Ft int
@@ -431,19 +437,19 @@ LIBUSB_ERROR code on failure.
 .Fn 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.
+on success and 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.
+another thread is 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
-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 a LIBUSB_ERROR
 code on failure.
 .Pp
 .Ft void
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"

Comment 6 dfilter service freebsd_committer

2011-08-23 08:35:33 UTC

Author: hselasky
Date: Tue Aug 23 07:35:21 2011
New Revision: 225102
URL: http://svn.freebsd.org/changeset/base/225102

Log:
  MFC r224903, r224917, r225035, r225090, r225091:
  - Add missing API function to the LibUSB v1.0 API.
  - Update LibUSB v1.0 manual page.
  
  PR:	docs/159898

Modified:
  stable/8/lib/libusb/Makefile
  stable/8/lib/libusb/libusb.3
  stable/8/lib/libusb/libusb.h
  stable/8/lib/libusb/libusb10.c
Directory Properties:
  stable/8/lib/libusb/   (props changed)
  stable/8/lib/libusb/usb.h   (props changed)

Modified: stable/8/lib/libusb/Makefile
==============================================================================
--- stable/8/lib/libusb/Makefile	Tue Aug 23 07:17:37 2011	(r225101)
+++ stable/8/lib/libusb/Makefile	Tue Aug 23 07:35:21 2011	(r225102)
@@ -43,6 +43,7 @@ MLINKS += libusb.3 libusb_get_device_lis
 MLINKS += libusb.3 libusb_free_device_list.3
 MLINKS += libusb.3 libusb_get_bus_number.3
 MLINKS += libusb.3 libusb_get_device_address.3
+MLINKS += libusb.3 libusb_get_device_speed.3
 MLINKS += libusb.3 libusb_get_max_packet_size.3
 MLINKS += libusb.3 libusb_ref_device.3
 MLINKS += libusb.3 libusb_unref_device.3

Modified: stable/8/lib/libusb/libusb.3
==============================================================================
--- stable/8/lib/libusb/libusb.3	Tue Aug 23 07:17:37 2011	(r225101)
+++ stable/8/lib/libusb/libusb.3	Tue Aug 23 07:35:21 2011	(r225102)
@@ -26,247 +26,211 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 18, 2010
+.Dd August 16, 2011
 .Dt LIBUSB 3
 .Os
 .Sh NAME
 .Nm libusb
-.
 .Nd "USB access library"
-.
-.
 .Sh LIBRARY
-.
-.
-USB access library (libusb -lusb)
-.
-.
+USB access library
+.Pq 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.
+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.
-. 
 .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.
+Other libusb routines may not be called after this function.
 .Pp
-.
 .Ft const char *
 .Fn libusb_strerror "int code"
-Get ASCII representation of the error given by the
+Get the 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.
-.
+Set the debug level to
+.Fa 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
-function returns the number of devices in list or a LIBUSB_ERROR code.
-.
+Populate
+.Fa 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.
 .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.
-.
+is set to 1 all devices in the list have their reference
+counter decremented once.
 .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"
-Return the device_address contained by the device
+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"
-Return 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. Return 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.
-.
+Open a device and obtain a device_handle.
+Returns 0 on success,
+LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
+on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
+disconnected and a LIBUSB_ERROR code on other errors.
 .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 
+A convenience function to open a device by vendor and product IDs
+.Fa vid
+and
 .Fa pid.
-Return NULL on error.
-.
+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. Return NULL on error.
-.
+.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"
-Return the bConfiguration value of the current configuration. return 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
+Set the active configuration to
 .Fa config
 for the device contained by
 .Fa 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 disconnected and a 
+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.
-.
 .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 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 
+This is a non-blocking function.
+It returns 0 on 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 releases an interface.
+All the claimed interfaces on a device must be released
+before closing the 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 
-disconnected and LIBUSB_ERROR code on failure.
-.
+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.
 .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,
-LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR
+Test if the USB device is still connected.
+Returns 0 on success,
+LIBUSB_ERROR_NO_DEVICE if it 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
-if the device has been disconnected and return a LIBUSB_ERROR code on failure.
-.
+Determine if a driver is active on a interface.
+Returns 0 if no kernel driver
+is active, 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
+if the device has been disconnected and a LIBUSB_ERROR code on failure.
 .Pp
-.
 .Ft int
 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
 or
 .Ft int
 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
-Gets the name of the driver attached to the given
+Copy the name of the driver attached to the given
 .Fa device
 and
 .Fa interface
-into the buffer given by
+into the buffer
 .Fa name
-and
+of length
 .Fa namelen .
 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
@@ -275,239 +239,230 @@ 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
 .Ft int
 .Fn 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 required by a kernel driver.
+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.
-.
+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 that was 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 disconnected, 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 
-and return another LIBUSB_ERROR code on error.
-.
+Get the USB configuration descriptor for the active configuration.
+Returns 0 on
+success, LIBUSB_ERROR_NOT_FOUND if the device is in
+an unconfigured state
+and a 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 a USB configuration descriptor based on its index
 .Fa idx.
-Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 
-and returns another LIBUSB_ERROR code on error.
-.
+Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
+and a 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 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.
-.
 .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 number of byte on success 
-and a LIBUSB_ERROR code on failure.
-.
+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 failure.
 .Pp
-.
 .Sh USB ASYNCHRONOUS I/O
-.
 .Pp
 .Ft struct libusb_transfer *
 .Fn libusb_alloc_transfer "int iso_packets"
-Allocate a transfer with
-.Fa iso_packets
-numbers of isochronous packet descriptors. Returns NULL on error.
-.
+Allocate a transfer with the number of isochronous packet descriptors
+specified by
+.Fa iso_packets .
+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 
+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.
-.
 .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.
-.
+This function asynchronously cancels a transfer.
+Returns 0 on success and a 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"
-Perform a USB control transfer. Returns the actual number of bytes
-transferred on success in the range from and including zero until and
+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
 .Fa wLength .
-On error a libusb error code is returned, for example
-LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the
+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 or another LIBUSB_ERROR code on other failures.
-The libusb error codes are always negative.
-.
+device has been disconnected and another LIBUSB_ERROR code on other failures.
+The LIBUSB_ERROR codes are all 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 
-LIBUSB_ERROR code on other failure.
-.
+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.
 .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 
-LIBUSB_ERROR code on other failure.
-.
+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.
 .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.
-.
+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
-on libusb_wait_for_event().
-.
+Release the event handling lock.
+This will wake up any thread blocked
+on
+.B 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 there is a thread handling events 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 in 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 
-transfer completes or another thread stops event handling, returns 1 if the
+the event handling lock through libusb_unlock_events().
+Returns 0 after a
+transfer completes or another thread stops event handling, and 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
-on success, returns a LIBUSB_ERROR code on failure.
-.
+Handle any pending events in blocking mode with a sensible timeout.
+Returns 0
+on success and 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 thread is 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
-if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR
+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 a 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.
@@ -544,16 +499,13 @@ The library is also compliant with LibUS
 .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 .

Modified: stable/8/lib/libusb/libusb.h
==============================================================================
--- stable/8/lib/libusb/libusb.h	Tue Aug 23 07:17:37 2011	(r225101)
+++ stable/8/lib/libusb/libusb.h	Tue Aug 23 07:35:21 2011	(r225102)
@@ -151,6 +151,14 @@ enum libusb_error {
 	LIBUSB_ERROR_OTHER = -99,
 };
 
+enum libusb_speed {
+	LIBUSB_SPEED_UNKNOWN = 0,
+	LIBUSB_SPEED_LOW = 1,
+	LIBUSB_SPEED_FULL = 2,
+	LIBUSB_SPEED_HIGH = 3,
+	LIBUSB_SPEED_SUPER = 4,
+};
+
 enum libusb_transfer_status {
 	LIBUSB_TRANSFER_COMPLETED,
 	LIBUSB_TRANSFER_ERROR,
@@ -304,6 +312,7 @@ ssize_t libusb_get_device_list(libusb_co
 void	libusb_free_device_list(libusb_device ** list, int unref_devices);
 uint8_t	libusb_get_bus_number(libusb_device * dev);
 uint8_t	libusb_get_device_address(libusb_device * dev);
+enum libusb_speed libusb_get_device_speed(libusb_device * dev);
 int	libusb_clear_halt(libusb_device_handle *devh, uint8_t endpoint);
 int	libusb_get_max_packet_size(libusb_device * dev, uint8_t endpoint);
 libusb_device *libusb_ref_device(libusb_device * dev);

Modified: stable/8/lib/libusb/libusb10.c
==============================================================================
--- stable/8/lib/libusb/libusb10.c	Tue Aug 23 07:17:37 2011	(r225101)
+++ stable/8/lib/libusb/libusb10.c	Tue Aug 23 07:35:21 2011	(r225102)
@@ -272,6 +272,27 @@ libusb_get_device_address(libusb_device 
 	return (libusb20_dev_get_address(dev->os_priv));
 }
 
+enum libusb_speed
+libusb_get_device_speed(libusb_device *dev)
+{
+	if (dev == NULL)
+		return (LIBUSB_SPEED_UNKNOWN);	/* should not happen */
+
+	switch (libusb20_dev_get_speed(dev->os_priv)) {
+	case LIBUSB20_SPEED_LOW:
+		return (LIBUSB_SPEED_LOW);
+	case LIBUSB20_SPEED_FULL:
+		return (LIBUSB_SPEED_FULL);
+	case LIBUSB20_SPEED_HIGH:
+		return (LIBUSB_SPEED_HIGH);
+	case LIBUSB20_SPEED_SUPER:
+		return (LIBUSB_SPEED_SUPER);
+	default:
+		break;
+	}
+	return (LIBUSB_SPEED_UNKNOWN);
+}
+
 int
 libusb_get_max_packet_size(libusb_device *dev, uint8_t endpoint)
 {
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"

Comment 7 Eitan Adler freebsd_committer

2012-03-04 04:31:35 UTC

Responsible Changed
From-To: freebsd-doc->eadler

I'll take it.

Comment 8 Eitan Adler freebsd_committer

2012-03-04 15:26:25 UTC

State Changed
From-To: open->patched

over to committer

Comment 9 Eitan Adler freebsd_committer

2012-03-04 15:26:25 UTC

Responsible Changed
From-To: eadler->hselasky

over to committer

Comment 10 Isabell Long freebsd_committer

2012-07-01 11:13:48 UTC

State Changed
From-To: patched->closed

These changes were committed and merged to older versions of FreeBSD in 
2011.  Closing this PR now.  Thanks!