* [patch] send.2: Add MSG_FASTOPEN flag
@ 2021-09-15 17:37 Wei Wang
2021-09-15 20:13 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 4+ messages in thread
From: Wei Wang @ 2021-09-15 17:37 UTC (permalink / raw)
To: linux-man, Alejandro Colomar, Michael Kerrisk
Cc: netdev, Yuchung Cheng, Eric Dumazet
MSG_FASTOPEN flag is available since Linux 3.7. Add detailed description
in the manpage according to RFC7413.
Signed-off-by: Wei Wang <weiwan@google.com>
Reviewed-by: Yuchung Cheng <ycheng@google.com>
Reviewed-by: Eric Dumazet <edumazet@google.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)
+, by performing an implicit
+.BR connect (2)
+operation. It blocks until the data is buffered and the handshake
+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
+, 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
+.BR connect (2)
+if the handshake fails. This flag requires enabling TCP Fast Open
+client support on sysctl net.ipv4.tcp_fastopen.
+
+Refer to
+.B TCP_FASTOPEN_CONNECT
+socket option in
+.BR tcp (7)
+for an alternative approach.
.SS sendmsg()
The definition of the
.I msghdr
--
2.33.0.309.g3052b89438-goog
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [patch] send.2: Add MSG_FASTOPEN flag
2021-09-15 17:37 [patch] send.2: Add MSG_FASTOPEN flag Wei Wang
@ 2021-09-15 20:13 ` Alejandro Colomar (man-pages)
2021-09-16 21:47 ` Wei Wang
0 siblings, 1 reply; 4+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-15 20:13 UTC (permalink / raw)
To: Wei Wang, Michael Kerrisk; +Cc: netdev, Yuchung Cheng, Eric Dumazet, linux-man
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@google.com>
> Reviewed-by: Yuchung Cheng <ycheng@google.com>
> Reviewed-by: Eric Dumazet <edumazet@google.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/
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch] send.2: Add MSG_FASTOPEN flag
2021-09-15 20:13 ` Alejandro Colomar (man-pages)
@ 2021-09-16 21:47 ` Wei Wang
0 siblings, 0 replies; 4+ messages in thread
From: Wei Wang @ 2021-09-16 21:47 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Michael Kerrisk, netdev, Yuchung Cheng, Eric Dumazet, linux-man
On Wed, Sep 15, 2021 at 1:14 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.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@google.com>
> > Reviewed-by: Yuchung Cheng <ycheng@google.com>
> > Reviewed-by: Eric Dumazet <edumazet@google.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/
^ permalink raw reply [flat|nested] 4+ messages in thread
* [patch] send.2: Add MSG_FASTOPEN flag
@ 2017-02-01 1:37 Wei Wang
0 siblings, 0 replies; 4+ messages in thread
From: Wei Wang @ 2017-02-01 1:37 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, Wei Wang
From: Wei Wang <weiwan-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org>
Add MSG_FASTOPEN flag description for send.2
Signed-off-by: Wei Wang <weiwan-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org>
---
man2/send.2 | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/man2/send.2 b/man2/send.2
index 7f2340666..4b1902f75 100644
--- a/man2/send.2
+++ b/man2/send.2
@@ -255,6 +255,22 @@ 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)"
+Marks the attempt to send data in SYN like a combination of
+.BR connect (2)
+operation. It blocks until the handshake has completed and data is
+buffered.
+
+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
+, 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
+.BR connect (2)
+if the handshake fails.
.SS sendmsg()
The definition of the
.I msghdr
--
2.11.0.483.g087da7b7c-goog
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-09-16 21:48 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-15 17:37 [patch] send.2: Add MSG_FASTOPEN flag Wei Wang
2021-09-15 20:13 ` Alejandro Colomar (man-pages)
2021-09-16 21:47 ` Wei Wang
-- strict thread matches above, loose matches on Subject: below --
2017-02-01 1:37 Wei Wang
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).