Date:   Thu, 16 Sep 2021 14:47:46 -0700
From:   Wei Wang <weiwan@...gle.com>
To:     "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
Cc:     Michael Kerrisk <mtk.manpages@...il.com>, netdev@...r.kernel.org,
        Yuchung Cheng <ycheng@...gle.com>,
        Eric Dumazet <edumazet@...gle.com>, linux-man@...r.kernel.org
Subject: Re: [patch] send.2: Add MSG_FASTOPEN flag

On Wed, Sep 15, 2021 at 1:14 PM Alejandro Colomar (man-pages)
<alx.manpages@...il.com> wrote:
>
> Hello, Wei!
>
> On 9/15/21 7:37 PM, Wei Wang wrote:
> > MSG_FASTOPEN flag is available since Linux 3.7. Add detailed description
> > in the manpage according to RFC7413.
> >
> > Signed-off-by: Wei Wang <weiwan@...gle.com>
> > Reviewed-by: Yuchung Cheng <ycheng@...gle.com>
> > Reviewed-by: Eric Dumazet <edumazet@...gle.com>
> > ---
> >   man2/send.2 | 27 +++++++++++++++++++++++++++
> >   1 file changed, 27 insertions(+)
> >
> > diff --git a/man2/send.2 b/man2/send.2
> > index fd28fed90..a40ae6214 100644
> > --- a/man2/send.2
> > +++ b/man2/send.2
> > @@ -252,6 +252,33 @@ data on sockets that support this notion (e.g., of type
> >   the underlying protocol must also support
> >   .I out-of-band
> >   data.
> > +.TP
> > +.BR MSG_FASTOPEN " (since Linux 3.7)"
> > +Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a
> > +combination of
> > +.BR connect (2)
> > +and
> > +.BR write (2)
>
> You should merge the comma with the above, to avoid an unwanted space:
>
> .BR write (2),
>
> > +, by performing an implicit
> > +.BR connect (2)
> > +operation. It blocks until the data is buffered and the handshake
>
> Please use semantic newlines.  See man-pages(7):
>
>     Use semantic newlines
>         In the source of a manual page,  new  sentences  should  be
>         started  on  new  lines, and long sentences should be split
>         into lines at clause breaks  (commas,  semicolons,  colons,
>         and  so on).  This convention, sometimes known as "semantic
>         newlines", makes it easier to see the  effect  of  patches,
>         which often operate at the level of individual sentences or
>         sentence clauses.
>
>
> This is especially important after a period, since groff(1) will usually
> put 2 spaces after it, but if you hardcode it like above, it will only
> print 1 space.
>
>
> > +has completed.
> > +For a non-blocking socket, it returns the number of bytes buffered
> > +and sent in the SYN packet. If the cookie is not available locally,
> > +it returns
> > +.B EINPROGRESS
>
> .BR EINPROGRESS ,
>
> > +, and sends a SYN with a Fast Open cookie request automatically.
> > +The caller needs to write the data again when the socket is connected.
> > +On errors, it returns the same errno as
>
> errno should be highlighted:
>
> .I errno
>
> Also, errno is set, not returned (as far as user space is concerned); so
> something along the lines of "errno is set by connect(2)" or "it can
> fail for the same reasons that connect(2) can".  Michael probably knows
> if there's a typical wording for this in the current manual pages, to
> add some consistency.
>
> BTW, should anything be added to the ERRORS section?
>
> > +.BR connect (2) > +if the handshake fails. This flag requires enabling TCP Fast Open
> > +client support on sysctl net.ipv4.tcp_fastopen.
>
> net.ipv4.tcp_fastopen should be highlighted:
>
> .IR net.ipv4.tcp_fastopen .
>
> > +
>
> Also from man-pages(7):
>
>     Formatting conventions (general)
>         Paragraphs should be separated by suitable markers (usually
>         either .PP or .IP).  Do not separate paragraphs using blank
>         lines, as this results in poor  rendering  in  some  output
>         formats (such as PostScript and PDF).
>
>
> Thanks!
>
> Alex

Thanks Alex! Will address those and send out v2.

>
>
>
> --
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Powered by blists - more mailing lists