From nobody Fri Feb 23 10:35:18 2024 X-Original-To: doc@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 4Th5xf6KQYz5CDKJ for ; Fri, 23 Feb 2024 10:35:18 +0000 (UTC) (envelope-from bugzilla-noreply@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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Th5xf1Hwgz4XR0 for ; Fri, 23 Feb 2024 10:35:18 +0000 (UTC) (envelope-from bugzilla-noreply@freebsd.org) ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1708684518; a=rsa-sha256; cv=none; b=QVgP0jk2JtdOy93pGGtv7Iq3vHgmBu90R5bmVfWD+MKcLkfB4PGn5E/RcMgBcFaQNxvU84 dzpNA/aECprwTQhjPBWenyniRXVCzuB21equ0idsaWwvR1iKW6J6XsiUZQTMPgGR2hMFDQ kN0ykT7dSt0ajLrP1VCZpA4PoJbt2HAOpo6fuBphgc/+dBauuuiJw5A89iKW8lhE/6BKoS a5iwN46mtz9dybnYyvLPkZBsJmE4xBJvTi6Hnp3VBhOCQOFgmqiIU0tiFWzgAI7tYBSBmF I5x/TnTooJwE8eL1uWk3GM2IBXjUL7JGCIutTzkYNopkXoeKnYuct2uha9WKZg== 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=1708684518; 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=RjWsjR6VEol2PDOWO++MPXS5YryV3Q8zsZTaTjlguR4=; b=dDSRHbyhLvQZ7NOOc0wzKa7oHSGGgfHuBnnlmiq0RJ7dbItewC696sRga6X39mRvxCiMM5 fLv5Mk6LnhuK0NpNRX7kVd1RKejpHHTX6c5ZojtKUZVBqsQxw96sUw3KUrsg+y9pKrRzwR fn9Qxy12o2opacRo8Ml8yvKkAUJBkiwwvBBgmCJIZwIAn3sqhKWRbnyMG5vyxLERPowCym MlPWUoEb6KVIBvSFlMaRlI6y00bMUDgD9Z84JcIuKRtBhSaxKAszXbfgyOA6CkoFs10BkJ 9RiYTMygGNvXSi2dlZqBsp/ejcq+XBgXRfDrd8FeZ/EHs1qPbMdDhvo/N/v1Zg== Received: from kenobi.freebsd.org (kenobi.freebsd.org [IPv6:2610:1c1:1:606c::50:1d]) (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 4Th5xf0Phwz1BLd for ; Fri, 23 Feb 2024 10:35:18 +0000 (UTC) (envelope-from bugzilla-noreply@freebsd.org) Received: from kenobi.freebsd.org ([127.0.1.5]) by kenobi.freebsd.org (8.15.2/8.15.2) with ESMTP id 41NAZIYb020652 for ; Fri, 23 Feb 2024 10:35:18 GMT (envelope-from bugzilla-noreply@freebsd.org) Received: (from www@localhost) by kenobi.freebsd.org (8.15.2/8.15.2/Submit) id 41NAZI7w020647 for doc@FreeBSD.org; Fri, 23 Feb 2024 10:35:18 GMT (envelope-from bugzilla-noreply@freebsd.org) X-Authentication-Warning: kenobi.freebsd.org: www set sender to bugzilla-noreply@freebsd.org using -f From: bugzilla-noreply@freebsd.org To: doc@FreeBSD.org Subject: [Bug 277238] kqueue(2), kevent(2) manpages are confusing and/or underspecified Date: Fri, 23 Feb 2024 10:35:18 +0000 X-Bugzilla-Reason: CC X-Bugzilla-Type: new X-Bugzilla-Watch-Reason: None X-Bugzilla-Product: Documentation X-Bugzilla-Component: Manual Pages X-Bugzilla-Version: Latest X-Bugzilla-Keywords: X-Bugzilla-Severity: Affects Many People X-Bugzilla-Who: jbe@magnetkern.de X-Bugzilla-Status: New X-Bugzilla-Resolution: X-Bugzilla-Priority: --- X-Bugzilla-Assigned-To: bugs@FreeBSD.org X-Bugzilla-Flags: X-Bugzilla-Changed-Fields: bug_id short_desc product version rep_platform op_sys bug_status bug_severity priority component assigned_to reporter cc Message-ID: Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Bugzilla-URL: https://bugs.freebsd.org/bugzilla/ Auto-Submitted: auto-generated List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D277238 Bug ID: 277238 Summary: kqueue(2), kevent(2) manpages are confusing and/or underspecified Product: Documentation Version: Latest Hardware: Any OS: Any Status: New Severity: Affects Many People Priority: --- Component: Manual Pages Assignee: bugs@FreeBSD.org Reporter: jbe@magnetkern.de CC: doc@FreeBSD.org The manpages of kqueue(2) and kevent(2) are difficult to understand and potentially underspecified. In particular: 1. It is not elaborated what is the purpose of EV_ENABLE and EV_DISABLE in comparison to temporarily deleting an event with EV_DELETE. Is it just a performance issue or are there other effects when disabling an event temporarily with EV_DISABLE (or EV_DISPATCH) opposed to using EV_DELETE (or EV_ONESHOT). 2. What does EV_RECEIPT exactly do? What does the phrase "remaining space in eventlist" refer to? Is it necessary and sufficient(!?) that the output buf= fer has the exact same length as the number of elements in the input buffer that have EV_RECEIPT set when doing bulk changes and wanting to avoid draining o= ther potentially pending events? This is not clarified. 3. What is the purpose of not specifying EV_CLEAR for those events where it= 's not implicitly enabled? How long would an event be reported as pending? Unt= il the event is disabled? Until the event is deleted? Is there any way to "acknowledge" the event? And which events in particular "report state transitions instead of the current state", i.e. for which events is EV_CLEAR particularly useful and how is it useful? 4. The list of flags does not distinguish between input and output flags. T= his also has caused previous confusion in the example code (#240015). Is it cor= rect that a flag is either used as an input flag (in changelist[]) or as an outp= ut flag (in eventlist[]), or is there a case when a flag can be set in either = of those? Why are there not two lists for flags in the manpage: one for the in= put flags and one for the output flags? 5. Monitoring a process to exit (using EVFILT_PROC with NOTE_EXIT) results = in the process' exit status (that may be checked with WIFEXITED and related macros) to be returned in the data field of the struct kevent in the eventl= ist. However, the manpage is unclear about whether the process' status is collec= ted or not; i.e. it is unclear if zombie processes would be created if that sta= tus in the data field is used and there is no further call to waitpid(). Accord= ing to my tests, zombies would be created if waitpid() is not explicitly invoke= d. If that is the case, it should be clarified in the manpage. 6. If an EVFILT_PROC / NOTE_EXIT event fires, the event seems to be automatically removed from the queue, i.e. a subsequent EV_DELETE would ret= urn with an ENOENT error. Thus, the behavior seems to be like EV_ONESHOT is explicitly set. While this behavior may be useful, it is not documented and thus could result in unexpected errors. 7. The section on EVFILT_TIMER does not specify which timer is used for absolute times (NOTE_ABSTIME), i.e. whether CLOCK_REALTIME, CLOCK_MONOTONIC= , or CLOCK_UPTIME is used. The manpage speaks of "non-monotonic timers". Does th= is mean NOTE_ABSTIME uses CLOCK_MONOTONIC? Or does it refer to relative timers (where CLOCK_MONOTONIC is used internally)? When exactly is a timer "non-monotonic" and what does that mean? What effect does the (then implici= tly set) EV_CLEAR flag have on timers? Overall, it's currently very hard to use kqueue/kevent solely based on the information on the manpage. This issue report has been filed after I asked on the forum about it: https://forums.freebsd.org/threads/how-to-use-kevent-confused-by-manpage.92= 419/ --=20 You are receiving this mail because: You are on the CC list for the bug.=