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