[iproute] ss: add detail explains of -m, -o, -e and -i options in ss man page

commit 340a45f79395144bd14fdf9be1904c0036456b6e
Author: yupeng <yupeng0921@gmail.com>
Date:   Tue Oct 24 23:55:29 2017 +0000

    add additional explain in ss man page

    Add detail explains of -m, -o, -e and -i options, which are not
documented anywhere

    Signed-off-by: Peng Yu <yupeng0921@gmail.com>

+how long time since the last ack received, the unit is millisecond
+
+.B pacing_rate <pacing_rate>bps/<max_pacing_rate>bps
+the pacing rate and max pacing rate
+
+.B rcv_space:<rcv_space>
+a helper variable for TCP internal auto tunning socket receive buffer
+
 .SH USAGE EXAMPLES
 .TP
 .B ss -t -a

On Tue, 24 Oct 2017 17:13:30 -0700
peng yu <yupeng0921@gmail.com> wrote:

> +.SH Additional explain of -m, -o, -e and -i options
> +Some fields may have different meanings if the netowrk protocl is
> different. Below explain focus on tcp protocol.

Thank you for the patch.
Some formatting and style changes should be done before I accept it.
First, the SECTIONS in man pages are usually terse and all upper case
(back to Unix man page style).  Why not just put the additional text as a second
paragraph on the part that explains the first option?

Also, please run all manual page submissions through a spell checker.
The ispell program is one option.

Please resubmit

peng yu <yupeng0921@gmail.com> writes:

> commit 340a45f79395144bd14fdf9be1904c0036456b6e
> Author: yupeng <yupeng0921@gmail.com>
> Date:   Tue Oct 24 23:55:29 2017 +0000
>
>     add additional explain in ss man page
>
>     Add detail explains of -m, -o, -e and -i options, which are not
> documented anywhere
>
>     Signed-off-by: Peng Yu <yupeng0921@gmail.com>
>
> diff --git a/man/man8/ss.8 b/man/man8/ss.8
> index 3bec97f..4597733 100644
> --- a/man/man8/ss.8
> +++ b/man/man8/ss.8
> @@ -176,6 +176,147 @@ states except for
>  - opposite to
>  .B bucket
>
> +.SH Additional explain of -m, -o, -e and -i options
> +Some fields may have different meanings if the netowrk protocl is
> different. Below explain focus on tcp protocol.
> +.TP
> +.B -m option
> +skmem:(r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,f<fwd_alloc>,w<wmem_queued>,o<opt_mem>,bl<back_log>)
> +
> +.B <rmem_alloc>
> +the memory allocated for receiving package
> +

Need to change 'package' to 'packet' in multiple places.

[...]

Thanks for your suggestion, below is a new patch. What I did:
1. change all 'package' to 'packet'
2. put my additional text as second paragraphs of the original options.
3. checked the man page by aspell
If anything else need to fix, please let me know.


commit 9803d27de31028733de789495d78ff7a39385009
Author: yupeng <yupeng0921@gmail.com>
Date:   Wed Oct 25 21:12:21 2017 +0000

    add additional explain in ss man page

    Add detail explains of -m, -o, -e and -i options, which are not
    documented anywhere

    Signed-off-by: Peng Yu <yupeng0921@gmail.com>

diff --git a/man/man8/ss.8 b/man/man8/ss.8
index 3bec97f..401ae3e 100644
--- a/man/man8/ss.8
+++ b/man/man8/ss.8
@@ -37,19 +37,152 @@ Display both listening and non-listening (for TCP
this means established connect
 Display only listening sockets (these are omitted by default).
 .TP
 .B \-o, \-\-options
-Show timer information.
+Show timer information. For tcp protocol, the output format is:
+.br
+timer:(<timer_name>,<expire_time>,<retrans>)
+.br
+.B <timer_name>
+the name of the timer, there are five kind of timer names:
+.RS
+.RS
+.BR on ": means one of these timers: tcp retrans timer, tcp early
retrans timer and tail loss probe timer"
+.br
+.BR keepalive ": tcp keep alive timer"
+.br
+.BR timewait ": timewait stage timer"
+.br
+.BR persist ": zero window probe timer"
+.br
+.BR unknown ": none of the above timers"
+.RE
+.B <expire_time>
+how long time the timer will expire
+.br
+.B <retrans>
+how many times the retran occurs
+.RE
 .TP
 .B \-e, \-\-extended
-Show detailed socket information
+Show detailed socket information. The output format is:
+.br
+uid:<uid_number> ino:<inode_number> sk:<cookie>
+.br
+.B <uid_number>
+the user id the socket belongs to
+.br
+.B <inode_number>
+the socket's inode number in VFS
+.br
+.B <cookie>
+an uuid of the socket
+
 .TP
 .B \-m, \-\-memory
-Show socket memory usage.
+Show socket memory usage. The output format is:
+.br
+skmem:(r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,f<fwd_alloc>,w<wmem_queued>,o<opt_mem>,bl<back_log>)
+.B <rmem_alloc>
+the memory allocated for receiving packet
+.br
+.B <rcv_buf>
+the total memory can be allocated for receiving packet
+.br
+.B <wmem_alloc>
+the memory used for sending packet (which has been sent to layer 3)
+.br
+.B <snd_buf>
+the total memory can be allocated for sending packet
+.br
+.B <fwd_alloc>
+the memory allocated by the socket as cache, but not used for
receiving/sending packet yet. If need memory to send/receive packet,
the memory in this cache will be used before allocate additional
memory.
+.br
+.B <wmem_queued>
+The memory allocated for sending packet (which has not been sent to layer 3)
+.br
+.B <opt_mem>
+The memory used for storing socket option, e.g., the key for TCP MD5 signature
+.br
+.B <back_log>
+The memory used for the sk backlog queue. On a process context, if
the process is receiving packet, and a new packet is received, it will
be put into the sk backlog queue, so it can be received by the process
immediately
 .TP
 .B \-p, \-\-processes
 Show process using socket.
 .TP
 .B \-i, \-\-info
-Show internal TCP information.
+Show internal TCP information. Below fields may appear:
+.br
+.B ts
+show string "ts" if the timestamp option is set
+.br
+.B sack
+show string "sack" if the sack option is set
+.br
+.B ecn
+show string "ecn" if the explicit congestion notification option is set
+.br
+.B ecnseen
+show string "ecnseen" if the saw ecn flag is found in received packets
+.br
+.B fastopen
+show string "fastopen" if the fastopen option is set
+.br
+.B cong_alg
+the congestion algorithm name, the default congestion algorithm is "cubic"
+.br
+.B wscale:<snd_wscale>:<rcv_wscale>
+if window scale option is used, this field shows the send scale
factory and receive scale factory
+.br
+.B rto:<icsk_rto>
+tcp re-transmission timeout value, the unit is millisecond
+.br
+.B backoff:<icsk_backoff>
+used for exponential backoff re-transmission, the actual
re-transmission timeout value is icsk_rto << icsk_backoff
+.br
+.B rtt:<rtt>/<rttvar>
+rtt is the average round trip time, rttvar is the mean deviation of
rtt, their units are millisecond
+.br
+.B ato:<ato>
+ack timeout, unit is millisecond, used for delay ack mode
+.br
+.B mss:<mss>
+max segment size
+.br
+.B cwnd:<cwnd>
+congestion window size
+.br
+.B ssthresh:<ssthresh>
+tcp congestion window slow start threshold
+.br
+.B bytes_acked:<bytes_acked>
+bytes acked
+.br
+.B bytes_received:<bytes_received>
+bytes received
+.br
+.B segs_out:<segs_out>
+segments sent out
+.br
+.B segs_in:<segs_in>
+segments received
+.br
+.B send <send_bps>bps
+egress bps
+.br
+.B lastsnd:<lastsnd>
+how long time since the last packet sent, the unit is millisecond
+.br
+.B lastrcv:<lastrcv>
+how long time since the last packet received, the unit is millisecond
+.br
+.B lastack:<lastack>
+how long time since the last ack received, the unit is millisecond
+.br
+.B pacing_rate <pacing_rate>bps/<max_pacing_rate>bps
+the pacing rate and max pacing rate
+.br
+.B rcv_space:<rcv_space>
+a helper variable for TCP internal auto tuning socket receive buffer
+
 .TP
 .B \-K, \-\-kill
 Attempts to forcibly close sockets. This option displays sockets that are

2017-10-25 8:06 GMT-07:00 Roman Mashak <mrv@mojatatu.com>:
> peng yu <yupeng0921@gmail.com> writes:
>
>> commit 340a45f79395144bd14fdf9be1904c0036456b6e
>> Author: yupeng <yupeng0921@gmail.com>
>> Date:   Tue Oct 24 23:55:29 2017 +0000
>>
>>     add additional explain in ss man page
>>
>>     Add detail explains of -m, -o, -e and -i options, which are not
>> documented anywhere
>>
>>     Signed-off-by: Peng Yu <yupeng0921@gmail.com>
>>
>> diff --git a/man/man8/ss.8 b/man/man8/ss.8
>> index 3bec97f..4597733 100644
>> --- a/man/man8/ss.8
>> +++ b/man/man8/ss.8
>> @@ -176,6 +176,147 @@ states except for
>>  - opposite to
>>  .B bucket
>>
>> +.SH Additional explain of -m, -o, -e and -i options
>> +Some fields may have different meanings if the netowrk protocl is
>> different. Below explain focus on tcp protocol.
>> +.TP
>> +.B -m option
>> +skmem:(r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,f<fwd_alloc>,w<wmem_queued>,o<opt_mem>,bl<back_log>)
>> +
>> +.B <rmem_alloc>
>> +the memory allocated for receiving package
>> +
>
> Need to change 'package' to 'packet' in multiple places.
>
> [...]
>

Hi Yupeng,

On Wed, Oct 25, 2017 at 02:20:25PM -0700, peng yu wrote:
> Thanks for your suggestion, below is a new patch. What I did:
> 1. change all 'package' to 'packet'
> 2. put my additional text as second paragraphs of the original options.
> 3. checked the man page by aspell
> If anything else need to fix, please let me know.

Thanks for quickly addressing all mentioned issues! Though here come a
few more (sorry):

Your MUA mangled the patch so it doesn't apply cleanly. Please in
future, use 'git format-patch' and 'git send-email' to avoid this. You
can still add comments to it (like those lines above) by inserting them
below the '---' marker (and above the diff-stat) format-patch usually
inserts. This way these comments won't be included in the commit
message.

More inline:

> commit 9803d27de31028733de789495d78ff7a39385009
> Author: yupeng <yupeng0921@gmail.com>
> Date:   Wed Oct 25 21:12:21 2017 +0000
> 
>     add additional explain in ss man page
> 
>     Add detail explains of -m, -o, -e and -i options, which are not
>     documented anywhere
> 
>     Signed-off-by: Peng Yu <yupeng0921@gmail.com>

You have something set up inconsistently regarding your name here: In
'Author' above it's "yupeng" while in SoB and From address it's "Peng
Yu". This is just a minor nit, but if you set it up consistently, the
submitted patches will appear more clean.

> diff --git a/man/man8/ss.8 b/man/man8/ss.8
> index 3bec97f..401ae3e 100644
> --- a/man/man8/ss.8
> +++ b/man/man8/ss.8
> @@ -37,19 +37,152 @@ Display both listening and non-listening (for TCP
> this means established connect

This is an example of where your MUA mangled the patch, the line above
shouldn't be broken.

>  Display only listening sockets (these are omitted by default).
>  .TP
>  .B \-o, \-\-options
> -Show timer information.
> +Show timer information. For tcp protocol, the output format is:
> +.br

I suggest replacing that explicit line break with:
.RS
.P

> +timer:(<timer_name>,<expire_time>,<retrans>)
> +.br

And this one with:
.P
.TP

> +.B <timer_name>
> +the name of the timer, there are five kind of timer names:
> +.RS
> +.RS

Then drop one of the .RS here.

> +.BR on ": means one of these timers: tcp retrans timer, tcp early
> retrans timer and tail loss probe timer"
> +.br
> +.BR keepalive ": tcp keep alive timer"
> +.br
> +.BR timewait ": timewait stage timer"
> +.br
> +.BR persist ": zero window probe timer"
> +.br
> +.BR unknown ": none of the above timers"
> +.RE

Insert .TP here.

> +.B <expire_time>
> +how long time the timer will expire
> +.br

Replace .br here with .TP and change the other additions equivalently. I
think the result is more readable, what do you think?

Thanks, Phil