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