Austin Group Defect Tracker

Aardvark Mark IV

Main | My View | View Issues | Change Log | Docs
  

Viewing Issue Simple Details [ Jump to Notes ] [ Issue History ] [ Print ]
ID Category Severity Type Date Submitted Last Update
0001196 [1003.1(2016/18)/Issue7+TC2] System Interfaces Editorial Enhancement Request 2018-07-19 16:49 2024-06-11 09:08
Reporter osoong View Status public  
Assigned To
Priority normal Resolution Accepted As Marked  
Status Closed  
Name Oliver Soong
Organization
User Reference
Section fread
Page Number 931
Line Number 31606-31607
Interp Status ---
Final Accepted Text Note: 0004283
Summary 0001196: Improved grammar regarding fread return value
Description For reference, the current text regarding the return value of fread() states, "Upon successful completion, fread() shall return the number of elements successfully read which is less than nitems only if a read error or end-of-file is encountered."

This is grammatically incorrect, although the intent can be inferred. The reasoning is split depending on whether American or British conventions are followed, particularly with regards to "which". In the so-called American convention, the clause following "which" is always nonrestrictive, and should be preceded by a comma. However, with a comma, the sentence implies read errors and end-of-file conditions are considered "successful completion". By contrast, the British convention allows the clause following "which" to be either restrictive or nonrestrictive, distinguished by the presence of a comma. The text as written, then, only states what should happen when a read error or end-of-file condition was encountered and the number of items successfully read was less than nitems. Technically, it makes no statement about what should happen when neither a read error nor an end-of-file condition was encountered, and it makes no statement about what should happen when a read error or end-of-file condition was encountered but the number of items successfully read was not less than nitems. Furthermore, it still implies that read errors and end-of-file conditions are considered "successful completion".

The C standard is somewhat clearer. It simply states, "The fread function returns the number of elements successfully read, which may be less than nmemb if a read error or end-of-file is encountered."

Since the British convention allows for both treatments of "which", I think the text will be correct for a broader audience if "which" was only used to introduce nonrestrictive clauses, which should pretty much always be set by commas. Furthermore, I think the text "upon successful completion" is extraneous and could be removed without harm here. Alternatively, the behavior on successful completion and the behavior on error could be separated.
Desired Action The first sentence of the return value section of fread() currently states, "Upon successful completion, fread() shall return the number of elements successfully read which is less than nitems only if a read error or end-of-file is encountered." My suggestion is to modify this to state, "The fread() function shall return the number of elements successfully read, which is less than nitems only if a read error or end-of-file is encountered." Alternatively, it could be made to say, "Upon successful completion, fread() shall return the number of elements successfully read. If a read error or end-of-file is encountered, the number of elements successfully read may be less than nitems."
Tags tc3-2008
Attached Files

- Relationships

-  Notes
(0004057)
geoffclare (manager)
2018-07-20 16:08

 I believe the first suggestion in the desired action is the right change, as it would make the fread() wording consistent with fwrite().

However, I noticed a couple of small problems with the fwrite() wording, which it would be good to fix at the same time:

1. It misuses the term "may" in "may be less". This could change to use "is less", as used for fread(), or perhaps both should change to "shall be less".

2. It is missing the word "only" after "less than nitems".
(0004058)
osoong (reporter)
2018-07-22 22:06

 This brings up a couple of points I missed before. If any of this seems long and obvious, it's because I'm slow.

First of all, "shall ... is" is inconsistent tense, and should be "shall ... will be". I don't know how to change the Desired Action, though.

Second, the "may be ... if" and "will be ... only if" phrases have some implications that I hadn't really considered. For fread(), C says, "The fread function returns the number of elements successfully read, which may be less than nmemb if a read error or end-of-file is encountered." Technically, C allows for situations other than read errors or end-of-file to cause the number of elements successfully read to be less than nmemb. By contrast, the proposed "will be ... only if" phrasing means that the only conditions that could cause the number of elements successfully read to be less than nitems are read errors and end-of-file. Normally, I'd presume that the POSIX text was phrased as it was because some requirement imposed by POSIX prevents those other situations allowed by C, but given the problems with the existing sentence, I'm not so certain, and I don't know enough about either standard to say for sure.

Third, for fwrite(), C says, "The fwrite function returns the number of elements successfully written, which will be less than nmemb only if a write error is encountered." In other words, if the number of elements successfully written was less than nmemb, then a write error was encountered. No other condition is allowed to cause fewer elements to be successfully written. By contrast, the current POSIX text says, "The fwrite() function shall return the number of elements successfully written, which may be less than nitems if a write error is encountered." This implies that conditions other than write errors could cause the number of elements successfully written to be less than nitems. Since that contradicts the C standard, I agree that the fwrite() text should say "will be ... only if".
(0004283)
geoffclare (manager)
2019-03-07 17:37
edited on: 2019-03-07 17:38

 Proposed changes...

On page 931 line 31606 section fread(), change:
Upon successful completion, fread() shall return the number of elements successfully read which is less than nitems only if a read error or end-of-file is encountered.
to:
The fread() function shall return the number of elements successfully read, which shall be less than nitems only if a read error or end-of-file is encountered.

On page 1001 line 34062 section fwrite(), change:
The fwrite() function shall return the number of elements successfully written, which may be less than nitems if a write error is encountered.
to:
The fwrite() function shall return the number of elements successfully written, which shall be less than nitems only if a write error is encountered.

- Issue History
Date Modified Username Field Change
2018-07-19 16:49 osoong New Issue
2018-07-19 16:49 osoong Name => Oliver Soong
2018-07-19 16:49 osoong Section => fread
2018-07-19 16:49 osoong Page Number => 931
2018-07-19 16:49 osoong Line Number => 31606-31607
2018-07-20 16:08 geoffclare Note Added: 0004057
2018-07-22 22:06 osoong Note Added: 0004058
2019-03-07 17:37 geoffclare Note Added: 0004283
2019-03-07 17:38 geoffclare Note Edited: 0004283
2019-03-11 15:48 geoffclare Interp Status => ---
2019-03-11 15:48 geoffclare Final Accepted Text => Note: 0004283
2019-03-11 15:48 geoffclare Status New => Resolved
2019-03-11 15:48 geoffclare Resolution Open => Accepted As Marked
2019-03-11 15:48 geoffclare Tag Attached: tc3-2008
2019-11-12 15:05 geoffclare Status Resolved => Applied
2024-06-11 09:08 agadmin Status Applied => Closed

Mantis 1.1.6[^]
Copyright © 2000 - 2008 Mantis Group
Powered by Mantis Bugtracker