Make --decode-pids usage more in line with --decode-fds

Enable -e decode-pids syntax and document it in the man page.

* src/filter_qualify.c (qual_options): Add "decode-pid" and "decode-pids"
that associated with qualify_decode_pid decoder.
* tests/options-syntax.test: Add option syntax checks for --decode-pids
and -e decode-pids.
* doc/strace.1.in (.BI "\-e " expr): Document decode-pids/decode-pid as
a possible argument.
(.SS Output format): Document -e decode-pids/--decode-pids.

Complements: v5.14-184-gbac60e6a0 "Use traditional parser for --decode-pids option"

3 files changed, 36 insertions, 0 deletions

diff --git a/doc/strace.1.in b/doc/strace.1.in
index 66e5448e9..91a0075ec 100644
--- a/doc/strace.1.in
+++ b/doc/strace.1.in
@@ -260,6 +260,7 @@ is one of
 .BR status ,
 .BR quiet " (or " silent " or " silence " or " q ),
 .BR decode\-fds " (or " decode\-fd ),
+.BR decode\-pids " (or " decode\-pid ),
 or
 .BR kvm ,
 and
@@ -869,6 +870,25 @@ Print character/block device numbers.
 Print PIDs associated with pidfd file descriptors.
 .RE
 .TP
+\fB\-e\ decode\-pids\fR=\,\fIset\fR
+.TQ
+\fB\-\-decode\-pids\fR=\,\fIset\fR
+Decode various information associated with process IDs
+(and also thread IDs, process group IDs, and session IDs).
+The default is
+.BR decode\-pids = none .
+.I set
+can include the following elements:
+.RS
+.TP 8
+.B comm
+Print command names associated with thread or process IDs.
+.TQ
+.B pidns
+Print thread, process, process group, and session IDs in strace's PID namespace
+if the tracee is in a different PID namespace.
+.RE
+.TP
 .BR "\-e\ kvm" = vcpu
 .TQ
 .BR "\-\-kvm" = vcpu
diff --git a/src/filter_qualify.c b/src/filter_qualify.c
index 92e3c93e0..e147b1982 100644
--- a/src/filter_qualify.c
+++ b/src/filter_qualify.c
@@ -651,6 +651,8 @@ static const struct qual_options {
 	{ "kvm",	qualify_kvm	},
 	{ "decode-fd",	qualify_decode_fd },
 	{ "decode-fds",	qualify_decode_fd },
+	{ "decode-pid",	qualify_decode_pid },
+	{ "decode-pids", qualify_decode_pid },
 };
 
 void
diff --git a/tests/options-syntax.test b/tests/options-syntax.test
index 5924ade85..e803efc7b 100755
--- a/tests/options-syntax.test
+++ b/tests/options-syntax.test
@@ -222,7 +222,21 @@ check_h 'deprecated option -F ignored
 check_e "invalid system call '/getcwd@ohmy'" -e trace=/getcwd@ohmy
 check_e "invalid -e kvm= argument: 'chdir'" -e kvm=chdir
 check_e "invalid -e kvm= argument: 'chdir'" --kvm=chdir
+
+check_h "must have PROG [ARGS] or -p PID" -e decode-pid=all
+check_h "must have PROG [ARGS] or -p PID" --decode-pid=none
+check_h "must have PROG [ARGS] or -p PID" -e decode-pids=comm
+check_h "must have PROG [ARGS] or -p PID" --decode-pid=pidns,comm
+check_h "must have PROG [ARGS] or -p PID" -e decode-pid=\!pidns
+check_h "must have PROG [ARGS] or -p PID" --decode-pids=\!comm,pidns
+check_h "must have PROG [ARGS] or -p PID" -Y -e decode-pids=\!comm,pidns
+check_h "must have PROG [ARGS] or -p PID" --decode-pids=\!comm,pidns -Y
+check_h "must have PROG [ARGS] or -p PID" --pidns-translation -e decode-pids=\!comm,pidns -Y
+check_h "must have PROG [ARGS] or -p PID" --decode-pids=\!comm,pidns --pidns-translation
+check_e "invalid decode-pids ''" --decode-pids=
+check_e "invalid decode-pids ''" -e decode-pids=
 check_e "invalid decode-pids 'chdir'" --decode-pids=chdir
+check_e "invalid decode-pids 'gettid'" -e decode-pid=comm,gettid
 
 case "$STRACE_NATIVE_ARCH" in
 x86_64)