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