A NOTE has been added to this issue. ====================================================================== https://austingroupbugs.net/view.php?id=1448 ====================================================================== Reported By: kre Assigned To: ====================================================================== Project: Issue 8 drafts Issue ID: 1448 Category: System Interfaces Type: Error Severity: Objection Priority: normal Status: New Name: Robert Elz Organization: User Reference: Section: XSH 3/poll() Page Number: 1399-1400 Line Number: 46800-1. 46807-46813, 46820, 46824, 46867 Final Accepted Text: ====================================================================== Date Submitted: 2021-02-02 22:12 UTC Last Modified: 2021-06-18 14:08 UTC ====================================================================== Summary: Misleading text in description of poll() ======================================================================
---------------------------------------------------------------------- (0005386) geoffclare (manager) - 2021-06-18 14:08 https://austingroupbugs.net/view.php?id=1448#c5386 ---------------------------------------------------------------------- In the June 17th teleconference we decided that we should align the wording for poll() with what is currently used for select(), i.e. talk about descriptors being "ready for reading/writing" (with an explanation of what that means). I think the following changes are close to what we would have come up with if we hadn't run out of time. My aim in posting them here is that we should use this as the starting point on the June 24th call, but will be able to address any feedback in that call rather than waiting for a subsequent call. Page and line numbers are for draft 1.1 but the changes account for the addition of ppoll() in draft 2. In the sentence beginning on line 46801, change:<blockquote>on which an application can read or write data</blockquote>to:<blockquote>on which an application can make an attempt to read or write data without blocking</blockquote> At line 46807, change:<blockquote>POLLIN Data other than high-priority data may be read without blocking.</blockquote>to:<blockquote>POLLIN The file descriptor is ready for reading data other than high-priority data.</blockquote> In line 46808 change:<blockquote>POLLRDNORM Normal data may be read without blocking.</blockquote>to:<blockquote>POLLRDNORM The file descriptor is ready for reading normal data.</blockquote> In line 46809 change:<blockquote>POLLRDBAND Priority data may be read without blocking.</blockquote>to:<blockquote>POLLRDBAND The file descriptor is ready for reading priority data.</blockquote> In line 46810 change:<blockquote>POLLPRI High-priority data may be read without blocking.</blockquote>to:<blockquote>POLLPRI The file descriptor is ready for reading high-priority data.</blockquote> In line 46811 change:<blockquote>POLLOUT Normal data may be written without blocking.</blockquote>to:<blockquote>POLLOUT The file descriptor is ready for writing normal data.</blockquote> In line 46813 change:<blockquote>POLLWRBAND Priority data may be written.</blockquote>to:<blockquote>POLLWRBAND The file descriptor is ready for writing priority data.</blockquote> In line 46814 change:<blockquote>An error has occurred on the device or stream.</blockquote>to:<blockquote>An error condition is present on the file descriptor. All error conditions that arise solely from the state of the object underlying the open file description and would be diagnosed by a return of -1 from a <i>read</i>() or <i>write</i>() call on the file descriptor shall be reported as a POLLERR event.</blockquote> On line 46820 delete the words (and punctuation):<blockquote>; a stream can never be writable if a hangup has occurred</blockquote> On line 46824 change:<blockquote>is invalid</blockquote>to:<blockquote>is not an open file descriptor</blockquote> Before line 46826 insert a new paragraph:<blockquote>A file descriptor shall be considered ready for reading when a call to an input function with O_NONBLOCK clear would not block, whether or not the function would transfer data successfully. (The function might return data, an end-of-file indication, or an error other than one indicating that it is blocked, and in each of these cases the descriptor is considered ready for reading.) A file descriptor shall be considered ready for writing when a call to an output function with O_NONBLOCK clear would not block, whether or not the function would transfer data successfully. How much data could be written without blocking depends upon the object underlying the open file description and its current state.</blockquote> On line 46826-7 after:<blockquote>The significance and semantics of normal, priority, and high-priority data are file and device-specific.</blockquote>add:<blockquote>The semantics of device disconnection are device-specific.</blockquote> On line 46867 change APPLICATION USAGE from:<blockquote>None</blockquote>to:<blockquote>When a <i>poll</i>() or <i>ppoll</i>() call indicates a file descriptor is ready for reading, this means that if an attempt to read data had been made at the time that the status of the file descriptor was checked, it would have returned at least one byte of data, an end-of-file indication, or an error, without blocking (even if O_NONBLOCK is clear). When a <i>poll</i>() or <i>ppoll</i>() call indicates that a file descriptor is ready for writing, this means that if an attempt to write one byte of data had been made at the time that the status of the file descriptor was checked, it would have written that byte or returned an error, without blocking. However, if an attempt to write more than one byte had been made, it might have blocked (if O_NONBLOCK is clear). In both cases, by the time the call returns and a subsequent I/O operation is attempted, the state of the file descriptor might have changed (for example, because another thread read or wrote some data) and, if O_NONBLOCK is clear, there is no guarantee that the operation will not block (unless it would not block for some other reason, such as setting MIN=0 and TIME=0 for a terminal in non-canonical mode). Therefore it is recommended that applications always set O_NONBLOCK on file descriptors whose readiness for I/O they query with <i>poll</i>() or <i>ppoll</i>(). The error conditions specified for <i>read</i>() and <i>write</i>() that are reported as POLLERR events are only those that arise solely from the state of the object underlying the open file description. They do not include, for example, [EAGAIN] as this relates to the state of the open file description not (solely) the object underlying it. Application writers should note that repeating a <i>poll</i>() or <i>ppoll</i>() call which indicated that I/O was possible on one or more of the file descriptors given, without causing some change to the state, either by altering the <i>fds</i> array or causing appropriate input or output to occur on at least one file descriptor indicated as ready, will result in ``busy waiting'' - a subsequent call will always return immediately indicating the same (or perhaps more) events as the previous one.</blockquote> On page 1480 line 49261 section pselect(), change APPLICATION USAGE from:<blockquote>None</blockquote>to:<blockquote>When a <i>pselect()</i>() or <i>select</i>() call indicates a file descriptor is ready for reading, this means that if an attempt to read data had been made at the time that the status of the file descriptor was checked, it would have returned at least one byte of data, an end-of-file indication, or an error, without blocking (even if O_NONBLOCK is clear). When a <i>pselect()</i>() or <i>select</i>() call indicates a file descriptor is ready for writing, this means that if an attempt to write one byte of data had been made at the time that the status of the file descriptor was checked, it would have written that byte or returned an error, without blocking. However, if an attempt to write more than one byte had been made, it might have blocked (if O_NONBLOCK is clear). In both cases, by the time the call returns and a subsequent I/O operation is attempted, the state of the file descriptor might have changed (for example, because another thread read or wrote some data) and, if O_NONBLOCK is clear, there is no guarantee that the operation will not block (unless it would not block for some other reason, such as setting MIN=0 and TIME=0 for a terminal in non-canonical mode). Therefore it is recommended that applications always set O_NONBLOCK on file descriptors whose readiness for I/O they query with <i>pselect()</i>() or <i>select</i>().</blockquote> Issue History Date Modified Username Field Change ====================================================================== 2021-02-02 22:12 kre New Issue 2021-02-02 22:12 kre Name => Robert Elz 2021-02-02 22:12 kre Section => XSH 3/poll() 2021-02-02 22:12 kre Page Number => 1399-1400 2021-02-02 22:12 kre Line Number => 46800-1. 46807-46813, 46820, 46824, 46867 2021-06-18 14:08 geoffclare Note Added: 0005386 ======================================================================
