The "socket programming HowTO" suggests wrong `socket.send` behavior

[d-maurer]

https://docs.python.org/3/howto/sockets.html#socket-howto
suggests (via the MySocket.mysend example in the section "Using a Socket") that send on a socket closed by the remote end returns 0 to indicate the disconnection.
On my system (Linux 5.4, Python 3.10), socket.send does not return 0 in this
case but raises OSError(EPIPE) instead.

Linked PRs

• gh-109532: fix socket HOWTO inaccuracy about send() on broken connection #144747

[serhiy-storchaka]

This was discussed in the following StackOverflow questions.

• https://stackoverflow.com/questions/34919846/when-and-why-socket-send-returns-0-in-python
• https://stackoverflow.com/questions/3081952/with-c-tcp-sockets-can-send-return-zero

It seems that nobody can guarantee that the underlying send() syscall does not return 0. And if it returns 0, Python's send() will return 0 too. This can happen in rare circumstances, this can be depended on platform (and never happen on some platforms).

The documentation does not say that send() returns 0 on broken connection, it says that if it returns 0, the connection is broken and you should not try to to send again. This is technically correct.

cc @vstinner