This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Description of file-object read() method is wrong.
Type: behavior Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: Nosy List: clintonroy, docs@python, grante, gregory.p.smith, pitrou, r.david.murray, yohell
Priority: normal Keywords: easy

Created on 2006-02-15 17:49 by grante, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
read.txt grante, 2006-02-15 17:51 Suggested changes for file-object read() documentation
Messages (7)
msg27523 - (view) Author: Grant Edwards (grante) Date: 2006-02-15 17:49
There are two errors in the documentation of the file
object's
read() method found at

http://www.python.org/doc/current/lib/bltin-file-objects.html#l2h-242

Suggested changes (unindented) are shown below interspersed
with the current text with insertions noted by a '+' in the
first column:

     Read at most size bytes from the file (less if the
read
     hits EOF before obtaining size bytes). If the size
     argument is negative or omitted, read all data
until EOF
     is reached.
     
+ Under some circumstances (e.g. system call aborted by
+ a signal) read() called with a negative or absent size
+ argument may return data before EOF is reached (even in
+ blocking mode).
     
     The bytes are returned as a string object. An
empty string
     is returned when EOF is encountered immediately. (For
     certain files, like ttys, it makes sense to continue
     reading after an EOF is hit.)

The last sentence above (the parenthetical one) is
false for
Linux/Unix.  Once you hit EOF on a tty, it will return EOF
forever until it's closed and re-opened.  If the above
sentence
is true for other OSes, I suggest it be so qualified --
otherwise it should just be deleted.
     
     Note that this method may call the underlying C
function
     fread() more than once in an effort to acquire as
close to
     size bytes as possible. Also note that when in
     non-blocking mode, less data than what was
requested may
     be returned, even if no size parameter was given. 
msg27524 - (view) Author: Grant Edwards (grante) Date: 2006-02-15 17:51
Logged In: YES 
user_id=61937

Well, that didn't work very well.  I really hate these web
interfaces.  I've attached the suggested changes as a text file.
msg27525 - (view) Author: YoHell (yohell) Date: 2006-02-16 11:17
Logged In: YES 
user_id=1008220

Well spoken!

However I'm not sure I quite follow you here:

> The last sentence above (the parenthetical one) is false 
> for Linux/Unix. Once you hit EOF on a tty, it will return
> EOF forever until it's closed and re-opened. 

A quote from Donn Cave in a discussion on comp.lang.python:
"""
They were probably thinking of the way the UNIX tty
driver delivers an EOF on <ctrl>D, after which of
course you can continue to read data from the same tty.

"""
This is also true for the Linux tty (afaik), so under those
circumstances it may really make sense to continue reading
past EOF.

example:
-------------------------------------------------
#!/usr/bin/python
import sys
while True:
    s = sys.stdin.read()
    print s
-------------------------------------------------

Pressing Ctrl-D while providing input to sys.stdin via the
keyboard will cause sys.stdin.read() to return, and you will
still be able to keep reading from sys.stdin without closing
and reopening it explicitly.

But then again I might have missed something.

/Joel Hedlund
msg27526 - (view) Author: Grant Edwards (grante) Date: 2006-02-16 13:08
Logged In: YES 
user_id=61937

My bad.  You're right about the Ctrl-D case.  The code I was
looking that caused a permanent EOF was when the master end
of a pty was closed.  I think.  Anyway, Ctrl-D doesn't cause
a permanent EOF condition and you can read more data afterwards.
msg27527 - (view) Author: Clinton Roy (clintonroy) Date: 2006-06-02 10:40
Logged In: YES 
user_id=31446

'''
Also note that when in non-blocking mode, less data than
what was requested may be returned, even if no size
parameter was given.'''

This sentence doesn't make much sense to me, if you haven't
given a size parameter, you haven't requested any size..
msg27528 - (view) Author: Clinton Roy (clintonroy) Date: 2006-06-02 10:52
Logged In: YES 
user_id=31446

'''
Also note that when in non-blocking mode, less data than
what was requested may be returned, even if no size
parameter was given.'''

This sentence doesn't make much sense to me, if you haven't
given a size parameter, you haven't requested any size..
msg169173 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-08-26 22:27
It looks to me like we (now, as of 67dc99a989cd) handle EINTR, so that the suggested caveat is no longer true.  Since the TTY example has also been explained as correct, I'm going to close this.  If I'm wrong about EINTR, someone (Antoine or Gregory, presumably) can reopen it...
History
Date User Action Args
2022-04-11 14:56:15adminsetgithub: 42903
2012-08-26 22:27:45r.david.murraysetstatus: open -> closed

assignee: docs@python ->

nosy: + r.david.murray, gregory.p.smith
messages: + msg169173
resolution: out of date
stage: patch review -> resolved
2010-07-16 14:20:20BreamoreBoysetassignee: docs@python

nosy: + docs@python
versions: - Python 2.6, Python 3.1
2009-04-22 14:35:41ajaksu2setkeywords: + easy
nosy: + pitrou
versions: + Python 3.1

stage: patch review
2009-03-21 00:25:44ajaksu2settype: behavior
versions: + Python 2.6
2006-02-15 17:49:14grantecreate