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