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 November 18, 2010 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 const char * 76.Fn libusb_strerror "int code" 77Get ASCII representation of the error given by the 78.Fa code 79argument. 80. 81. 82.Pp 83. 84.Ft void 85.Fn libusb_set_debug "libusb_context *ctx" "int level" 86Set debug to the 87.Fa level 88level. 89. 90.Pp 91. 92.Ft ssize_t 93.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" 94Fill into 95.Fa list 96the list of usb device available. All the device created by this 97function must be unref and free when you are done with them. This 98function returns the number of devices in list or a LIBUSB_ERROR code. 99. 100.Pp 101. 102.Ft void 103.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" 104Free the list of devices discovered by libusb_get_device_list. If 105.Fa unref_device 106is set to 1 all devices are unref one time. 107. 108.Pp 109. 110.Ft uint8_t 111.Fn libusb_get_bus_number "libusb_device *dev" 112Returns the number of the bus contained by the device 113.Fa dev. 114. 115.Pp 116. 117.Ft uint8_t 118.Fn libusb_get_device_address "libusb_device *dev" 119Return the device_address contained by the device 120.Fa dev. 121. 122.Pp 123. 124.Ft int 125.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" 126Return the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the 127endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. 128. 129.Pp 130. 131.Ft libusb_device * 132.Fn libusb_ref_device "libusb_device *dev" 133Increment the reference counter of the device 134.Fa dev. 135. 136.Pp 137. 138.Ft void 139.Fn libusb_unref_device "libusb_device *dev" 140Decrement the reference counter of the device 141.Fa dev. 142. 143.Pp 144. 145.Ft int 146.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" 147Open a device and obtain a device_handle. Return 0 on success, 148LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS 149on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been 150disconnected and a LIBUSB_ERROR code on error. 151. 152.Pp 153. 154.Ft libusb_device_handle * 155.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" 156Convenience function to open a device with is 157.Fa vid 158and 159.Fa pid. 160Return NULL on error. 161. 162.Pp 163. 164.Ft void 165.Fn libusb_close "libusb_device_handle *devh" 166Close a device handle. 167. 168.Pp 169. 170.Ft libusb_device * 171.Fn libusb_get_device(libusb_device_handle *devh) 172Get the device contained by devh. Return NULL on error. 173. 174.Pp 175. 176.Ft int 177.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" 178Return the bConfiguration value of the current configuration. return 0 179on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 180and a LIBUSB_ERROR code on error. 181. 182.Pp 183. 184.Ft int 185.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 186Set the active configuration 187.Fa config 188for the device contained by 189.Fa devh. 190This function return 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested 191configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 192claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a 193LIBUSB_ERROR code on failure. 194. 195.Pp 196. 197.Ft int 198.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 199Claim an interface in a given libusb_handle 200.Fa devh. 201This is a non-blocking function. It return 0 success, LIBUSB_ERROR_NOT_FOUND 202if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 203driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has 204been disconnected and a LIBUSB_ERROR code on failure. 205. 206.Pp 207. 208.Ft int 209.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" 210This function release an interface. All the claimed interface must be released 211before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 212interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been 213disconnected and LIBUSB_ERROR on failure. 214. 215.Pp 216. 217.Ft int 218.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" 219Activate an alternate setting for an interface. Returns 0 on success, 220LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 221setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 222disconnected and LIBUSB_ERROR code on failure. 223. 224.Pp 225. 226.Ft int 227.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" 228Clear an halt/stall for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 229if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 230disconnected and a LIBUSB_ERROR code on failure. 231. 232.Pp 233. 234.Ft int 235.Fn libusb_reset_device "libusb_device_handle *devh" 236Perform an USB port reset for an usb device. Returns 0 on success, 237LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 238been disconnected and a LIBUSB_ERROR code on failure. 239. 240.Pp 241. 242.Ft int 243.Fn libusb_check_connected "libusb_device_handle *devh" 244Test if USB device is still connected. Returns 0 on success, 245LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR 246code on failure. 247. 248.Pp 249. 250.Ft int 251.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" 252Determine if a driver is active on a interface. Returns 0 if no kernel driver 253is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE 254if the device has been disconnected and return a LIBUSB_ERROR code on failure. 255. 256.Pp 257. 258.Ft int 259.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 260or 261.Ft int 262.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 263Gets the name of the driver attached to the given 264.Fa device 265and 266.Fa interface 267into the buffer given by 268.Fa name 269and 270.Fa namelen . 271Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached 272to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does 273not exist. 274This function is non-portable. 275The buffer pointed to by 276.Fa name 277is only zero terminated on success. 278. 279.Pp 280. 281.Ft int 282.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 283or 284.Ft int 285.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" 286Detach a kernel driver from an interface. 287This is needed to claim an interface required by a kernel driver. 288Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, 289LIBUSB_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. 290. 291.Pp 292. 293.Ft int 294.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" 295Re-attach an interface kernel driver previously detached. Returns 0 on success, 296LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE 297if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be 298attached because the interface is claimed by a program or driver and a 299LIBUSB_ERROR code on failure. 300. 301.Pp 302. 303.Sh USB DESCRIPTORS 304. 305.Pp 306. 307.Ft int 308.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 309Get the USB device descriptor for the device 310.Fa dev. 311This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on 312failure. 313. 314.Pp 315.Ft int 316.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" 317Get the USB configuration descriptor for the active configuration. Returns 0 on 318success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state 319and return another LIBUSB_ERROR code on error. 320. 321.Pp 322.Ft int 323.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" 324Get USB configuration descriptor based on its index 325.Fa idx. 326Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 327and returns another LIBUSB_ERROR code on error. 328. 329.Pp 330.Ft int 331.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" 332Get a USB configuration descriptor with a specific bConfigurationValue. This is 333a non-blocking function which does not send request through the device. Returns 0 334on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another 335LIBUSB_ERROR code on failure. 336. 337.Pp 338.Ft void 339.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 340Free a configuration descriptor. 341. 342.Pp 343.Ft int 344.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 345Retrieve a string descriptor in C style ascii. Returns a number of byte on success 346and a LIBUSB_ERROR code on failure. 347. 348.Pp 349. 350.Sh USB ASYNCHRONOUS I/O 351. 352.Pp 353.Ft struct libusb_transfer * 354.Fn libusb_alloc_transfer "int iso_packets" 355Allocate a transfer with 356.Fa iso_packets 357numbers of isochronous packet descriptors. Returns NULL on error. 358. 359.Pp 360.Ft void 361.Fn libusb_free_transfer "struct libusb_transfer *tr" 362Free a transfer. 363. 364.Pp 365.Ft int 366.Fn libusb_submit_transfer "struct libusb_transfer *tr" 367This function will submit a transfer and returns immediately. Returns 0 on 368success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 369LIBUSB_ERROR code on other failure. 370. 371.Pp 372.Ft int 373.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 374This function asynchronously cancel a transfer. Returns 0 on success and 375LIBUSB_ERROR code on failure. 376. 377.Pp 378.Sh USB SYNCHRONOUS I/O 379. 380.Pp 381.Ft int 382.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" 383Perform a USB control transfer. Returns the actual number of bytes 384transferred on success in the range from and including zero until and 385including 386.Fa wLength . 387On error a libusb error code is returned, for example 388LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the 389control request was not supported, LIBUSB_ERROR_NO_DEVICE if the 390device has been disconnected or another LIBUSB_ERROR code on other failures. 391The libusb error codes are always negative. 392. 393.Pp 394.Ft int 395.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 396Perform an USB bulk transfer. 397A timeout value of zero means no timeout. 398The timeout value is given in milliseconds. 399Returns 0 on success, LIBUSB_ERROR_TIMEOUT 400if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 401supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 402LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 403LIBUSB_ERROR code on other failure. 404. 405.Pp 406.Ft int 407.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 408Perform an USB Interrupt transfer. 409A timeout value of zero means no timeout. 410The timeout value is given in milliseconds. 411Returns 0 on success, LIBUSB_ERROR_TIMEOUT 412if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 413supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 414LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 415LIBUSB_ERROR code on other failure. 416. 417.Pp 418.Sh USB EVENTS 419. 420.Pp 421.Ft int 422.Fn libusb_try_lock_events "libusb_context *ctx" 423Try to acquire the event handling lock. Returns 0 if the lock was obtained and 1 424if not. 425. 426.Pp 427.Ft void 428.Fn libusb_lock_events "libusb_context *ctx" 429Acquire the event handling lock. This function is blocking. 430. 431.Pp 432.Ft void 433.Fn libusb_unlock_events "libusb_context *ctx" 434Release the event handling lock. This will wake up any thread blocked 435on libusb_wait_for_event(). 436. 437.Pp 438.Ft int 439.Fn libusb_event_handling_ok "libusb_context *ctx" 440Determine if it still OK for this thread to be doing event handling. Returns 1 441if event handling can start or continue. Returns 0 if this thread must give up 442the events lock. 443. 444.Pp 445.Ft int 446.Fn libusb_event_handler_active "libusb_context *ctx" 447Determine if an active thread is handling events. Returns 1 if yes and 0 if there 448are no threads currently handling events. 449. 450.Pp 451.Ft void 452.Fn libusb_lock_event_waiters "libusb_context *ctx" 453Acquire the event_waiters lock. This lock is designed to be obtained under the 454situation where you want to be aware when events are completed, but some other 455thread is event handling so calling libusb_handle_events() is not allowed. 456. 457.Pp 458.Ft void 459.Fn libusb_unlock_event_waiters "libusb_context *ctx" 460Release the event_waiters lock. 461. 462.Pp 463.Ft int 464.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" 465Wait for another thread to signal completion of an event. Must be called 466with the event waiters lock held, see libusb_lock_event_waiters(). This will 467block until the timeout expires or a transfer completes or a thread releases 468the event handling lock through libusb_unlock_events(). Returns 0 after a 469transfer completes or another thread stops event handling, returns 1 if the 470timeout expired. 471. 472.Pp 473.Ft int 474.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" 475Handle any pending events by checking if timeouts have expired and by 476checking the set of file descriptors for activity. Returns 0 on success, or a 477LIBUSB_ERROR code on failure. 478. 479.Pp 480.Ft int 481.Fn libusb_handle_events "libusb_context *ctx" 482Handle any pending events in blocking mode with a sensible timeout. Returns 0 483on success, returns a LIBUSB_ERROR code on failure. 484. 485.Pp 486.Ft int 487.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 488Handle any pending events by polling file desciptors, without checking if 489another threads are already doing so. Must be called with the event lock held. 490. 491.Pp 492.Ft int 493.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" 494Determine the next internal timeout that libusb needs to handle. Returns 0 495if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR 496code on failure. 497. 498.Pp 499.Ft void 500.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 501Register notification functions for file descriptor additions/removals. 502These functions will be invoked for every new or removed file descriptor 503that libusb uses as an event source. 504. 505.Pp 506.Ft const struct libusb_pollfd ** 507.Fn libusb_get_pollfds "libusb_context *ctx" 508Retrive a list of file descriptors that should be polled by your main loop as 509libusb event sources. Returns a NULL-terminated list on success or NULL on failure. 510. 511.Sh LIBUSB VERSION 0.1 COMPATIBILITY 512.Pp 513The library is also compliant with LibUSB version 0.1.12. 514.Pp 515.Fn usb_open 516.Fn usb_close 517.Fn usb_get_string 518.Fn usb_get_string_simple 519.Fn usb_get_descriptor_by_endpoint 520.Fn usb_get_descriptor 521.Fn usb_parse_descriptor 522.Fn usb_parse_configuration 523.Fn usb_destroy_configuration 524.Fn usb_fetch_and_parse_descriptors 525.Fn usb_bulk_write 526.Fn usb_bulk_read 527.Fn usb_interrupt_write 528.Fn usb_interrupt_read 529.Fn usb_control_msg 530.Fn usb_set_configuration 531.Fn usb_claim_interface 532.Fn usb_release_interface 533.Fn usb_set_altinterface 534.Fn usb_resetep 535.Fn usb_clear_halt 536.Fn usb_reset 537.Fn usb_strerror 538.Fn usb_init 539.Fn usb_set_debug 540.Fn usb_find_busses 541.Fn usb_find_devices 542.Fn usb_device 543.Fn usb_get_busses 544.Fn usb_check_connected 545. 546.Sh SEE ALSO 547.Xr libusb20 3 , 548.Xr usb 4 , 549.Xr usbconfig 8 550.Pp 551.Pa http://libusb.sourceforge.net/ 552. 553.Sh HISTORY 554. 555.Nm 556support first appeared in 557.Fx 8.0 . 558