Skip to content

socket.shutdown documentation: on some platforms, closing one half closes the other half #51023

Closed
Closed
socket.shutdown documentation: on some platforms, closing one half closes the other half#51023
Labels
docsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

Description

@nicdumz
nicdumz
mannequin
opened on Aug 24, 2009
BPO 6774
Nosy @birkenfeld, @pitrou
Files
  • socketshutdown.patch: Documentation patch for socket.shutdown: specify platform dependent behaviors
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2012-01-29.15:46:00.924>
created_at = <Date 2009-08-24.08:45:20.083>
labels = ['type-bug', 'docs']
title = 'socket.shutdown documentation: on some platforms, closing one half closes the other half'
updated_at = <Date 2012-01-29.15:46:00.906>
user = 'https://bugs.python.org/nicdumz'

    bugs.python.org fields:

    activity = <Date 2012-01-29.15:46:00.906>
actor = 'neologix'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-01-29.15:46:00.924>
closer = 'neologix'
components = ['Documentation']
creation = <Date 2009-08-24.08:45:20.083>
creator = 'nicdumz'
dependencies = []
files = ['14778']
hgrepos = []
issue_num = 6774
keywords = ['patch']
message_count = 8.0
messages = ['91912', '109971', '151124', '151148', '151150', '151241', '152239', '152241']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'pitrou', 'kiilerix', 'nicdumz', 'neologix', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6774'
versions = ['Python 3.3']

    Activity

    1. nicdumz commented on Aug 24, 2009

      @nicdumz
      nicdumzmannequin
      on Aug 24, 2009
      MannequinAuthor

      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!

    2. nicdumz
      assigned
      birkenfeld
      on Aug 24, 2009
    3. nicdumz
      added
      docsDocumentation in the Doc dir
      type-bugAn unexpected behavior, bug, or error
      on Aug 24, 2009
    4. BreamoreBoy
      assigned
      docspython
      and unassigned
      birkenfeld
      on Jul 11, 2010

    5. birkenfeld commented on Jul 11, 2010

      @birkenfeld
      birkenfeld
      on Jul 11, 2010
      Member

      Thanks, applied in r82798.

    6. birkenfeld
      closed this as completedon Jul 11, 2010

    7. kiilerix commented on Jan 12, 2012

      @kiilerix
      kiilerixmannequin
      on Jan 12, 2012
      Mannequin

      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."

    8. kiilerix
      changed the 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[/+] on Jan 12, 2012

    9. neologix commented on Jan 12, 2012

      @neologix
      neologixmannequin
      on Jan 12, 2012
      Mannequin

      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.

    10. neologix
      reopened this on Jan 12, 2012

    11. nicdumz commented on Jan 12, 2012

      @nicdumz
      nicdumzmannequin
      on Jan 12, 2012
      MannequinAuthor

      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.

    12. neologix commented on Jan 14, 2012

      @neologix
      neologixmannequin
      on Jan 14, 2012
      Mannequin

      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.

    13. python-dev commented on Jan 29, 2012

      @python-dev
      python-devmannequin
      on Jan 29, 2012
      Mannequin

      New changeset 9be82f458b79 by Charles-François Natali in branch 'default':
      Issue bpo-6774: Back out c8b77efe8b56, which only brings confusion.
      http://hg.python.org/cpython/rev/9be82f458b79

    14. neologix commented on Jan 29, 2012

      @neologix
      neologixmannequin
      on Jan 29, 2012
      Mannequin

      I've reverted the commit.

    15. neologix
      closed this as completedon Jan 29, 2012
    16. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      docsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

      Projects

      No projects

        Milestone

        No milestone

        Relationships

        None yet

        Development

        No branches or pull requests

        Issue actions