1.\" 2.\" Copyright (c) 2009 Sylvestre Gallon 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd January, 26, 2023 26.Dt LIBUSB 3 27.Os 28.Sh NAME 29.Nm libusb 30.Nd "USB access library" 31.Sh LIBRARY 32USB access library 33.Pq libusb, -lusb 34.Sh SYNOPSIS 35.In libusb.h 36.Sh DESCRIPTION 37The 38.Nm 39library contains interfaces for directly managing a usb device. 40The current implementation supports v1.0 of the libusb API. 41.Sh LIBRARY INITIALISATION AND DEINITIALISATION 42.Ft "const struct libusb_version *" 43.Fn libusb_get_version "void" 44This function returns version information about LibUSB. 45.Pp 46.Ft int 47.Fn libusb_init "libusb_context **ctx" 48Call this function before any other libusb v1.0 API function, to 49initialise a valid libusb v1.0 context. 50If the 51.Fa ctx 52argument is non-NULL, a pointer to the libusb context is stored at 53the given location. 54This function returns 0 upon success or LIBUSB_ERROR on failure. 55.Pp 56.Ft int 57.Fn libusb_init_context "libusb_context **ctx" "const struct libusb_init_option []" "int num_options" 58Call this function before any other libusb v1.0 API function, to 59initialise a valid libusb v1.0 context. 60If the 61.Fa ctx 62argument is non-NULL, a pointer to the libusb context is stored at 63the given location. 64Additional options, like the USB debug level, may be given using the 65second and third argument. 66If no options are needed, simply use libusb_init(). 67This function returns 0 upon success or a LIBUSB_ERROR value on failure. 68.Pp 69.Ft void 70.Fn libusb_exit "libusb_context *ctx" 71Deinitialise libusb. 72Must be called at the end of the application. 73Other libusb routines may not be called after this function. 74.Pp 75.Ft int 76.Fn libusb_has_capability "uint32_t capability" 77This function checks the runtime capabilities of 78.Nm . 79This function will return non-zero if the given 80.Fa capability 81is supported, 0 if it is not supported. 82The valid values for 83.Fa capability 84are: 85.Bl -tag -width LIBUSB_CAP -offset indent 86.It Va LIBUSB_CAP_HAS_CAPABILITY 87.Nm 88supports 89.Fn libusb_has_capability . 90.It Va LIBUSB_CAP_HAS_HOTPLUG 91.Nm 92supports hotplug notifications. 93.It Va LIBUSB_CAP_HAS_HID_ACCESS 94.Nm 95can access HID devices without requiring user intervention. 96.It Va LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER 97.Nm 98supports detaching of the default USB driver with 99.Fn libusb_detach_kernel_driver . 100.El 101.Pp 102.Ft const char * 103.Fn libusb_strerror "int code" 104Get the ASCII representation of the error given by the 105.Fa code 106argument. 107This function does not return NULL. 108.Pp 109.Ft const char * 110.Fn libusb_error_name "int code" 111Get the ASCII representation of the error enum given by the 112.Fa code 113argument. 114This function does not return NULL. 115.Pp 116.Ft void 117.Fn libusb_set_debug "libusb_context *ctx" "int level" 118Set the debug level to 119.Fa level . 120.Pp 121.Ft ssize_t 122.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" 123Populate 124.Fa list 125with the list of usb devices available, adding a reference to each 126device in the list. 127All the list entries created by this 128function must have their reference counter 129decremented when you are done with them, 130and the list itself must be freed. 131This 132function returns the number of devices in the list or a LIBUSB_ERROR code. 133.Pp 134.Ft void 135.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" 136Free the list of devices discovered by libusb_get_device_list. 137If 138.Fa unref_device 139is set to 1 all devices in the list have their reference 140counter decremented once. 141.Pp 142.Ft uint8_t 143.Fn libusb_get_bus_number "libusb_device *dev" 144Returns the number of the bus contained by the device 145.Fa dev . 146.Pp 147.Ft uint8_t 148.Fn libusb_get_port_number "libusb_device *dev" 149Returns the port number which the device given by 150.Fa dev 151is attached to. 152.Pp 153.Ft int 154.Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize" 155Stores, in the buffer 156.Fa buf 157of size 158.Fa bufsize , 159the list of all port numbers from root for the device 160.Fa dev . 161.Pp 162.Ft int 163.Fn libusb_get_port_path "libusb_context *ctx" "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize" 164Deprecated function equivalent to libusb_get_port_numbers. 165.Pp 166.Ft uint8_t 167.Fn libusb_get_device_address "libusb_device *dev" 168Returns the device_address contained by the device 169.Fa dev . 170.Pp 171.Ft enum libusb_speed 172.Fn libusb_get_device_speed "libusb_device *dev" 173Returns the wire speed at which the device is connected. 174See the LIBUSB_SPEED_XXX enums for more information. 175LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed. 176.Pp 177.Ft int 178.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" 179Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the 180endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. 181.Pp 182.Ft int 183.Fn libusb_get_max_iso_packet_size "libusb_device *dev" "unsigned char endpoint" 184Returns the packet size multiplied by the packet multiplier on success, 185LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and 186LIBUSB_ERROR_OTHERS on other failure. 187.Pp 188.Ft libusb_device * 189.Fn libusb_ref_device "libusb_device *dev" 190Increment the reference counter of the device 191.Fa dev . 192.Pp 193.Ft void 194.Fn libusb_unref_device "libusb_device *dev" 195Decrement the reference counter of the device 196.Fa dev . 197.Pp 198.Ft int 199.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" 200Open a device and obtain a device_handle. 201Returns 0 on success, 202LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS 203on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been 204disconnected and a LIBUSB_ERROR code on other errors. 205.Pp 206.Ft libusb_device_handle * 207.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" 208A convenience function to open a device by vendor and product IDs 209.Fa vid 210and 211.Fa pid . 212Returns NULL on error. 213.Pp 214.Ft void 215.Fn libusb_close "libusb_device_handle *devh" 216Close a device handle. 217.Pp 218.Ft libusb_device * 219.Fn libusb_get_device "libusb_device_handle *devh" 220Get the device contained by devh. 221Returns NULL on error. 222.Pp 223.Ft int 224.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" 225Returns the value of the current configuration. 226Returns 0 227on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 228and a LIBUSB_ERROR code on error. 229.Pp 230.Ft int 231.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 232Set the active configuration to 233.Fa config 234for the device contained by 235.Fa devh . 236This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested 237configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 238claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a 239LIBUSB_ERROR code on failure. 240.Pp 241.Ft int 242.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 243Claim an interface in a given libusb_handle 244.Fa devh . 245This is a non-blocking function. 246It returns 0 on success, LIBUSB_ERROR_NOT_FOUND 247if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 248driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has 249been disconnected and a LIBUSB_ERROR code on failure. 250.Pp 251.Ft int 252.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" 253This function releases an interface. 254All the claimed interfaces on a device must be released 255before closing the device. 256Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 257interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been 258disconnected and LIBUSB_ERROR on failure. 259.Pp 260.Ft int 261.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" 262Activate an alternate setting for an interface. 263Returns 0 on success, 264LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 265setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 266disconnected and a LIBUSB_ERROR code on failure. 267.Pp 268.Ft int 269.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" 270Clear an halt/stall for a endpoint. 271Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 272if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 273disconnected and a LIBUSB_ERROR code on failure. 274.Pp 275.Ft int 276.Fn libusb_reset_device "libusb_device_handle *devh" 277Perform an USB port reset for an usb device. 278Returns 0 on success, 279LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 280been disconnected and a LIBUSB_ERROR code on failure. 281.Pp 282.Ft int 283.Fn libusb_check_connected "libusb_device_handle *devh" 284Test if the USB device is still connected. 285Returns 0 on success, 286LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR 287code on failure. 288.Pp 289.Ft int 290.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" 291Determine if a driver is active on a interface. 292Returns 0 if no kernel driver is active 293and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE 294if the device has been disconnected and a LIBUSB_ERROR code on failure. 295.Pp 296.Ft int 297.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 298or 299.Ft int 300.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 301Copy the name of the driver attached to the given 302.Fa device 303and 304.Fa interface 305into the buffer 306.Fa name 307of length 308.Fa namelen . 309Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached 310to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does 311not exist. 312This function is non-portable. 313The buffer pointed to by 314.Fa name 315is only zero terminated on success. 316.Pp 317.Ft int 318.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 319or 320.Ft int 321.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" 322Detach a kernel driver from an interface. 323This is needed to claim an interface already claimed by a kernel driver. 324Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, 325LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 326LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 327and a LIBUSB_ERROR code on failure. 328This function is non-portable. 329.Pp 330.Ft int 331.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" 332Re-attach an interface kernel driver that was previously detached. 333Returns 0 on success, 334LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 335LIBUSB_ERROR_NO_DEVICE 336if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be 337attached because the interface is claimed by a program or driver and a 338LIBUSB_ERROR code on failure. 339.Pp 340.Ft int 341.Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable" 342This function enables automatic kernel interface driver detach when an 343interface is claimed. 344When the interface is restored the kernel driver is allowed to be re-attached. 345If the 346.Fa enable 347argument is non-zero the feature is enabled. 348Else disabled. 349Returns 0 on success and a LIBUSB_ERROR code on 350failure. 351.Sh USB DESCRIPTORS 352.Ft int 353.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 354Get the USB device descriptor for the device 355.Fa dev . 356This is a non-blocking function. 357Returns 0 on success and a LIBUSB_ERROR code on 358failure. 359.Pp 360.Ft int 361.Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" 362Get the USB configuration descriptor for the active configuration. 363Returns 0 on 364success, LIBUSB_ERROR_NOT_FOUND if the device is in 365an unconfigured state 366and a LIBUSB_ERROR code on error. 367.Pp 368.Ft int 369.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" 370Get a USB configuration descriptor based on its index 371.Fa idx . 372Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 373and a LIBUSB_ERROR code on error. 374.Pp 375.Ft int 376.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" 377Get a USB configuration descriptor with a specific bConfigurationValue. 378This is 379a non-blocking function which does not send a request through the device. 380Returns 0 381on success, LIBUSB_ERROR_NOT_FOUND if the configuration 382does not exist and a 383LIBUSB_ERROR code on failure. 384.Pp 385.Ft void 386.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 387Free a configuration descriptor. 388.Pp 389.Ft int 390.Fn libusb_get_string_descriptor "libusb_device_handle *devh" "uint8_t desc_idx" "uint16_t langid" "unsigned char *data" "int length" 391Retrieve a string descriptor in raw format. 392Returns the number of bytes actually transferred on success 393or a negative LIBUSB_ERROR code on failure. 394.Pp 395.Ft int 396.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 397Retrieve a string descriptor in C style ASCII. 398Returns the positive number of bytes in the resulting ASCII string 399on success and a LIBUSB_ERROR code on failure. 400.Pp 401.Ft int 402.Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp" 403This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by 404.Fa buf 405and having a length of 406.Fa len . 407Typically these arguments are the extra and extra_length fields of the 408endpoint descriptor. 409On success the pointer to resulting descriptor is stored at the location given by 410.Fa ep_comp . 411Returns zero on success and a LIBUSB_ERROR code on failure. 412On success the parsed USB 3.0 endpoint companion descriptor must be 413freed using the libusb_free_ss_endpoint_comp function. 414.Pp 415.Ft void 416.Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp" 417This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by 418.Fa ep_comp . 419.Pp 420.Ft int 421.Fn libusb_get_ss_endpoint_companion_descriptor "struct libusb_context *ctx" "const struct libusb_endpoint_descriptor *endpoint" "struct libusb_ss_endpoint_companion_descriptor **ep_comp" 422This function finds and parses the USB 3.0 endpoint companion descriptor given by 423.Fa endpoint . 424Returns zero on success and a LIBUSB_ERROR code on failure. 425On success the parsed USB 3.0 endpoint companion descriptor must be 426freed using the libusb_free_ss_endpoint_companion_descriptor function. 427.Pp 428.Ft void 429.Fn libusb_free_ss_endpoint_companion_descriptor "struct libusb_ss_endpoint_companion_descriptor *ep_comp" 430This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by 431.Fa ep_comp . 432.Pp 433.Ft int 434.Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos" 435This function queries the USB device given by 436.Fa handle 437and stores a pointer to a parsed BOS descriptor into 438.Fa bos . 439Returns zero on success and a LIBUSB_ERROR code on failure. 440On success the parsed BOS descriptor must be 441freed using the libusb_free_bos_descriptor function. 442.Pp 443.Ft int 444.Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos" 445This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by 446.Fa buf 447and having a length of 448.Fa len . 449On success the pointer to resulting descriptor is stored at the location given by 450.Fa bos . 451Returns zero on success and a LIBUSB_ERROR code on failure. 452On success the parsed BOS descriptor must be freed using the 453libusb_free_bos_descriptor function. 454.Pp 455.Ft void 456.Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos" 457This function is NULL safe and frees a parsed BOS descriptor given by 458.Fa bos . 459.Pp 460.Ft int 461.Fn libusb_get_usb_2_0_extension_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension" 462This function parses the USB 2.0 extension descriptor from the descriptor given by 463.Fa dev_cap 464and stores a pointer to the parsed descriptor into 465.Fa usb_2_0_extension . 466Returns zero on success and a LIBUSB_ERROR code on failure. 467On success the parsed USB 2.0 extension descriptor must be freed using the 468libusb_free_usb_2_0_extension_descriptor function. 469.Pp 470.Ft void 471.Fn libusb_free_usb_2_0_extension_descriptor "struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension" 472This function is NULL safe and frees a parsed USB 2.0 extension descriptor given by 473.Fa usb_2_0_extension . 474.Pp 475.Ft int 476.Fn libusb_get_ss_usb_device_capability_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_capability" 477This function parses the SuperSpeed device capability descriptor from the descriptor given by 478.Fa dev_cap 479and stores a pointer to the parsed descriptor into 480.Fa ss_usb_device_capability . 481Returns zero on success and a LIBUSB_ERROR code on failure. 482On success the parsed SuperSpeed device capability descriptor must be freed using the 483libusb_free_ss_usb_device_capability_descriptor function. 484.Pp 485.Ft void 486.Fn libusb_free_ss_usb_device_capability_descriptor "struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_capability" 487This function is NULL safe and frees a parsed SuperSpeed device capability descriptor given by 488.Fa ss_usb_device_capability . 489.Pp 490.Ft int 491.Fn libusb_get_container_id_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_container_id_descriptor **container_id" 492This function parses the container ID descriptor from the descriptor given by 493.Fa dev_cap 494and stores a pointer to the parsed descriptor into 495.Fa container_id . 496Returns zero on success and a LIBUSB_ERROR code on failure. 497On success the parsed container ID descriptor must be freed using the 498libusb_free_container_id_descriptor function. 499.Pp 500.Ft void 501.Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id" 502This function is NULL safe and frees a parsed container ID descriptor given by 503.Fa container_id . 504.Sh USB ASYNCHRONOUS I/O 505.Ft struct libusb_transfer * 506.Fn libusb_alloc_transfer "int iso_packets" 507Allocate a transfer with the number of isochronous packet descriptors 508specified by 509.Fa iso_packets . 510Returns NULL on error. 511.Pp 512.Ft void 513.Fn libusb_free_transfer "struct libusb_transfer *tr" 514Free a transfer. 515.Pp 516.Ft int 517.Fn libusb_submit_transfer "struct libusb_transfer *tr" 518This function will submit a transfer and returns immediately. 519Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if 520the device has been disconnected and a 521LIBUSB_ERROR code on other failure. 522.Pp 523.Ft int 524.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 525This function asynchronously cancels a transfer. 526Returns 0 on success and a LIBUSB_ERROR code on failure. 527.Sh USB SYNCHRONOUS I/O 528.Ft int 529.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" 530Perform a USB control transfer. 531Returns the actual number of bytes 532transferred on success, in the range from and including zero up to and 533including 534.Fa wLength . 535On error a LIBUSB_ERROR code is returned, for example 536LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the 537control request was not supported, LIBUSB_ERROR_NO_DEVICE if the 538device has been disconnected and another LIBUSB_ERROR code on other failures. 539The LIBUSB_ERROR codes are all negative. 540.Pp 541.Ft int 542.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 543Perform an USB bulk transfer. 544A timeout value of zero means no timeout. 545The timeout value is given in milliseconds. 546Returns 0 on success, LIBUSB_ERROR_TIMEOUT 547if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not 548supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 549LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 550a LIBUSB_ERROR code on other failure. 551.Pp 552.Ft int 553.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 554Perform an USB Interrupt transfer. 555A timeout value of zero means no timeout. 556The timeout value is given in milliseconds. 557Returns 0 on success, LIBUSB_ERROR_TIMEOUT 558if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not 559supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 560LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 561a LIBUSB_ERROR code on other failure. 562.Sh USB STREAMS SUPPORT 563.Ft int 564.Fn libusb_alloc_streams "libusb_device_handle *dev" "uint32_t num_streams" "unsigned char *endpoints" "int num_endpoints" 565This function verifies that the given number of streams using the 566given number of endpoints is allowed and allocates the resources 567needed to use so-called USB streams. 568Currently only a single stream per endpoint is supported to simplify 569the internals of LibUSB. 570This function returns 0 on success or a LIBUSB_ERROR code on failure. 571.Pp 572.Ft int 573.Fn libusb_free_streams "libusb_device_handle *dev" "unsigned char *endpoints" "int num_endpoints" 574This function release resources needed for streams usage. 575Returns 0 on success or a LIBUSB_ERROR code on failure. 576.Pp 577.Ft void 578.Fn libusb_transfer_set_stream_id "struct libusb_transfer *transfer" "uint32_t stream_id" 579This function sets the stream ID for the given USB transfer. 580.Pp 581.Ft uint32_t 582.Fn libusb_transfer_get_stream_id "struct libusb_transfer *transfer" 583This function returns the stream ID for the given USB transfer. 584If no stream ID is used a value of zero is returned. 585.Sh USB EVENTS 586.Ft int 587.Fn libusb_try_lock_events "libusb_context *ctx" 588Try to acquire the event handling lock. 589Returns 0 if the lock was obtained and 1 if not. 590.Pp 591.Ft void 592.Fn libusb_lock_events "libusb_context *ctx" 593Acquire the event handling lock. 594This function is blocking. 595.Pp 596.Ft void 597.Fn libusb_unlock_events "libusb_context *ctx" 598Release the event handling lock. 599This will wake up any thread blocked 600on 601.Fn libusb_wait_for_event . 602.Pp 603.Ft int 604.Fn libusb_event_handling_ok "libusb_context *ctx" 605Determine if it still OK for this thread to be doing event handling. 606Returns 1 607if event handling can start or continue. 608Returns 0 if this thread must give up 609the events lock. 610.Pp 611.Ft int 612.Fn libusb_event_handler_active "libusb_context *ctx" 613Determine if an active thread is handling events. 614Returns 1 if there is a thread handling events and 0 if there 615are no threads currently handling events. 616.Pp 617.Ft void 618.Fn libusb_interrupt_event_handler "libusb_context *ctx" 619Causes the 620.Fn libusb_handle_events 621familiy of functions to return to the caller one time. 622The 623.Fn libusb_handle_events 624functions may be called again after calling this function. 625.Pp 626.Ft void 627.Fn libusb_lock_event_waiters "libusb_context *ctx" 628Acquire the event_waiters lock. 629This lock is designed to be obtained in the 630situation where you want to be aware when events are completed, but some other 631thread is event handling so calling 632.Fn libusb_handle_events 633is not allowed. 634.Pp 635.Ft void 636.Fn libusb_unlock_event_waiters "libusb_context *ctx" 637Release the event_waiters lock. 638.Pp 639.Ft int 640.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" 641Wait for another thread to signal completion of an event. 642Must be called 643with the event waiters lock held, see 644.Fn libusb_lock_event_waiters . 645This will 646block until the timeout expires or a transfer completes or a thread releases 647the event handling lock through 648.Fn libusb_unlock_events . 649Returns 0 after a 650transfer completes or another thread stops event handling, and 1 if the 651timeout expired. 652.Pp 653.Ft int 654.Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed" 655Handle any pending events by checking if timeouts have expired and by 656checking the set of file descriptors for activity. 657If the 658.Fa completed 659argument is not equal to NULL, this function will 660loop until a transfer completion callback sets the variable pointed to 661by the 662.Fa completed 663argument to non-zero. 664If the 665.Fa tv 666argument is not equal to NULL, this function will return 667LIBUSB_ERROR_TIMEOUT after the given timeout. 668Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout. 669.Pp 670.Ft int 671.Fn libusb_handle_events_completed "libusb_context *ctx" "int *completed" 672Handle any pending events by checking the set of file descriptors for activity. 673If the 674.Fa completed 675argument is not equal to NULL, this function will 676loop until a transfer completion callback sets the variable pointed to 677by the 678.Fa completed 679argument to non-zero. 680Returns 0 on success, or a LIBUSB_ERROR code on failure. 681.Pp 682.Ft int 683.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" 684Handle any pending events by checking if timeouts have expired and by 685checking the set of file descriptors for activity. 686Returns 0 on success, or a 687LIBUSB_ERROR code on failure or timeout. 688.Pp 689.Ft int 690.Fn libusb_handle_events "libusb_context *ctx" 691Handle any pending events in blocking mode with a sensible timeout. 692Returns 0 693on success and a LIBUSB_ERROR code on failure. 694.Pp 695.Ft int 696.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 697Handle any pending events by polling file descriptors, without checking if 698another thread is already doing so. 699Must be called with the event lock held. 700.Pp 701.Ft int 702.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" 703Determine the next internal timeout that libusb needs to handle. 704Returns 0 705if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR 706code on failure or timeout. 707.Pp 708.Ft void 709.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 710Register notification functions for file descriptor additions/removals. 711These functions will be invoked for every new or removed file descriptor 712that libusb uses as an event source. 713.Pp 714.Ft const struct libusb_pollfd ** 715.Fn libusb_get_pollfds "libusb_context *ctx" 716Retrieve a list of file descriptors that should be polled by your main loop as 717libusb event sources. 718Returns a NULL-terminated list on success or NULL on failure. 719.Pp 720.Ft int 721.Fn libusb_hotplug_register_callback "libusb_context *ctx" "libusb_hotplug_event events" "libusb_hotplug_flag flags" "int vendor_id" "int product_id" "int dev_class" "libusb_hotplug_callback_fn cb_fn" "void *user_data" "libusb_hotplug_callback_handle *handle" 722This function registers a hotplug filter. 723The 724.Fa events 725argument select which events makes the hotplug filter trigger. 726Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. 727One or more events must be specified. 728The 729.Fa vendor_id , 730.Fa product_id 731and 732.Fa dev_class 733arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor. 734Else the specified value is used for matching. 735If the 736.Fa flags 737argument is set to LIBUSB_HOTPLUG_ENUMERATE, all currently attached and matching USB devices will be passed to the hotplug filter, given by the 738.Fa cb_fn 739argument. 740Else the 741.Fa flags 742argument should be set to LIBUSB_HOTPLUG_NO_FLAGS. 743This function returns 0 upon success or a LIBUSB_ERROR code on failure. 744.Pp 745.Ft int 746.Fn libusb_hotplug_callback_fn "libusb_context *ctx" "libusb_device *device" "libusb_hotplug_event event" "void *user_data" 747The hotplug filter function. 748If this function returns non-zero, the filter is removed. 749Else the filter is kept and can receive more events. 750The 751.Fa user_data 752argument is the same as given when the filter was registered. 753The 754.Fa event 755argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. 756.Pp 757.Ft void 758.Fn libusb_hotplug_deregister_callback "libusb_context *ctx" "libusb_hotplug_callback_handle handle" 759This function unregisters a hotplug filter. 760.Sh LIBUSB VERSION 0.1 COMPATIBILITY 761The library is also compliant with LibUSB version 0.1.12. 762.Pp 763.Fn usb_open 764.Fn usb_close 765.Fn usb_get_string 766.Fn usb_get_string_simple 767.Fn usb_get_descriptor_by_endpoint 768.Fn usb_get_descriptor 769.Fn usb_parse_descriptor 770.Fn usb_parse_configuration 771.Fn usb_destroy_configuration 772.Fn usb_fetch_and_parse_descriptors 773.Fn usb_bulk_write 774.Fn usb_bulk_read 775.Fn usb_interrupt_write 776.Fn usb_interrupt_read 777.Fn usb_control_msg 778.Fn usb_set_configuration 779.Fn usb_claim_interface 780.Fn usb_release_interface 781.Fn usb_set_altinterface 782.Fn usb_resetep 783.Fn usb_clear_halt 784.Fn usb_reset 785.Fn usb_strerror 786.Fn usb_init 787.Fn usb_set_debug 788.Fn usb_find_busses 789.Fn usb_find_devices 790.Fn usb_device 791.Fn usb_get_busses 792.Fn usb_check_connected 793.Fn usb_get_driver_np 794.Fn usb_detach_kernel_driver_np 795.Sh SEE ALSO 796.Xr libusb20 3 , 797.Xr usb 4 , 798.Xr usbconfig 8 , 799.Xr usbdump 8 800.Pp 801.Lk https://libusb.info/ 802.Sh HISTORY 803.Nm 804support first appeared in 805.Fx 8.0 . 806