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