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 November 18, 2010
  30 .Dt LIBUSB 3
  31 .Os
  32 .Sh NAME
  33 .Nm libusb
  34 .
  35 .Nd "USB access library"
  36 .
  37 .
  38 .Sh LIBRARY
  39 .
  40 .
  41 USB access library (libusb -lusb)
  42 .
  43 .
  44 .Sh SYNOPSIS
  45 .
  46 .
  47 .In libusb.h
  48 .
  49 .
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 library contains interfaces for directly managing a usb device.
  54 The current implementation supports v1.0 of the libusb API.
  55 .
  56 .
  57 .Sh LIBRARY INITIALISATION / DEINITIALISATION
  58 .
  59 .Pp
  60 .
  61 .Ft int
  62 .Fn libusb_init libusb_context **ctx
  63 This function initialises libusb. Must be called at the beginning
  64 of the program. This function returns 0 on success or LIBUSB_ERROR on
  65 failure.
  66 .
  67 .Pp
  68 .
  69 .Ft void
  70 .Fn libusb_exit "libusb_context *ctx"
  71 Deinitialise libusb. Must be called at the end of the application.
  72 .
  73 .Pp
  74 .
  75 .Ft const char *
  76 .Fn libusb_strerror "int code"
  77 Get ASCII representation of the error given by the
  78 .Fa code
  79 argument.
  80 .
  81 .
  82 .Pp
  83 .
  84 .Ft void
  85 .Fn libusb_set_debug "libusb_context *ctx" "int level"
  86 Set debug to the
  87 .Fa level
  88 level.
  89 .
  90 .Pp
  91 .
  92 .Ft ssize_t
  93 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
  94 Fill into
  95 .Fa list
  96 the list of usb device available. All the device created by this
  97 function must be unref and free when you are done with them. This
  98 function returns the number of devices in list or a LIBUSB_ERROR code.
  99 .
 100 .Pp
 101 .
 102 .Ft void
 103 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
 104 Free the list of devices discovered by libusb_get_device_list. If
 105 .Fa unref_device
 106 is set to 1 all devices are unref one time.
 107 .
 108 .Pp
 109 .
 110 .Ft uint8_t
 111 .Fn libusb_get_bus_number "libusb_device *dev"
 112 Returns the number of the bus contained by the device
 113 .Fa dev.
 114 .
 115 .Pp
 116 .
 117 .Ft uint8_t
 118 .Fn libusb_get_device_address "libusb_device *dev"
 119 Return the device_address contained by the device
 120 .Fa dev.
 121 .
 122 .Pp
 123 .
 124 .Ft int
 125 .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
 126 Return the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
 127 endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
 128 .
 129 .Pp
 130 .
 131 .Ft libusb_device *
 132 .Fn libusb_ref_device "libusb_device *dev"
 133 Increment the reference counter of the device
 134 .Fa dev.
 135 .
 136 .Pp
 137 .
 138 .Ft void
 139 .Fn libusb_unref_device "libusb_device *dev"
 140 Decrement the reference counter of the device
 141 .Fa dev.
 142 .
 143 .Pp
 144 .
 145 .Ft int
 146 .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
 147 Open a device and obtain a device_handle. Return 0 on success,
 148 LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS
 149 on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been
 150 disconnected and a LIBUSB_ERROR code on error.
 151 .
 152 .Pp
 153 .
 154 .Ft libusb_device_handle *
 155 .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
 156 Conveniance function to open a device with is
 157 .Fa vid
 158 and
 159 .Fa pid.
 160 Return NULL on error.
 161 .
 162 .Pp
 163 .
 164 .Ft void
 165 .Fn libusb_close "libusb_device_handle *devh"
 166 Close a device handle.
 167 .
 168 .Pp
 169 .
 170 .Ft libusb_device *
 171 .Fn libusb_get_device(libusb_device_handle *devh)
 172 Get the device contained by devh. Return NULL on error.
 173 .
 174 .Pp
 175 .
 176 .Ft int
 177 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
 178 Return the bConfiguration value of the current configuration. return 0
 179 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
 180 and a LIBUSB_ERROR code on error.
 181 .
 182 .Pp
 183 .
 184 .Ft int
 185 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
 186 Set the active configuration
 187 .Fa config
 188 for the device contained by
 189 .Fa devh.
 190 This function return 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
 191 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
 192 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
 193 LIBUSB_ERROR code on failure.
 194 .
 195 .Pp
 196 .
 197 .Ft int
 198 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
 199 Claim an interface in a given libusb_handle
 200 .Fa devh.
 201 This is a non-blocking function. It return 0 success, LIBUSB_ERROR_NOT_FOUND
 202 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
 203 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
 204 been disconnected and a LIBUSB_ERROR code on failure.
 205 .
 206 .Pp
 207 .
 208 .Ft int
 209 .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
 210 This function release an interface. All the claimed interface must be released
 211 before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
 212 interafce was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
 213 disconnected and LIBUSB_ERROR on failure.
 214 .
 215 .Pp
 216 .
 217 .Ft int
 218 .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
 219 Activate an alternate setting for an interface. Returns 0 on success,
 220 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
 221 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
 222 disconnected and LIBUSB_ERROR code on failure.
 223 .
 224 .Pp
 225 .
 226 .Ft int
 227 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
 228 Clear an halt/stall for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
 229 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
 230 disconnected and a LIBUSB_ERROR code on failure.
 231 .
 232 .Pp
 233 .
 234 .Ft int
 235 .Fn libusb_reset_device "libusb_device_handle *devh"
 236 Perform an USB port reset for an usb device. Returns 0 on success,
 237 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
 238 been disconnected and a LIBUSB_ERROR code on failure.
 239 .
 240 .Pp
 241 .
 242 .Ft int
 243 .Fn libusb_check_connected "libusb_device_handle *devh"
 244 Test if USB device is still connected. Returns 0 on success,
 245 LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR
 246 code on failure.
 247 .
 248 .Pp
 249 .
 250 .Ft int
 251 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
 252 Determine if a driver is active on a interface. Returns 0 if no kernel driver
 253 is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE
 254 if the device has been disconnected and return a LIBUSB_ERROR code on failure.
 255 .
 256 .Pp
 257 .
 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 Gets the name of the driver attached to the given
 264 .Fa device
 265 and
 266 .Fa interface
 267 into the buffer given by
 268 .Fa name
 269 and
 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 .
 279 .Pp
 280 .
 281 .Ft int
 282 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
 283 or
 284 .Ft int
 285 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
 286 Detach a kernel driver from an interface.
 287 This is needed to claim an interface required by a kernel driver.
 288 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
 289 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. This function is non-portable.
 290 .
 291 .Pp
 292 .
 293 .Ft int
 294 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
 295 Re-attach an interface kernel driver previously detached. Returns 0 on success,
 296 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE
 297 if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be
 298 attached because the interface is claimed by a program or driver and a
 299 LIBUSB_ERROR code on failure.
 300 .
 301 .Pp
 302 .
 303 .Sh USB DESCRIPTORS
 304 .
 305 .Pp
 306 .
 307 .Ft int
 308 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
 309 Get the USB device descriptor for the device
 310 .Fa dev.
 311 This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on
 312 failure.
 313 .
 314 .Pp
 315 .Ft int
 316 .Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
 317 Get the USB configuration descriptor for the active configuration. Returns 0 on
 318 success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state
 319 and return another LIBUSB_ERROR code on error.
 320 .
 321 .Pp
 322 .Ft int
 323 .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
 324 Get USB configuration descriptor based on its index
 325 .Fa idx.
 326 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
 327 and returns another LIBUSB_ERROR code on error.
 328 .
 329 .Pp
 330 .Ft int
 331 .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
 332 Get a USB configuration descriptor with a specific bConfigurationValue. This is
 333 a non-blocking function which does not send request through the device. Returns 0
 334 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another
 335 LIBUSB_ERROR code on failure.
 336 .
 337 .Pp
 338 .Ft void
 339 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
 340 Free a configuration descriptor.
 341 .
 342 .Pp
 343 .Ft int
 344 .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
 345 Retrieve a string descriptor in C style ascii. Returns a number of byte on success
 346 and a LIBUSB_ERROR code on failure.
 347 .
 348 .Pp
 349 .
 350 .Sh USB ASYNCHRONOUS I/O
 351 .
 352 .Pp
 353 .Ft struct libusb_transfer *
 354 .Fn libusb_alloc_transfer "int iso_packets"
 355 Allocate a transfer with
 356 .Fa iso_packets
 357 numbers of isochronous packet descriptors. Returns NULL on error.
 358 .
 359 .Pp
 360 .Ft void
 361 .Fn libusb_free_transfer "struct libusb_transfer *tr"
 362 Free a transfer.
 363 .
 364 .Pp
 365 .Ft int
 366 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
 367 This function will submit a transfer and returns immediately. Returns 0 on
 368 success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
 369 LIBUSB_ERROR code on other failure.
 370 .
 371 .Pp
 372 .Ft int
 373 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
 374 This function asynchronously cancel a transfer. Returns 0 on success and
 375 LIBUSB_ERROR code on failure.
 376 .
 377 .Pp
 378 .Sh USB SYNCHRONOUS I/O
 379 .
 380 .Pp
 381 .Ft int
 382 .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"
 383 Perform a USB control transfer. Returns the actual number of bytes
 384 transferred on success in the range from and including zero until and
 385 including
 386 .Xa wLength .
 387 On error a libusb error code is returned, for example
 388 LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the
 389 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
 390 device has been disconnected or another LIBUSB_ERROR code on other failures.
 391 The libusb error codes are always negative.
 392 .
 393 .Pp
 394 .Ft int
 395 .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
 396 Perform an USB bulk transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT
 397 if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not
 398 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
 399 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
 400 LIBUSB_ERROR code on other failure.
 401 .
 402 .Pp
 403 .Ft int
 404 .Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
 405 Perform an USB Interrupt transfer. Returns 0 on success, LIBUSB_ERROR_TIMEOUT
 406 if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not
 407 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
 408 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
 409 LIBUSB_ERROR code on other failure.
 410 .
 411 .Pp
 412 .Sh USB EVENTS
 413 .
 414 .Pp
 415 .Ft int
 416 .Fn libusb_try_lock_events "libusb_context *ctx"
 417 Try to acquire the event handling lock. Returns 0 if the lock was obtained and 1
 418 if not.
 419 .
 420 .Pp
 421 .Ft void
 422 .Fn libusb_lock_events "libusb_context *ctx"
 423 Acquire the event handling lock. This function is blocking.
 424 .
 425 .Pp
 426 .Ft void
 427 .Fn libusb_unlock_events "libusb_context *ctx"
 428 Release the event handling lock. This will wake up any thread blocked
 429 on libusb_wait_for_event().
 430 .
 431 .Pp
 432 .Ft int
 433 .Fn libusb_event_handling_ok "libusb_context *ctx"
 434 Determine if it still OK for this thread to be doing event handling. Returns 1
 435 if event handling can start or continue. Returns 0 if this thread must give up
 436 the events lock.
 437 .
 438 .Pp
 439 .Ft int
 440 .Fn libusb_event_handler_active "libusb_context *ctx"
 441 Determine if an active thread is handling events. Returns 1 if yes and 0 if there
 442 are no threads currently handling events.
 443 .
 444 .Pp
 445 .Ft void
 446 .Fn libusb_lock_event_waiters "libusb_context *ctx"
 447 Acquire the event_waiters lock. This lock is designed to be obtained under the
 448 situation where you want to be aware when events are completed, but some other
 449 thread is event handling so calling libusb_handle_events() is not allowed.
 450 .
 451 .Pp
 452 .Ft void
 453 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
 454 Release the event_waiters lock.
 455 .
 456 .Pp
 457 .Ft int
 458 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
 459 Wait for another thread to signal completion of an event. Must be called
 460 with the event waiters lock held, see libusb_lock_event_waiters(). This will
 461 block until the timeout expires or a transfer completes or a thread releases
 462 the event handling lock through libusb_unlock_events(). Returns 0 after a
 463 transfer completes or another thread stops event handling, returns 1 if the
 464 timeout expired.
 465 .
 466 .Pp
 467 .Ft int
 468 .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
 469 Handle any pending events by checking if timeouts have expired and by
 470 checking the set of file descriptors for activity. Returns 0 on success, or a
 471 LIBUSB_ERROR code on failure.
 472 .
 473 .Pp
 474 .Ft int
 475 .Fn libusb_handle_events "libusb_context *ctx"
 476 Handle any pending events in blocking mode with a sensible timeout. Returns 0
 477 on success, returns a LIBUSB_ERROR code on failure.
 478 .
 479 .Pp
 480 .Ft int
 481 .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
 482 Handle any pending events by polling file desciptors, without checking if
 483 another threads are already doing so. Must be called with the event lock held.
 484 .
 485 .Pp
 486 .Ft int
 487 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
 488 Determine the next internal timeout that libusb needs to handle. Returns 0
 489 if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR
 490 code on failure.
 491 .
 492 .Pp
 493 .Ft void
 494 .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
 495 Register notification functions for file descriptor additions/removals.
 496 These functions will be invoked for every new or removed file descriptor
 497 that libusb uses as an event source.
 498 .
 499 .Pp
 500 .Ft const struct libusb_pollfd **
 501 .Fn libusb_get_pollfds "libusb_context *ctx"
 502 Retrive a list of file descriptors that should be polled by your main loop as
 503 libusb event sources. Returns a NULL-terminated list on success or NULL on failure.
 504 .
 505 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
 506 .Pp
 507 The library is also compliant with LibUSB version 0.1.12.
 508 .Pp
 509 .Fn usb_open
 510 .Fn usb_close
 511 .Fn usb_get_string
 512 .Fn usb_get_string_simple
 513 .Fn usb_get_descriptor_by_endpoint
 514 .Fn usb_get_descriptor
 515 .Fn usb_parse_descriptor
 516 .Fn usb_parse_configuration
 517 .Fn usb_destroy_configuration
 518 .Fn usb_fetch_and_parse_descriptors
 519 .Fn usb_bulk_write
 520 .Fn usb_bulk_read
 521 .Fn usb_interrupt_write
 522 .Fn usb_interrupt_read
 523 .Fn usb_control_msg
 524 .Fn usb_set_configuration
 525 .Fn usb_claim_interface
 526 .Fn usb_release_interface
 527 .Fn usb_set_altinterface
 528 .Fn usb_resetep
 529 .Fn usb_clear_halt
 530 .Fn usb_reset
 531 .Fn usb_strerror
 532 .Fn usb_init
 533 .Fn usb_set_debug
 534 .Fn usb_find_busses
 535 .Fn usb_find_devices
 536 .Fn usb_device
 537 .Fn usb_get_busses
 538 .Fn usb_check_connected
 539 .
 540 .Sh SEE ALSO
 541 .Xr libusb20 3 ,
 542 .Xr usb 4 ,
 543 .Xr usbconfig 8
 544 .Pp
 545 .Pa http://libusb.sourceforge.net/
 546 .
 547 .Sh HISTORY
 548 .
 549 .Nm
 550 support first appeared in
 551 .Fx 8.0 .