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