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