From 07d78399eb7994d45338f58a331dae9fb8fe1023 Mon Sep 17 00:00:00 2001
From: Yan-Hao Wang <bses30074@gmail.com>
Date: Fri, 6 Dec 2024 09:23:35 -0700
Subject: [PATCH] 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 48e34d65d6a..ebcf7a56515 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