bugGNU Octave - Bugs: bug #62725, fputs, puts documentation have...

 
 

bug #62725: fputs, puts documentation have unclear reference to EOF

Submitter:  Colin Macdonald <cbm>
Submitted:  Fri 08 Jul 2022 08:06:50 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Sat 09 Jul 2022 08:45:23 PM UTC, comment #3: 

I just use 'grep' on the documentation and this appears to be the only place where EOF is used as a return value (this was a quick search).

I changed both the generated return value and the documentation for fputs and puts in this changeset http://hg.savannah.gnu.org/hgweb/octave/rev/05a64f60bc1e.

This bug report invites a larger question: Are there other instances of Octave functions where a platform-specific value leaks through to Octave?  If so, it would be good to fix those as well to have a defined value.

Rik <rik5>
Group administrator
Fri 08 Jul 2022 09:29:04 PM UTC, comment #2: 

Thanks!  Your further proposal makes sense: fputs is not a M*tl*b function so no compatibility concerns.

Colin Macdonald <cbm>
Fri 08 Jul 2022 09:04:02 PM UTC, comment #1: 

Triggering is not hard: open an existing file foo for reading and try to print a string to it:


fid=fopen("foo","r");
a=fputs(fid,"bar")


On my system, a is indeed the double -1. Yes, your suggestion solves the documentation bug (it is indeed a bug, because the octave interpreter does not know EOF, different from, for example, SEEK_CUR), but I would even say that fputs should not just pass through the return value from the internally used C function, but rather check this return value and itself return 0 for success and -1 for error, as it probably does already on the vast majority of installations, and it should also be documented like that. In C, this would be just a


return -(r<0)


where r is the return value of the system function, which takes practically zero additional time compared to what fputs itself costs.

Michael Leitner <mleitner>
Fri 08 Jul 2022 08:06:50 PM UTC, original submission:  

`help fputs` says:


     Return a non-negative number on success or EOF on error.


This is probably clear to C programmers but likely confusing to Octave programmers.  Maybe it should should say:


     Return a non-negative number on success or a negative value
     on error (specifically the C-code constant @code{EOF}, which
     is system dependent but often @code{"-1"}).


I'm not sure how to trigger a `fputs` failure to check this in practice...

Colin Macdonald <cbm>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by mleitner (Posted a comment)
  • -email is unavailable- added by cbm (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-07-09 rik5 Open/ClosedOpen Closed
    2022-07-09 rik5 StatusNone Fixed
        Summary&quot;help fputs&quot; has unclear reference to EOF fputs, puts documentation have unclear reference to EOF

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code