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