classification
Title: socket.shutdown documentation: on some platforms, closing one half closes the other half
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, kiilerix, neologix, nicdumz, pitrou, python-dev
Priority: normal Keywords: patch

Created on 2009-08-24 08:45 by nicdumz, last changed 2012-01-29 15:46 by neologix. This issue is now closed.

Files
File name Uploaded Description Edit
socketshutdown.patch nicdumz, 2009-08-24 08:45 Documentation patch for socket.shutdown: specify platform dependent behaviors
Messages (8)
msg91912 - (view) Author: Nicolas Dumazet (nicdumz) Date: 2009-08-24 08:45
I had a bad time understanding what happens in Mac OS X after a shutdown
call: after calling shutdown(SH_WR) on side A, a corresponding
shutdown(SH_RD) on side B would raise a socket.error: socket is not
connected.
It is quite surprising when you are used to sockets in Linux, which
expect you to shut one end, and then the other one.

It turns out that under Mac OS X, a shutdown call closes the connection
on the other half. And the only mention I could find of this behavior
was here, r68611 :
http://svn.python.org/view/python/trunk/Lib/test/test_socket.py?r1=64125&r2=68611&pathrev=68611

I think that the documentation should specify that (surprising)
behavior: I attached a patch explaining that detail.


Thanks!
msg109971 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-07-11 09:23
Thanks, applied in r82798.
msg151124 - (view) Author: Mads Kiilerich (kiilerix) * Date: 2012-01-12 13:19
I was scared by the note in the documentation and wondered if the socket Python API was completely incapable of handling half-closed connections cross platform. pitrou helped me on IRC to track the note down to this issue.


IMO the bug report should have been rejected and the documentation patch should be removed. It shouldn't be that surprising that shutting something down that already has been shutdown (by the peer) will fail.

I don't see any indication that a "shutdown call closes the connection on the other half". It makes it half-closed as it should - and if it did anything else (which the note indicates) then it would be a big violation of BSD TCP API.

Ok, it might be slightly surprising that the next shutdown on the other end fails, but that is fully covered by "Note Some behavior may be platform dependent, since calls are made to the operating system socket APIs." It is not specific to Python in any way, AFAICT.

If anything it could just say something like "Note that shutdown of a socket that already has been shut down by the peer is platform dependent and might fail."
msg151148 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2012-01-12 19:48
> I was scared by the note in the documentation and wondered if the
> socket Python API was completely incapable of handling half-closed
> connections cross platform.
[...]
> It makes it half-closed as it should

Indeed. Calling shutdown(SHUT_WR) doesn't close the other end (which doesn't make much sense), it just sends a FIN (or RST depending on the context). It's the other end which decides to return ENOTCONN upon shutdown(SHUT_RD) on OS X, which is questionable (not sure it's against the BSD socket API, since shutdown(SHUT_RD) doesn't have any counterpart in the TCP layer).

I also find this note confusing and scary for no good reason, and since I don't think we should document every OS idiosyncrasies, it would probably be better to revert it.

I'll leave this open for a couple days to see if anyone objects, otherwise I'll revert it.
msg151150 - (view) Author: Nicolas Dumazet (nicdumz) Date: 2012-01-12 21:16
> It's the other end which decides to return ENOTCONN upon shutdown(SHUT_RD) on OS X, which is questionable
> (not sure it's against the BSD socket API, since shutdown(SHUT_RD) doesn't have any counterpart in the TCP layer).

Exactly. The same code raises a socket.error in one platform (mac os) and not on another (linux). Why not document this questionable behavior?

I'm sorry, I realize that my original patch was imprecise. I'm not an expert here, and I simply read http://svn.python.org/view/python/trunk/Lib/test/test_socket.py?r1=64125&r2=68611&pathrev=68611 . Ok, fine -- it doesn't close the other end per se, but shutdown(SH_RD) after a FIN on MacOS raises a socket.error . This is questionable, unexpected, and should be documented.


If possible, I'd like to push for a rewording instead of a revert.
msg151241 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2012-01-14 10:29
> This is questionable, unexpected, and should be documented.

There's already this note at the top of the socket module documentation:
"""
Note

Some behavior may be platform dependent, since calls are made to the
operating system socket APIs.
"""

There are other such subtleties with the socket API, e.g. SO_REUSEADDR
which doesn't have the same semantics on Windows. As I said earlier, I
don't think we should document every platform quirks: it will make
users worry for no reason, and as time passes, there's a chance that
the documentation doesn't match the actual behavior.
For example, this specific behavior might very well be a bug, and it's
not our responsibility to document this.
msg152239 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-01-29 15:43
New changeset 9be82f458b79 by Charles-François Natali in branch 'default':
Issue #6774: Back out c8b77efe8b56, which only brings confusion.
http://hg.python.org/cpython/rev/9be82f458b79
msg152241 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2012-01-29 15:46
I've reverted the commit.
History
Date User Action Args
2012-01-29 15:46:00neologixsetstatus: open -> closed
versions: + Python 3.3
messages: + msg152241

resolution: rejected
stage: resolved
2012-01-29 15:43:53python-devsetnosy: + python-dev
messages: + msg152239
2012-01-14 10:29:42neologixsetmessages: + msg151241
2012-01-12 21:16:21nicdumzsetmessages: + msg151150
2012-01-12 19:48:00neologixsetstatus: closed -> open
resolution: accepted -> (no value)
messages: + msg151148
2012-01-12 13:24:13pitrousetnosy: + neologix
2012-01-12 13:19:26kiilerixsetnosy: + pitrou, kiilerix

messages: + msg151124
title: socket.shudown documentation: on some platforms, closing one half closes the other half -> socket.shutdown documentation: on some platforms, closing one half closes the other half
2010-07-11 09:23:23georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg109971
2010-07-11 09:18:04BreamoreBoysetassignee: georg.brandl -> docs@python

nosy: + docs@python
2009-08-24 08:45:20nicdumzcreate