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