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 23, 2016
  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 const char *
  65 .Fn libusb_strerror "int code"
  66 Get the ASCII representation of the error given by the
  67 .Fa code
  68 argument.
  69 This function does not return NULL.
  70 .Pp
  71 .Ft const char *
  72 .Fn libusb_error_name "int code"
  73 Get the ASCII representation of the error enum given by the
  74 .Fa code
  75 argument.
  76 This function does not return NULL.
  77 .Pp
  78 .Ft void
  79 .Fn libusb_set_debug "libusb_context *ctx" "int level"
  80 Set 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"
  85 Populate
  86 .Fa list
  87 with the list of usb devices available, adding a reference to each
  88 device in the list.
  89 All the list entries created by this
  90 function must have their reference counter
  91 decremented when you are done with them,
  92 and the list itself must be freed.
  93 This
  94 function 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"
  98 Free the list of devices discovered by libusb_get_device_list.
  99 If
 100 .Fa unref_device
 101 is set to 1 all devices in the list have their reference
 102 counter decremented once.
 103 .Pp
 104 .Ft uint8_t
 105 .Fn libusb_get_bus_number "libusb_device *dev"
 106 Returns 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"
 111 Returns the port number which the device given by
 112 .Fa dev
 113 is attached to.
 114 .Pp
 115 .Ft int
 116 .Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
 117 Stores, in the buffer
 118 .Fa buf
 119 of size
 120 .Fa bufsize ,
 121 the 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"
 126 Deprecated function equivalent to libusb_get_port_numbers.
 127 .Pp
 128 .Ft uint8_t
 129 .Fn libusb_get_device_address "libusb_device *dev"
 130 Returns 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"
 135 Returns the wire speed at which the device is connected.
 136 See the LIBUSB_SPEED_XXX enums for more information.
 137 LIBUSB_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"
 141 Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
 142 endpoint 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"
 146 Returns the packet size multiplied by the packet multiplier on success,
 147 LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and
 148 LIBUSB_ERROR_OTHERS on other failure.
 149 .Pp
 150 .Ft libusb_device *
 151 .Fn libusb_ref_device "libusb_device *dev"
 152 Increment the reference counter of the device
 153 .Fa dev .
 154 .Pp
 155 .Ft void
 156 .Fn libusb_unref_device "libusb_device *dev"
 157 Decrement 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"
 162 Open a device and obtain a device_handle.
 163 Returns 0 on success,
 164 LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
 165 on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
 166 disconnected 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"
 170 A convenience function to open a device by vendor and product IDs
 171 .Fa vid
 172 and
 173 .Fa pid .
 174 Returns NULL on error.
 175 .Pp
 176 .Ft void
 177 .Fn libusb_close "libusb_device_handle *devh"
 178 Close a device handle.
 179 .Pp
 180 .Ft libusb_device *
 181 .Fn libusb_get_device "libusb_device_handle *devh"
 182 Get the device contained by devh.
 183 Returns NULL on error.
 184 .Pp
 185 .Ft int
 186 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
 187 Returns the value of the current configuration.
 188 Returns 0
 189 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
 190 and a LIBUSB_ERROR code on error.
 191 .Pp
 192 .Ft int
 193 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
 194 Set the active configuration to
 195 .Fa config
 196 for the device contained by
 197 .Fa devh .
 198 This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
 199 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
 200 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
 201 LIBUSB_ERROR code on failure.
 202 .Pp
 203 .Ft int
 204 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
 205 Claim an interface in a given libusb_handle
 206 .Fa devh .
 207 This is a non-blocking function.
 208 It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
 209 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
 210 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
 211 been 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"
 215 This function releases an interface.
 216 All the claimed interfaces on a device must be released
 217 before closing the device.
 218 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
 219 interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
 220 disconnected 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"
 224 Activate an alternate setting for an interface.
 225 Returns 0 on success,
 226 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
 227 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
 228 disconnected and a LIBUSB_ERROR code on failure.
 229 .Pp
 230 .Ft int
 231 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
 232 Clear an halt/stall for a endpoint.
 233 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
 234 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
 235 disconnected and a LIBUSB_ERROR code on failure.
 236 .Pp
 237 .Ft int
 238 .Fn libusb_reset_device "libusb_device_handle *devh"
 239 Perform an USB port reset for an usb device.
 240 Returns 0 on success,
 241 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
 242 been disconnected and a LIBUSB_ERROR code on failure.
 243 .Pp
 244 .Ft int
 245 .Fn libusb_check_connected "libusb_device_handle *devh"
 246 Test if the USB device is still connected.
 247 Returns 0 on success,
 248 LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
 249 code on failure.
 250 .Pp
 251 .Ft int
 252 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
 253 Determine if a driver is active on a interface.
 254 Returns 0 if no kernel driver is active
 255 and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
 256 if 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"
 260 or
 261 .Ft int
 262 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
 263 Copy the name of the driver attached to the given
 264 .Fa device
 265 and
 266 .Fa interface
 267 into the buffer
 268 .Fa name
 269 of length
 270 .Fa namelen .
 271 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
 272 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
 273 not exist.
 274 This function is non-portable.
 275 The buffer pointed to by
 276 .Fa name
 277 is only zero terminated on success.
 278 .Pp
 279 .Ft int
 280 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
 281 or
 282 .Ft int
 283 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
 284 Detach a kernel driver from an interface.
 285 This is needed to claim an interface already claimed by a kernel driver.
 286 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
 287 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
 288 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
 289 and a LIBUSB_ERROR code on failure.
 290 This function is non-portable.
 291 .Pp
 292 .Ft int
 293 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
 294 Re-attach an interface kernel driver that was previously detached.
 295 Returns 0 on success,
 296 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
 297 LIBUSB_ERROR_NO_DEVICE
 298 if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
 299 attached because the interface is claimed by a program or driver and a
 300 LIBUSB_ERROR code on failure.
 301 .Pp
 302 .Ft int
 303 .Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable"
 304 This function enables automatic kernel interface driver detach when an
 305 interface is claimed.
 306 When the interface is restored the kernel driver is allowed to be re-attached.
 307 If the
 308 .Fa enable
 309 argument is non-zero the feature is enabled.
 310 Else disabled.
 311 Returns 0 on success and a LIBUSB_ERROR code on
 312 failure.
 313 .Sh USB DESCRIPTORS
 314 .Ft int
 315 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
 316 Get the USB device descriptor for the device
 317 .Fa dev .
 318 This is a non-blocking function.
 319 Returns 0 on success and a LIBUSB_ERROR code on
 320 failure.
 321 .Pp
 322 .Ft int
 323 .Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
 324 Get the USB configuration descriptor for the active configuration.
 325 Returns 0 on
 326 success, LIBUSB_ERROR_NOT_FOUND if the device is in
 327 an unconfigured state
 328 and 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"
 332 Get a USB configuration descriptor based on its index
 333 .Fa idx.
 334 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
 335 and 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"
 339 Get a USB configuration descriptor with a specific bConfigurationValue.
 340 This is
 341 a non-blocking function which does not send a request through the device.
 342 Returns 0
 343 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
 344 does not exist and a
 345 LIBUSB_ERROR code on failure.
 346 .Pp
 347 .Ft void
 348 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
 349 Free 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"
 353 Retrieve a string descriptor in raw format.
 354 Returns the number of bytes actually transferred on success
 355 or 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"
 359 Retrieve a string descriptor in C style ASCII.
 360 Returns the positive number of bytes in the resulting ASCII string
 361 on 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"
 365 This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by
 366 .Fa buf
 367 and having a length of
 368 .Fa len .
 369 Typically these arguments are the extra and extra_length fields of the
 370 endpoint descriptor.
 371 On success the pointer to resulting descriptor is stored at the location given by
 372 .Fa ep_comp .
 373 Returns zero on success and a LIBUSB_ERROR code on failure.
 374 On success the parsed USB 3.0 endpoint companion descriptor must be
 375 freed 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"
 379 This 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"
 384 This function finds and parses the USB 3.0 endpoint companion descriptor given by
 385 .Fa endpoint .
 386 Returns zero on success and a LIBUSB_ERROR code on failure.
 387 On success the parsed USB 3.0 endpoint companion descriptor must be
 388 freed 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"
 392 This 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"
 397 This function queries the USB device given by
 398 .Fa handle
 399 and stores a pointer to a parsed BOS descriptor into
 400 .Fa bos .
 401 Returns zero on success and a LIBUSB_ERROR code on failure.
 402 On success the parsed BOS descriptor must be
 403 freed 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"
 407 This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by
 408 .Fa buf
 409 and having a length of
 410 .Fa len .
 411 On success the pointer to resulting descriptor is stored at the location given by
 412 .Fa bos .
 413 Returns zero on success and a LIBUSB_ERROR code on failure.
 414 On success the parsed BOS descriptor must be freed using the
 415 libusb_free_bos_descriptor function.
 416 .Pp
 417 .Ft void
 418 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
 419 This 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"
 424 This function parses the USB 2.0 extension descriptor from the descriptor given by
 425 .Fa dev_cap
 426 and stores a pointer to the parsed descriptor into
 427 .Fa usb_2_0_extension .
 428 Returns zero on success and a LIBUSB_ERROR code on failure.
 429 On success the parsed USB 2.0 extension descriptor must be freed using the
 430 libusb_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"
 434 This 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"
 439 This function parses the SuperSpeed device capability descriptor from the descriptor given by
 440 .Fa dev_cap
 441 and stores a pointer to the parsed descriptor into
 442 .Fa ss_usb_device_capability .
 443 Returns zero on success and a LIBUSB_ERROR code on failure.
 444 On success the parsed SuperSpeed device capability descriptor must be freed using the
 445 libusb_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"
 449 This 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"
 454 This function parses the container ID descriptor from the descriptor given by
 455 .Fa dev_cap
 456 and stores a pointer to the parsed descriptor into
 457 .Fa container_id .
 458 Returns zero on success and a LIBUSB_ERROR code on failure.
 459 On success the parsed container ID descriptor must be freed using the
 460 libusb_free_container_id_descriptor function.
 461 .Pp
 462 .Ft void
 463 .Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id"
 464 This 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"
 469 Allocate a transfer with the number of isochronous packet descriptors
 470 specified by
 471 .Fa iso_packets .
 472 Returns NULL on error.
 473 .Pp
 474 .Ft void
 475 .Fn libusb_free_transfer "struct libusb_transfer *tr"
 476 Free a transfer.
 477 .Pp
 478 .Ft int
 479 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
 480 This function will submit a transfer and returns immediately.
 481 Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
 482 the device has been disconnected and a
 483 LIBUSB_ERROR code on other failure.
 484 .Pp
 485 .Ft int
 486 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
 487 This function asynchronously cancels a transfer.
 488 Returns 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"
 492 Perform a USB control transfer.
 493 Returns the actual number of bytes
 494 transferred on success, in the range from and including zero up to and
 495 including
 496 .Fa wLength .
 497 On error a LIBUSB_ERROR code is returned, for example
 498 LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
 499 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
 500 device has been disconnected and another LIBUSB_ERROR code on other failures.
 501 The 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"
 505 Perform an USB bulk transfer.
 506 A timeout value of zero means no timeout.
 507 The timeout value is given in milliseconds.
 508 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
 509 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
 510 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
 511 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
 512 a 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"
 516 Perform an USB Interrupt transfer.
 517 A timeout value of zero means no timeout.
 518 The timeout value is given in milliseconds.
 519 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
 520 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
 521 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
 522 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
 523 a 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"
 527 This function verifies that the given number of streams using the
 528 given number of endpoints is allowed and allocates the resources
 529 needed to use so-called USB streams.
 530 Currently only a single stream per endpoint is supported to simplify
 531 the internals of LibUSB.
 532 This 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"
 536 This function release resources needed for streams usage.
 537 Returns 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"
 541 This 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"
 545 This function returns the stream ID for the given USB transfer.
 546 If 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"
 550 Try to acquire the event handling lock.
 551 Returns 0 if the lock was obtained and 1 if not.
 552 .Pp
 553 .Ft void
 554 .Fn libusb_lock_events "libusb_context *ctx"
 555 Acquire the event handling lock.
 556 This function is blocking.
 557 .Pp
 558 .Ft void
 559 .Fn libusb_unlock_events "libusb_context *ctx"
 560 Release the event handling lock.
 561 This will wake up any thread blocked
 562 on
 563 .Fn libusb_wait_for_event .
 564 .Pp
 565 .Ft int
 566 .Fn libusb_event_handling_ok "libusb_context *ctx"
 567 Determine if it still OK for this thread to be doing event handling.
 568 Returns 1
 569 if event handling can start or continue.
 570 Returns 0 if this thread must give up
 571 the events lock.
 572 .Pp
 573 .Ft int
 574 .Fn libusb_event_handler_active "libusb_context *ctx"
 575 Determine if an active thread is handling events.
 576 Returns 1 if there is a thread handling events and 0 if there
 577 are no threads currently handling events.
 578 .Pp
 579 .Ft void
 580 .Fn libusb_lock_event_waiters "libusb_context *ctx"
 581 Acquire the event_waiters lock.
 582 This lock is designed to be obtained in the
 583 situation where you want to be aware when events are completed, but some other
 584 thread 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"
 588 Release the event_waiters lock.
 589 .Pp
 590 .Ft int
 591 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
 592 Wait for another thread to signal completion of an event.
 593 Must be called
 594 with the event waiters lock held, see libusb_lock_event_waiters().
 595 This will
 596 block until the timeout expires or a transfer completes or a thread releases
 597 the event handling lock through libusb_unlock_events().
 598 Returns 0 after a
 599 transfer completes or another thread stops event handling, and 1 if the
 600 timeout expired.
 601 .Pp
 602 .Ft int
 603 .Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed"
 604 Handle any pending events by checking if timeouts have expired and by
 605 checking the set of file descriptors for activity.
 606 If the
 607 .Fa completed
 608 argument is not equal to NULL, this function will
 609 loop until a transfer completion callback sets the variable pointed to
 610 by the
 611 .Fa completed
 612 argument to non-zero.
 613 If the
 614 .Fa tv
 615 argument is not equal to NULL, this function will return
 616 LIBUSB_ERROR_TIMEOUT after the given timeout.
 617 Returns 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"
 621 Handle any pending events by checking the set of file descriptors for activity.
 622 If the
 623 .Fa completed
 624 argument is not equal to NULL, this function will
 625 loop until a transfer completion callback sets the variable pointed to
 626 by the
 627 .Fa completed
 628 argument to non-zero.
 629 Returns 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"
 633 Handle any pending events by checking if timeouts have expired and by
 634 checking the set of file descriptors for activity.
 635 Returns 0 on success, or a
 636 LIBUSB_ERROR code on failure or timeout.
 637 .Pp
 638 .Ft int
 639 .Fn libusb_handle_events "libusb_context *ctx"
 640 Handle any pending events in blocking mode with a sensible timeout.
 641 Returns 0
 642 on 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"
 646 Handle any pending events by polling file descriptors, without checking if
 647 another thread is already doing so.
 648 Must be called with the event lock held.
 649 .Pp
 650 .Ft int
 651 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
 652 Determine the next internal timeout that libusb needs to handle.
 653 Returns 0
 654 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
 655 code 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"
 659 Register notification functions for file descriptor additions/removals.
 660 These functions will be invoked for every new or removed file descriptor
 661 that libusb uses as an event source.
 662 .Pp
 663 .Ft const struct libusb_pollfd **
 664 .Fn libusb_get_pollfds "libusb_context *ctx"
 665 Retrive a list of file descriptors that should be polled by your main loop as
 666 libusb event sources.
 667 Returns 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"
 671 This function registers a hotplug filter.
 672 The
 673 .Fa events
 674 argument select which events makes the hotplug filter trigger.
 675 Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
 676 One or more events must be specified.
 677 The
 678 .Fa vendor_id ,
 679 .Fa product_id
 680 and
 681 .Fa dev_class
 682 arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor.
 683 Else the specified value is used for matching.
 684 If the
 685 .Fa flags
 686 argument 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
 688 argument.
 689 Else the
 690 .Fa flags
 691 argument should be set to LIBUSB_HOTPLUG_NO_FLAGS.
 692 This 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"
 696 The hotplug filter function.
 697 If this function returns non-zero, the filter is removed.
 698 Else the filter is kept and can receive more events.
 699 The
 700 .Fa user_data
 701 argument is the same as given when the filter was registered.
 702 The
 703 .Fa event
 704 argument 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"
 708 This function unregisters a hotplug filter.
 709 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
 710 The 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
 753 support first appeared in
 754 .Fx 8.0 .