From 2f6565681e627d11dde0177503100669df020684 Mon Sep 17 00:00:00 2001
From: Jerome Marchand <jmarchan@redhat.com>
Date: Sun, 28 Aug 2022 07:44:01 +0200
Subject: [PATCH] Fix some documentation issues (#4197)

* compactsnoop-manpage: fix the name of the tool in the NAME section
In its manpage, compactsnoop tools is called compacstall in the NAME
section. I don't know where that name comes from, but it should be
compactsnoop.

* dirtop-manpage: use '-d' option in the EXAMPLES section
The mandatory '-d' option of dirtop is missing in the EXAMPLES
section. Copy it from the usage message. Also remove '.py' suffixes.

* funclatency-manpage: fix typo in one of the examples
There is a spurious colon in one of the manpage examples. Remove it.

* tools/killsnoop: add '-s' option in the synopsis of the example file
Commit 33c8b1ac ("Update man page and example file") added '-s' option
to the manpage and an example in the example file, but missed the
sysnopsis in that later case.

* trace-manpage: add missing options (-c,-n,-f and -B) to the synopsis
Copy the full sysopsis from the usage message.

* tcptracer-manpage: add missing '-t' option in the manpage
Add '-t' option to the synopsis and description.

* tcpsubnet-manpage: remove '--ebpf' option from the manpage
This option is explicitly suppressed in argparse and no manpage of
other tools mentions it.

* manpages: remove '.py' suffix from the synopsis of some *snoop tools
Other manpages don't show the suffix, nor do the usage messages.
---
 man/man8/bindsnoop.8        | 2 +-
 man/man8/compactsnoop.8     | 4 ++--
 man/man8/dirtop.8           | 8 ++++----
 man/man8/drsnoop.8          | 2 +-
 man/man8/funclatency.8      | 2 +-
 man/man8/opensnoop.8        | 2 +-
 man/man8/tcpsubnet.8        | 5 +----
 man/man8/tcptracer.8        | 5 ++++-
 man/man8/trace.8            | 6 ++++--
 tools/killsnoop_example.txt | 2 ++
 10 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/man/man8/bindsnoop.8 b/man/man8/bindsnoop.8
index f8fa1850..0eb42ccb 100644
--- a/man/man8/bindsnoop.8
+++ b/man/man8/bindsnoop.8
@@ -2,7 +2,7 @@
 .SH NAME
 bindsnoop \- Trace bind() system calls.
 .SH SYNOPSIS
-.B bindsnoop.py [\fB-h\fP] [\fB-w\fP] [\fB-t\fP] [\fB-p\fP PID] [\fB-P\fP PORT] [\fB-E\fP] [\fB-U\fP] [\fB-u\fP UID] [\fB--count\fP] [\fB--cgroupmap MAP\fP] [\fB--mntnsmap MNTNSMAP\fP]
+.B bindsnoop [\fB-h\fP] [\fB-w\fP] [\fB-t\fP] [\fB-p\fP PID] [\fB-P\fP PORT] [\fB-E\fP] [\fB-U\fP] [\fB-u\fP UID] [\fB--count\fP] [\fB--cgroupmap MAP\fP] [\fB--mntnsmap MNTNSMAP\fP]
 .SH DESCRIPTION
 bindsnoop reports socket options set before the bind call that would impact this system call behavior.
 .PP
diff --git a/man/man8/compactsnoop.8 b/man/man8/compactsnoop.8
index a2933d7a..e9cde0ce 100644
--- a/man/man8/compactsnoop.8
+++ b/man/man8/compactsnoop.8
@@ -1,8 +1,8 @@
 .TH compactsnoop 8  "2019-11-1" "USER COMMANDS"
 .SH NAME
-compactstall \- Trace compact zone events. Uses Linux eBPF/bcc.
+compactsnoop \- Trace compact zone events. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B compactsnoop.py [\-h] [\-T] [\-p PID] [\-d DURATION] [\-K] [\-e]
+.B compactsnoop [\-h] [\-T] [\-p PID] [\-d DURATION] [\-K] [\-e]
 .SH DESCRIPTION
 compactsnoop traces the compact zone events, showing which processes are
 allocing pages with memory compaction. This can be useful for discovering
diff --git a/man/man8/dirtop.8 b/man/man8/dirtop.8
index cc61a676..eaa0c0c4 100644
--- a/man/man8/dirtop.8
+++ b/man/man8/dirtop.8
@@ -55,19 +55,19 @@ Number of interval summaries.
 .TP
 Summarize block device I/O by directory, 1 second screen refresh:
 #
-.B dirtop.py
+.B dirtop -d '/hdfs/uuid/*/yarn'
 .TP
 Don't clear the screen, and top 8 rows only:
 #
-.B dirtop.py -Cr 8
+.B dirtop -d '/hdfs/uuid/*/yarn' -Cr 8
 .TP
 5 second summaries, 10 times only:
 #
-.B dirtop.py 5 10
+.B dirtop  -d '/hdfs/uuid/*/yarn' 5 10
 .TP
 Report read & write IOs generated in mutliple yarn and data directories:
 #
-.B dirtop.py -d '/hdfs/uuid/*/yarn,/hdfs/uuid/*/data'
+.B dirtop -d '/hdfs/uuid/*/yarn,/hdfs/uuid/*/data'
 .SH FIELDS
 .TP
 loadavg:
diff --git a/man/man8/drsnoop.8 b/man/man8/drsnoop.8
index 90ca901f..8fb3789a 100644
--- a/man/man8/drsnoop.8
+++ b/man/man8/drsnoop.8
@@ -2,7 +2,7 @@
 .SH NAME
 drsnoop \- Trace direct reclaim events. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B drsnoop.py [\-h] [\-T] [\-U] [\-p PID] [\-t TID] [\-u UID] [\-d DURATION] [-n name] [-v]
+.B drsnoop [\-h] [\-T] [\-U] [\-p PID] [\-t TID] [\-u UID] [\-d DURATION] [-n name] [-v]
 .SH DESCRIPTION
 drsnoop trace direct reclaim events, showing which processes are allocing pages 
 with direct reclaiming. This can be useful for discovering when allocstall (/p-
diff --git a/man/man8/funclatency.8 b/man/man8/funclatency.8
index 9012b832..f96f6098 100644
--- a/man/man8/funclatency.8
+++ b/man/man8/funclatency.8
@@ -89,7 +89,7 @@ Print the BPF program (for debugging purposes).
 .TP
 Time vfs_read() for process ID 181 only:
 #
-.B funclatency \-p 181 vfs_read:
+.B funclatency \-p 181 vfs_read
 .TP
 Time both vfs_fstat() and vfs_fstatat() calls, by use of a wildcard:
 #
diff --git a/man/man8/opensnoop.8 b/man/man8/opensnoop.8
index fee83263..d1888772 100644
--- a/man/man8/opensnoop.8
+++ b/man/man8/opensnoop.8
@@ -2,7 +2,7 @@
 .SH NAME
 opensnoop \- Trace open() syscalls. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B opensnoop.py [\-h] [\-T] [\-U] [\-x] [\-p PID] [\-t TID] [\-u UID]
+.B opensnoop [\-h] [\-T] [\-U] [\-x] [\-p PID] [\-t TID] [\-u UID]
              [\-d DURATION] [\-n NAME] [\-e] [\-f FLAG_FILTER]
              [--cgroupmap MAPPATH] [--mntnsmap MAPPATH]
 .SH DESCRIPTION
diff --git a/man/man8/tcpsubnet.8 b/man/man8/tcpsubnet.8
index 525b8082..ad5f1be1 100644
--- a/man/man8/tcpsubnet.8
+++ b/man/man8/tcpsubnet.8
@@ -2,7 +2,7 @@
 .SH NAME
 tcpsubnet \- Summarize and aggregate IPv4 TCP traffic by subnet.
 .SH SYNOPSIS
-.B tcpsubnet [\-h] [\-v] [\--ebpf] [\-J] [\-f FORMAT] [\-i INTERVAL] [subnets]
+.B tcpsubnet [\-h] [\-v] [\-J] [\-f FORMAT] [\-i INTERVAL] [subnets]
 .SH DESCRIPTION
 This tool summarizes and aggregates IPv4 TCP sent to the subnets
 passed in argument and prints to stdout on a fixed interval.
@@ -35,9 +35,6 @@ Interval between updates, seconds (default 1).
 Format output units. Supported values are bkmBKM. When using
 kmKM the output will be rounded to floor.
 .TP
-\--ebpf
-Prints the BPF program.
-.TP
 subnets
 Comma separated list of subnets. Traffic will be categorized
 in theses subnets. Order matters.
diff --git a/man/man8/tcptracer.8 b/man/man8/tcptracer.8
index 59240f4b..19a6164d 100644
--- a/man/man8/tcptracer.8
+++ b/man/man8/tcptracer.8
@@ -2,7 +2,7 @@
 .SH NAME
 tcptracer \- Trace TCP established connections. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B tcptracer [\-h] [\-v] [\-p PID] [\-N NETNS] [\-\-cgroupmap MAPPATH] [--mntnsmap MAPPATH] [\-4 | \-6]
+.B tcptracer [\-h] [\-v] [-t] [\-p PID] [\-N NETNS] [\-\-cgroupmap MAPPATH] [--mntnsmap MAPPATH] [\-4 | \-6]
 .SH DESCRIPTION
 This tool traces established TCP connections that open and close while tracing,
 and prints a line of output per connect, accept and close events. This includes
@@ -23,6 +23,9 @@ Print usage message.
 \-v
 Print full lines, with long event type names and network namespace numbers.
 .TP
+\-t
+Include timestamp on output
+.TP
 \-p PID
 Trace this process ID only (filtered in-kernel).
 .TP
diff --git a/man/man8/trace.8 b/man/man8/trace.8
index c4417e5f..64a5e799 100644
--- a/man/man8/trace.8
+++ b/man/man8/trace.8
@@ -2,9 +2,11 @@
 .SH NAME
 trace \- Trace a function and print its arguments or return value, optionally evaluating a filter. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B trace [-h] [-b BUFFER_PAGES] [-p PID] [-L TID] [--uid UID] [-v] [-Z STRING_SIZE] [-S] [-s SYM_FILE_LIST]
-         [-M MAX_EVENTS] [-t] [-u] [-T] [-C] [-K] [-U] [-a] [-I header] [-A]
+.B trace [-h] [-b BUFFER_PAGES] [-p PID] [-L TID] [--uid UID] [-v] [-Z STRING_SIZE] [-S] [-M MAX_EVENTS] [-t]
+         [-u] [-T] [-C] [-c CGROUP_PATH] [-n NAME] [-f MSG_FILTER] [-B] [-s SYM_FILE_LIST] [-K] [-U] [-a]
+         [-I header] [-A]
          probe [probe ...]
+
 .SH DESCRIPTION
 trace probes functions you specify and displays trace messages if a particular
 condition is met. You can control the message format to display function
diff --git a/tools/killsnoop_example.txt b/tools/killsnoop_example.txt
index 7746f2a0..038d09c6 100644
--- a/tools/killsnoop_example.txt
+++ b/tools/killsnoop_example.txt
@@ -27,6 +27,8 @@ Trace signals issued by the kill() syscall
   -h, --help         show this help message and exit
   -x, --failed       only show failed kill syscalls
   -p PID, --pid PID  trace this PID only
+  -s SIGNAL, --signal SIGNAL
+                        trace this signal only
 
 examples:
     ./killsnoop           # trace all kill() signals
-- 
2.38.1