Date: Mon, 22 Aug 2011 16:42:47 -0400 (EDT) From: Benjamin Kaduk <kaduk@MIT.EDU> To: Hans Petter Selasky <hselasky@c2i.net> Cc: freebsd-doc@freebsd.org Subject: Re: docs/159898: [patch] libusb.3 whitespace, markup, grammar fixes Message-ID: <alpine.GSO.1.10.1108221640210.7526@multics.mit.edu> In-Reply-To: <201108222110.23301.hselasky@c2i.net> References: <201108201410.p7KEAB8n025467@freefall.freebsd.org> <alpine.GSO.1.10.1108212112200.7526@multics.mit.edu> <201108222110.23301.hselasky@c2i.net>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] On Mon, 22 Aug 2011, Hans Petter Selasky wrote: > On Monday 22 August 2011 03:13:33 Benjamin Kaduk wrote: >> On Sat, 20 Aug 2011, Hans Petter Selasky wrote: >>> Looks good. Who will commit it? >>> >>> --HPS >> >> Hmm, it seems that perhaps you are stuck with it, Hans Petter. >> >> -Ben > > Could you update the patch. It does not apply? > > --HPS > > Hmm... Looks like a unified diff to me... > The text leading up to this was: > -------------------------- > |--- libusb.3.whitespace 2011-08-18 13:42:48.000000000 -0400 > |+++ libusb.3 2011-08-19 11:18:45.000000000 -0400 > -------------------------- > Patching file libusb.3 using Plan A... > Hunk #1 failed at 33. > Hunk #2 failed at 47. > Hunk #3 failed at 56. > Hunk #4 failed at 125. > Hunk #5 succeeded at 197 with fuzz 1 (offset 42 lines). > Hunk #6 failed at 211. > Hunk #7 failed at 231. > Hunk #8 failed at 249. > Hunk #9 succeeded at 255 with fuzz 2 (offset 9 lines). > Hunk #10 failed at 264. > Hunk #11 failed at 286. > Hunk #12 failed at 313. > Hunk #13 failed at 334. > Hunk #14 failed at 348. > Hunk #15 failed at 363. > Hunk #16 failed at 374. > Hunk #17 failed at 395. > Hunk #18 failed at 409. > Hunk #19 failed at 432. > Hunk #20 failed at 446. > 18 out of 20 hunks failed--saving rejects to libusb.3.rej Oops, I forgot to mention to you that there are two patches -- one which is just whitespace changes, and the second one with the content changes. I think the doc team tries to keep whitespace changes separate, so it would be two separate commits. I attached the whitespace diff; if you apply that first, I think that the failed hunks above will succeed. Sorry for the omission, Ben [-- Attachment #2 --] --- libusb.3.orig 2011-08-18 11:28:50.000000000 -0400 +++ libusb.3.whitespace 2011-08-18 13:42:48.000000000 -0400 @@ -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 @@ 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 @@ 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 @@ 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 @@ .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 @@ 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 @@ .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 .help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.GSO.1.10.1108221640210.7526>