diff --git a/lib/libusb/Makefile b/lib/libusb/Makefile --- a/lib/libusb/Makefile +++ b/lib/libusb/Makefile @@ -11,7 +11,7 @@ SRCS+= libusb20_ugen20.c INCS+= libusb20.h INCS+= libusb20_desc.h -MAN= libusb.3 libusb20.3 +MAN= libusb.3 libusb20.3 libusb20_dev_open.3 libusb20_be_device_foreach.3 MKLINT= no NOGCCERROR= PTHREAD_LIBS?= -lpthread diff --git a/lib/libusb/libusb20_be_device_foreach.3 b/lib/libusb/libusb20_be_device_foreach.3 new file mode 100644 --- /dev/null +++ b/lib/libusb/libusb20_be_device_foreach.3 @@ -0,0 +1,66 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Rick Parrish +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 14, 2025 +.Dt LIBUSB20 3 +.Os +.Sh NAME +.Nm libusb20_be_device_foreach +.Nd iterates USB devices present in a USB backend. +.Sh LIBRARY +.Lb libusb (-l usb) +.Sh SYNOPSIS +.In libusb20.h +.Ft struct libusb20_device * +.Fn libusb20_dev_open "struct libusb20_backend *pbe" "struct libusb20_device *pdev" +.Sh DESCRIPTION +The starting value of pdev is NULL. A backend pointer may be obtained by calling +.Xr libusb20_be_alloc_default 3 . +This function returns the next USB device in the list. Calling +.Xr libusb20_be_device_foreach 3 +again with the return value of the previous call yields the next device. +To begin interacting with a USB device, pass the opaque pointer in a call to +.Xr libusb20_dev_open 3 . +.Sh RETURN VALUES +NULL for end of list, otherwise this is a pointer to the next device. +.Sh SEE ALSO +.Xr libusb20_be_alloc_default 3 +.Xr libusb20_be_device_foreach 3 +.Xr libusb20_be_free 3 +.Xr libusb20_dev_open 3 +.Sh EXAMPLE +.Bd -literal + #include + libusb20_backend *be = libusb20_be_alloc_default(); + libusb20_device *device = NULL; + while ( (device = libusb20_be_device_foreach(be, device)) != NULL ) { + if (libusb20_dev_open(device, 0) == LIBUSB20_SUCCESS) { + /* do something */ + libusb20_dev_close(device); + } + } + libusb20_be_free(be); +.Ed diff --git a/lib/libusb/libusb20_dev_open.3 b/lib/libusb/libusb20_dev_open.3 new file mode 100644 --- /dev/null +++ b/lib/libusb/libusb20_dev_open.3 @@ -0,0 +1,74 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Rick Parrish +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 14, 2025 +.Dt LIBUSB20 3 +.Os +.Sh NAME +.Nm libusb20_dev_open +.Nd opens a USB device so that querying device strings and setting up USB transfers becomes possible. +.Sh LIBRARY +.Lb libusb (-l usb) +.Sh SYNOPSIS +.In libusb20.h +.Ft int +.Fn libusb20_dev_open "struct libusb20_device *pdev" "uin16_t transfer_max" +.Sh DESCRIPTION +The +.Fn libusb20_dev_open +function accepts an opaque pointer to a +.Xr libusb20_device 3 +obtained from +.Xr libusb20_be_device_foreach 3 . +A zero for transfer_max limits the device to only control transfers. +Call +.Xr libusb20_close 3 +to free resources taken by the open device handle. +.Sh RETURN VALUES +LIBUSB20_SUCCESS +LIBUSB20_ERROR_BUSY +LIBUSB20_ERROR_ACCESS +LIBUSB20_ERROR_NO_MEM +More errors are defined in +.Xr libusb20 3 +and libusb20.h +.Sh SEE ALSO +.Xr libusb20_be_device_foreach 3 , +.Xr libusb20_dev_close 3 , +.Xr libusb20 3 +.Sh EXAMPLE +.Bd -literal + #include + libusb20_backend *be = libusb20_be_alloc_default(); + libusb20_device *device = NULL; + while ( (device = libusb20_be_device_foreach(be, device)) != NULL ) { + if (libusb20_dev_open(device, 0) == LIBUSB20_SUCCESS) { + /* do something */ + libusb20_dev_close(device); + } + } + libusb20_be_free(be); +.Ed