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 June 12, 2025 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.Sh DEVICE HANDLING AND ENUMERATION 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 libusb_device * 224.Fn libusb_get_parent "libusb_device *dev" 225Get dev's parent device. 226Returns NULL if the device has no parent (i.e. is a root device). 227.Pp 228.Ft int 229.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" 230Returns the value of the current configuration. 231Returns 0 232on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 233and a LIBUSB_ERROR code on error. 234.Pp 235.Ft int 236.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 237Set the active configuration to 238.Fa config 239for the device contained by 240.Fa devh . 241This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested 242configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 243claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a 244LIBUSB_ERROR code on failure. 245.Pp 246.Ft int 247.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 248Claim an interface in a given libusb_handle 249.Fa devh . 250This is a non-blocking function. 251It returns 0 on success, LIBUSB_ERROR_NOT_FOUND 252if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 253driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has 254been disconnected and a LIBUSB_ERROR code on failure. 255.Pp 256.Ft int 257.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" 258This function releases an interface. 259All the claimed interfaces on a device must be released 260before closing the device. 261Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 262interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been 263disconnected and LIBUSB_ERROR on failure. 264.Pp 265.Ft int 266.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" 267Activate an alternate setting for an interface. 268Returns 0 on success, 269LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 270setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 271disconnected and a LIBUSB_ERROR code on failure. 272.Pp 273.Ft int 274.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" 275Clear an halt/stall for a endpoint. 276Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 277if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been 278disconnected and a LIBUSB_ERROR code on failure. 279.Pp 280.Ft int 281.Fn libusb_reset_device "libusb_device_handle *devh" 282Perform an USB port reset for an usb device. 283Returns 0 on success, 284LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 285been disconnected and a LIBUSB_ERROR code on failure. 286.Pp 287.Ft int 288.Fn libusb_check_connected "libusb_device_handle *devh" 289Test if the USB device is still connected. 290Returns 0 on success, 291LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR 292code on failure. 293.Pp 294.Ft int 295.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" 296Determine if a driver is active on a interface. 297Returns 0 if no kernel driver is active 298and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE 299if the device has been disconnected and a LIBUSB_ERROR code on failure. 300.Pp 301.Ft int 302.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 303or 304.Ft int 305.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 306Copy the name of the driver attached to the given 307.Fa device 308and 309.Fa interface 310into the buffer 311.Fa name 312of length 313.Fa namelen . 314Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached 315to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does 316not exist. 317This function is non-portable. 318The buffer pointed to by 319.Fa name 320is only zero terminated on success. 321.Pp 322.Ft int 323.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 324or 325.Ft int 326.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" 327Detach a kernel driver from an interface. 328This is needed to claim an interface already claimed by a kernel driver. 329Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, 330LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 331LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 332and a LIBUSB_ERROR code on failure. 333This function is non-portable. 334.Pp 335.Ft int 336.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" 337Re-attach an interface kernel driver that was previously detached. 338Returns 0 on success, 339LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 340LIBUSB_ERROR_NO_DEVICE 341if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be 342attached because the interface is claimed by a program or driver and a 343LIBUSB_ERROR code on failure. 344.Pp 345.Ft int 346.Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable" 347This function enables automatic kernel interface driver detach when an 348interface is claimed. 349When the interface is restored the kernel driver is allowed to be re-attached. 350If the 351.Fa enable 352argument is non-zero the feature is enabled. 353Else disabled. 354Returns 0 on success and a LIBUSB_ERROR code on 355failure. 356.Sh USB DESCRIPTORS 357.Ft int 358.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 359Get the USB device descriptor for the device 360.Fa dev . 361This is a non-blocking function. 362Returns 0 on success and a LIBUSB_ERROR code on 363failure. 364.Pp 365.Ft int 366.Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" 367Get the USB configuration descriptor for the active configuration. 368Returns 0 on 369success, LIBUSB_ERROR_NOT_FOUND if the device is in 370an unconfigured state 371and a LIBUSB_ERROR code on error. 372.Pp 373.Ft int 374.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" 375Get a USB configuration descriptor based on its index 376.Fa idx . 377Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist 378and a LIBUSB_ERROR code on error. 379.Pp 380.Ft int 381.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" 382Get a USB configuration descriptor with a specific bConfigurationValue. 383This is 384a non-blocking function which does not send a request through the device. 385Returns 0 386on success, LIBUSB_ERROR_NOT_FOUND if the configuration 387does not exist and a 388LIBUSB_ERROR code on failure. 389.Pp 390.Ft void 391.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 392Free a configuration descriptor. 393.Pp 394.Ft int 395.Fn libusb_get_string_descriptor "libusb_device_handle *devh" "uint8_t desc_idx" "uint16_t langid" "unsigned char *data" "int length" 396Retrieve a string descriptor in raw format. 397Returns the number of bytes actually transferred on success 398or a negative LIBUSB_ERROR code on failure. 399.Pp 400.Ft int 401.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 402Retrieve a string descriptor in C style ASCII. 403Returns the positive number of bytes in the resulting ASCII string 404on success and a LIBUSB_ERROR code on failure. 405.Pp 406.Ft int 407.Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp" 408This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by 409.Fa buf 410and having a length of 411.Fa len . 412Typically these arguments are the extra and extra_length fields of the 413endpoint descriptor. 414On success the pointer to resulting descriptor is stored at the location given by 415.Fa ep_comp . 416Returns zero on success and a LIBUSB_ERROR code on failure. 417On success the parsed USB 3.0 endpoint companion descriptor must be 418freed using the libusb_free_ss_endpoint_comp function. 419.Pp 420.Ft void 421.Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp" 422This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by 423.Fa ep_comp . 424.Pp 425.Ft int 426.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" 427This function finds and parses the USB 3.0 endpoint companion descriptor given by 428.Fa endpoint . 429Returns zero on success and a LIBUSB_ERROR code on failure. 430On success the parsed USB 3.0 endpoint companion descriptor must be 431freed using the libusb_free_ss_endpoint_companion_descriptor function. 432.Pp 433.Ft void 434.Fn libusb_free_ss_endpoint_companion_descriptor "struct libusb_ss_endpoint_companion_descriptor *ep_comp" 435This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by 436.Fa ep_comp . 437.Pp 438.Ft int 439.Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos" 440This function queries the USB device given by 441.Fa handle 442and stores a pointer to a parsed BOS descriptor into 443.Fa bos . 444Returns zero on success and a LIBUSB_ERROR code on failure. 445On success the parsed BOS descriptor must be 446freed using the libusb_free_bos_descriptor function. 447.Pp 448.Ft int 449.Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos" 450This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by 451.Fa buf 452and having a length of 453.Fa len . 454On success the pointer to resulting descriptor is stored at the location given by 455.Fa bos . 456Returns zero on success and a LIBUSB_ERROR code on failure. 457On success the parsed BOS descriptor must be freed using the 458libusb_free_bos_descriptor function. 459.Pp 460.Ft void 461.Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos" 462This function is NULL safe and frees a parsed BOS descriptor given by 463.Fa bos . 464.Pp 465.Ft int 466.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" 467This function parses the USB 2.0 extension descriptor from the descriptor given by 468.Fa dev_cap 469and stores a pointer to the parsed descriptor into 470.Fa usb_2_0_extension . 471Returns zero on success and a LIBUSB_ERROR code on failure. 472On success the parsed USB 2.0 extension descriptor must be freed using the 473libusb_free_usb_2_0_extension_descriptor function. 474.Pp 475.Ft void 476.Fn libusb_free_usb_2_0_extension_descriptor "struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension" 477This function is NULL safe and frees a parsed USB 2.0 extension descriptor given by 478.Fa usb_2_0_extension . 479.Pp 480.Ft int 481.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" 482This function parses the SuperSpeed device capability descriptor from the descriptor given by 483.Fa dev_cap 484and stores a pointer to the parsed descriptor into 485.Fa ss_usb_device_capability . 486Returns zero on success and a LIBUSB_ERROR code on failure. 487On success the parsed SuperSpeed device capability descriptor must be freed using the 488libusb_free_ss_usb_device_capability_descriptor function. 489.Pp 490.Ft void 491.Fn libusb_free_ss_usb_device_capability_descriptor "struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_capability" 492This function is NULL safe and frees a parsed SuperSpeed device capability descriptor given by 493.Fa ss_usb_device_capability . 494.Pp 495.Ft int 496.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" 497This function parses the container ID descriptor from the descriptor given by 498.Fa dev_cap 499and stores a pointer to the parsed descriptor into 500.Fa container_id . 501Returns zero on success and a LIBUSB_ERROR code on failure. 502On success the parsed container ID descriptor must be freed using the 503libusb_free_container_id_descriptor function. 504.Pp 505.Ft void 506.Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id" 507This function is NULL safe and frees a parsed container ID descriptor given by 508.Fa container_id . 509.Sh USB ASYNCHRONOUS I/O 510.Ft struct libusb_transfer * 511.Fn libusb_alloc_transfer "int iso_packets" 512Allocate a transfer with the number of isochronous packet descriptors 513specified by 514.Fa iso_packets . 515Returns NULL on error. 516.Pp 517.Ft void 518.Fn libusb_free_transfer "struct libusb_transfer *tr" 519Free a transfer. 520.Pp 521.Ft int 522.Fn libusb_submit_transfer "struct libusb_transfer *tr" 523This function will submit a transfer and returns immediately. 524Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if 525the device has been disconnected and a 526LIBUSB_ERROR code on other failure. 527.Pp 528.Ft int 529.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 530This function asynchronously cancels a transfer. 531Returns 0 on success and a LIBUSB_ERROR code on failure. 532.Sh USB SYNCHRONOUS I/O 533.Ft int 534.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" 535Perform a USB control transfer. 536Returns the actual number of bytes 537transferred on success, in the range from and including zero up to and 538including 539.Fa wLength . 540On error a LIBUSB_ERROR code is returned, for example 541LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the 542control request was not supported, LIBUSB_ERROR_NO_DEVICE if the 543device has been disconnected and another LIBUSB_ERROR code on other failures. 544The LIBUSB_ERROR codes are all negative. 545.Pp 546.Ft int 547.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 548Perform an USB bulk transfer. 549A timeout value of zero means no timeout. 550The timeout value is given in milliseconds. 551Returns 0 on success, LIBUSB_ERROR_TIMEOUT 552if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not 553supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 554LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 555a LIBUSB_ERROR code on other failure. 556.Pp 557.Ft int 558.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 559Perform an USB Interrupt transfer. 560A timeout value of zero means no timeout. 561The timeout value is given in milliseconds. 562Returns 0 on success, LIBUSB_ERROR_TIMEOUT 563if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not 564supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 565LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and 566a LIBUSB_ERROR code on other failure. 567.Sh USB STREAMS SUPPORT 568.Ft int 569.Fn libusb_alloc_streams "libusb_device_handle *dev" "uint32_t num_streams" "unsigned char *endpoints" "int num_endpoints" 570This function verifies that the given number of streams using the 571given number of endpoints is allowed and allocates the resources 572needed to use so-called USB streams. 573Currently only a single stream per endpoint is supported to simplify 574the internals of LibUSB. 575This function returns 0 on success or a LIBUSB_ERROR code on failure. 576.Pp 577.Ft int 578.Fn libusb_free_streams "libusb_device_handle *dev" "unsigned char *endpoints" "int num_endpoints" 579This function release resources needed for streams usage. 580Returns 0 on success or a LIBUSB_ERROR code on failure. 581.Pp 582.Ft void 583.Fn libusb_transfer_set_stream_id "struct libusb_transfer *transfer" "uint32_t stream_id" 584This function sets the stream ID for the given USB transfer. 585.Pp 586.Ft uint32_t 587.Fn libusb_transfer_get_stream_id "struct libusb_transfer *transfer" 588This function returns the stream ID for the given USB transfer. 589If no stream ID is used a value of zero is returned. 590.Sh USB EVENTS 591.Ft int 592.Fn libusb_try_lock_events "libusb_context *ctx" 593Try to acquire the event handling lock. 594Returns 0 if the lock was obtained and 1 if not. 595.Pp 596.Ft void 597.Fn libusb_lock_events "libusb_context *ctx" 598Acquire the event handling lock. 599This function is blocking. 600.Pp 601.Ft void 602.Fn libusb_unlock_events "libusb_context *ctx" 603Release the event handling lock. 604This will wake up any thread blocked 605on 606.Fn libusb_wait_for_event . 607.Pp 608.Ft int 609.Fn libusb_event_handling_ok "libusb_context *ctx" 610Determine if it still OK for this thread to be doing event handling. 611Returns 1 612if event handling can start or continue. 613Returns 0 if this thread must give up 614the events lock. 615.Pp 616.Ft int 617.Fn libusb_event_handler_active "libusb_context *ctx" 618Determine if an active thread is handling events. 619Returns 1 if there is a thread handling events and 0 if there 620are no threads currently handling events. 621.Pp 622.Ft void 623.Fn libusb_interrupt_event_handler "libusb_context *ctx" 624Causes the 625.Fn libusb_handle_events 626familiy of functions to return to the caller one time. 627The 628.Fn libusb_handle_events 629functions may be called again after calling this function. 630.Pp 631.Ft void 632.Fn libusb_lock_event_waiters "libusb_context *ctx" 633Acquire the event_waiters lock. 634This lock is designed to be obtained in the 635situation where you want to be aware when events are completed, but some other 636thread is event handling so calling 637.Fn libusb_handle_events 638is not allowed. 639.Pp 640.Ft void 641.Fn libusb_unlock_event_waiters "libusb_context *ctx" 642Release the event_waiters lock. 643.Pp 644.Ft int 645.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" 646Wait for another thread to signal completion of an event. 647Must be called 648with the event waiters lock held, see 649.Fn libusb_lock_event_waiters . 650This will 651block until the timeout expires or a transfer completes or a thread releases 652the event handling lock through 653.Fn libusb_unlock_events . 654Returns 0 after a 655transfer completes or another thread stops event handling, and 1 if the 656timeout expired. 657.Pp 658.Ft int 659.Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed" 660Handle any pending events by checking if timeouts have expired and by 661checking the set of file descriptors for activity. 662If the 663.Fa completed 664argument is not equal to NULL, this function will 665loop until a transfer completion callback sets the variable pointed to 666by the 667.Fa completed 668argument to non-zero. 669If the 670.Fa tv 671argument is not equal to NULL, this function will return 672LIBUSB_ERROR_TIMEOUT after the given timeout. 673Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout. 674.Pp 675.Ft int 676.Fn libusb_handle_events_completed "libusb_context *ctx" "int *completed" 677Handle any pending events by checking the set of file descriptors for activity. 678If the 679.Fa completed 680argument is not equal to NULL, this function will 681loop until a transfer completion callback sets the variable pointed to 682by the 683.Fa completed 684argument to non-zero. 685Returns 0 on success, or a LIBUSB_ERROR code on failure. 686.Pp 687.Ft int 688.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" 689Handle any pending events by checking if timeouts have expired and by 690checking the set of file descriptors for activity. 691Returns 0 on success, or a 692LIBUSB_ERROR code on failure or timeout. 693.Pp 694.Ft int 695.Fn libusb_handle_events "libusb_context *ctx" 696Handle any pending events in blocking mode with a sensible timeout. 697Returns 0 698on success and a LIBUSB_ERROR code on failure. 699.Pp 700.Ft int 701.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 702Handle any pending events by polling file descriptors, without checking if 703another thread is already doing so. 704Must be called with the event lock held. 705.Pp 706.Ft int 707.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" 708Determine the next internal timeout that libusb needs to handle. 709Returns 0 710if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR 711code on failure or timeout. 712.Pp 713.Ft void 714.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 715Register notification functions for file descriptor additions/removals. 716These functions will be invoked for every new or removed file descriptor 717that libusb uses as an event source. 718.Pp 719.Ft const struct libusb_pollfd ** 720.Fn libusb_get_pollfds "libusb_context *ctx" 721Retrieve a list of file descriptors that should be polled by your main loop as 722libusb event sources. 723Returns a NULL-terminated list on success or NULL on failure. 724.Pp 725.Ft int 726.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" 727This function registers a hotplug filter. 728The 729.Fa events 730argument select which events makes the hotplug filter trigger. 731Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. 732One or more events must be specified. 733The 734.Fa vendor_id , 735.Fa product_id 736and 737.Fa dev_class 738arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor. 739Else the specified value is used for matching. 740If the 741.Fa flags 742argument is set to LIBUSB_HOTPLUG_ENUMERATE, all currently attached and matching USB devices will be passed to the hotplug filter, given by the 743.Fa cb_fn 744argument. 745Else the 746.Fa flags 747argument should be set to LIBUSB_HOTPLUG_NO_FLAGS. 748This function returns 0 upon success or a LIBUSB_ERROR code on failure. 749.Pp 750.Ft int 751.Fn libusb_hotplug_callback_fn "libusb_context *ctx" "libusb_device *device" "libusb_hotplug_event event" "void *user_data" 752The hotplug filter function. 753If this function returns non-zero, the filter is removed. 754Else the filter is kept and can receive more events. 755The 756.Fa user_data 757argument is the same as given when the filter was registered. 758The 759.Fa event 760argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. 761.Pp 762.Ft void 763.Fn libusb_hotplug_deregister_callback "libusb_context *ctx" "libusb_hotplug_callback_handle handle" 764This function unregisters a hotplug filter. 765.Sh LIBUSB VERSION 0.1 COMPATIBILITY 766The library is also compliant with LibUSB version 0.1.12. 767.Pp 768.Fn usb_open 769.Fn usb_close 770.Fn usb_get_string 771.Fn usb_get_string_simple 772.Fn usb_get_descriptor_by_endpoint 773.Fn usb_get_descriptor 774.Fn usb_parse_descriptor 775.Fn usb_parse_configuration 776.Fn usb_destroy_configuration 777.Fn usb_fetch_and_parse_descriptors 778.Fn usb_bulk_write 779.Fn usb_bulk_read 780.Fn usb_interrupt_write 781.Fn usb_interrupt_read 782.Fn usb_control_msg 783.Fn usb_set_configuration 784.Fn usb_claim_interface 785.Fn usb_release_interface 786.Fn usb_set_altinterface 787.Fn usb_resetep 788.Fn usb_clear_halt 789.Fn usb_reset 790.Fn usb_strerror 791.Fn usb_init 792.Fn usb_set_debug 793.Fn usb_find_busses 794.Fn usb_find_devices 795.Fn usb_device 796.Fn usb_get_busses 797.Fn usb_check_connected 798.Fn usb_get_driver_np 799.Fn usb_detach_kernel_driver_np 800.Sh SEE ALSO 801.Xr libusb20 3 , 802.Xr usb 4 , 803.Xr usbconfig 8 , 804.Xr usbdump 8 805.Pp 806.Lk https://libusb.info/ 807.Sh HISTORY 808.Nm 809support first appeared in 810.Fx 8.0 . 811