From nobody Mon Mar 3 16:56:51 2025 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 4Z64jJ090vz5pnPW; Mon, 03 Mar 2025 16:56:52 +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 "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Z64jH61BPz465P; Mon, 03 Mar 2025 16:56:51 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1741021011; 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=qQ2XtcDHAxEkIdtMPRGGFvrOE7ypUTaCytpogXZBBec=; b=Mrd/YHwOAOuug+48WfnJo2qksTyqxPf4ErP8mOI0Xw9/MuU4Z28JOePTa/8a97DTLtsWFU WnhfXWzOx8KHsd0tBRH7yKHiDnLsV67T/tMSrtGxbnhMTgY/VfRKy6vJVSxxhLnZgxeiuE Z5gd3lDNReDk0Yhjx0S7CNntNFL+d5+TENbzxfsIGs3fGlMovC6HGuk0W8Dlu6kRORLVXq YaYWKHASCq9BkgnQ9C10pY8bpyOPK4kxIDLpETW6U6ISFibLggCIxfi1jKavF9buMWtyK2 uHWS7tzv24RPDX6lAIOr57wKXTc7P1IekJDnT0yvDmHEKBwP3P7yV1ZE4Wzlcg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1741021011; a=rsa-sha256; cv=none; b=LpdyIuUmBKkNgNmKRj04IdE60KNxf+7psgYmCHtPNZAtgKb60MmQ4/Dt5bJDuO6DPe3yBN N//lRTb1WgZ4c16fdwMkJmG+IuipXku8NUr0bDEtM5MOnSTyEvhitoa90aW2qw1GS+zvYC Pvf2OeiaZw9b0HJgv6UqrgwL0tyBcFg9vbHMreE8ouVzWc1o1VTj5VNfcUSJBy8HS+qn+k r5uQXgv91qu0hisKJuH1UfARojBYPx5oHtHlOmRnUH0gy8tRJ+6A0PhOgRHihi1g7A0e9K TSCa8bZKXEeYKcOrhNA+vlC34wc5e8EwJkMDQ2SMLDxvrDXnx0ihfUa9EhD3ZA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1741021011; 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=qQ2XtcDHAxEkIdtMPRGGFvrOE7ypUTaCytpogXZBBec=; b=wCJ3+jHwAld/thKIgE/IF2Tl7nnSR+n7xJmMzK7iK/hts0kuF+P13yVa2G+DBTxrcT8a9L u9u1rty7NbdRVZAImlIoRZ31mhen7HRL97m0h8h3a6mFnQM62qml/pOWIbSck0ac36v1Pz HNaZ/45dEPIL2x+aAeJNsqGcDcdcbredCnIc6jWDlqjjwImD22FF48toPg2VOOvpcWraE1 CDLFh7UAjx6FV1lQiP/g7jZyaDo+dswktYMg0oG/tIq/ODQ4zHMzfYitz05qKCxe4sGhME rWi1k1uZgVDL8Kv5ci1uL3GeQz/+d5dmFTr6Rp7xEWL/Q+DUnTIDyR5blaKfOg== 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 4Z64jH5Qs7zwJb; Mon, 03 Mar 2025 16:56:51 +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 523GupYC083462; Mon, 3 Mar 2025 16:56:51 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 523GupGH083459; Mon, 3 Mar 2025 16:56:51 GMT (envelope-from git) Date: Mon, 3 Mar 2025 16:56:51 GMT Message-Id: <202503031656.523GupGH083459@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: John Baldwin Subject: git: 8e8058b7373b - stable/14 - 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/stable/14 X-Git-Reftype: branch X-Git-Commit: 8e8058b7373b2af1e2113a303d34434579d5cb6e Auto-Submitted: auto-generated The branch stable/14 has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=8e8058b7373b2af1e2113a303d34434579d5cb6e commit 8e8058b7373b2af1e2113a303d34434579d5cb6e Author: John Baldwin AuthorDate: 2024-12-30 19:09:48 +0000 Commit: John Baldwin CommitDate: 2025-03-03 16:56:20 +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 (cherry picked from commit 9b1585384d53d0f9cc4585a6efd8cc95116407d7) --- lib/libc/sys/Makefile.inc | 1 + lib/libc/sys/kqueue.2 | 65 ++++++++++++++++++++++++++++++----------------- 2 files changed, 42 insertions(+), 24 deletions(-) diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 7628f121feac..f01b085f712b 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -443,6 +443,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/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 index 066ad717111a..d6e949baa24c 100644 --- a/lib/libc/sys/kqueue.2 +++ b/lib/libc/sys/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