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