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