lib/libusb/libusb.3

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