netdev - Re: [patch] send.2: Add MSG

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <4d9952e8-040b-1bde-51a4-9687d6adb320@gmail.com>
Date:   Wed, 15 Sep 2021 22:13:55 +0200
From:   "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
To:     Wei Wang <weiwan@...gle.com>,
        Michael Kerrisk <mtk.manpages@...il.com>
Cc:     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

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



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