[PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[Rob Linden]

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@gmail.com>
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@gmail.com>
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@gmail.com>
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

Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2603 bytes --]

Hi Rob, Branden!

On 2023-07-12 11:05, Rob Linden wrote:
> Hello Alejandro!
> 
> This is a combined repost of the 3 individual patches I sent in June.

Thanks!

>  (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).

Yup, normally, I prefer them separate, but if they are somewhat related,
I prefer a set of mails, so that subsequent patch mails appear as replies
to the first mail.  Also, since I was away for a long time, my mailbox
was a bit messy.

Basically:
	git format-patch master..HEAD -v2 ...


> 
> 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.

This sounds reasonable to me.  Please include it in the commit message.

> 
> 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.

This seems reasonable, but could you please provide something a bit more
tangible than "I think"?  Some kernel documentation?  Some test program?
(A test program would be excellent even if you have something else.)
Another reason?

> 
> 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).

Please also include this in the third commit message.

> 
> Thanks & all the best,
> rob
> 
> 
> From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
> From: rokkbert <rokkbert@gmail.com>

[...]

> +.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"

I believe it should be recvmsg()-only, since it's a compound adjective.
Branden, can you please confirm if I'm right?

[...]

This third patch doesn't apply cleanly.  Please check.  Also, please send
as separate mails that are in reply to a first one, as a patch email
series, instead of a single email.

Thanks,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2598 bytes --]

Hi Alex,

At 2023-07-15T18:34:59+0200, Alejandro Colomar wrote:
> > From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
> > From: rokkbert <rokkbert@gmail.com>
> 
> [...]
> 
> > +.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"
> 
> I believe it should be recvmsg()-only, since it's a compound
> adjective.  Branden, can you please confirm if I'm right?

It's a little difficult to answer this because this two-word phrase does
not exist within a sentence.

Online authorities suggest that the hyphen should be omitted in most
cases, and don't call out "only" as an exception (unlike "based").

https://www.grammarbook.com/punctuation/hyphens.asp
http://www.mit.edu/course/21/21.guide/hyphen.htm
https://grammarist.com/grammar/hyphens/

In the man page in question, what we have is a sort of heading
(typographically, a paragraph tag), with some annotations on it, not a
complete sentence.  Adding the hyphen doesn't clarify anything in this
case, so I would omit it.

I did some web searches to try to find analogous examples but I kept
running into exhibits of use from sources that I don't consider to be of
generally high reliability in the practice of standard grammar, such as
commercial advertising and job postings at the retail level.

On the broader subject of marking up these annotations, and looking at
existing Linux man-pages practice, I perceive a possible need for
further guidance in man-pages(7).  So here's a straw-man patch for your
consideration.

commit 43b89c2304552b18c9a9ea02bca05ffd94d6518c (HEAD -> master)
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Jul 15 14:54:32 2023 -0500

    man-pages(7): Add attributive annotation advice.

    Prompted-by: Alejandro Colomar <alx@kernel.org>
    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index d63f2d8f2..aa39dbfd2 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -255,6 +255,13 @@ .SS Sections within a manual page
 Including version information is especially useful to users
 who are constrained to using older kernel or C library versions
 (which is typical in embedded systems, for example).
+.IP
+When an aspect of an interface requires multiple annotations,
+such as an applicable architecture,
+data type,
+or indication of read-only status,
+include these before the version information and separate them
+with semicolons.
 .TP
 .B OPTIONS
 A description of the command-line options accepted by a

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4093 bytes --]

[CC -= Rob, to not noise him too much]

Hi Branden,

On 2023-07-15 21:59, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-15T18:34:59+0200, Alejandro Colomar wrote:
>>> From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
>>> From: rokkbert <rokkbert@gmail.com>
>>
>> [...]
>>
>>> +.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"
>>
>> I believe it should be recvmsg()-only, since it's a compound
>> adjective.  Branden, can you please confirm if I'm right?
> 
> It's a little difficult to answer this because this two-word phrase does
> not exist within a sentence.

But can that construct be anything other than a compound 
> 
> Online authorities suggest that the hyphen should be omitted in most
> cases, and don't call out "only" as an exception (unlike "based").
> 
> https://www.grammarbook.com/punctuation/hyphens.asp

[criticizing that link]

+ Examples:
+ an off-campus apartment
+ state-of-the-art design
+ 
+ When a compound adjective follows a noun, a hyphen is usually not necessary.
+ 
+ Example: The apartment is off campus.

What?  "is" is a verb.  The compound adjective follows a verb, not a noun.
Or does it mean after in the sense that anything can come in between, as
long as it's the noun which it modifies and it has come before the
adjective?  Is that a valid use of the word "follows"?  I'm not native,
but that sounds, ughh.


BTW, that's the only case where it says to not use hyphens, and since by
being alone it's necessarily not following a noun, I'd say it doesn't fall
in this rule, and so a hyphen would be deserved.

> http://www.mit.edu/course/21/21.guide/hyphen.htm
> https://grammarist.com/grammar/hyphens/

I don't see reasons to avoid it in the links above.

So, I'm tending to conclude that it's necessary, or at least useful or
tasteful.  Please quote the relevant parts if you disagree.

> 
> In the man page in question, what we have is a sort of heading
> (typographically, a paragraph tag), with some annotations on it, not a
> complete sentence.  Adding the hyphen doesn't clarify anything in this
> case, so I would omit it.
> 
> I did some web searches to try to find analogous examples but I kept
> running into exhibits of use from sources that I don't consider to be of
> generally high reliability in the practice of standard grammar, such as
> commercial advertising and job postings at the retail level.
> 
> On the broader subject of marking up these annotations, and looking at
> existing Linux man-pages practice, I perceive a possible need for
> further guidance in man-pages(7).  So here's a straw-man patch for your
> consideration.
> 
> commit 43b89c2304552b18c9a9ea02bca05ffd94d6518c (HEAD -> master)
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> Date:   Sat Jul 15 14:54:32 2023 -0500
> 
>     man-pages(7): Add attributive annotation advice.
> 
>     Prompted-by: Alejandro Colomar <alx@kernel.org>

We use Reported-by: (mostly for bug fixes), Suggested-by: (for features),
or when none fits, just Cc:.

>     Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

LGTM.  Please send a patch.

Thanks!
Alex

> 
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index d63f2d8f2..aa39dbfd2 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -255,6 +255,13 @@ .SS Sections within a manual page
>  Including version information is especially useful to users
>  who are constrained to using older kernel or C library versions
>  (which is typical in embedded systems, for example).
> +.IP
> +When an aspect of an interface requires multiple annotations,
> +such as an applicable architecture,
> +data type,
> +or indication of read-only status,
> +include these before the version information and separate them
> +with semicolons.
>  .TP
>  .B OPTIONS
>  A description of the command-line options accepted by a
> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5228 bytes --]

Hi Alex,

At 2023-07-16T03:31:54+0200, Alejandro Colomar wrote:
> > https://www.grammarbook.com/punctuation/hyphens.asp
> 
> [criticizing that link]
> 
> + Examples:
> + an off-campus apartment
> + state-of-the-art design
> + 
> + When a compound adjective follows a noun, a hyphen is usually not
> + necessary.
> + 
> + Example: The apartment is off campus.
> 
> What?  "is" is a verb.  The compound adjective follows a verb, not a
> noun.  Or does it mean after in the sense that anything can come in
> between, as long as it's the noun which it modifies and it has come
> before the adjective?  Is that a valid use of the word "follows"?  I'm
> not native, but that sounds, ughh.

You're right that they employed an unhelpful example.  The apartment
example affords an ambiguous syntactical parse, which a hyphen _can_
clarify.

A.  The apartment is off-campus.

Here "off-campus" is an attributive phrase, and "is" is what some
primary school educators in the U.S. call a "linking verb"; in some
languages, my impression is that a "zero copula", meaning no verb at
all, is permitted or even preferred there.  Renderings of broken English
are often presented this way in literature and entertainment.

A1.        *The apartment off-campus.
analogue:  *My dog old and sick.

Because natural language demands a bit of Postel's Law, the foregoing
are generally understood by English speakers despite their non-standard
structure.

But consider the following alternative.

B.  The apartment is off campus and in a suburb.

Here we can parse the sentence as compounding two predicate adjectives
that are in the form of prepositional phrases, and therefore _not_
hyphenated.

One of the reasons I think grammarbook's example is a poor one is that
_semantically_, one infers the same information regardless of which
_syntactical_ parse one uses.  Where possible, examples should be
selected to indicate potential miscommunication, as in this classic
illustration of the value of the Oxford example from a young Objectivist
penning acknowledgments in a thesis for school.

*I'd like to thank my parents, Ayn Rand and God.

> BTW, that's the only case where it says to not use hyphens, and since
> by being alone it's necessarily not following a noun, I'd say it
> doesn't fall in this rule, and so a hyphen would be deserved.

I'd agree.  I cite authorities only because I cannot expect people to
take only my word at such things.  My authority as a grammarian is
limited.  Unlike some, I don't have God and Ayn Rand for parents.

> I don't see reasons to avoid it in the links above.
> 
> So, I'm tending to conclude that it's necessary, or at least useful or
> tasteful.  Please quote the relevant parts if you disagree.

Recalling the case at issue:

.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"

I would find the addition of a hyphen before "only" to be superfluous.
As I said before, it disambiguates nothing.  Further, if any of these
annotations ever has to be compounded, as in a man page that documents
several functions but requires annotation only for a subset of them, the
use of hyphens as you intend is liable to add clutter.

.BR MSG_BAZQUEUE " (" foomsg "()-, " barmsg "()-only; since Linux 7.99)"

Consider also the possibility that you may want to invert set
membership; perhaps 6 out of 7 functions in a page accept a certain
parameter.

.BR MSG_BAZQUEUE " (not " quxmsg "(); since Linux 7.99)"

There is no correct place for a hyphen here.

> > commit 43b89c2304552b18c9a9ea02bca05ffd94d6518c (HEAD -> master)
> > Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> > Date:   Sat Jul 15 14:54:32 2023 -0500
> > 
> >     man-pages(7): Add attributive annotation advice.
> > 
> >     Prompted-by: Alejandro Colomar <alx@kernel.org>
> 
> We use Reported-by: (mostly for bug fixes), Suggested-by: (for
> features), or when none fits, just Cc:.

Okay.

> >     Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> 
> LGTM.  Please send a patch.

Will do.  I've gotten sidetracked by the great automated "Mr. Sed"[1]
project, which turns out to have some prerequisites if I am to
demonstrate no changes in formatted text as I intend.

Early findings:

1.  I think I have raised warnings to this list before about
    manipulating adjustment and hyphenation outside of table regions
    with `ad` and `hy` requests; the Linux man-pages do so
    systematically around hundreds of tables, attempting (but failing)
    to (reliably) "reset" them after tables, often with miserable
    results.  Fixing this is a separate, prior sed(1) project.

2.  An ".sp 1" hack, also after tables, to work around a groff
    pre-1.23.0 bug is also not necessary and the time to sweep it away
    is near.  I may not _have_ to do this one to satisfy "Mr. Sed",
    though.  I will keep you advised.

Regards,
Branden

[1] the rewrite of man page cross references to use the new groff 1.23.0
    `MR` macro, a feature I have written about on this list before and
    which is covered in the release announcement sent here earlier this
    month by Bertrand Garrigues

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3398 bytes --]

Hi,

On 2023-07-16 04:34, G. Branden Robinson wrote:
[...]

> Because natural language demands a bit of Postel's Law, the foregoing
> are generally understood by English speakers despite their non-standard
> structure.
> 
[...]

>> BTW, that's the only case where it says to not use hyphens, and since
>> by being alone it's necessarily not following a noun, I'd say it
>> doesn't fall in this rule, and so a hyphen would be deserved.
> 
> I'd agree.  I cite authorities only because I cannot expect people to
> take only my word at such things.  My authority as a grammarian is
> limited.  Unlike some, I don't have God and Ayn Rand for parents.

And yet your words make more sense than those of the "authorities".  ;)

> 
>> I don't see reasons to avoid it in the links above.
>>
>> So, I'm tending to conclude that it's necessary, or at least useful or
>> tasteful.  Please quote the relevant parts if you disagree.

I should have said, or decree their authority rescinded in our territories.
They no authority here no mo.  :D

> 
> Recalling the case at issue:
> 
> .BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"
> 
> I would find the addition of a hyphen before "only" to be superfluous.
> As I said before, it disambiguates nothing.  Further, if any of these
> annotations ever has to be compounded, as in a man page that documents
> several functions but requires annotation only for a subset of them, the
> use of hyphens as you intend is liable to add clutter.
> 
> .BR MSG_BAZQUEUE " (" foomsg "()-, " barmsg "()-only; since Linux 7.99)"
> 
> Consider also the possibility that you may want to invert set
> membership; perhaps 6 out of 7 functions in a page accept a certain
> parameter.
> 
> .BR MSG_BAZQUEUE " (not " quxmsg "(); since Linux 7.99)"
> 
> There is no correct place for a hyphen here.

Yeah, a hyphen is better omitted for your reasons.

---  Mr. Sed project:

> 
> Will do.  I've gotten sidetracked by the great automated "Mr. Sed"[1]
> project, which turns out to have some prerequisites if I am to
> demonstrate no changes in formatted text as I intend.
> 
> Early findings:
> 
> 1.  I think I have raised warnings to this list before about
>     manipulating adjustment and hyphenation outside of table regions
>     with `ad` and `hy` requests; the Linux man-pages do so
>     systematically around hundreds of tables, attempting (but failing)
>     to (reliably) "reset" them after tables, often with miserable
>     results.  Fixing this is a separate, prior sed(1) project.

Great.

> 
> 2.  An ".sp 1" hack, also after tables, to work around a groff
>     pre-1.23.0 bug is also not necessary and the time to sweep it away
>     is near.

While it may not be necessary, I'm all-in for killing such a workaround
ASAP, to avoid contributors from imitating it.

Cheers,
Alex

>  I may not _have_ to do this one to satisfy "Mr. Sed",
>     though.  I will keep you advised.
> 
> Regards,
> Branden
> 
> [1] the rewrite of man page cross references to use the new groff 1.23.0
>     `MR` macro, a feature I have written about on this list before and
>     which is covered in the release announcement sent here earlier this
>     month by Bertrand Garrigues

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]