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 AND DEINITIALISATION
46 .Ft "const struct libusb_version *"
47 .Fn libusb_get_version "void"
48 This function returns version information about LibUSB.
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
59 .Fn libusb_exit "libusb_context *ctx"
61 Must be called at the end of the application.
62 Other libusb routines may not be called after this function.
65 .Fn libusb_strerror "int code"
66 Get the ASCII representation of the error given by the
69 This function does not return NULL.
72 .Fn libusb_error_name "int code"
73 Get the ASCII representation of the error enum given by the
76 This function does not return NULL.
79 .Fn libusb_set_debug "libusb_context *ctx" "int level"
80 Set the debug level to
84 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
87 with the list of usb devices available, adding a reference to each
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.
94 function returns the number of devices in the list or a LIBUSB_ERROR code.
97 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
98 Free the list of devices discovered by libusb_get_device_list.
101 is set to 1 all devices in the list have their reference
102 counter decremented once.
105 .Fn libusb_get_bus_number "libusb_device *dev"
106 Returns the number of the bus contained by the device
110 .Fn libusb_get_port_number "libusb_device *dev"
111 Returns the port number which the device given by
116 .Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
117 Stores, in the buffer
121 the list of all port numbers from root for the device
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.
129 .Fn libusb_get_device_address "libusb_device *dev"
130 Returns the device_address contained by the device
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.
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.
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.
151 .Fn libusb_ref_device "libusb_device *dev"
152 Increment the reference counter of the device
156 .Fn libusb_unref_device "libusb_device *dev"
157 Decrement the reference counter of the device
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.
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
174 Returns NULL on error.
177 .Fn libusb_close "libusb_device_handle *devh"
178 Close a device handle.
181 .Fn libusb_get_device "libusb_device_handle *devh"
182 Get the device contained by devh.
183 Returns NULL on error.
186 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
187 Returns the value of the current configuration.
189 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
190 and a LIBUSB_ERROR code on error.
193 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
194 Set the active configuration to
196 for the device contained by
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.
204 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
205 Claim an interface in a given libusb_handle
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.
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.
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.
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.
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.
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
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.
259 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
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
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
274 This function is non-portable.
275 The buffer pointed to by
277 is only zero terminated on success.
280 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
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.
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.
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.
309 argument is non-zero the feature is enabled.
311 Returns 0 on success and a LIBUSB_ERROR code on
315 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
316 Get the USB device descriptor for the device
318 This is a non-blocking function.
319 Returns 0 on success and a LIBUSB_ERROR code on
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.
326 success, LIBUSB_ERROR_NOT_FOUND if the device is in
327 an unconfigured state
328 and a LIBUSB_ERROR code on error.
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
334 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
335 and a LIBUSB_ERROR code on error.
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.
341 a non-blocking function which does not send a request through the device.
343 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
345 LIBUSB_ERROR code on failure.
348 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
349 Free a configuration descriptor.
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.
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.
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
367 and having a length of
369 Typically these arguments are the extra and extra_length fields of the
371 On success the pointer to resulting descriptor is stored at the location given by
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.
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
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
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.
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
396 .Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos"
397 This function queries the USB device given by
399 and stores a pointer to a parsed BOS descriptor into
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.
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
409 and having a length of
411 On success the pointer to resulting descriptor is stored at the location given by
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.
418 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
419 This function is NULL safe and frees a parsed BOS descriptor given by
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
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.
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 .
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
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.
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 .
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
456 and stores a pointer to the parsed descriptor into
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.
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
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
472 Returns NULL on error.
475 .Fn libusb_free_transfer "struct libusb_transfer *tr"
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.
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
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
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.
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.
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
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.
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.
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.
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.
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.
554 .Fn libusb_lock_events "libusb_context *ctx"
555 Acquire the event handling lock.
556 This function is blocking.
559 .Fn libusb_unlock_events "libusb_context *ctx"
560 Release the event handling lock.
561 This will wake up any thread blocked
563 .Fn libusb_wait_for_event .
566 .Fn libusb_event_handling_ok "libusb_context *ctx"
567 Determine if it still OK for this thread to be doing event handling.
569 if event handling can start or continue.
570 Returns 0 if this thread must give up
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.
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.
587 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
588 Release the event_waiters lock.
591 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
592 Wait for another thread to signal completion of an event.
594 with the event waiters lock held, see libusb_lock_event_waiters().
596 block until the timeout expires or a transfer completes or a thread releases
597 the event handling lock through libusb_unlock_events().
599 transfer completes or another thread stops event handling, and 1 if the
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.
608 argument is not equal to NULL, this function will
609 loop until a transfer completion callback sets the variable pointed to
612 argument to non-zero.
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.
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.
624 argument is not equal to NULL, this function will
625 loop until a transfer completion callback sets the variable pointed to
628 argument to non-zero.
629 Returns 0 on success, or a LIBUSB_ERROR code on failure.
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.
639 .Fn libusb_handle_events "libusb_context *ctx"
640 Handle any pending events in blocking mode with a sensible timeout.
642 on success and a LIBUSB_ERROR code on failure.
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.
651 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
652 Determine the next internal timeout that libusb needs to handle.
654 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
655 code on failure or timeout.
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.
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.
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.
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.
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.
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
691 argument should be set to LIBUSB_HOTPLUG_NO_FLAGS.
692 This function returns 0 upon success or a LIBUSB_ERROR code on failure.
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.
701 argument is the same as given when the filter was registered.
704 argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
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.
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
724 .Fn usb_interrupt_write
725 .Fn usb_interrupt_read
727 .Fn usb_set_configuration
728 .Fn usb_claim_interface
729 .Fn usb_release_interface
730 .Fn usb_set_altinterface
741 .Fn usb_check_connected
742 .Fn usb_get_driver_np
743 .Fn usb_detach_kernel_driver_np
750 .Pa http://libusb.sourceforge.net/
753 support first appeared in