1.\" 2.\" Copyright (c) 2009 Sylvestre Gallon 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd June 22, 2009 30.Dt LIBUSB 3 31.Os 32.Sh NAME 33.Nm libusb 34. 35.Nd "USB access library" 36. 37. 38.Sh LIBRARY 39. 40. 41USB access library (libusb -lusb) 42. 43. 44.Sh SYNOPSIS 45. 46. 47.In libusb.h 48. 49. 50.Sh DESCRIPTION 51The 52.Nm 53library contains interfaces for directly managing a usb device. 54The current implementation supports v1.0 of the libusb API. 55. 56. 57.Sh LIBRARY INITIALISATION / DEINITIALISATION 58. 59.Pp 60. 61.Ft int 62.Fn libusb_init libusb_context **ctx 63This function initialises libusb. Must be called at the beginning 64of the program. This function returns 0 on success or LIBUSB_ERROR on 65failure. 66. 67.Pp 68. 69.Ft void 70.Fn libusb_exit "libusb_context *ctx" 71Deinitialise libusb. Must be called at the end of the application. 72. 73.Pp 74. 75.Ft void 76.Fn libusb_set_debug "libusb_context *ctx" "int level" 77Set debug to the 78.Fa level 79level. 80. 81.Pp 82. 83.Ft ssize_t 84.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" 85Fill into 86.Fa list 87the list of usb device available. All the device created by this 88function must be unref and free when you are done with them. This 89function returns the number of devices in list or a LIBUSB_ERROR code. 90. 91.Pp 92. 93.Ft void 94.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" 95Free the list of devices discovered by libusb_get_device_list. If 96.Fa unref_device 97is set to 1 all devices are unref one time. 98. 99.Pp 100. 101.Ft uint8_t 102.Fn libusb_get_bus_number "libusb_device *dev" 103Returns the number of the bus contained by the device 104.Fa dev. 105. 106.Pp 107. 108.Ft uint8_t 109.Fn libusb_get_device_address "libusb_device *dev" 110Return the device_address contained by the device 111.Fa dev. 112. 113.Pp 114. 115.Ft int 116.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" 117Return the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the 118endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. 119. 120.Pp 121. 122.Ft libusb_device * 123.Fn libusb_ref_device "libusb_device *dev" 124Increment the reference counter of the device 125.Fa dev. 126. 127.Pp 128. 129.Ft void 130.Fn libusb_unref_device "libusb_device *dev" 131Decrement the reference counter of the device 132.Fa dev. 133. 134.Pp 135. 136.Ft int 137.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" 138Open a device and obtain a device_handle. Return 0 on success, 139LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS 140on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been 141disconnected and a LIBUSB_ERROR code on error. 142. 143.Pp 144. 145.Ft libusb_device_handle * 146.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" 147Convenience function to open a device with is 148.Fa vid 149and 150.Fa pid. 151Return NULL on error. 152. 153.Pp 154. 155.Ft void 156.Fn libusb_close "libusb_device_handle *devh" 157Close a device handle. 158. 159.Pp 160. 161.Ft libusb_device * 162.Fn libusb_get_device(libusb_device_handle *devh) 163Get the device contained by devh. Return NULL on error. 164. 165.Pp 166. 167.Ft int 168.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" 169Return the bConfiguration value of the current configuration. return 0 170on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 171and a LIBUSB_ERROR code on error. 172. 173.Pp 174. 175.Ft int 176.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 177Set the active configuration 178.Fa config 179for the device contained by 180.Fa devh. 181This function return 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested 182configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 183claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a 184LIBUSB_ERROR code on failure. 185. 186.Pp 187. 188.Ft int 189.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 190Claim an interface in a given libusb_handle 191.Fa devh. 192This is a non-blocking function. It return 0 success, LIBUSB_ERROR_NOT_FOUND 193if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 194driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has 195been disconnected and a LIBUSB_ERROR code on failure. 196. 197.Pp 198. 199.Ft int 200.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" 201This function release an interface. All the claimed interface must be released 202before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 203interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been 204disconnected and LIBUSB_ERROR on failure. 205. 206.Pp 207. 208.Ft int 209.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" 210Activate an alternate setting for an interface. Returns 0 on success, 211LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 212setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 213disconnected and LIBUSB_ERROR code on failure. 214. 215.Pp 216. 217.Ft int 218.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" 219Clear an halt/stall for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 220if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 221disconnected and a LIBUSB_ERROR code on failure. 222. 223.Pp 224. 225.Ft int 226.Fn libusb_reset_device "libusb_device_handle *devh" 227Perform an USB port reset for an usb device. Returns 0 on success, 228LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 229been disconnected and a LIBUSB_ERROR code on failure. 230. 231.Pp 232. 233.Ft int 234.Fn libusb_check_connected "libusb_device_handle *devh" 235Test if USB device is still connected. Returns 0 on success, 236LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR 237code on failure. 238. 239.Pp 240. 241.Ft int 242.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" 243Determine if a driver is active on a interface. Returns 0 if no kernel driver 244is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE 245if the device has been disconnected and return a LIBUSB_ERROR code on failure. 246. 247.Pp 248. 249.Ft int 250.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 251Detach a kernel driver from an interface. This is needed to claim an interface 252required by a kernel driver. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if 253no kernel driver was active, LIBUSB_ERROR_INVALID_PARAM if the interface does not 254exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a 255LIBUSB_ERROR code on failure. 256. 257.Pp 258. 259.Ft int 260.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" 261Re-attach an interface kernel driver previously detached. Returns 0 on success, 262LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE 263if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be 264attached because the interface is claimed by a program or driver and a 265LIBUSB_ERROR code on failure. 266. 267.Pp 268. 269.Sh USB DESCRIPTORS 270. 271.Pp 272. 273.Ft int 274.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 275Get the USB device descriptor for the device 276.Fa dev. 277This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on 278failure. 279. 280.Pp 281.Ft int 282.Fn libsub_get_active_config_descriptor "libusb_device *dev" "libusb_device_descriptor **config" 283Get the USB configuration descriptor for the active configuration. Returns 0 on 284success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 285and return another LIBUSB_ERROR code on error. 286. 287.Pp 288.Ft int 289.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" 290Get USB configuration descriptor based on its index 291.Fa idx. 292Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 293and returns another LIBUSB_ERROR code on error. 294. 295.Pp 296.Ft int 297.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" 298Get a USB configuration descriptor with a specific bConfigurationValue. This is 299a non-blocking function which does not send request through the device. Returns 0 300on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another 301LIBUSB_ERROR code on failure. 302. 303.Pp 304.Ft void 305.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 306Free a configuration descriptor. 307. 308.Pp 309.Ft int 310.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 311Retrieve a string descriptor in C style ascii. Returns a number of byte on success 312and a LIBUSB_ERROR code on failure. 313. 314.Pp 315. 316.Sh USB ASYNCHRONOUS I/O 317. 318.Pp 319.Ft struct libusb_transfer * 320.Fn libusb_alloc_transfer "int iso_packets" 321Allocate a transfer with 322.Fa iso_packets 323numbers of isochronous packet descriptors. Returns NULL on error. 324. 325.Pp 326.Ft void 327.Fn libusb_free_transfer "struct libusb_transfer *tr" 328Free a transfer. 329. 330.Pp 331.Ft int 332.Fn libusb_submit_transfer "struct libusb_transfer *tr" 333This function will submit a transfer and returns immediately. Returns 0 on 334success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 335LIBUSB_ERROR code on other failure. 336. 337.Pp 338.Ft int 339.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 340This function asynchronously cancel a transfer. Returns 0 on success and 341LIBUSB_ERROR code on failure. 342. 343.Pp 344.Sh USB SYNCHRONOUS I/O 345. 346.Pp 347.Ft int 348.Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout" 349Perform a USB control transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT 350if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 351supported, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 352LIBUSB_ERROR code on other failure. 353. 354.Pp 355.Ft int 356.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 357Perform an USB bulk transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT 358if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 359supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 360LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 361LIBUSB_ERROR code on other failure. 362. 363.Pp 364.Ft int 365.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 366Perform an USB Interrupt transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT 367if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 368supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 369LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 370LIBUSB_ERROR code on other failure. 371. 372.Pp 373.Sh USB EVENTS 374. 375.Pp 376.Ft int 377.Fn libusb_try_lock_events "libusb_context *ctx" 378Try to acquire the event handling lock. Returns 0 if the lock was obtained and 1 379if not. 380. 381.Pp 382.Ft void 383.Fn libusb_lock_events "libusb_context *ctx" 384Acquire the event handling lock. This function is blocking. 385. 386.Pp 387.Ft void 388.Fn libusb_unlock_events "libusb_context *ctx" 389Release the event handling lock. This will wake up any thread blocked 390on libusb_wait_for_event(). 391. 392.Pp 393.Ft int 394.Fn libusb_event_handling_ok "libusb_context *ctx" 395Determine if it still OK for this thread to be doing event handling. Returns 1 396if event handling can start or continue. Returns 0 if this thread must give up 397the events lock. 398. 399.Pp 400.Ft int 401.Fn libusb_event_handler_active "libusb_context *ctx" 402Determine if an active thread is handling events. Returns 1 if yes and 0 if there 403are no threads currently handling events. 404. 405.Pp 406.Ft void 407.Fn libusb_lock_event_waiters "libusb_context *ctx" 408Acquire the event_waiters lock. This lock is designed to be obtained under the 409situation where you want to be aware when events are completed, but some other 410thread is event handling so calling libusb_handle_events() is not allowed. 411. 412.Pp 413.Ft void 414.Fn libusb_unlock_event_waiters "libusb_context *ctx" 415Release the event_waiters lock. 416. 417.Pp 418.Ft int 419.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" 420Wait for another thread to signal completion of an event. Must be called 421with the event waiters lock held, see libusb_lock_event_waiters(). This will 422block until the timeout expires or a transfer completes or a thread releases 423the event handling lock through libusb_unlock_events(). Returns 0 after a 424transfer completes or another thread stops event handling, returns 1 if the 425timeout expired. 426. 427.Pp 428.Ft int 429.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" 430Handle any pending events by checking if timeouts have expired and by 431checking the set of file descriptors for activity. Returns 0 on success, or a 432LIBUSB_ERROR code on failure. 433. 434.Pp 435.Ft int 436.Fn libusb_handle_events "libusb_context *ctx" 437Handle any pending events in blocking mode with a sensible timeout. Returns 0 438on success, returns a LIBUSB_ERROR code on failure. 439. 440.Pp 441.Ft int 442.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 443Handle any pending events by polling file desciptors, without checking if 444another threads are already doing so. Must be called with the event lock held. 445. 446.Pp 447.Ft int 448.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" 449Determine the next internal timeout that libusb needs to handle. Returns 0 450if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR 451code on failure. 452. 453.Pp 454.Ft void 455.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 456Register notification functions for file descriptor additions/removals. 457These functions will be invoked for every new or removed file descriptor 458that libusb uses as an event source. 459. 460.Pp 461.Ft const struct libusb_pollfd ** 462.Fn libusb_get_pollfds "libusb_context *ctx" 463Retrive a list of file descriptors that should be polled by your main loop as 464libusb event sources. Returns a NULL-terminated list on success or NULL on failure. 465. 466.Sh LIBUSB VERSION 0.1 COMPATIBILITY 467.Pp 468The library is also compliant with LibUSB version 0.1.12. 469.Pp 470.Fn usb_open 471.Fn usb_close 472.Fn usb_get_string 473.Fn usb_get_string_simple 474.Fn usb_get_descriptor_by_endpoint 475.Fn usb_get_descriptor 476.Fn usb_parse_descriptor 477.Fn usb_parse_configuration 478.Fn usb_destroy_configuration 479.Fn usb_fetch_and_parse_descriptors 480.Fn usb_bulk_write 481.Fn usb_bulk_read 482.Fn usb_interrupt_write 483.Fn usb_interrupt_read 484.Fn usb_control_msg 485.Fn usb_set_configuration 486.Fn usb_claim_interface 487.Fn usb_release_interface 488.Fn usb_set_altinterface 489.Fn usb_resetep 490.Fn usb_clear_halt 491.Fn usb_reset 492.Fn usb_strerror 493.Fn usb_init 494.Fn usb_set_debug 495.Fn usb_find_busses 496.Fn usb_find_devices 497.Fn usb_device 498.Fn usb_get_busses 499.Fn usb_check_connected 500. 501.Sh SEE ALSO 502.Xr libusb20 3 , 503.Xr usb 4 , 504.Xr usbconfig 8 505.Pp 506.Pa http://libusb.sourceforge.net/ 507. 508.Sh HISTORY 509. 510.Nm 511support first appeared in 512.Fx 8.0 . 513