git: 7616d35f91cb - stable/13 - ptrace(2): explain how to select specific thread to operate on

The branch stable/13 has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=7616d35f91cb0d4f1a741fb385078581096f6953

commit 7616d35f91cb0d4f1a741fb385078581096f6953
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-12-05 22:43:18 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2023-01-20 03:20:45 +0000

    ptrace(2): explain how to select specific thread to operate on
    
    Tested by:      pho
    
    (cherry picked from commit 0e07241c372d7352537a4a786c96a580a721be3c)
---
 lib/libc/sys/ptrace.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2
index 74bf646efd3c..b107dcef97ae 100644
--- a/lib/libc/sys/ptrace.2
+++ b/lib/libc/sys/ptrace.2
@@ -122,6 +122,25 @@ Kernel drops any
 signals queued to the traced children, which could be either generated by
 not yet consumed debug events, or sent by other means, the later should
 not be done anyway.
+.Sh SELECTING THE TARGET
+The
+.Fa pid
+argument of the call specifies the target on which to perform
+the requested operation.
+For operations affecting the global process state, the process ID
+is typically passed there.
+Similarly, for operations affecting only a thread, the thread ID
+needs to be passed.
+.Pp
+Still, for global operations, the ID of any thread can be used as the
+target, and system will perform the request on the process owning
+that thread.
+If a thread operation got the process ID as
+.Fa pid ,
+the system randomly selects a thread from among the threads owned
+by the process.
+For single-threaded processes there is no difference between specifying
+process or thread ID as the target.
 .Sh DISABLING PTRACE
 The
 .Nm