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