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