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 @@ -229,7 +229,6 @@ MLINKS += libusb20.3 libusb20_dev_get_debug.3 MLINKS += libusb20.3 libusb20_dev_get_fd.3 MLINKS += libusb20.3 libusb20_dev_kernel_driver_active.3 -MLINKS += libusb20.3 libusb20_dev_open.3 MLINKS += libusb20.3 libusb20_dev_process.3 MLINKS += libusb20.3 libusb20_dev_request_sync.3 MLINKS += libusb20.3 libusb20_dev_req_string_sync.3 @@ -261,7 +260,6 @@ MLINKS += libusb20.3 libusb20_be_add_dev_quirk.3 MLINKS += libusb20.3 libusb20_be_remove_dev_quirk.3 MLINKS += libusb20.3 libusb20_be_alloc_default.3 -MLINKS += libusb20.3 libusb20_be_device_foreach.3 MLINKS += libusb20.3 libusb20_be_dequeue_device.3 MLINKS += libusb20.3 libusb20_be_enqueue_device.3 MLINKS += libusb20.3 libusb20_be_free.3 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,49 @@ +.\" +.\" Copyright (c) 2025 Rick Parrish +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd December 14, 2025 +.Dt LIBUSB20 3 +.Os +.Sh NAME +.Nm libusb20_be_device_foreach +.Nd iterates connected USB devices +.Sh SYNOPSIS +.Lb libusb +.Pq -lusb +.In libusb20.h +.Ft struct libusb20_device * +.Fn libusb20_be_device_foreach "struct libusb20_backend *pbe" "struct libusb20_device *pdev" +.Sh DESCRIPTION +The +.Nm +call iterates connected USB devices, one device at a time. +A backend pointer may be obtained by calling +.Xr libusb20_be_alloc_default 3 . +The starting value of pdev is NULL. +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 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 + struct libusb20_backend *be = libusb20_be_alloc_default(); + struct 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,66 @@ +.\" +.\" Copyright (c) 2025 Rick Parrish +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd December 14, 2025 +.Dt LIBUSB20 3 +.Os +.Sh NAME +.Nm libusb20_dev_open +.Nd open a USB device to retrieve descriptors and initiate transfers +.Sh SYNOPSIS +.Lb libusb +.Pq -lusb +.In libusb20.h +.Ft int +.Fn libusb20_dev_open "struct libusb20_device *pdev" "uin16_t transfer_max" +.Sh DESCRIPTION +The +.Nm +call opens a USB device to retrieve descriptors and initiate transfers. +.Nm +accepts a 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_dev_close 3 +to free resources taken by the open device handle. +.Sh ERRORS +.Nm +returns one of the following to report success or failure: +.Bl -tag -width "LIBUSB20_ERROR_NO_MEM" -compact +.It Er LIBUSB20_SUCCESS +The operation succeeds. +.It Er LIBUSB20_ERROR_BUSY +The device in use elsewhere. +.It Er LIBUSB20_ERROR_ACCESS +A permissions issue. +.It Er LIBUSB20_ERROR_NO_DEVICE +The device detached. +.It Er LIBUSB20_ERROR_NO_MEM +This library could not allocate memory. +.It More errors in +.Xr libusb20 3 +and +.In libusb20.h +.El +.Sh EXAMPLES +.Bd -literal + #include + struct libusb20_backend *be = libusb20_be_alloc_default(); + struct 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 +.Sh SEE ALSO +.Xr libusb20_be_device_foreach 3 , +.Xr libusb20_dev_close 3 , +.Xr libusb20 3