Austin Group Defect Tracker

Aardvark Mark III


Viewing Issue Simple Details Jump to Notes ] Issue History ] Print ]
ID Category Severity Type Date Submitted Last Update
0000895 [1003.1(2013)/Issue7+TC1] System Interfaces Editorial Omission 2014-11-22 01:07 2015-03-05 16:08
Reporter safinaskar View Status public  
Assigned To
Priority normal Resolution Withdrawn  
Status Closed  
Name Askar Safin
Organization
User Reference
Section fgets, fprintf, fread, etc
Page Number POSIX 2013 edition, p. 858, etc
Line Number 28671, etc
Interp Status ---
Final Accepted Text
Summary 0000895: POSIX doesn't clearly specify what happens at partial read/write
Description POSIX doesn't clearly specify what happens at partial read/write in description of some functions. Also read/write-related functions have another issues.

fgets page says: "Upon successful completion, fgets( ) shall return s". What means "successful completion"? Is reading of all n - 1 bytes without newline a success? Is reaching a newline a success? Let's imagine that fgets successfully have read some bytes and then reached EOF or some read error. Is this a success? What is returned in this case? Is EOF or error indicators or errno set in this case?

fprintf page says: "Upon successful completion, the dprintf( ), fprintf( ), and printf( ) functions shall return the number of bytes transmitted". Again, is partial write a success? What happens at partial write?
Also, fprintf page doesn't say that printf and fprintf should set error indicator on error!

Same for fputs.

fread page says that number of successfully read items returned on partial read. And this is good. But is EOF/error indicator/errno set on partial read due to EOF/error? What fread returns if we get error at start? What happens if we get EOF at start? Some of this questions are clear from examples, but they should be clear from main part of the page.

fwrite: what exactly happens on partial write?

Same for puts.

Some of this issues goes for scanf.

Maybe same issues exist for some other functions (for example wprintf etc)
Desired Action So, please read carefully pages for all mentioned functions (and maybe for some others) and specify exactly, what happens on partial read/write (due to error, to EOF), what happens if there is no read or write at all, what function returns, when EOF/error indicator/errno is set
Tags No tags attached.
Attached Files

- Relationships

-  Notes
(0002439)
dalias (reporter)
2014-11-22 03:43

These functions are all specified by ISO C, so any deficiency in the specification should probably be addressed with WG14. However, I believe all of these issues are already covered adequately by the current wording. Read and write operations on stdio streams take place as if by repeated calls to fgetc or fputc. If any of those fgetc or fputc calls would produce an error, it's generally an error for the whole operation. EOF is not a failure unless it's specified to be (certain functions don't "succeed" if no data is read, for instance).

These conditions are detailed in the documentation for individual functions too. For example, the fgets function is specified to stop upon reading n-1 bytes, or a newline, or end of file. Any of these conditions is "success", except the special case of immediately hitting EOF, which is noted. The return value on success is clearly defined, along with this special case (EOF with no data) and the error cases.
(0002440)
safinaskar (reporter)
2014-11-22 19:23

> These functions are all specified by ISO C, so any deficiency in the specification should probably be addressed with WG14
Okey, let's talk about C standard (C99). :)

C99 is more clear than POSIX, but still has issues.

C99 clearly says in the beginning of <stdio.h> section that EOF indicator is always set on EOF and error indicator is always set on error (unlike POSIX). :) And this is very good.

So, mentions of this indicators are not needed in particular functions descriptions. Also, C99 doesn't specify whatever errno is set on errors in this functions, so errno mentions are not needed, too. So, all C99 should say in functions descriptions is what functions return. And C99 almost fully done this simple task. :)

*printf, *scanf, fread, fwrite, fputs, puts functions are OK in C99. fgets section doesn't say what is "success" and so doesn't say what the function return on partial read due to EOF.

So, please redirect this fgets issue to WG14. ^_^

Now, let's talk about POSIX (2013 issue).

> Read and write operations on stdio streams take place as if by repeated calls to fgetc or fputc
POSIX says in XSH 2.5 that all stdio.h I/O is performed as if it was implemented using fgetc/fputc. And I didn't notice this at first. This makes some things clearer, thanks. But how I supposed to find this sentence? Functions themselves don't refer to XSH 2.5. So, please, make this referring.

> If any of those fgetc or fputc calls would produce an error, it's generally an error for the whole operation
How I supposed to know this from POSIX spec? Also, there is opposite precedent in POSIX spec: "read" and "write" functions. If you start some read/write operation, this operation reads/writes some bytes and then you interrupt the process with some signal (handler for this signal should be set), then this read/write will not fail with EINTR, it will instead successfully return you number of read/written bytes. (Am I right?) So this precedent suggests that stdio.h should behave the same. So, why I should think that stdio.h behave opposite way? Where should I know this?

> EOF is not a failure unless it's specified to be (certain functions don't "succeed" if no data is read, for instance).
Again, where I should know this?

> Any of these conditions is "success", except the special case of immediately hitting EOF, which is noted.
Where I should know that this three conditions are success? "If the stream is at end-of-file..." - okey, let's assume this means "stream is at end-of-file BEFORE running of fgets", but this is still bad phrase.

Now, let me repeat issues with (as an example) fgets in POSIX.

What means "success"? What of the following conditions are "success"?
A. n - 1 bytes have read
B. delimeter (i. e. new line) reached
C. EOF reached after some bytes
D. EOF reached at start
E. error after some bytes
(I will not put here "F. error at start", because this is clearly failure, all other cases may be threaded as "success")

"If the stream is at end-of-file" - what this means? Any EOF during fgets? Or EOF only at start of fgets? Okey, now I see this means "EOF at start", but it was very hard to me to understand the phrase this way, so I think it still needs rewriting.
(0002441)
dalias (reporter)
2014-11-22 20:52

The text about behaving as if by repeated fgetc/fputc is also in ISO C. The issue of having to read the introductory text rather than simply finding this copied in the description of each function also exists in ISO C, and it seems unlikely to change there.

EINTR is specified as an error condition for both fgetc and fputc (see the "shall fail" text). They do not retry on EINTR, and therefore the "aggregate stdio functions" built on fgetc/fputc do not retry but see and report the error. For some functions (fread and fwrite), a read or write error is specified to cause them to return a "short read" or "short write"; for others; an error value (typically NULL or EOF) is returned. This is documented for each individual function.

For when EOF is a failure, see the individual functions. scanf fails if EOF is reached without converting any items, but this is not an "error" in the sense of something that needs to set errno (because it's not one of the "shall fail" conditions); it's just one of the possible results.

For fgets, A, B, and C are "success". D could also be seen as "success" (it's not an error since it's not covered in the "shall fail" text) but it's handled specially anyway under "return value".

In any case, there is a lot of language in the standards whose meaning is not entirely obvious until you take the time to study it. This is generally inevitable. Writing a formal specification that reflects existing practice is hard work, and the more details you add, the more room there is or mistakes and unintended contradictions. I do think it would be possible to make the text for these functions much more clear and understandable, but it would require extraordinary amounts of work to ensure that the new text has the exact same meaning as the old text, and I think it would be hard to justify such a project. On the other hand, adding non-normative clarifying text under "application usage" for these functions could be practical and may be worthwhile. But if you want this to happen, you probably need to propose such text, or find someone else willing to write a proposal.
(0002442)
safinaskar (reporter)
2014-11-22 23:26

Well, okey... :( Please, somebody, close this bug. But if someone fix mentioned issues I will be happy :)

- Issue History
Date Modified Username Field Change
2014-11-22 01:07 safinaskar New Issue
2014-11-22 01:07 safinaskar Name => Askar Safin
2014-11-22 01:07 safinaskar Section => fgets, fprintf, fread, etc
2014-11-22 01:07 safinaskar Page Number => POSIX 2013 edition, p. 858, etc
2014-11-22 01:07 safinaskar Line Number => 28671, etc
2014-11-22 03:43 dalias Note Added: 0002439
2014-11-22 19:23 safinaskar Note Added: 0002440
2014-11-22 20:52 dalias Note Added: 0002441
2014-11-22 23:26 safinaskar Note Added: 0002442
2015-03-05 16:08 Don Cragun Interp Status => ---
2015-03-05 16:08 Don Cragun Status New => Closed
2015-03-05 16:08 Don Cragun Resolution Open => Withdrawn


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