2 .\" Copyright (c) 2009 Sylvestre Gallon
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd "USB access library"
41 library contains interfaces for directly managing a usb device.
42 The current implementation supports v1.0 of the libusb API.
43 .Sh LIBRARY INITIALISATION AND DEINITIALISATION
44 .Ft "const struct libusb_version *"
45 .Fn libusb_get_version "void"
46 This function returns version information about LibUSB.
49 .Fn libusb_init "libusb_context **ctx"
50 This function initialises libusb.
51 It must be called at the beginning
52 of the program, before other libusb routines are used.
53 This function returns 0 on success or LIBUSB_ERROR on
57 .Fn libusb_exit "libusb_context *ctx"
59 Must be called at the end of the application.
60 Other libusb routines may not be called after this function.
63 .Fn libusb_has_capability "uint32_t capability"
64 This function checks the runtime capabilities of
66 This function will return non-zero if the given
68 is supported, 0 if it is not supported.
72 .Bl -tag -width LIBUSB_CAP -offset indent
73 .It Va LIBUSB_CAP_HAS_CAPABILITY
76 .Fn libusb_has_capability .
77 .It Va LIBUSB_CAP_HAS_HOTPLUG
79 supports hotplug notifications.
80 .It Va LIBUSB_CAP_HAS_HID_ACCESS
82 can access HID devices without requiring user intervention.
83 .It Va LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER
85 supports detaching of the default USB driver with
86 .Fn libusb_detach_kernel_driver .
90 .Fn libusb_strerror "int code"
91 Get the ASCII representation of the error given by the
94 This function does not return NULL.
97 .Fn libusb_error_name "int code"
98 Get the ASCII representation of the error enum given by the
101 This function does not return NULL.
104 .Fn libusb_set_debug "libusb_context *ctx" "int level"
105 Set the debug level to
109 .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list"
112 with the list of usb devices available, adding a reference to each
114 All the list entries created by this
115 function must have their reference counter
116 decremented when you are done with them,
117 and the list itself must be freed.
119 function returns the number of devices in the list or a LIBUSB_ERROR code.
122 .Fn libusb_free_device_list "libusb_device **list" "int unref_devices"
123 Free the list of devices discovered by libusb_get_device_list.
126 is set to 1 all devices in the list have their reference
127 counter decremented once.
130 .Fn libusb_get_bus_number "libusb_device *dev"
131 Returns the number of the bus contained by the device
135 .Fn libusb_get_port_number "libusb_device *dev"
136 Returns the port number which the device given by
141 .Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
142 Stores, in the buffer
146 the list of all port numbers from root for the device
150 .Fn libusb_get_port_path "libusb_context *ctx" "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize"
151 Deprecated function equivalent to libusb_get_port_numbers.
154 .Fn libusb_get_device_address "libusb_device *dev"
155 Returns the device_address contained by the device
158 .Ft enum libusb_speed
159 .Fn libusb_get_device_speed "libusb_device *dev"
160 Returns the wire speed at which the device is connected.
161 See the LIBUSB_SPEED_XXX enums for more information.
162 LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed.
165 .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint"
166 Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the
167 endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure.
170 .Fn libusb_get_max_iso_packet_size "libusb_device *dev" "unsigned char endpoint"
171 Returns the packet size multiplied by the packet multiplier on success,
172 LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and
173 LIBUSB_ERROR_OTHERS on other failure.
176 .Fn libusb_ref_device "libusb_device *dev"
177 Increment the reference counter of the device
181 .Fn libusb_unref_device "libusb_device *dev"
182 Decrement the reference counter of the device
186 .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh"
187 Open a device and obtain a device_handle.
188 Returns 0 on success,
189 LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS
190 on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been
191 disconnected and a LIBUSB_ERROR code on other errors.
193 .Ft libusb_device_handle *
194 .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid"
195 A convenience function to open a device by vendor and product IDs
199 Returns NULL on error.
202 .Fn libusb_close "libusb_device_handle *devh"
203 Close a device handle.
206 .Fn libusb_get_device "libusb_device_handle *devh"
207 Get the device contained by devh.
208 Returns NULL on error.
211 .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config"
212 Returns the value of the current configuration.
214 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
215 and a LIBUSB_ERROR code on error.
218 .Fn libusb_set_configuration "libusb_device_handle *devh" "int config"
219 Set the active configuration to
221 for the device contained by
223 This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested
224 configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently
225 claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a
226 LIBUSB_ERROR code on failure.
229 .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number"
230 Claim an interface in a given libusb_handle
232 This is a non-blocking function.
233 It returns 0 on success, LIBUSB_ERROR_NOT_FOUND
234 if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or
235 driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has
236 been disconnected and a LIBUSB_ERROR code on failure.
239 .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number"
240 This function releases an interface.
241 All the claimed interfaces on a device must be released
242 before closing the device.
243 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the
244 interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been
245 disconnected and LIBUSB_ERROR on failure.
248 .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting"
249 Activate an alternate setting for an interface.
250 Returns 0 on success,
251 LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested
252 setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
253 disconnected and a LIBUSB_ERROR code on failure.
256 .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint"
257 Clear an halt/stall for a endpoint.
258 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND
259 if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been
260 disconnected and a LIBUSB_ERROR code on failure.
263 .Fn libusb_reset_device "libusb_device_handle *devh"
264 Perform an USB port reset for an usb device.
265 Returns 0 on success,
266 LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has
267 been disconnected and a LIBUSB_ERROR code on failure.
270 .Fn libusb_check_connected "libusb_device_handle *devh"
271 Test if the USB device is still connected.
272 Returns 0 on success,
273 LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR
277 .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface"
278 Determine if a driver is active on a interface.
279 Returns 0 if no kernel driver is active
280 and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE
281 if the device has been disconnected and a LIBUSB_ERROR code on failure.
284 .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
287 .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen"
288 Copy the name of the driver attached to the given
296 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached
297 to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does
299 This function is non-portable.
300 The buffer pointed to by
302 is only zero terminated on success.
305 .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface"
308 .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface"
309 Detach a kernel driver from an interface.
310 This is needed to claim an interface already claimed by a kernel driver.
311 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active,
312 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
313 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
314 and a LIBUSB_ERROR code on failure.
315 This function is non-portable.
318 .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface"
319 Re-attach an interface kernel driver that was previously detached.
320 Returns 0 on success,
321 LIBUSB_ERROR_INVALID_PARAM if the interface does not exist,
322 LIBUSB_ERROR_NO_DEVICE
323 if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be
324 attached because the interface is claimed by a program or driver and a
325 LIBUSB_ERROR code on failure.
328 .Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable"
329 This function enables automatic kernel interface driver detach when an
330 interface is claimed.
331 When the interface is restored the kernel driver is allowed to be re-attached.
334 argument is non-zero the feature is enabled.
336 Returns 0 on success and a LIBUSB_ERROR code on
340 .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc"
341 Get the USB device descriptor for the device
343 This is a non-blocking function.
344 Returns 0 on success and a LIBUSB_ERROR code on
348 .Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config"
349 Get the USB configuration descriptor for the active configuration.
351 success, LIBUSB_ERROR_NOT_FOUND if the device is in
352 an unconfigured state
353 and a LIBUSB_ERROR code on error.
356 .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config"
357 Get a USB configuration descriptor based on its index
359 Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
360 and a LIBUSB_ERROR code on error.
363 .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config"
364 Get a USB configuration descriptor with a specific bConfigurationValue.
366 a non-blocking function which does not send a request through the device.
368 on success, LIBUSB_ERROR_NOT_FOUND if the configuration
370 LIBUSB_ERROR code on failure.
373 .Fn libusb_free_config_descriptor "libusb_config_descriptor *config"
374 Free a configuration descriptor.
377 .Fn libusb_get_string_descriptor "libusb_device_handle *devh" "uint8_t desc_idx" "uint16_t langid" "unsigned char *data" "int length"
378 Retrieve a string descriptor in raw format.
379 Returns the number of bytes actually transferred on success
380 or a negative LIBUSB_ERROR code on failure.
383 .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length"
384 Retrieve a string descriptor in C style ASCII.
385 Returns the positive number of bytes in the resulting ASCII string
386 on success and a LIBUSB_ERROR code on failure.
389 .Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp"
390 This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by
392 and having a length of
394 Typically these arguments are the extra and extra_length fields of the
396 On success the pointer to resulting descriptor is stored at the location given by
398 Returns zero on success and a LIBUSB_ERROR code on failure.
399 On success the parsed USB 3.0 endpoint companion descriptor must be
400 freed using the libusb_free_ss_endpoint_comp function.
403 .Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp"
404 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by
408 .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"
409 This function finds and parses the USB 3.0 endpoint companion descriptor given by
411 Returns zero on success and a LIBUSB_ERROR code on failure.
412 On success the parsed USB 3.0 endpoint companion descriptor must be
413 freed using the libusb_free_ss_endpoint_companion_descriptor function.
416 .Fn libusb_free_ss_endpoint_companion_descriptor "struct libusb_ss_endpoint_companion_descriptor *ep_comp"
417 This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by
421 .Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos"
422 This function queries the USB device given by
424 and stores a pointer to a parsed BOS descriptor into
426 Returns zero on success and a LIBUSB_ERROR code on failure.
427 On success the parsed BOS descriptor must be
428 freed using the libusb_free_bos_descriptor function.
431 .Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos"
432 This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by
434 and having a length of
436 On success the pointer to resulting descriptor is stored at the location given by
438 Returns zero on success and a LIBUSB_ERROR code on failure.
439 On success the parsed BOS descriptor must be freed using the
440 libusb_free_bos_descriptor function.
443 .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos"
444 This function is NULL safe and frees a parsed BOS descriptor given by
448 .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"
449 This function parses the USB 2.0 extension descriptor from the descriptor given by
451 and stores a pointer to the parsed descriptor into
452 .Fa usb_2_0_extension .
453 Returns zero on success and a LIBUSB_ERROR code on failure.
454 On success the parsed USB 2.0 extension descriptor must be freed using the
455 libusb_free_usb_2_0_extension_descriptor function.
458 .Fn libusb_free_usb_2_0_extension_descriptor "struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension"
459 This function is NULL safe and frees a parsed USB 2.0 extension descriptor given by
460 .Fa usb_2_0_extension .
463 .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"
464 This function parses the SuperSpeed device capability descriptor from the descriptor given by
466 and stores a pointer to the parsed descriptor into
467 .Fa ss_usb_device_capability .
468 Returns zero on success and a LIBUSB_ERROR code on failure.
469 On success the parsed SuperSpeed device capability descriptor must be freed using the
470 libusb_free_ss_usb_device_capability_descriptor function.
473 .Fn libusb_free_ss_usb_device_capability_descriptor "struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_capability"
474 This function is NULL safe and frees a parsed SuperSpeed device capability descriptor given by
475 .Fa ss_usb_device_capability .
478 .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"
479 This function parses the container ID descriptor from the descriptor given by
481 and stores a pointer to the parsed descriptor into
483 Returns zero on success and a LIBUSB_ERROR code on failure.
484 On success the parsed container ID descriptor must be freed using the
485 libusb_free_container_id_descriptor function.
488 .Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id"
489 This function is NULL safe and frees a parsed container ID descriptor given by
491 .Sh USB ASYNCHRONOUS I/O
492 .Ft struct libusb_transfer *
493 .Fn libusb_alloc_transfer "int iso_packets"
494 Allocate a transfer with the number of isochronous packet descriptors
497 Returns NULL on error.
500 .Fn libusb_free_transfer "struct libusb_transfer *tr"
504 .Fn libusb_submit_transfer "struct libusb_transfer *tr"
505 This function will submit a transfer and returns immediately.
506 Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if
507 the device has been disconnected and a
508 LIBUSB_ERROR code on other failure.
511 .Fn libusb_cancel_transfer "struct libusb_transfer *tr"
512 This function asynchronously cancels a transfer.
513 Returns 0 on success and a LIBUSB_ERROR code on failure.
514 .Sh USB SYNCHRONOUS I/O
516 .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"
517 Perform a USB control transfer.
518 Returns the actual number of bytes
519 transferred on success, in the range from and including zero up to and
522 On error a LIBUSB_ERROR code is returned, for example
523 LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the
524 control request was not supported, LIBUSB_ERROR_NO_DEVICE if the
525 device has been disconnected and another LIBUSB_ERROR code on other failures.
526 The LIBUSB_ERROR codes are all negative.
529 .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
530 Perform an USB bulk transfer.
531 A timeout value of zero means no timeout.
532 The timeout value is given in milliseconds.
533 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
534 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
535 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
536 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
537 a LIBUSB_ERROR code on other failure.
540 .Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout"
541 Perform an USB Interrupt transfer.
542 A timeout value of zero means no timeout.
543 The timeout value is given in milliseconds.
544 Returns 0 on success, LIBUSB_ERROR_TIMEOUT
545 if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not
546 supported, LIBUSB_ERROR_OVERFLOW if the device offered more data,
547 LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and
548 a LIBUSB_ERROR code on other failure.
549 .Sh USB STREAMS SUPPORT
551 .Fn libusb_alloc_streams "libusb_device_handle *dev" "uint32_t num_streams" "unsigned char *endpoints" "int num_endpoints"
552 This function verifies that the given number of streams using the
553 given number of endpoints is allowed and allocates the resources
554 needed to use so-called USB streams.
555 Currently only a single stream per endpoint is supported to simplify
556 the internals of LibUSB.
557 This function returns 0 on success or a LIBUSB_ERROR code on failure.
560 .Fn libusb_free_streams "libusb_device_handle *dev" "unsigned char *endpoints" "int num_endpoints"
561 This function release resources needed for streams usage.
562 Returns 0 on success or a LIBUSB_ERROR code on failure.
565 .Fn libusb_transfer_set_stream_id "struct libusb_transfer *transfer" "uint32_t stream_id"
566 This function sets the stream ID for the given USB transfer.
569 .Fn libusb_transfer_get_stream_id "struct libusb_transfer *transfer"
570 This function returns the stream ID for the given USB transfer.
571 If no stream ID is used a value of zero is returned.
574 .Fn libusb_try_lock_events "libusb_context *ctx"
575 Try to acquire the event handling lock.
576 Returns 0 if the lock was obtained and 1 if not.
579 .Fn libusb_lock_events "libusb_context *ctx"
580 Acquire the event handling lock.
581 This function is blocking.
584 .Fn libusb_unlock_events "libusb_context *ctx"
585 Release the event handling lock.
586 This will wake up any thread blocked
588 .Fn libusb_wait_for_event .
591 .Fn libusb_event_handling_ok "libusb_context *ctx"
592 Determine if it still OK for this thread to be doing event handling.
594 if event handling can start or continue.
595 Returns 0 if this thread must give up
599 .Fn libusb_event_handler_active "libusb_context *ctx"
600 Determine if an active thread is handling events.
601 Returns 1 if there is a thread handling events and 0 if there
602 are no threads currently handling events.
605 .Fn libusb_interrupt_event_handler "libusb_context *ctx"
607 .Fn libusb_handle_events
608 familiy of functions to return to the caller one time.
610 .Fn libusb_handle_events
611 functions may be called again after calling this function.
614 .Fn libusb_lock_event_waiters "libusb_context *ctx"
615 Acquire the event_waiters lock.
616 This lock is designed to be obtained in the
617 situation where you want to be aware when events are completed, but some other
618 thread is event handling so calling
619 .Fn libusb_handle_events
623 .Fn libusb_unlock_event_waiters "libusb_context *ctx"
624 Release the event_waiters lock.
627 .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv"
628 Wait for another thread to signal completion of an event.
630 with the event waiters lock held, see
631 .Fn libusb_lock_event_waiters .
633 block until the timeout expires or a transfer completes or a thread releases
634 the event handling lock through
635 .Fn libusb_unlock_events .
637 transfer completes or another thread stops event handling, and 1 if the
641 .Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed"
642 Handle any pending events by checking if timeouts have expired and by
643 checking the set of file descriptors for activity.
646 argument is not equal to NULL, this function will
647 loop until a transfer completion callback sets the variable pointed to
650 argument to non-zero.
653 argument is not equal to NULL, this function will return
654 LIBUSB_ERROR_TIMEOUT after the given timeout.
655 Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout.
658 .Fn libusb_handle_events_completed "libusb_context *ctx" "int *completed"
659 Handle any pending events by checking the set of file descriptors for activity.
662 argument is not equal to NULL, this function will
663 loop until a transfer completion callback sets the variable pointed to
666 argument to non-zero.
667 Returns 0 on success, or a LIBUSB_ERROR code on failure.
670 .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv"
671 Handle any pending events by checking if timeouts have expired and by
672 checking the set of file descriptors for activity.
673 Returns 0 on success, or a
674 LIBUSB_ERROR code on failure or timeout.
677 .Fn libusb_handle_events "libusb_context *ctx"
678 Handle any pending events in blocking mode with a sensible timeout.
680 on success and a LIBUSB_ERROR code on failure.
683 .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv"
684 Handle any pending events by polling file descriptors, without checking if
685 another thread is already doing so.
686 Must be called with the event lock held.
689 .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv"
690 Determine the next internal timeout that libusb needs to handle.
692 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR
693 code on failure or timeout.
696 .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data"
697 Register notification functions for file descriptor additions/removals.
698 These functions will be invoked for every new or removed file descriptor
699 that libusb uses as an event source.
701 .Ft const struct libusb_pollfd **
702 .Fn libusb_get_pollfds "libusb_context *ctx"
703 Retrieve a list of file descriptors that should be polled by your main loop as
704 libusb event sources.
705 Returns a NULL-terminated list on success or NULL on failure.
708 .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"
709 This function registers a hotplug filter.
712 argument select which events makes the hotplug filter trigger.
713 Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
714 One or more events must be specified.
720 arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor.
721 Else the specified value is used for matching.
724 argument is set to LIBUSB_HOTPLUG_ENUMERATE, all currently attached and matching USB devices will be passed to the hotplug filter, given by the
729 argument should be set to LIBUSB_HOTPLUG_NO_FLAGS.
730 This function returns 0 upon success or a LIBUSB_ERROR code on failure.
733 .Fn libusb_hotplug_callback_fn "libusb_context *ctx" "libusb_device *device" "libusb_hotplug_event event" "void *user_data"
734 The hotplug filter function.
735 If this function returns non-zero, the filter is removed.
736 Else the filter is kept and can receive more events.
739 argument is the same as given when the filter was registered.
742 argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT.
745 .Fn libusb_hotplug_deregister_callback "libusb_context *ctx" "libusb_hotplug_callback_handle handle"
746 This function unregisters a hotplug filter.
747 .Sh LIBUSB VERSION 0.1 COMPATIBILITY
748 The library is also compliant with LibUSB version 0.1.12.
753 .Fn usb_get_string_simple
754 .Fn usb_get_descriptor_by_endpoint
755 .Fn usb_get_descriptor
756 .Fn usb_parse_descriptor
757 .Fn usb_parse_configuration
758 .Fn usb_destroy_configuration
759 .Fn usb_fetch_and_parse_descriptors
762 .Fn usb_interrupt_write
763 .Fn usb_interrupt_read
765 .Fn usb_set_configuration
766 .Fn usb_claim_interface
767 .Fn usb_release_interface
768 .Fn usb_set_altinterface
779 .Fn usb_check_connected
780 .Fn usb_get_driver_np
781 .Fn usb_detach_kernel_driver_np
788 .Lk https://libusb.info/
791 support first appeared in