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
0000926 [1003.1(2004)/Issue 6] Base Definitions Editorial Error 2015-02-22 14:20 2019-06-10 08:54
Reporter harveyab View Status public  
Assigned To
Priority normal Resolution Accepted As Marked  
Status Closed  
Name Harvey Block
Organization
User Reference
Section Example code for fread()
Page Number (page or range of pages)
Line Number (Line or range of lines)
Interp Status ---
Final Accepted Text see Note: 0002569
Summary 0000926: Documentation error in fread() example at (http://pubs.opengroup.org/onlinepubs/009695399/functions/fread.html) [^]
Description (I don't know what you wanted for "Catagory")

This site incorrectly uses fread() in the example:
http://pubs.opengroup.org/onlinepubs/009695399/functions/fread.html [^]

EXAMPLES

    Reading from a Stream

    The following example reads a single element from the fp stream into the array pointed to by buf.

    #include <stdio.h>
    ...
    size_t bytes_read;
    char buf[100];
    FILE *fp;
    ...
    bytes_read = fread(buf, sizeof(buf), 1, fp);
    ...

--------------------
This may (or may not) work as intended, but it is incorrect and misleading.

The explanation is confusing and incorrect:

    The following example reads a single element from the fp stream into the array pointed to by buf.

What is an element? A char? A string of always exactly 100 chars?
Or did you intend that the example program should read up to 100 char "elements" into the buffer?
Most programmers reading your example would be interested in reading char "elements" into a buffer large enough to hold a string of any size up to a maximum of 100 (in this case).
With your example when would it ever make sense to read in more than one element? It is a guaranteed buffer overrun.

The last line should be:

    bytes_read = fread(buf, 1, sizeof(buf), fp);

Or perhaps better:

    bytes_read = fread(buf, sizeof(char), sizeof(buf), fp);

The element is a char, NOT an arbitrarily sized buffer of char.

If the buffer was an array of 32 bit int, then the element size would be 4 bytes, and the line should be written as:

    bytes_read = fread(buf, sizeof(int), 100, fp);

Or:

    bytes_read = fread(buf, sizeof(int), sizeof(buf)/sizeof(int), fp);

If the implementation of fread() is simply to multiply these two parameters together and read in that many bytes, then it makes no difference. But that would be, in my opinion, a poor implementation.

It would seem to me that when reading ints, if there are only 5 bytes available to be read, it should read only 4 into the first element of the buffer as one int. And if the element is really a char in your example, then do you really want it to read ONLY complete "elements" of 100 char each? Very unlikely for a "simple" example.

Your error here has already been duplicated by other documentation websites such as:
http://www.tutorialspoint.com/c_standard_library/c_function_fread.htm [^]

Please contact me at harveyab@juno.com with any comments or questions.

Harvey Block
Desired Action Correct the documentation example.
Tags tc2-2008
Attached Files

- Relationships
duplicate of 0000232Closedajosey 1003.1(2008)/Issue 7 wrong example for fread() call 

-  Notes
(0002557)
geoffclare (manager)
2015-02-23 09:35

 This is effectively a duplicate of 0000232 which was fixed in SUSv4 TC1.

Note that the URL given is for the fread page in the 2004 edition of SUSv3. The up to date online version of the standard is the 2013 edition of SUSv4 (which incorporates TC1).
(0002558)
harveyab (reporter)
2015-02-24 08:52

 Do a Google search for "fread()" and this (old 2004) page is the very first hit in (2015).
That is NOT a good situation.
(0002561)
ajosey (manager)
2015-02-24 15:31

 We have added a header to the majority of the man pages in the 2004 edition with a notice that a newer edition of this document appears here (with a link to the front page of the latest edition).
(0002562)
harveyab (reporter)
2015-02-24 21:20

 I contend that the new version is even more confusing. It has examples both ways. It is not at all clear that in your first part of the example, an element is (and must be) exactly 100 bytes in order to be a complete element. Even though that is apparently the case. Would it not make more sense to give an example of reading several ints and actually show how this is intended to work?

And why does the old version rank as the first hit in Google?

And how many people are actually going to read the whole page looking for a hint that there is an updated version of the whole huge document?

Even if you click on the "here" link, you then have to do yet another search for the fread page.

Searching for help on the Internet is bad enough without old stuff like this being the first hit.
(0002563)
ajosey (manager)
2015-02-25 08:03

 In general we encourage commenters to suggest specific changes to solve the perceived problem so the standard developers can take a view. Perhaps for your first comment in Note 0002562 you could submit some example code?

I suspect the google search ranking is based on number of links elsewhere to the page. The notice of a newer document is at the top of the majority of each page of the document set - so there is no need to read the whole page.
Yes the links could be improved. The current link was programmatically inserted as a simple html link, again if you have a specific suggestion for a solution it would be considered.
(0002564)
ajosey (manager)
2015-02-25 09:39

 I noted that the last bug note did not trigger an alert , so this is flagging that a response to bug note 0002562 was entered in bug note 0002563.
(0002565)
harveyab (reporter)
2015-02-25 12:28

 Can't this (old) page be edited? It is not like this was correct for an older version of the C library that was documented in the past. An improved example follows:

EXAMPLES

  Reading from a Stream

  The following example reads multiple single-byte elements from the fp stream into the array pointed to by buf.

    #include <stdio.h>
    ...
    size_t bytes_read;
    int buf_size = 100;
    char buf[buf_size];
    FILE *fp;
    ...
    bytes_read = fread(buf, sizeof(char), buf_size, fp); /* Read up to 100 chars (bytes) into the array */
    ...

  If a read error occurs, bytes_read will contain the number of bytes actually read from the stream.

  The following example reads up to 3 elements from the fp stream into the array pointed to by buf.

    #include <stdio.h>
    ...
    size_t ints_read;
    int buf[3];
    FILE *fp;
    ...
    ints_read = fread(buf, sizeof(int), 3, fp); /* Read 3 ints (that would be 12 bytes on some machines) */
    ...

  If a read error occurs, ints_read will be the number of complete ints read. The next int in the array may be partially read.
(0002568)
nick (manager)
2015-02-26 16:55

 As regards the suggestion of editing the old 2004 edition of the fread() page,
this is (an HTML translation of) a historical version of a formal standard
published by ISO, IEEE and The Open Group. By changing it we would be rewriting history.
(0002569)
nick (manager)
2015-02-26 16:55
edited on: 2015-02-26 17:02

 In the next Technical Corrigendum, on P921, L31022-31023 (for the Issue 7-2013 edition), change:
     
The following example reads a single element from the fp stream into the array pointed to by buf.

to:
     
The following example transfers a single 100-byte fixed length record from the fp stream into the array pointed to by buf.
(0002571)
harveyab (reporter)
2015-03-04 06:11
edited on: 2015-03-04 06:18

 Well I'm disappointed. To me the proposed change may be correct, but it does not seem to me to be straightforward nor typical. And may be misleading to the average reader.

And correcting an error in a history book is not rewriting history. You got the history wrong in the first place. It seems that if you can add a note to the page saying that there is a newer version, you can make other changes as well. But I won't push it.

And for that matter if you are unwilling to make a better change to a new version, I wouldn't trust that you would make a reasonable change to an old one anyway.
(0002572)
ajosey (manager)
2015-03-04 08:41

 There are processes governing change to the standards set down by ISO/IEC JTC1, IEEE and The Open Group - and adding a note in the page header is not changing the content - so something we were able to do.

As to whether a change is better than any other is subjective, and the nature of standards development is such that it is a consensus process whereby the standards developers have to come to agreement with formal balloting within the sponsoring standards organizations - often that will mean that an individual may not see their proposals agreed with.

If you need to discuss this further its best to switch to the mailing list rather than the bug report .

- Issue History
Date Modified Username Field Change
2015-02-22 14:20 harveyab New Issue
2015-02-22 14:20 harveyab Name => Harvey Block
2015-02-22 14:20 harveyab URL => http://pubs.opengroup.org/onlinepubs/009695399/functions/fread.html [^]
2015-02-22 14:20 harveyab Section => Example code for fread()
2015-02-23 09:35 geoffclare Note Added: 0002557
2015-02-23 09:37 geoffclare Relationship added duplicate of 0000232
2015-02-24 08:52 harveyab Note Added: 0002558
2015-02-24 15:31 ajosey Note Added: 0002561
2015-02-24 21:20 harveyab Note Added: 0002562
2015-02-25 08:03 ajosey Note Added: 0002563
2015-02-25 09:39 ajosey Note Added: 0002564
2015-02-25 12:28 harveyab Note Added: 0002565
2015-02-26 16:55 nick Note Added: 0002568
2015-02-26 16:55 nick Note Added: 0002569
2015-02-26 16:57 nick Status New => Resolved
2015-02-26 16:57 nick Resolution Open => Accepted As Marked
2015-02-26 16:58 nick Tag Attached: tc2-2008
2015-02-26 16:58 nick Note Edited: 0002569
2015-02-26 16:59 nick Project Online Pubs => 1003.1(2004)/Issue 6
2015-02-26 17:00 nick Page Number => (page or range of pages)
2015-02-26 17:00 nick Line Number => (Line or range of lines)
2015-02-26 17:00 nick Interp Status => ---
2015-02-26 17:00 nick Final Accepted Text => see Note: 0002569
2015-02-26 17:01 nick Note Edited: 0002569
2015-02-26 17:02 nick Note Edited: 0002569
2015-03-04 06:11 harveyab Note Added: 0002571
2015-03-04 06:18 harveyab Note Edited: 0002571
2015-03-04 08:41 ajosey Note Added: 0002572
2019-06-10 08:54 agadmin Status Resolved => Closed

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