Date:   Fri, 12 Nov 2021 21:55:58 +0100
From:   "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
To:     Wei Wang <weiwan@...gle.com>
Cc:     Michael Kerrisk <mtk.manpages@...il.com>,
        linux-man@...r.kernel.org, netdev@...r.kernel.org,
        Yuchung Cheng <ycheng@...gle.com>,
        Neal Cardwell <ncardwell@...gle.com>,
        Eric Dumazet <edumazet@...gle.com>,
        "G. Branden Robinson" <g.branden.robinson@...il.com>
Subject: Re: [patch v3] tcp.7: Add description for TCP_FASTOPEN and
 TCP_FASTOPEN_CONNECT options

Hi Wei,

On 11/5/21 18:19, Wei Wang wrote:
> On Fri, Oct 15, 2021 at 3:12 PM Alejandro Colomar (man-pages)
> <alx.manpages@...il.com> wrote:
>>
>> Hi Wei,
>>
>> On 10/15/21 6:08 PM, Wei Wang wrote:
>>> On Fri, Sep 24, 2021 at 4:54 PM Wei Wang <weiwan@...gle.com> wrote:
>>>>
>>>> TCP_FASTOPEN socket option was added by:
>>>> commit 8336886f786fdacbc19b719c1f7ea91eb70706d4
>>>> TCP_FASTOPEN_CONNECT socket option was added by the following patch
>>>> series:
>>>> commit 065263f40f0972d5f1cd294bb0242bd5aa5f06b2
>>>> commit 25776aa943401662617437841b3d3ea4693ee98a
>>>> commit 19f6d3f3c8422d65b5e3d2162e30ef07c6e21ea2
>>>> commit 3979ad7e82dfe3fb94a51c3915e64ec64afa45c3
>>>> Add detailed description for these 2 options.
>>>> Also add descriptions for /proc entry tcp_fastopen and tcp_fastopen_key.
>>>>
>>>> Signed-off-by: Wei Wang <weiwan@...gle.com>

Sorry for the delay.
I have applied it now.
I also applied some minor changes on top of your patch
(see below).

Thanks!
Alex


---

     tcp.7: Minor tweaks to Wei's patch

     - wsfix
     - Boldface literals (see groff_man(7)).
     - Replace '\ ' by \~, per Branden's advise.
     - Use phrasal semantic newlines.
     - Put '...' in a C comment, to avoid interfering with groff.
       It has the side effect that the code example is pure C now.
     - Remove incorrect trailing '.IP'.

     Cc: Wei Wang <weiwan@...gle.com>
     Signed-off-by: Alejandro Colomar <alx.manpages@...il.com>

diff --git a/man7/tcp.7 b/man7/tcp.7
index 264e3ccc4..69d85c05a 100644
--- a/man7/tcp.7
+++ b/man7/tcp.7
@@ -423,26 +423,31 @@ option.
  .\" Since 2.4.0-test7
  Enable RFC\ 2883 TCP Duplicate SACK support.
  .TP
-.IR tcp_fastopen  " (Bitmask; default: 0x1; since Linux 3.7)"
-Enables RFC\ 7413 Fast Open support.
+.IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)"
+Enables RFC\~7413 Fast Open support.
  The flag is used as a bitmap with the following values:
  .RS
-.IP 0x1
+.TP
+.B 0x1
  Enables client side Fast Open support
-.IP 0x2
+.TP
+.B 0x2
  Enables server side Fast Open support
-.IP 0x4
+.TP
+.B 0x4
  Allows client side to transmit data in SYN without Fast Open option
-.IP 0x200
+.TP
+.B 0x200
  Allows server side to accept SYN data without Fast Open option
-.IP 0x400
+.TP
+.B 0x400
  Enables Fast Open on all listeners without
  .B TCP_FASTOPEN
  socket option
  .RE
  .TP
  .IR tcp_fastopen_key " (since Linux 3.7)"
-Set server side RFC\ 7413 Fast Open key to generate Fast Open cookie
+Set server side RFC\~7413 Fast Open key to generate Fast Open cookie
  when server side Fast Open support is enabled.
  .TP
  .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)"
@@ -1226,19 +1231,19 @@ This option should not be used in code intended 
to be
  portable.
  .TP
  .BR TCP_FASTOPEN " (since Linux 3.6)"
-This option enables Fast Open (RFC\ 7413) on the listener socket.
+This option enables Fast Open (RFC\~7413) on the listener socket.
  The value specifies the maximum length of pending SYNs
  (similar to the backlog argument in
  .BR listen (2)).
  Once enabled,
-the listener socket grants the TCP Fast Open cookie on incoming
-SYN with TCP Fast Open option.
+the listener socket grants the TCP Fast Open cookie
+on incoming SYN with TCP Fast Open option.
  .IP
  More importantly it accepts the data in SYN with a valid Fast Open cookie
  and responds SYN-ACK acknowledging both the data and the SYN sequence.
  .BR accept (2)
-returns a socket that is available for read and write when the handshake
-has not completed yet.
+returns a socket that is available for read and write
+when the handshake has not completed yet.
  Thus the data exchange can commence before the handshake completes.
  This option requires enabling the server-side support on sysctl
  .IR net.ipv4.tcp_fastopen
@@ -1252,18 +1257,18 @@ or
  below.
  .TP
  .BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)"
-This option enables an alternative way to perform Fast Open on the active
-side (client).
+This option enables an alternative way to perform Fast Open
+on the active side (client).
  When this option is enabled,
  .BR connect (2)
-would behave differently depending on if a Fast Open cookie is available
-for the destination.
+would behave differently depending on
+if a Fast Open cookie is available for the destination.
  .IP
  If a cookie is not available (i.e. first contact to the destination),
  .BR connect (2)
  behaves as usual by sending a SYN immediately,
-except the SYN would include an empty Fast Open cookie option to solicit a
-cookie.
+except the SYN would include an empty Fast Open cookie option
+to solicit a cookie.
  .IP
  If a cookie is available,
  .BR connect (2)
@@ -1297,13 +1302,12 @@ without
  .BR write (2)
  will cause the blocking socket to be blocked forever.
  .IP
-The application should  either set
+The application should either set
  .B TCP_FASTOPEN_CONNECT
  socket option before
  .BR write (2)
  or
-.BR sendmsg (2)
-,
+.BR sendmsg (2),
  or call
  .BR write (2)
  or
@@ -1322,11 +1326,10 @@ setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 
1, ...);
  connect(s);
  write(s); // write() should always follow connect() in order to 
trigger SYN to go out
  read(s)/write(s);
-...
+/* ... */
  close(s);
  .EE
  .in
-.IP
  .SS Sockets API
  TCP provides limited support for out-of-band data,
  in the form of (a single byte of) urgent data.

Powered by blists - more mailing lists