pkill: better document ancestor-hiding

More prominently note that we'll hide ancestors in the first two
paragraphs that provide an overview of pkill/pgrep.  It also seems
worth noting in the description of -a that we won't ever unhide the
pgrep/pkill command itself, as mypid is skipped in all process iteration
by way of PSKIP().

Reviewed by:	allanjude, des
Sponsored by:	Klara, Inc.
Differential Revision:	https://reviews.freebsd.org/D51009

1 files changed, 18 insertions, 3 deletions

diff --git a/bin/pkill/pkill.1 b/bin/pkill/pkill.1
index f06b448b5df8..40abbba96362 100644
--- a/bin/pkill/pkill.1
+++ b/bin/pkill/pkill.1
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 5, 2020
+.Dd June 24, 2025
 .Dt PKILL 1
 .Os
 .Sh NAME
@@ -71,12 +71,17 @@ The
 .Nm pgrep
 command searches the process table on the running system and prints the
 process IDs of all processes that match the criteria given on the command
-line.
+line, excluding itself and all direct ancestors unless the
+.Fl a
+option is specified.
 .Pp
 The
 .Nm pkill
 command searches the process table on the running system and signals all
-processes that match the criteria given on the command line.
+processes that match the criteria given on the command line, excluding itself
+and all direct ancestors unless the
+.Fl a
+option is specified.
 .Pp
 The following options are available:
 .Bl -tag -width ".Fl F Ar pidfile"
@@ -130,6 +135,16 @@ or
 process and all of its ancestors are excluded (unless
 .Fl v
 is used).
+Note that the
+.Fl a
+option will not
+.Dq unhide
+the
+.Nm pgrep
+or
+.Nm pkill
+process itself, even with
+.Fl v .
 .It Fl c Ar class
 Restrict matches to processes running with specified login class
 .Ar class .