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_has_capability "uint32_t capability"
66 This function checks the runtime capabilities of
68 This function will return non-zero if the given
70 is supported, 0 if it is not supported.
74 .Bl -tag -width LIBUSB_CAP -offset indent
75 .It Va LIBUSB_CAP_HAS_CAPABILITY
78 .Fn libusb_has_capability .
79 .It Va LIBUSB_CAP_HAS_HOTPLUG
81 supports hotplug notifications.
82 .It Va LIBUSB_CAP_HAS_HID_ACCESS
84 can access HID devices without requiring user intervention.
85 .It Va LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER
87 supports detaching of the default USB driver with
88 .Fn libusb_detach_kernel_driver .
92 .Fn libusb_strerror "int code"
93 Get the ASCII representation of the error given by the
96 This function does not return NULL.
99 .Fn libusb_error_name "int code"
100 Get the ASCII representation of the error enum given by the
103 This function does not return NULL.
106 .Fn libusb_set_debug "libusb_context *ctx" "int level"
107 Set the debug level to
111 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
114 with the list of usb devices available, adding a reference to each
116 All the list entries created by this
117 function must have their reference counter
118 decremented when you are done with them,
119 and the list itself must be freed.
121 function returns the number of devices in the list or a LIBUSB_ERROR code.
124 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
125 Free the list of devices discovered by libusb_get_device_list.
128 is set to 1 all devices in the list have their reference
129 counter decremented once.
132 .Fn libusb_get_bus_number "libusb_device *dev"
133 Returns the number of the bus contained by the device
137 .Fn libusb_get_port_number "libusb_device *dev"
138 Returns the port number which the device given by
143 .Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
144 Stores, in the buffer
148 the list of all port numbers from root for the device
152 .Fn libusb_get_port_path "libusb_context *ctx" "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
153 Deprecated function equivalent to libusb_get_port_numbers.
156 .Fn libusb_get_device_address "libusb_device *dev"
157 Returns the device_address contained by the device
160 .Ft enum libusb_speed
161 .Fn libusb_get_device_speed "libusb_device *dev"
162 Returns the wire speed at which the device is connected.
163 See the LIBUSB_SPEED_XXX enums for more information.
164 LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
167 .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
168 Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
169 endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
172 .Fn libusb_get_max_iso_packet_size "libusb_device *dev" "unsigned char endpoint"
173 Returns the packet size multiplied by the packet multiplier on success,
174 LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and
175 LIBUSB_ERROR_OTHERS on other failure.
178 .Fn libusb_ref_device "libusb_device *dev"
179 Increment the reference counter of the device
183 .Fn libusb_unref_device "libusb_device *dev"
184 Decrement the reference counter of the device
188 .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
189 Open a device and obtain a device_handle.
190 Returns 0 on success,
191 LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
192 on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
193 disconnected and a LIBUSB_ERROR code on other errors.
195 .Ft libusb_device_handle *
196 .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
197 A convenience function to open a device by vendor and product IDs
201 Returns NULL on error.
204 .Fn libusb_close "libusb_device_handle *devh"
205 Close a device handle.
208 .Fn libusb_get_device "libusb_device_handle *devh"
209 Get the device contained by devh.
210 Returns NULL on error.
213 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
214 Returns the value of the current configuration.
216 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
217 and a LIBUSB_ERROR code on error.
220 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
221 Set the active configuration to
223 for the device contained by
225 This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
226 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
227 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
228 LIBUSB_ERROR code on failure.
231 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
232 Claim an interface in a given libusb_handle
234 This is a non-blocking function.
235 It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
236 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
237 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
238 been disconnected and a LIBUSB_ERROR code on failure.
241 .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
242 This function releases an interface.
243 All the claimed interfaces on a device must be released
244 before closing the device.
245 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
246 interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
247 disconnected and LIBUSB_ERROR on failure.
250 .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
251 Activate an alternate setting for an interface.
252 Returns 0 on success,
253 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
254 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
255 disconnected and a LIBUSB_ERROR code on failure.
258 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
259 Clear an halt/stall for a endpoint.
260 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
261 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
262 disconnected and a LIBUSB_ERROR code on failure.
265 .Fn libusb_reset_device "libusb_device_handle *devh"
266 Perform an USB port reset for an usb device.
267 Returns 0 on success,
268 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
269 been disconnected and a LIBUSB_ERROR code on failure.
272 .Fn libusb_check_connected "libusb_device_handle *devh"
273 Test if the USB device is still connected.
274 Returns 0 on success,
275 LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
279 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
280 Determine if a driver is active on a interface.
281 Returns 0 if no kernel driver is active
282 and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
283 if the device has been disconnected and a LIBUSB_ERROR code on failure.
286 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
289 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
290 Copy the name of the driver attached to the given
298 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
299 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
301 This function is non-portable.
302 The buffer pointed to by
304 is only zero terminated on success.
307 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
310 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
311 Detach a kernel driver from an interface.
312 This is needed to claim an interface already claimed by a kernel driver.
313 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
314 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
315 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
316 and a LIBUSB_ERROR code on failure.
317 This function is non-portable.
320 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
321 Re-attach an interface kernel driver that was previously detached.
322 Returns 0 on success,
323 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
324 LIBUSB_ERROR_NO_DEVICE
325 if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
326 attached because the interface is claimed by a program or driver and a
327 LIBUSB_ERROR code on failure.
330 .Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable"
331 This function enables automatic kernel interface driver detach when an
332 interface is claimed.
333 When the interface is restored the kernel driver is allowed to be re-attached.
336 argument is non-zero the feature is enabled.
338 Returns 0 on success and a LIBUSB_ERROR code on
342 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
343 Get the USB device descriptor for the device
345 This is a non-blocking function.
346 Returns 0 on success and a LIBUSB_ERROR code on
350 .Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
351 Get the USB configuration descriptor for the active configuration.
353 success, LIBUSB_ERROR_NOT_FOUND if the device is in
354 an unconfigured state
355 and a LIBUSB_ERROR code on error.
358 .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
359 Get a USB configuration descriptor based on its index
361 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
362 and a LIBUSB_ERROR code on error.
365 .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
366 Get a USB configuration descriptor with a specific bConfigurationValue.
368 a non-blocking function which does not send a request through the device.
370 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
372 LIBUSB_ERROR code on failure.
375 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
376 Free a configuration descriptor.
379 .Fn libusb_get_string_descriptor "libusb_device_handle *devh" "uint8_t desc_idx" "uint16_t langid" "unsigned char *data" "int length"
380 Retrieve a string descriptor in raw format.
381 Returns the number of bytes actually transferred on success
382 or a negative LIBUSB_ERROR code on failure.
385 .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
386 Retrieve a string descriptor in C style ASCII.
387 Returns the positive number of bytes in the resulting ASCII string
388 on success and a LIBUSB_ERROR code on failure.
391 .Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp"
392 This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by
394 and having a length of
396 Typically these arguments are the extra and extra_length fields of the
398 On success the pointer to resulting descriptor is stored at the location given by
400 Returns zero on success and a LIBUSB_ERROR code on failure.
401 On success the parsed USB 3.0 endpoint companion descriptor must be
402 freed using the libusb_free_ss_endpoint_comp function.
405 .Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp"
406 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by
410 .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"
411 This function finds and parses the USB 3.0 endpoint companion descriptor given by
413 Returns zero on success and a LIBUSB_ERROR code on failure.
414 On success the parsed USB 3.0 endpoint companion descriptor must be
415 freed using the libusb_free_ss_endpoint_companion_descriptor function.
418 .Fn libusb_free_ss_endpoint_companion_descriptor "struct libusb_ss_endpoint_companion_descriptor *ep_comp"
419 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by
423 .Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos"
424 This function queries the USB device given by
426 and stores a pointer to a parsed BOS descriptor into
428 Returns zero on success and a LIBUSB_ERROR code on failure.
429 On success the parsed BOS descriptor must be
430 freed using the libusb_free_bos_descriptor function.
433 .Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos"
434 This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by
436 and having a length of
438 On success the pointer to resulting descriptor is stored at the location given by
440 Returns zero on success and a LIBUSB_ERROR code on failure.
441 On success the parsed BOS descriptor must be freed using the
442 libusb_free_bos_descriptor function.
445 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
446 This function is NULL safe and frees a parsed BOS descriptor given by
450 .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"
451 This function parses the USB 2.0 extension descriptor from the descriptor given by
453 and stores a pointer to the parsed descriptor into
454 .Fa usb_2_0_extension .
455 Returns zero on success and a LIBUSB_ERROR code on failure.
456 On success the parsed USB 2.0 extension descriptor must be freed using the
457 libusb_free_usb_2_0_extension_descriptor function.
460 .Fn libusb_free_usb_2_0_extension_descriptor "struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension"
461 This function is NULL safe and frees a parsed USB 2.0 extension descriptor given by
462 .Fa usb_2_0_extension .
465 .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"
466 This function parses the SuperSpeed device capability descriptor from the descriptor given by
468 and stores a pointer to the parsed descriptor into
469 .Fa ss_usb_device_capability .
470 Returns zero on success and a LIBUSB_ERROR code on failure.
471 On success the parsed SuperSpeed device capability descriptor must be freed using the
472 libusb_free_ss_usb_device_capability_descriptor function.
475 .Fn libusb_free_ss_usb_device_capability_descriptor "struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_capability"
476 This function is NULL safe and frees a parsed SuperSpeed device capability descriptor given by
477 .Fa ss_usb_device_capability .
480 .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"
481 This function parses the container ID descriptor from the descriptor given by
483 and stores a pointer to the parsed descriptor into
485 Returns zero on success and a LIBUSB_ERROR code on failure.
486 On success the parsed container ID descriptor must be freed using the
487 libusb_free_container_id_descriptor function.
490 .Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id"
491 This function is NULL safe and frees a parsed container ID descriptor given by
493 .Sh USB ASYNCHRONOUS I/O
494 .Ft struct libusb_transfer *
495 .Fn libusb_alloc_transfer "int iso_packets"
496 Allocate a transfer with the number of isochronous packet descriptors
499 Returns NULL on error.
502 .Fn libusb_free_transfer "struct libusb_transfer *tr"
506 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
507 This function will submit a transfer and returns immediately.
508 Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
509 the device has been disconnected and a
510 LIBUSB_ERROR code on other failure.
513 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
514 This function asynchronously cancels a transfer.
515 Returns 0 on success and a LIBUSB_ERROR code on failure.
516 .Sh USB SYNCHRONOUS I/O
518 .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"
519 Perform a USB control transfer.
520 Returns the actual number of bytes
521 transferred on success, in the range from and including zero up to and
524 On error a LIBUSB_ERROR code is returned, for example
525 LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
526 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
527 device has been disconnected and another LIBUSB_ERROR code on other failures.
528 The LIBUSB_ERROR codes are all negative.
531 .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
532 Perform an USB bulk transfer.
533 A timeout value of zero means no timeout.
534 The timeout value is given in milliseconds.
535 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
536 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
537 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
538 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
539 a LIBUSB_ERROR code on other failure.
542 .Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
543 Perform an USB Interrupt transfer.
544 A timeout value of zero means no timeout.
545 The timeout value is given in milliseconds.
546 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
547 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
548 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
549 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
550 a LIBUSB_ERROR code on other failure.
551 .Sh USB STREAMS SUPPORT
553 .Fn libusb_alloc_streams "libusb_device_handle *dev" "uint32_t num_streams" "unsigned char *endpoints" "int num_endpoints"
554 This function verifies that the given number of streams using the
555 given number of endpoints is allowed and allocates the resources
556 needed to use so-called USB streams.
557 Currently only a single stream per endpoint is supported to simplify
558 the internals of LibUSB.
559 This function returns 0 on success or a LIBUSB_ERROR code on failure.
562 .Fn libusb_free_streams "libusb_device_handle *dev" "unsigned char *endpoints" "int num_endpoints"
563 This function release resources needed for streams usage.
564 Returns 0 on success or a LIBUSB_ERROR code on failure.
567 .Fn libusb_transfer_set_stream_id "struct libusb_transfer *transfer" "uint32_t stream_id"
568 This function sets the stream ID for the given USB transfer.
571 .Fn libusb_transfer_get_stream_id "struct libusb_transfer *transfer"
572 This function returns the stream ID for the given USB transfer.
573 If no stream ID is used a value of zero is returned.
576 .Fn libusb_try_lock_events "libusb_context *ctx"
577 Try to acquire the event handling lock.
578 Returns 0 if the lock was obtained and 1 if not.
581 .Fn libusb_lock_events "libusb_context *ctx"
582 Acquire the event handling lock.
583 This function is blocking.
586 .Fn libusb_unlock_events "libusb_context *ctx"
587 Release the event handling lock.
588 This will wake up any thread blocked
590 .Fn libusb_wait_for_event .
593 .Fn libusb_event_handling_ok "libusb_context *ctx"
594 Determine if it still OK for this thread to be doing event handling.
596 if event handling can start or continue.
597 Returns 0 if this thread must give up
601 .Fn libusb_event_handler_active "libusb_context *ctx"
602 Determine if an active thread is handling events.
603 Returns 1 if there is a thread handling events and 0 if there
604 are no threads currently handling events.
607 .Fn libusb_lock_event_waiters "libusb_context *ctx"
608 Acquire the event_waiters lock.
609 This lock is designed to be obtained in the
610 situation where you want to be aware when events are completed, but some other
611 thread is event handling so calling
612 .Fn libusb_handle_events
616 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
617 Release the event_waiters lock.
620 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
621 Wait for another thread to signal completion of an event.
623 with the event waiters lock held, see
624 .Fn libusb_lock_event_waiters .
626 block until the timeout expires or a transfer completes or a thread releases
627 the event handling lock through
628 .Fn libusb_unlock_events .
630 transfer completes or another thread stops event handling, and 1 if the
634 .Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed"
635 Handle any pending events by checking if timeouts have expired and by
636 checking the set of file descriptors for activity.
639 argument is not equal to NULL, this function will
640 loop until a transfer completion callback sets the variable pointed to
643 argument to non-zero.
646 argument is not equal to NULL, this function will return
647 LIBUSB_ERROR_TIMEOUT after the given timeout.
648 Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout.
651 .Fn libusb_handle_events_completed "libusb_context *ctx" "int *completed"
652 Handle any pending events by checking the set of file descriptors for activity.
655 argument is not equal to NULL, this function will
656 loop until a transfer completion callback sets the variable pointed to
659 argument to non-zero.
660 Returns 0 on success, or a LIBUSB_ERROR code on failure.
663 .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
664 Handle any pending events by checking if timeouts have expired and by
665 checking the set of file descriptors for activity.
666 Returns 0 on success, or a
667 LIBUSB_ERROR code on failure or timeout.
670 .Fn libusb_handle_events "libusb_context *ctx"
671 Handle any pending events in blocking mode with a sensible timeout.
673 on success and a LIBUSB_ERROR code on failure.
676 .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
677 Handle any pending events by polling file descriptors, without checking if
678 another thread is already doing so.
679 Must be called with the event lock held.
682 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
683 Determine the next internal timeout that libusb needs to handle.
685 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
686 code on failure or timeout.
689 .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
690 Register notification functions for file descriptor additions/removals.
691 These functions will be invoked for every new or removed file descriptor
692 that libusb uses as an event source.
694 .Ft const struct libusb_pollfd **
695 .Fn libusb_get_pollfds "libusb_context *ctx"
696 Retrieve a list of file descriptors that should be polled by your main loop as
697 libusb event sources.
698 Returns a NULL-terminated list on success or NULL on failure.
701 .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"
702 This function registers a hotplug filter.
705 argument select which events makes the hotplug filter trigger.
706 Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
707 One or more events must be specified.
713 arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor.
714 Else the specified value is used for matching.
717 argument is set to LIBUSB_HOTPLUG_ENUMERATE, all currently attached and matching USB devices will be passed to the hotplug filter, given by the
722 argument should be set to LIBUSB_HOTPLUG_NO_FLAGS.
723 This function returns 0 upon success or a LIBUSB_ERROR code on failure.
726 .Fn libusb_hotplug_callback_fn "libusb_context *ctx" "libusb_device *device" "libusb_hotplug_event event" "void *user_data"
727 The hotplug filter function.
728 If this function returns non-zero, the filter is removed.
729 Else the filter is kept and can receive more events.
732 argument is the same as given when the filter was registered.
735 argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
738 .Fn libusb_hotplug_deregister_callback "libusb_context *ctx" "libusb_hotplug_callback_handle handle"
739 This function unregisters a hotplug filter.
740 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
741 The library is also compliant with LibUSB version 0.1.12.
746 .Fn usb_get_string_simple
747 .Fn usb_get_descriptor_by_endpoint
748 .Fn usb_get_descriptor
749 .Fn usb_parse_descriptor
750 .Fn usb_parse_configuration
751 .Fn usb_destroy_configuration
752 .Fn usb_fetch_and_parse_descriptors
755 .Fn usb_interrupt_write
756 .Fn usb_interrupt_read
758 .Fn usb_set_configuration
759 .Fn usb_claim_interface
760 .Fn usb_release_interface
761 .Fn usb_set_altinterface
772 .Fn usb_check_connected
773 .Fn usb_get_driver_np
774 .Fn usb_detach_kernel_driver_np
781 .Lk https://libusb.info/
784 support first appeared in