2 .\" Copyright (c) 2009 Sylvestre Gallon
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .Nd "USB access library"
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
47 .Fn libusb_init libusb_context **ctx
48 This function initialises libusb.
49 It must be called at the beginning
50 of the program, before other libusb routines are used.
51 This function returns 0 on success or LIBUSB_ERROR on
55 .Fn libusb_exit "libusb_context *ctx"
57 Must be called at the end of the application.
58 Other libusb routines may not be called after this function.
61 .Fn libusb_strerror "int code"
62 Get the ASCII representation of the error given by the
65 This function does not return NULL.
68 .Fn libusb_error_name "int code"
69 Get the ASCII representation of the error enum given by the
72 This function does not return NULL.
75 .Fn libusb_set_debug "libusb_context *ctx" "int level"
76 Set the debug level to
80 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
83 with the list of usb devices available, adding a reference to each
85 All the list entries created by this
86 function must have their reference counter
87 decremented when you are done with them,
88 and the list itself must be freed.
90 function returns the number of devices in the list or a LIBUSB_ERROR code.
93 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
94 Free the list of devices discovered by libusb_get_device_list.
97 is set to 1 all devices in the list have their reference
98 counter decremented once.
101 .Fn libusb_get_bus_number "libusb_device *dev"
102 Returns the number of the bus contained by the device
106 .Fn libusb_get_device_address "libusb_device *dev"
107 Returns the device_address contained by the device
110 .Ft enum libusb_speed
111 .Fn libusb_get_device_speed "libusb_device *dev"
112 Returns the wire speed at which the device is connected.
113 See the LIBUSB_SPEED_XXX enums for more information.
114 LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
117 .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
118 Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
119 endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
122 .Fn libusb_get_max_iso_packet_size "libusb_device *dev" "unsigned char endpoint"
123 Returns the packet size multiplied by the packet multiplier on success,
124 LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and
125 LIBUSB_ERROR_OTHERS on other failure.
128 .Fn libusb_ref_device "libusb_device *dev"
129 Increment the reference counter of the device
133 .Fn libusb_unref_device "libusb_device *dev"
134 Decrement the reference counter of the device
138 .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
139 Open a device and obtain a device_handle.
140 Returns 0 on success,
141 LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
142 on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
143 disconnected and a LIBUSB_ERROR code on other errors.
145 .Ft libusb_device_handle *
146 .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
147 A convenience function to open a device by vendor and product IDs
151 Returns NULL on error.
154 .Fn libusb_close "libusb_device_handle *devh"
155 Close a device handle.
158 .Fn libusb_get_device "libusb_device_handle *devh"
159 Get the device contained by devh.
160 Returns NULL on error.
163 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
164 Returns the value of the current configuration.
166 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
167 and a LIBUSB_ERROR code on error.
170 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
171 Set the active configuration to
173 for the device contained by
175 This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
176 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
177 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
178 LIBUSB_ERROR code on failure.
181 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
182 Claim an interface in a given libusb_handle
184 This is a non-blocking function.
185 It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
186 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
187 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
188 been disconnected and a LIBUSB_ERROR code on failure.
191 .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
192 This function releases an interface.
193 All the claimed interfaces on a device must be released
194 before closing the device.
195 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
196 interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
197 disconnected and LIBUSB_ERROR on failure.
200 .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
201 Activate an alternate setting for an interface.
202 Returns 0 on success,
203 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
204 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
205 disconnected and a LIBUSB_ERROR code on failure.
208 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
209 Clear an halt/stall for a endpoint.
210 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
211 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
212 disconnected and a LIBUSB_ERROR code on failure.
215 .Fn libusb_reset_device "libusb_device_handle *devh"
216 Perform an USB port reset for an usb device.
217 Returns 0 on success,
218 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
219 been disconnected and a LIBUSB_ERROR code on failure.
222 .Fn libusb_check_connected "libusb_device_handle *devh"
223 Test if the USB device is still connected.
224 Returns 0 on success,
225 LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
229 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
230 Determine if a driver is active on a interface.
231 Returns 0 if no kernel driver is active
232 and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
233 if the device has been disconnected and a LIBUSB_ERROR code on failure.
236 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
239 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
240 Copy the name of the driver attached to the given
248 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
249 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
251 This function is non-portable.
252 The buffer pointed to by
254 is only zero terminated on success.
257 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
260 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
261 Detach a kernel driver from an interface.
262 This is needed to claim an interface already claimed by a kernel driver.
263 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
264 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
265 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
266 and a LIBUSB_ERROR code on failure.
267 This function is non-portable.
270 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
271 Re-attach an interface kernel driver that was previously detached.
272 Returns 0 on success,
273 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
274 LIBUSB_ERROR_NO_DEVICE
275 if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
276 attached because the interface is claimed by a program or driver and a
277 LIBUSB_ERROR code on failure.
280 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
281 Get the USB device descriptor for the device
283 This is a non-blocking function.
284 Returns 0 on success and a LIBUSB_ERROR code on
288 .Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
289 Get the USB configuration descriptor for the active configuration.
291 success, LIBUSB_ERROR_NOT_FOUND if the device is in
292 an unconfigured state
293 and a LIBUSB_ERROR code on error.
296 .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
297 Get a USB configuration descriptor based on its index
299 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
300 and a LIBUSB_ERROR code on error.
303 .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
304 Get a USB configuration descriptor with a specific bConfigurationValue.
306 a non-blocking function which does not send a request through the device.
308 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
310 LIBUSB_ERROR code on failure.
313 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
314 Free a configuration descriptor.
317 .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
318 Retrieve a string descriptor in C style ASCII.
319 Returns the positive number of bytes in the resulting ASCII string
320 on success and a LIBUSB_ERROR code on failure.
323 .Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp"
324 This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by
326 and having a length of
328 Typically these arguments are the extra and extra_length fields of the
330 On success the pointer to resulting descriptor is stored at the location given by
332 Returns zero on success and a LIBUSB_ERROR code on failure.
333 On success the parsed USB 3.0 endpoint companion descriptor must be
334 freed using the libusb_free_ss_endpoint_comp function.
337 .Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp"
338 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor.
341 .Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos"
342 This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by
344 and having a length of
346 On success the pointer to resulting descriptor is stored at the location given by
348 Returns zero on success and a LIBUSB_ERROR code on failure.
349 On success the parsed BOS descriptor must be freed using the
350 libusb_free_bos_descriptor function.
353 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
354 This function is NULL safe and frees a parsed BOS descriptor.
355 .Sh USB ASYNCHRONOUS I/O
356 .Ft struct libusb_transfer *
357 .Fn libusb_alloc_transfer "int iso_packets"
358 Allocate a transfer with the number of isochronous packet descriptors
361 Returns NULL on error.
364 .Fn libusb_free_transfer "struct libusb_transfer *tr"
368 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
369 This function will submit a transfer and returns immediately.
370 Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
371 the device has been disconnected and a
372 LIBUSB_ERROR code on other failure.
375 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
376 This function asynchronously cancels a transfer.
377 Returns 0 on success and a LIBUSB_ERROR code on failure.
378 .Sh USB SYNCHRONOUS I/O
380 .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"
381 Perform a USB control transfer.
382 Returns the actual number of bytes
383 transferred on success, in the range from and including zero up to and
386 On error a LIBUSB_ERROR code is returned, for example
387 LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
388 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
389 device has been disconnected and another LIBUSB_ERROR code on other failures.
390 The LIBUSB_ERROR codes are all negative.
393 .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
394 Perform an USB bulk transfer.
395 A timeout value of zero means no timeout.
396 The timeout value is given in milliseconds.
397 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
398 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
399 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
400 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
401 a LIBUSB_ERROR code on other failure.
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.
406 A timeout value of zero means no timeout.
407 The timeout value is given in milliseconds.
408 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
409 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
410 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
411 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
412 a LIBUSB_ERROR code on other failure.
415 .Fn libusb_try_lock_events "libusb_context *ctx"
416 Try to acquire the event handling lock.
417 Returns 0 if the lock was obtained and 1 if not.
420 .Fn libusb_lock_events "libusb_context *ctx"
421 Acquire the event handling lock.
422 This function is blocking.
425 .Fn libusb_unlock_events "libusb_context *ctx"
426 Release the event handling lock.
427 This will wake up any thread blocked
429 .Fn libusb_wait_for_event .
432 .Fn libusb_event_handling_ok "libusb_context *ctx"
433 Determine if it still OK for this thread to be doing event handling.
435 if event handling can start or continue.
436 Returns 0 if this thread must give up
440 .Fn libusb_event_handler_active "libusb_context *ctx"
441 Determine if an active thread is handling events.
442 Returns 1 if there is a thread handling events and 0 if there
443 are no threads currently handling events.
446 .Fn libusb_lock_event_waiters "libusb_context *ctx"
447 Acquire the event_waiters lock.
448 This lock is designed to be obtained in the
449 situation where you want to be aware when events are completed, but some other
450 thread is event handling so calling libusb_handle_events() is not allowed.
453 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
454 Release the event_waiters lock.
457 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
458 Wait for another thread to signal completion of an event.
460 with the event waiters lock held, see libusb_lock_event_waiters().
462 block until the timeout expires or a transfer completes or a thread releases
463 the event handling lock through libusb_unlock_events().
465 transfer completes or another thread stops event handling, and 1 if the
469 .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
470 Handle any pending events by checking if timeouts have expired and by
471 checking the set of file descriptors for activity.
472 Returns 0 on success, or a
473 LIBUSB_ERROR code on failure.
476 .Fn libusb_handle_events "libusb_context *ctx"
477 Handle any pending events in blocking mode with a sensible timeout.
479 on success and a LIBUSB_ERROR code on failure.
482 .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
483 Handle any pending events by polling file descriptors, without checking if
484 another thread is already doing so.
485 Must be called with the event lock held.
488 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
489 Determine the next internal timeout that libusb needs to handle.
491 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
495 .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
496 Register notification functions for file descriptor additions/removals.
497 These functions will be invoked for every new or removed file descriptor
498 that libusb uses as an event source.
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.
504 Returns a NULL-terminated list on success or NULL on failure.
505 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
506 The library is also compliant with LibUSB version 0.1.12.
511 .Fn usb_get_string_simple
512 .Fn usb_get_descriptor_by_endpoint
513 .Fn usb_get_descriptor
514 .Fn usb_parse_descriptor
515 .Fn usb_parse_configuration
516 .Fn usb_destroy_configuration
517 .Fn usb_fetch_and_parse_descriptors
520 .Fn usb_interrupt_write
521 .Fn usb_interrupt_read
523 .Fn usb_set_configuration
524 .Fn usb_claim_interface
525 .Fn usb_release_interface
526 .Fn usb_set_altinterface
537 .Fn usb_check_connected
538 .Fn usb_get_driver_np
539 .Fn usb_detach_kernel_driver_np
546 .Pa http://libusb.sourceforge.net/
549 support first appeared in