Kaz Kylheku said:
pete said:
Richard Heathfield wrote: [...]
No, it says "Reading stops after an EOF or a newline", which is
true, and clearly not an error. Do not confuse the concept of an EOF
condition (end of file has been encountered) with the concept of a
return value.
The most confusing thing about the concept of an EOF condition is that
there's no such thing. EOF is a macro. End-of-file is a condition.
The man page is confusing the concept of end-of-file with
the concept of EOF.
I think it's merely not being sufficiently clear about the fact that
fgets reads characters (as if) by calling fgetc.
fgets() reads in at most one less than size characters from
stream and stores them into the buffer pointed to by s.
Reading stops after an EOF or a newline. If a newline is read,
it is stored into the buffer. A '\0' is stored after the last
character in the buffer.
On one system I have here, the above text is is found in a page dated
1993-04-04, attributed as being from the ``Linux Programmer's Manual''.
The project which resulted in the current C library didn't even
exist in 1993!
So this is very obsolete text, and not the official documentation which
accompanies the (library part of) the implementation.
On my system (Ubuntu with recent updates), the same text is found in
a page dated 2008-08-06, part of the Linux man-pages project (release
3.15; the most recent release, 3.22, is less than a month old).
That would be the GNU Info manual, accessed by ``info libc''.
That documentation for fgets doesn't mention EOF:
-- Function: char * fgets (char *S, int COUNT, FILE *STREAM)
The `fgets' function reads characters from the stream STREAM up to
and including a newline character and stores them in the string S,
adding a null character to mark the end of the string. You must
supply COUNT characters worth of space in S, but the number of
characters read is at most COUNT - 1. The extra character space
is used to hold the null character at the end of the string.
If the system is already at end of file when you call `fgets', then
the contents of the array S are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer S.
Note that this doesn't explicitly say what happens if the of the
input file doesn't end in a newline character, though I suppose
you could infer the behavior from what's written. The C standard
doesn't specify this, but the glibc documentation probably should.
(I'm aware that there are arguments regarding whether man pages or
info documents are, or should be, considered the best source of
information; I don't propose to get into those arguments here.)