Skip to contentSkip to conversation

select.2: s/minimum/maximum/

DISCUSSION G.raud 2 participants 2 messages Aug 22, 2013 – Aug 23, 2013 1 message not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

G.raud

author
#0 lore raw
Quoted 7 lines

Date: Thu, 22 Aug 2013 09:22:32 +0200
From: "Michael Kerrisk (man-pages)" <[email protected]>
Subject: Re: select.2: s/minimum/maximum/

Quoted 2 lines · G.raud

In this part of the manpage:

Quoted 8 lines
Quoted 2 lines

" The timeout argument specifies the minimum interval that select() should block waiting for a file descriptor to become ready.        "

This isn't correct (though maybe there is room for a better wording).

The 'timeout' places a ceiling on how long the call will block, but that ceiling has the *minimum* value provided by the argument. See what I mean?

The text that you cite and that is not correct is extracted from the present manpage.  The corrected text should be:

" The timeout argument specifies the maximum interval that select() should block waiting for a file descriptor to become ready.  "

which is close to the POSIX description and is correct in that "specify" does not mean "is equal to" but can be understood as "is close to", which is all most of the programmers need to know.

I suggest prepending the following before the complete description bewtween parentheses if a better (i.e. more explicit) wording is desired:

 " timeout is a lower bound on the actual maximum waiting time."

Signature · 5 lines
G.raud Meyer
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

#2 lore raw

Hi,

Quoted 10 lines · G.raud
Quoted 10 lines

Date: Thu, 22 Aug 2013 09:22:32 +0200
From: "Michael Kerrisk (man-pages)" <[email protected]>
Subject: Re: select.2: s/minimum/maximum/

Quoted 4 lines · G.raud

In this part of the manpage:

" The timeout argument specifies the minimum interval that select()
should block waiting for a file descriptor to become ready. "

Quoted 8 lines
Quoted 5 lines

This isn't correct (though maybe there is room for a better wording).

The 'timeout' places a ceiling on how long the call will block, but that ceiling has the *minimum* value provided by the argument. See what I mean?

The text that you cite and that is not correct is extracted from the present manpage.

Your original report was rather briefly worded, and my "This" referred to your subject line, not the text you cited.

Quoted 4 lines

The corrected text should be:

" The timeout argument specifies the maximum interval that select()
should block waiting for a file descriptor to become ready. "

Again, this is NOT correct. According to that statement, an implementation that did not block at all would also be conformant, since 0 is always less than or equal to whatever value is specified in 'timeout'. This point was the subject of changes in several man pages (poll(2), epoll_pwait(2), select(2), sigtimedwait(2)) back in May 2012, after someone (I can't remember who) reported the point about one of those pages.

Quoted 3 lines

which is close to the POSIX description and is correct in that "specify" does not mean "is equal to" but can be understood as "is close to", which is all most of the programmers need to know.

Either of these interpretations would be a surprising way of defining "specify", IMO.

By the way, I see what you mean about the POSIX description of select(). It speaks of "maximum". But there, I would say the problem is an imprecision in the standard. They get things worded better in the poll() spec, which says: "poll() shall wait at least timeout milliseconds".

Quoted 4 lines

I suggest prepending the following before the complete description bewtween parentheses if a better (i.e. more explicit) wording is desired:

" timeout is a lower bound on the actual maximum waiting time."

Now, I do (I think) understand why the current text troubles you: it's because the description is counter-intuitive. But, when one thinks about it, one realizes that it is accurate (and s/minimum/maximum/ is not). And the very next sentences are there to help the reader understand this point:

(This interval will be rounded up to the system clock granular‐ ity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.)

One could I suppose reword something like this:

The timeout argument specifies the interval that select() should block waiting for a file descriptor to become ready. In effect, timeout specifies a minimum interval: the timeout will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.

But I'm not sure that that is really much of an improvement.

Cheers,

Michael

Signature · 7 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html