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