[PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Arkadiusz Drabczyk]

Corresponding manpage on FreeBSD already contains that information.

Signed-off-by: Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
---
 man3/fread.3 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man3/fread.3 b/man3/fread.3
index 2dd7be9..97a306e 100644
--- a/man3/fread.3
+++ b/man3/fread.3
@@ -92,6 +92,9 @@ is 1.
 If an error occurs, or the end of the file is reached,
 the return value is a short item count (or zero).
 .PP
+The file position indicator for the stream is advanced by the number
+of characters successfully read or written.
+.PP
 .BR fread ()
 does not distinguish between end-of-file and error, and callers must use
 .BR feof (3)
-- 
2.9.0

Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Jakub Wilk]

* Arkadiusz Drabczyk <arkadiusz@drabczyk.org>, 2020-06-16, 20:26:
>+The file position indicator for the stream is advanced by the number
>+of characters successfully read or written.

s/characters/bytes/

-- 
Jakub Wilk

Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Arkadiusz Drabczyk]

On Tue, Jun 16, 2020 at 09:00:17PM +0200, Jakub Wilk wrote:
> * Arkadiusz Drabczyk <arkadiusz@drabczyk.org>, 2020-06-16, 20:26:
> > +The file position indicator for the stream is advanced by the number
> > +of characters successfully read or written.
> 
> s/characters/bytes/

It says `characters' in C11 and C17
https://web.archive.org/web/20181230041359if_/http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf
standards:

"Description

The fread function reads, into the array pointed to by ptr , up to
nmemb elements whose size is specified by size , from the stream
pointed to by stream . For each object, size calls are made to the
fgetc function and the results stored, in the order read, in an array
of unsigned char exactly overlaying the object. The file position
indicator for the stream (if defined) is advanced by the number of
characters successfully read. If an error occurs, the resulting value
of the file position indicator for the stream is indeterminate. If a
partial element is read, its value is indeterminate."

but indeed `bytes' sounds nicer especially if unsigned char is not
mentioned in the manpage. I sent v2.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

AW: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Walter Harms]

Hi,
i do not think character is correct it would confuse fseek() it says:
"The new position, measured in bytes"

to make things more complicated fread has a "size" and returns the
number of "things" read (" This number equals the number of bytes 
transferred only  when size  is 1.").

therefor i would suggest to move the success case
> > +The file position indicator for the stream is advanced by the number
> > +of characters successfully read or written.
into the "description section"

And add a word about partial reads into the "return value" section. E.g.
to make clear what happens when you try to read size=10 while only 4 are left.

jm2c
 wh

________________________________________
Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
Gesendet: Mittwoch, 17. Juni 2020 00:50
An: Jakub Wilk
Cc: Michael Kerrisk; linux-man@vger.kernel.org
Betreff: Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

On Tue, Jun 16, 2020 at 09:00:17PM +0200, Jakub Wilk wrote:
> * Arkadiusz Drabczyk <arkadiusz@drabczyk.org>, 2020-06-16, 20:26:
> > +The file position indicator for the stream is advanced by the number
> > +of characters successfully read or written.
>
> s/characters/bytes/

It says `characters' in C11 and C17
https://web.archive.org/web/20181230041359if_/http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf
standards:

"Description

The fread function reads, into the array pointed to by ptr , up to
nmemb elements whose size is specified by size , from the stream
pointed to by stream . For each object, size calls are made to the
fgetc function and the results stored, in the order read, in an array
of unsigned char exactly overlaying the object. The file position
indicator for the stream (if defined) is advanced by the number of
characters successfully read. If an error occurs, the resulting value
of the file position indicator for the stream is indeterminate. If a
partial element is read, its value is indeterminate."

but indeed `bytes' sounds nicer especially if unsigned char is not
mentioned in the manpage. I sent v2.

--
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Arkadiusz Drabczyk]

On Wed, Jun 17, 2020 at 07:46:25AM +0000, Walter Harms wrote:
> Hi,
> i do not think character is correct it would confuse fseek() it says:
> "The new position, measured in bytes"

ok, v2 already sent.

> to make things more complicated fread has a "size" and returns the
> number of "things" read (" This number equals the number of bytes 
> transferred only  when size  is 1.").
> 
> therefor i would suggest to move the success case
> > > +The file position indicator for the stream is advanced by the number
> > > +of characters successfully read or written.
> into the "description section"

ok, let's see what Michael thinks about it.

> And add a word about partial reads into the "return value" section. E.g.
> to make clear what happens when you try to read size=10 while only 4 are left.
> 

Isn't it already covered by this fragment:

"If an error occurs, or the end of the file is reached, the return
value is a short item count (or zero)."

?

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

AW: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Walter Harms]

________________________________________
Von: Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
Gesendet: Mittwoch, 17. Juni 2020 19:30
An: Walter Harms
Cc: Jakub Wilk; Michael Kerrisk; linux-man@vger.kernel.org
Betreff: Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

On Wed, Jun 17, 2020 at 07:46:25AM +0000, Walter Harms wrote:
> Hi,
> i do not think character is correct it would confuse fseek() it says:
> "The new position, measured in bytes"

ok, v2 already sent.

> to make things more complicated fread has a "size" and returns the
> number of "things" read (" This number equals the number of bytes
> transferred only  when size  is 1.").
>
> therefor i would suggest to move the success case
> > > +The file position indicator for the stream is advanced by the number
> > > +of characters successfully read or written.
> into the "description section"

ok, let's see what Michael thinks about it.

> And add a word about partial reads into the "return value" section. E.g.
> to make clear what happens when you try to read size=10 while only 4 are left.
>

Isn't it already covered by this fragment:

"If an error occurs, or the end of the file is reached, the return
value is a short item count (or zero)."

IMHO no,
what does a "short item count" mean ?
E.g. my size is 4 bytes and there are 3 bytes left to read. what is the return value 
and will the last few bytes ever read ? 

--
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

[Arkadiusz Drabczyk]

On Thu, Jun 18, 2020 at 08:37:02AM +0000, Walter Harms wrote:
> Isn't it already covered by this fragment:
>
> "If an error occurs, or the end of the file is reached, the return
> value is a short item count (or zero)."
>
> IMHO no,
> what does a "short item count" mean ?

"items of data" refers to nmemb:

"The function fread() reads nmemb items of data"

so "item count" means number of size-long sequences of bytes and
"short" means fewer than requested. But I think you know that well and
you just think that "short item count" is not clear enough, right?

(And of course I hope that I get it right.)

> E.g. my size is 4 bytes and there are 3 bytes left to read. what is
> the return value?

If the requested size is 4 but there are only 3 bytes left then
fread() will return 0, no matter what's the value of nmemb because
it's not able to read even a single item and feof() will return
non-zero. I think that this is explained clearly enough in the
manpage.

> and will the last few bytes ever read ?

That is interesting. POSIX
https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/ says
that "If a partial element is read, its value is unspecified.". But as
fread() returns number of items it has successfully read the returned
value should always be checked and it's different than requested nmemb
it means an error and I guess there is no way to tell how many bytes
have been partially read - for example if size == 4 and nmemb == 1 and
returned value is 0 you don't know if fread() read 1, 2 or 3 bytes.

Anyway, the patch that I sent explains that file pointer is moved
after fread()/fwrite(). The discussion about return value should be
started in a separate thread.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

AW: [PATCH] fread.3: return value

[Walter Harms]

________________________________________
Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
Gesendet: Donnerstag, 18. Juni 2020 13:43
An: Walter Harms
Cc: linux-man@vger.kernel.org
Betreff: Re: [PATCH] fread.3: Explain that file position is moved after calling fread()/fwrite()

On Thu, Jun 18, 2020 at 08:37:02AM +0000, Walter Harms wrote:
>> Isn't it already covered by this fragment:
>>
>> "If an error occurs, or the end of the file is reached, the return
>> value is a short item count (or zero)."
>>
>> IMHO no,
>> what does a "short item count" mean ?

>"items of data" refers to nmemb:

>"The function fread() reads nmemb items of data"

>so "item count" means number of size-long sequences of bytes and
>"short" means fewer than requested. But I think you know that well and
>you just think that "short item count" is not clear enough, right?

>(And of course I hope that I get it right.)

When reading that i try to "ignore" what i know and get the position of an first time reader,
so i noticed that this was fishy (i guess short item count is derived from short read) 

>> E.g. my size is 4 bytes and there are 3 bytes left to read. what is
>> the return value?

>If the requested size is 4 but there are only 3 bytes left then
>fread() will return 0, no matter what's the value of nmemb because
>it's not able to read even a single item and feof() will return
>non-zero. I think that this is explained clearly enough in the
>manpage.

IMHO i would be more clear to drop that "short item count". 
"If an error occurs, or the end of the file is reached, the  return value is zero"

>> and will the last few bytes ever read ?

>That is interesting. POSIX
>https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/ says
>that "If a partial element is read, its value is unspecified.". But as
>fread() returns number of items it has successfully read the returned
>value should always be checked and it's different than requested nmemb
>it means an error and I guess there is no way to tell how many bytes
>have been partially read - for example if size == 4 and nmemb == 1 and
>returned value is 0 you don't know if fread() read 1, 2 or 3 bytes.

the GNU version fills the buffer with the remaining bytes but returns 0.


>Anyway, the patch that I sent explains that file pointer is moved
>after fread()/fwrite(). The discussion about return value should be
>started in a separate thread.

i have changed the subject.

--
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] fread.3: return value

[Arkadiusz Drabczyk]

On Thu, Jun 18, 2020 at 02:32:02PM +0000, Walter Harms wrote:
> >If the requested size is 4 but there are only 3 bytes left then
> >fread() will return 0, no matter what's the value of nmemb because
> >it's not able to read even a single item and feof() will return
> >non-zero. I think that this is explained clearly enough in the
> >manpage.
> 
> IMHO i would be more clear to drop that "short item count". 
> "If an error occurs, or the end of the file is reached, the  return value is zero"

But the thing is that return value does not have to be zero, at least
when the end of the file is reached. Check this:

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  FILE *fp = fopen("/bin/sh", "rb");
  if (!fp) {
    perror("fopen");
    return EXIT_FAILURE;
  }

  fseek(fp, -10, SEEK_END);

  unsigned char buffer[12];

  size_t ret = fread(buffer, 4, 3, fp);
  if (ret != 3) {
    fprintf(stderr, "fread() failed: %zu\n", ret);
    printf("feof: %d\n", feof(fp) ? 1 : 0);
    exit(EXIT_FAILURE);
  }

  fclose(fp);

  exit(EXIT_SUCCESS);
}

Output:

fread() failed: 2
feof: 1

> >That is interesting. POSIX
> >https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/ says
> >that "If a partial element is read, its value is unspecified.". But as
> >fread() returns number of items it has successfully read the returned
> >value should always be checked and it's different than requested nmemb
> >it means an error and I guess there is no way to tell how many bytes
> >have been partially read - for example if size == 4 and nmemb == 1 and
> >returned value is 0 you don't know if fread() read 1, 2 or 3 bytes.
> 
> the GNU version fills the buffer with the remaining bytes

And so does libuClibc-0.9.33.2 and musl 1.1.20-git-79-gd6c855c that I
have at hand. It's probably the easiest implementation of fread(). 

> but returns 0.

That's not always the case as I showed above.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>