From nobody Mon Dec 30 19:10:10 2024 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4YMQfC0FNgz5hcqk; Mon, 30 Dec 2024 19:10:11 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4YMQfB6PH0z4611; Mon, 30 Dec 2024 19:10:10 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1735585810; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=25xep2v8RdOk/mBK+/wMNMmdBSwj/mMPiOj4m04JCZQ=; b=VtXnx8zT95z7JLgCVEAps6sIXtIrWwuTQW3ob79qxG0jNOyRbLOt6kCbMuUfnHwkC0V2FY m4YsP0EqauxlMeHjDjYMdoQzeVYZ3EBkoQSMWX7FxLiVzQtGYGxQINc5tJuM3ROqn6iqna x8qlFV5jsofpujQT8+OLGqkBWYTpnTG/5Q8doB4lbJgFCAGG7q4PZ/lb9XAkclYq9xXtpS AFgFqbQOVj+QD2IbkYas98aNbjJVihDibWF/L3XMHaQ5JRHBthKvZngFhsQm/POA1CnzoA 4z0fQhwbx0y2GJfslFIIIh/KIBG1AN5wOEwVE/+v8w9Rf3BFJKxHabGU1iv/YA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1735585810; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=25xep2v8RdOk/mBK+/wMNMmdBSwj/mMPiOj4m04JCZQ=; b=TdT7JNtIF3M8PWvtL7PuKgziKJ+KIc1iIydboFzQmytkQ21xN9CR5fQsQWbM6LMA4rulP5 VLvysdXvot4uyCS5tkw0hExU02hopGrYAZHnXAd9LhC0/Q8Pc0nnbX2I9mGrNqw1nEb/32 Ow+c16rUyQwyOkmsbVKoaswgqhqmTJauqtC6uiiv7P95sx54XiPoGxOpNgYGPbz1OUfMcg Omz4BUt+BDJ0c3DIJphvnVtZU9CcfOxpMV+kk5bbZ3qIL7dOBRGqHJrZKc/J/Z6BYKM+ku g5ALQLSbuZqx/SK1FFhzTR6YyFgGYFvIJlnzB/FCeqcoktU5+//oWmZVSAe+WA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1735585810; a=rsa-sha256; cv=none; b=X+jkgpnctN0zO/vx4CCmfd+6jiZ9j7H0lH0lovqyNrY1Cht8zLlH13HWMKGsKpsXr92+TI 7fPkrN8s+TDB/cR3O7EO0BWpbxQL5qHrH/e0D6kEkIO5G6FUNYfGrDX+SfSLy/joipB9WE Eb7dQodTgGpwP6GFxo9ltdIqus01hvOd0RbHnWhQbgzepVx+NLuGewACxIDqYdbSFTthmh s+yUDzKGR86Pyd1A1FIRdLESua4u0WgJxKog+K7p6KoS05rOsSt4d2T9NskI6hSwWO00R0 8a2NevtdY67kpSKJUvQ50otJiO29TZVBmTHFIVgeKCsX7GLfDGqqsHJ34f0rhg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4YMQfB5syYz15nm; Mon, 30 Dec 2024 19:10:10 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 4BUJAADA038693; Mon, 30 Dec 2024 19:10:10 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 4BUJAAOg038687; Mon, 30 Dec 2024 19:10:10 GMT (envelope-from git) Date: Mon, 30 Dec 2024 19:10:10 GMT Message-Id: <202412301910.4BUJAAOg038687@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: John Baldwin Subject: git: 9b1585384d53 - main - kqueue.2: Editorial pass List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: jhb X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 9b1585384d53d0f9cc4585a6efd8cc95116407d7 Auto-Submitted: auto-generated The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=9b1585384d53d0f9cc4585a6efd8cc95116407d7 commit 9b1585384d53d0f9cc4585a6efd8cc95116407d7 Author: John Baldwin AuthorDate: 2024-12-30 19:09:48 +0000 Commit: John Baldwin CommitDate: 2024-12-30 19:09:48 +0000 kqueue.2: Editorial pass - Use consistent language to describe user values unchanged by the kernel. - Replace passive language with active in a few places. - Add a history note for kqueuex() and kqueue1(). - Add an MLINK and synopsis for kqueue1(). - Various wording and markup tweaks. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D48203 --- lib/libsys/Makefile.sys | 1 + lib/libsys/kqueue.2 | 65 +++++++++++++++++++++++++++++++------------------ 2 files changed, 42 insertions(+), 24 deletions(-) diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys index 29c40eb334ba..b38cd5935e2f 100644 --- a/lib/libsys/Makefile.sys +++ b/lib/libsys/Makefile.sys @@ -454,6 +454,7 @@ MLINKS+=jail.2 jail_attach.2 \ jail.2 jail_set.2 MLINKS+=kldunload.2 kldunloadf.2 MLINKS+=kqueue.2 kevent.2 \ + kqueue.2 kqueue1.2 \ kqueue.2 kqueuex.2 \ kqueue.2 EV_SET.3 MLINKS+=link.2 linkat.2 diff --git a/lib/libsys/kqueue.2 b/lib/libsys/kqueue.2 index 066ad717111a..d6e949baa24c 100644 --- a/lib/libsys/kqueue.2 +++ b/lib/libsys/kqueue.2 @@ -38,6 +38,8 @@ .Ft int .Fn kqueuex "u_int flags" .Ft int +.Fn kqueue1 "int flags" +.Ft int .Fo kevent .Fa "int kq" .Fa "const struct kevent *changelist" @@ -92,26 +94,35 @@ which will allow sharing of the kqueue between two processes. The .Fn kqueuex system call also creates a new kernel event queue, and additionally takes -the +a .Fa flags argument, which is a bitwise-inclusive OR of the following flags: .Bl -tag -width "KQUEUE_CLOEXEC" -.It Fa KQUEUE_CLOEXEC +.It Dv KQUEUE_CLOEXEC The returned file descriptor is automatically closed on .Xr execve 2 .El +.Pp The -.Ql fd = kqueue() -call is equivalent to -.Ql fd = kqueuex(0) . +.Fn kqueue +system call is equivalent to calling +.Fn kqueuex +with +.Fa flags +set to 0. .Pp -For compatibility with -.Nx , -the +The .Fn kqueue1 -function is provided, which accepts the -.Dv O_CLOEXEC -flag with the expected semantic. +function exists for compatibility with +.Nx . +The +.Fa flags +argument accepts zero or more of the following values: +.Bl -tag -width O_CLOEXEC +.It Dv O_CLOEXEC +The returned file descriptor is automatically closed on +.Xr execve 2 +.El .Pp The .Fn kevent @@ -211,24 +222,25 @@ Filter-specific data value. Opaque user-defined value passed through the kernel unchanged. .It Fa ext Extended data passed to and from kernel. -The +The meaning of the .Fa ext[0] and .Fa ext[1] -members use is defined by the filter. -If the filter does not use them, the members are copied unchanged. +members is defined by the filter. +If a filter does not use them, +these members are passed through the kernel unchanged. The .Fa ext[2] and .Fa ext[3] -members are always passed through the kernel as-is, -making additional context available to application. +members are always passed through the kernel unchanged, +providing additional user-defined values. .El .Pp The .Va flags field can contain the following values: -.Bl -tag -width EV_DISPATCH +.Bl -tag -width EV_KEEPUDATA .It Dv EV_ADD Adds the event to the kqueue. Re-adding an existing event @@ -270,12 +282,12 @@ to hold the .Dv EV_ERROR event, then subsequent changes will not get processed. .It Dv EV_ONESHOT -Causes the event to return only the first occurrence of the filter +Return only the first occurrence of the filter being triggered. After the user retrieves the event from the kqueue, it is deleted. .It Dv EV_CLEAR -After the event is retrieved by the user, its state is reset. +Reset the state of the event after it is retrieved by the user. This is useful for filters which report state transitions instead of the current state. Note that some filters may automatically @@ -287,18 +299,16 @@ See .Sx RETURN VALUES below. .It Dv EV_KEEPUDATA -Causes -.Fn kevent -to leave unchanged any +Preserve the .Fa udata associated with an existing event. This allows other aspects of the event to be modified without requiring the caller to know the .Fa udata -value presently associated. +value previously registered with the event. This is especially useful with .Dv NOTE_TRIGGER -or flags like +or .Dv EV_ENABLE . This flag may not be used with .Dv EV_ADD . @@ -872,6 +882,13 @@ and .Fn kevent system calls first appeared in .Fx 4.1 . +The +.Fn kqueuex +system call +and +.Fn kevent1 +function first appeared in +.Fx 14.0 . .Sh AUTHORS The .Fn kqueue