git: 07d78399eb79 - main - pfind(9): Update to recent behavior

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=07d78399eb7994d45338f58a331dae9fb8fe1023

commit 07d78399eb7994d45338f58a331dae9fb8fe1023
Author:     Yan-Hao Wang <bses30074@gmail.com>
AuthorDate: 2024-12-06 16:23:35 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-12-06 16:47:31 +0000

    pfind(9): Update to recent behavior
    
    The pfind(9) manual page in FreeBSD contains outdated content, such as
    references to zpfind() and the zombproc list, which have already been
    removed.
    
    Instead, there are new functions available for process search, as
    defined in sys/proc.h:
    
    1. pfind_any(): Finds a process (including zombies) by its ID.
    
    2, pfind_any_locked(): Finds a process by its ID like pfind but doesn't
       find lock the process hash bucket. It assert the process hash bucket
       is lock or not.
    
    In the current FreeBSD implementation, the allproc list is used, and the
    `p->p_state` field can determine whether a process is a zombie or not.
    
    I have attempted to revise the pfind(9) manual page as shown in my
    patch. However, since English is not my native language, the
    documentation team may need to refine my patch or not use it. My primary
    goal is to highlight the outdated content for correction.
    
    [[ imp fixed a few markup bugs, tweaked language a little ]]
    
    PR: 283091
    Reviewed by: imp
---
 share/man/man9/pfind.9 | 49 +++++++++++++++++++++++++++----------------------
 1 file changed, 27 insertions(+), 22 deletions(-)

diff --git a/share/man/man9/pfind.9 b/share/man/man9/pfind.9
index 48e34d65d6ab..ebcf7a565150 100644
--- a/share/man/man9/pfind.9
+++ b/share/man/man9/pfind.9
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd July 11, 2001
+.Dd December 3, 2024
 .Dt PFIND 9
 .Os
 .Sh NAME
@@ -34,7 +34,9 @@
 .Ft "struct proc *"
 .Fn pfind "pid_t pid"
 .Ft "struct proc *"
-.Fn zpfind "pid_t pid"
+.Fn pfind_any "pid_t pid"
+.Ft "struct proc *"
+.Fn pfind_any_locked "pid_t pid"
 .Sh DESCRIPTION
 .Fn pfind
 takes a
@@ -47,36 +49,39 @@ is on the
 .Va allproc
 list.
 .Pp
-.Fn zpfind
+.Fn pfind_any
 takes a
 .Fa pid
 as its argument.
-If
-.Fn zpfind
-finds a process whose PID is equal to that of argument
-and is a zombie process, meaning that it must reside on the
-.Va zombproc
-list,
-.Fn zpfind
-returns a pointer to that
-.Vt proc
-structure.
+.Fn pfind_any
+searches the
+.Va allproc
+list and returns the first process whose PID matches and whose state is
+.Va PRS_ZOMBIE .
 .Pp
-Both
-.Fn pfind
+.Fn pfind_any_locked
+is similar to
+.Fn pfind_any
+,but it does not lock the process hash bucket
+for the given
+.Vt pid .
+Instead, it asserts the corresponding process hash bucket is already locked.
+All three functions
+.Fn pfind ,
+.Fn pfind_any ,
 and
-.Fn zpfind
+.Fn pgfind_any_locked
 lock the
 .Vt proc
-structure that is returned using
-.Fn PROC_LOCK "p" .
+structure before returning.
 .Sh RETURN VALUES
-.Fn pfind
+.Fn pfind ,
+.Fn pfind_any ,
 and
-.Fn zpfind
-return a pointer to a
+.Fn pfind_any_locked
+return pointer to a
 .Vt proc
-structure on success and a
+structure on success or
 .Dv NULL
 on failure.
 .Sh SEE ALSO