git: 88f2c58d1a85 - main - cdevpriv(9): document devfs_foreach_cdevpriv()

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=88f2c58d1a857f0ccedd49da3dc29d8d193b4fdd

commit 88f2c58d1a857f0ccedd49da3dc29d8d193b4fdd
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2024-03-23 06:48:57 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2024-03-23 06:59:00 +0000

    cdevpriv(9): document devfs_foreach_cdevpriv()
    
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
---
 share/man/man9/Makefile             |  1 +
 share/man/man9/devfs_set_cdevpriv.9 | 41 +++++++++++++++++++++++++++++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 87fb2f0906c9..597b487bb8ae 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -998,6 +998,7 @@ MLINKS+=dev_refthread.9 devvn_refthread.9 \
 	dev_refthread.9 dev_relthread.9
 MLINKS+=devfs_set_cdevpriv.9 devfs_clear_cdevpriv.9 \
 	devfs_set_cdevpriv.9 devfs_get_cdevpriv.9
+	devfs_set_cdevpriv.9 devfs_foreach_cdevpriv.9
 MLINKS+=device_add_child.9 device_add_child_ordered.9
 MLINKS+=device_enable.9 device_disable.9 \
 	device_enable.9 device_is_enabled.9
diff --git a/share/man/man9/devfs_set_cdevpriv.9 b/share/man/man9/devfs_set_cdevpriv.9
index 945d31a58d0a..3258ca082e5f 100644
--- a/share/man/man9/devfs_set_cdevpriv.9
+++ b/share/man/man9/devfs_set_cdevpriv.9
@@ -22,13 +22,14 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 2, 2015
+.Dd March 23, 2024
 .Dt DEVFS_CDEVPRIV 9
 .Os
 .Sh NAME
 .Nm devfs_set_cdevpriv ,
 .Nm devfs_get_cdevpriv ,
-.Nm devfs_clear_cdevpriv
+.Nm devfs_clear_cdevpriv ,
+.Nm devfs_foreach_cdevpriv
 .Nd manage per-open filedescriptor data for devices
 .Sh SYNOPSIS
 .In sys/param.h
@@ -42,6 +43,12 @@ typedef	void d_priv_dtor_t(void *data);
 .Fn devfs_set_cdevpriv "void *priv" "d_priv_dtor_t *dtr"
 .Ft void
 .Fn devfs_clear_cdevpriv "void"
+.Ft int
+.Fo devfs_foreach_cdevpriv
+.Fa "struct cdev *dev"
+.Fa "int (*cb)(void *data, void *arg)"
+.Fa "void *arg"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn devfs_xxx_cdevpriv
@@ -111,6 +118,36 @@ filedescriptor, or
 .Fn devfs_clear_cdevpriv
 was called.
 .El
+.Pp
+The function
+.Fn devfs_foreach_cdevpriv
+sequentially calls the function
+.Fa cb
+for each
+.Nm cdevpriv
+structure, currently associated with the
+.Fa cdev
+device.
+The iterated
+.Nm cdevpriv
+data pointer and the user-supplied context
+.Fa arg
+are passed to the function
+.Fa cb .
+If
+.Fa cb
+returns non-zero value, the iteration stops on that element.
+The
+.Fn devfs_foreach_cdevpriv
+returns the return value from the last call to
+.Fa cb ,
+or zero if no
+.Nm cdevpriv
+data is currently associated with the device.
+.Pp
+Current implementation of the iterator makes it impossible to use
+any blockable locking inside the callback
+.Fa cb .
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr open 2 ,