classification
Title: socket.fileno() documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jelle Zijlstra, docs@python, georg.brandl, kushal.das, pitrou, python-dev, r.david.murray, zach.ware
Priority: normal Keywords: patch

Created on 2013-10-12 16:33 by georg.brandl, last changed 2016-06-07 02:38 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue19234.patch kushal.das, 2016-06-02 17:48 Adds more lines to explain the behavior of socket.fileno() in case of error. review
Messages (7)
msg199592 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-12 16:33
-------- Original-Nachricht --------
Betreff: [docs] socket.fileno() documentation
Datum: Thu, 10 Oct 2013 19:27:35 +0200
Von: Vlado Potisk <vlado@poti.sk>
An: docs@python.org

I might be wrong but in my opinion the socket library documentation is not
clear enough regarding the behaviour of the fileno() method in a case of a
failure.

In the Python 3.2 socket library documentation there is:
----
exception socket.error

    A subclass of IOError, this exception is raised for socket-related errors.
-----
 socket.close()

    Close the socket. All future operations on the socket object will fail.
----
 socket.fileno()

    Return the socket’s file descriptor (a small integer).
----

Based on the information quoted above, I wrote a test if a socket is active or
if it has been closed already:

try:
	sock.fileno()
except socket.error:
	return False
return True

But is doesn't work. I have found out that fileno() returns -1 on a closed
socket. Replacing fileno() with e.g. getsockname() fixes the code.

It looks like a fileno's failure - unlike to getsockname's failure - is not
expressed by raising an exception, but by returning -1. However this seems to
be not documented and that's why I'm unsure if I may rely on this.
msg199594 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-10-12 16:41
See also issue 19154.  For consistency with the rest of Python it should probably raise ValueError.  But at this point it has done what it does for a long time (which is to return what the underlying posix function returns), so we should probably just document it.
msg199646 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-10-13 00:51
Indeed, this should probably be documented as-is - or, if we want to change the behaviour, discussed on python-dev first.
msg266898 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2016-06-02 17:48
Adds more lines to explain the behavior of socket.fileno() in  case of error.
msg266939 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2016-06-02 20:04
I think the additions are redundant; pick one or the other.  The first should be sufficient.
msg267283 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-04 17:24
New changeset d83007ab69e2 by Kushal Das in branch '3.5':
Issue #19234: Documents socket.fileno() returns -1 on failure
https://hg.python.org/cpython/rev/d83007ab69e2

New changeset 3c745b656dca by Kushal Das in branch 'default':
Issue #19234: Merge from 3.5
https://hg.python.org/cpython/rev/3c745b656dca
msg267454 - (view) Author: Jelle Zijlstra (Jelle Zijlstra) * (Python triager) Date: 2016-06-05 18:35
This looks fixed.
History
Date User Action Args
2016-06-07 02:38:19berker.peksagsetstage: patch review -> resolved
2016-06-05 18:35:46Jelle Zijlstrasetstatus: open -> closed

nosy: + Jelle Zijlstra
messages: + msg267454

resolution: fixed
2016-06-04 17:24:58python-devsetnosy: + python-dev
messages: + msg267283
2016-06-02 20:04:22zach.waresetversions: + Python 2.7, Python 3.5, Python 3.6
nosy: + zach.ware

messages: + msg266939

stage: patch review
2016-06-02 17:48:33kushal.dassetfiles: + issue19234.patch

nosy: + kushal.das
messages: + msg266898

keywords: + patch
2013-10-13 00:51:38pitrousetnosy: + pitrou
messages: + msg199646
2013-10-12 16:41:44r.david.murraysetnosy: + r.david.murray
messages: + msg199594
2013-10-12 16:33:57georg.brandlcreate