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
48 .Fn libusb_init libusb_context **ctx
49 This function initialises libusb.
50 It must be called at the beginning
51 of the program, before other libusb routines are used.
52 This function returns 0 on success or LIBUSB_ERROR on
56 .Fn libusb_exit "libusb_context *ctx"
58 Must be called at the end of the application.
59 Other libusb routines may not be called after this function.
62 .Fn libusb_strerror "int code"
63 Get the ASCII representation of the error given by the
66 This function does not return NULL.
69 .Fn libusb_error_name "int code"
70 Get the ASCII representation of the error enum given by the
73 This function does not return NULL.
76 .Fn libusb_set_debug "libusb_context *ctx" "int level"
77 Set the debug level to
81 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
84 with the list of usb devices available, adding a reference to each
86 All the list entries created by this
87 function must have their reference counter
88 decremented when you are done with them,
89 and the list itself must be freed.
91 function returns the number of devices in the list or a LIBUSB_ERROR code.
94 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
95 Free the list of devices discovered by libusb_get_device_list.
98 is set to 1 all devices in the list have their reference
99 counter decremented once.
102 .Fn libusb_get_bus_number "libusb_device *dev"
103 Returns the number of the bus contained by the device
107 .Fn libusb_get_device_address "libusb_device *dev"
108 Returns the device_address contained by the device
111 .Ft enum libusb_speed
112 .Fn libusb_get_device_speed "libusb_device *dev"
113 Returns the wire speed at which the device is connected.
114 See the LIBUSB_SPEED_XXX enums for more information.
115 LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
118 .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
119 Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
120 endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
123 .Fn libusb_ref_device "libusb_device *dev"
124 Increment the reference counter of the device
128 .Fn libusb_unref_device "libusb_device *dev"
129 Decrement the reference counter of the device
133 .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
134 Open a device and obtain a device_handle.
135 Returns 0 on success,
136 LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
137 on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
138 disconnected and a LIBUSB_ERROR code on other errors.
140 .Ft libusb_device_handle *
141 .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
142 A convenience function to open a device by vendor and product IDs
146 Returns NULL on error.
149 .Fn libusb_close "libusb_device_handle *devh"
150 Close a device handle.
153 .Fn libusb_get_device "libusb_device_handle *devh"
154 Get the device contained by devh.
155 Returns NULL on error.
158 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
159 Returns the bConfiguration value of the current configuration.
161 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
162 and a LIBUSB_ERROR code on error.
165 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
166 Set the active configuration to
168 for the device contained by
170 This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
171 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
172 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
173 LIBUSB_ERROR code on failure.
176 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
177 Claim an interface in a given libusb_handle
179 This is a non-blocking function.
180 It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
181 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
182 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
183 been disconnected and a LIBUSB_ERROR code on failure.
186 .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
187 This function releases an interface.
188 All the claimed interfaces on a device must be released
189 before closing the device.
190 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
191 interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
192 disconnected and LIBUSB_ERROR on failure.
195 .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
196 Activate an alternate setting for an interface.
197 Returns 0 on success,
198 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
199 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
200 disconnected and a LIBUSB_ERROR code on failure.
203 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
204 Clear an halt/stall for a endpoint.
205 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
206 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
207 disconnected and a LIBUSB_ERROR code on failure.
210 .Fn libusb_reset_device "libusb_device_handle *devh"
211 Perform an USB port reset for an usb device.
212 Returns 0 on success,
213 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
214 been disconnected and a LIBUSB_ERROR code on failure.
217 .Fn libusb_check_connected "libusb_device_handle *devh"
218 Test if the USB device is still connected.
219 Returns 0 on success,
220 LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
224 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
225 Determine if a driver is active on a interface.
226 Returns 0 if no kernel driver is active
227 and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
228 if the device has been disconnected and a LIBUSB_ERROR code on failure.
231 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
234 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
235 Copy the name of the driver attached to the given
243 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
244 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
246 This function is non-portable.
247 The buffer pointed to by
249 is only zero terminated on success.
252 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
255 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
256 Detach a kernel driver from an interface.
257 This is needed to claim an interface already claimed by a kernel driver.
258 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
259 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
260 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
261 and a LIBUSB_ERROR code on failure.
262 This function is non-portable.
265 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
266 Re-attach an interface kernel driver that was previously detached.
267 Returns 0 on success,
268 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
269 LIBUSB_ERROR_NO_DEVICE
270 if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
271 attached because the interface is claimed by a program or driver and a
272 LIBUSB_ERROR code on failure.
277 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
278 Get the USB device descriptor for the device
280 This is a non-blocking function.
281 Returns 0 on success and a LIBUSB_ERROR code on
285 .Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
286 Get the USB configuration descriptor for the active configuration.
288 success, LIBUSB_ERROR_NOT_FOUND if the device is in
289 an unconfigured state
290 and a LIBUSB_ERROR code on error.
293 .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
294 Get a USB configuration descriptor based on its index
296 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
297 and a LIBUSB_ERROR code on error.
300 .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
301 Get a USB configuration descriptor with a specific bConfigurationValue.
303 a non-blocking function which does not send a request through the device.
305 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
307 LIBUSB_ERROR code on failure.
310 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
311 Free a configuration descriptor.
314 .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
315 Retrieve a string descriptor in C style ASCII.
316 Returns the positive number of bytes in the resulting ASCII string
317 on success and a LIBUSB_ERROR code on failure.
320 .Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp"
321 This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by
323 and having a length of
325 Typically these arguments are the extra and extra_length fields of the
327 On success the pointer to resulting descriptor is stored at the location given by
329 Returns zero on success and a LIBUSB_ERROR code on failure.
330 On success the parsed USB 3.0 endpoint companion descriptor must be
331 freed using the libusb_free_ss_endpoint_comp function.
334 .Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp"
335 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor.
338 .Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos"
339 This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by
341 and having a length of
343 On success the pointer to resulting descriptor is stored at the location given by
345 Returns zero on success and a LIBUSB_ERROR code on failure.
346 On success the parsed BOS descriptor must be freed using the
347 libusb_free_bos_descriptor function.
350 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
351 This function is NULL safe and frees a parsed BOS descriptor.
353 .Sh USB ASYNCHRONOUS I/O
355 .Ft struct libusb_transfer *
356 .Fn libusb_alloc_transfer "int iso_packets"
357 Allocate a transfer with the number of isochronous packet descriptors
360 Returns NULL on error.
363 .Fn libusb_free_transfer "struct libusb_transfer *tr"
367 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
368 This function will submit a transfer and returns immediately.
369 Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
370 the device has been disconnected and a
371 LIBUSB_ERROR code on other failure.
374 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
375 This function asynchronously cancels a transfer.
376 Returns 0 on success and a LIBUSB_ERROR code on failure.
378 .Sh USB SYNCHRONOUS I/O
381 .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"
382 Perform a USB control transfer.
383 Returns the actual number of bytes
384 transferred on success, in the range from and including zero up to and
387 On error a LIBUSB_ERROR code is returned, for example
388 LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
389 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
390 device has been disconnected and another LIBUSB_ERROR code on other failures.
391 The LIBUSB_ERROR codes are all negative.
394 .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
395 Perform an USB bulk transfer.
396 A timeout value of zero means no timeout.
397 The timeout value is given in milliseconds.
398 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
399 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
400 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
401 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
402 a LIBUSB_ERROR code on other failure.
405 .Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
406 Perform an USB Interrupt transfer.
407 A timeout value of zero means no timeout.
408 The timeout value is given in milliseconds.
409 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
410 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
411 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
412 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
413 a LIBUSB_ERROR code on other failure.
418 .Fn libusb_try_lock_events "libusb_context *ctx"
419 Try to acquire the event handling lock.
420 Returns 0 if the lock was obtained and 1 if not.
423 .Fn libusb_lock_events "libusb_context *ctx"
424 Acquire the event handling lock.
425 This function is blocking.
428 .Fn libusb_unlock_events "libusb_context *ctx"
429 Release the event handling lock.
430 This will wake up any thread blocked
432 .B libusb_wait_for_event() .
435 .Fn libusb_event_handling_ok "libusb_context *ctx"
436 Determine if it still OK for this thread to be doing event handling.
438 if event handling can start or continue.
439 Returns 0 if this thread must give up
443 .Fn libusb_event_handler_active "libusb_context *ctx"
444 Determine if an active thread is handling events.
445 Returns 1 if there is a thread handling events and 0 if there
446 are no threads currently handling events.
449 .Fn libusb_lock_event_waiters "libusb_context *ctx"
450 Acquire the event_waiters lock.
451 This lock is designed to be obtained in the
452 situation where you want to be aware when events are completed, but some other
453 thread is event handling so calling libusb_handle_events() is not allowed.
456 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
457 Release the event_waiters lock.
460 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
461 Wait for another thread to signal completion of an event.
463 with the event waiters lock held, see libusb_lock_event_waiters().
465 block until the timeout expires or a transfer completes or a thread releases
466 the event handling lock through libusb_unlock_events().
468 transfer completes or another thread stops event handling, and 1 if the
472 .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
473 Handle any pending events by checking if timeouts have expired and by
474 checking the set of file descriptors for activity.
475 Returns 0 on success, or a
476 LIBUSB_ERROR code on failure.
479 .Fn libusb_handle_events "libusb_context *ctx"
480 Handle any pending events in blocking mode with a sensible timeout.
482 on success and a LIBUSB_ERROR code on failure.
485 .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
486 Handle any pending events by polling file desciptors, without checking if
487 another thread is already doing so.
488 Must be called with the event lock held.
491 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
492 Determine the next internal timeout that libusb needs to handle.
494 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
498 .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
499 Register notification functions for file descriptor additions/removals.
500 These functions will be invoked for every new or removed file descriptor
501 that libusb uses as an event source.
503 .Ft const struct libusb_pollfd **
504 .Fn libusb_get_pollfds "libusb_context *ctx"
505 Retrive a list of file descriptors that should be polled by your main loop as
506 libusb event sources.
507 Returns a NULL-terminated list on success or NULL on failure.
508 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
510 The library is also compliant with LibUSB version 0.1.12.
515 .Fn usb_get_string_simple
516 .Fn usb_get_descriptor_by_endpoint
517 .Fn usb_get_descriptor
518 .Fn usb_parse_descriptor
519 .Fn usb_parse_configuration
520 .Fn usb_destroy_configuration
521 .Fn usb_fetch_and_parse_descriptors
524 .Fn usb_interrupt_write
525 .Fn usb_interrupt_read
527 .Fn usb_set_configuration
528 .Fn usb_claim_interface
529 .Fn usb_release_interface
530 .Fn usb_set_altinterface
541 .Fn usb_check_connected
542 .Fn usb_get_driver_np
543 .Fn usb_detach_kernel_driver_np
550 .Pa http://libusb.sourceforge.net/
553 support first appeared in