Hello Alejandro!
This is a combined repost of the 3 individual patches I sent in June. (I
had thought it makes sense to split it up, because the changes were
unrelated, so maybe one could be approved while another one needs
discussion).
I think there is a mistake on the manpage for recv. In the description of
the flag MSG_ERRQUEUE it says that data is passed via "msg_iovec". This is
probably referring to msg_iov in struct msghdr (from
/usr/include/bits/socket.h). A "msg_iovec" doesn't seem to exist. Maybe it
was spelled wrong because it's of type struct iovec. If it is indeed wrong
then the following patch corrects it.
I think the flag MSG_ERRQUEUE, that is described on the man page recv.2 is
only applicable to recvmsg, and not recv or recvfrom. Maybe it would be
good to mention it, just like it is specified for MSG_CMSG_CLOEXEC. The
following patch does that.
While reading the recv manpage I came up with some suggestions which I
believe would make it easier for the reader. They are not corrections
(except for the last block, which I believe was incomplete), just
improvements (IMHO).
Thanks & all the best,
rob
>From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
From: rokkbert <rokkbert@xxxxxxxxx>
Date: Tue, 6 Jun 2023 10:00:20 +0200
Subject: [PATCH 1/3] recv.2: field msg_iov in struct msghdr is wrongly called
msg_iovec. Corrected to msg_iov.
---
man2/recv.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/recv.2 b/man2/recv.2
index 27d6d612c..62e43c9aa 100644
--- a/man2/recv.2
+++ b/man2/recv.2
@@ -159,7 +159,7 @@ and
for more information.
The payload of the original packet that caused the error
is passed as normal data via
-.IR msg_iovec .
+.IR msg_iov .
The original destination address of the datagram that caused the error
is supplied via
.IR msg_name .
--
2.39.2
>From c3ec57d21d2b754ee05913cfa035f5e31aaaae95 Mon Sep 17 00:00:00 2001
From: rokkbert <rokkbert@xxxxxxxxx>
Date: Tue, 13 Jun 2023 17:45:32 +0200
Subject: [PATCH 2/3] recv.2: added note that flag MSG_ERRQUEUE is only
applicable to recvmsg. Only recvmsg allows the caller to even pass the
required struct msghdr to receive the error data.
---
man2/recv.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/recv.2 b/man2/recv.2
index 62e43c9aa..3697d0c84 100644
--- a/man2/recv.2
+++ b/man2/recv.2
@@ -145,7 +145,7 @@ which will affect all threads in the calling process
and as well as other processes that hold file descriptors
referring to the same open file description.
.TP
-.BR MSG_ERRQUEUE " (since Linux 2.2)"
+.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"
This flag
specifies that queued errors should be received from the socket error queue.
The error is passed in
--
2.39.2
>From 4f4ea0984d0a207960121f142e1b9e181194ef8e Mon Sep 17 00:00:00 2001
From: rokkbert <rokkbert@xxxxxxxxx>
Date: Tue, 13 Jun 2023 17:55:08 +0200
Subject: [PATCH 3/3] recv.2: increased verbosity and, hopefully,
understandability a bit.
---
man2/recv.2 | 15 ++++++++++-----
1 file changed, 10 insertions(+), 5 deletions(-)
diff --git a/man2/recv.2 b/man2/recv.2
index 3697d0c84..f675f65aa 100644
--- a/man2/recv.2
+++ b/man2/recv.2
@@ -92,7 +92,10 @@ All three calls return the length of the message on
successful
completion.
If a message is too long to fit in the supplied buffer, excess
bytes may be discarded depending on the type of socket the message is
-received from.
+received from, e.g. for
+.BR SOCK_DGRAM ", but not for " SOCK_STREAM .
+To find out how many bytes are available see the flags
+.BR MSG_PEEK " and " MSG_TRUNC .
.PP
If no messages are available at the socket, the receive calls wait for a
message to arrive, unless the socket is nonblocking (see
@@ -100,7 +103,7 @@ message to arrive, unless the socket is nonblocking (see
in which case the value \-1 is returned and
.I errno
is set to
-.BR EAGAIN " or " EWOULDBLOCK .
+.BR EAGAIN " or " EWOULDBLOCK " (see " ERRORS ).
The receive calls normally return any data available, up to the requested
amount, rather than waiting for receipt of the full amount requested.
.PP
@@ -256,7 +259,8 @@ For use with Internet stream sockets, see
.TP
.BR MSG_WAITALL " (since Linux 2.2)"
This flag requests that the operation block until the full request is
-satisfied.
+satisfied, i.e.
+.BR len " bytes have been written to the buffer."
However, the call may still return less data than requested if
a signal is caught, an error or disconnect occurs, or the next data to be
received is of a different type than that returned.
@@ -432,8 +436,9 @@ is returned to indicate that expedited or
out-of-band data was received.
indicates that no data was received but an extended error from the socket
error queue.
.SH RETURN VALUE
-These calls return the number of bytes received, or \-1
-if an error occurred.
+These calls return the number of bytes copied to buf, the number of bytes
+received by the socket (see
+.BR MSG_TRUNC "), or -1 if an error occurred."
In the event of an error,
.I errno
is set to indicate the error.
--
2.39.2
