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