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