shutdown(2) is underdocumented

shutdown(2) is underdocumented

[Askar Safin]

shutdown(2) is underdocumented. Here is a lot of more details on
shutdown(2): https://github.com/WebAssembly/WASI/issues/547 . I
discovered them by experiment. So, please, document them

-- 
Askar Safin

Re: shutdown(2) is underdocumented

[Matthew House]

On Sat, Jul 22, 2023 at 8:40 AM Askar Safin <safinaskar@gmail.com> wrote:
> shutdown(2) is underdocumented. Here is a lot of more details on
> shutdown(2): https://github.com/WebAssembly/WASI/issues/547 . I
> discovered them by experiment. So, please, document them
>
> --
> Askar Safin

Documenting the asymmetry is probably a good idea: the TCP protocol only
defines the equivalent of shutdown(SHUT_WR) and shutdown(SHUT_RDWR), and
there's no natural equivalent of a shutdown(SHUT_RD), so I don't think the
semantics themselves can easily be made more symmetric.

To expand, the current behavior, where shutdown(SHUT_RD) by itself silently
drops incoming data received before a shutdown(SHUT_WR), but replies with a
RST to data received after a shutdown(SHUT_WR), is definitely pretty weird,
even looking at the relevant RFCs. tcp_rcv_state_process() in
net/ipv4/tcp_input.c implements this behavior: a RST is sent back if and
only if the connection is in the FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT,
CLOSING, or LAST-ACK state (i.e., not in the ESTABLISHED state), data is
received on the socket, and shutdown(SHUT_RD) has previously been called.
The logic is accompanied by the comment:

/*
 * RFC 793 says to queue data in these states,
 * RFC 1122 says we MUST send a reset.
 * BSD 4.4 also does reset.
 */

Looking at RFC 793 Section 3.5, it defines the CLOSE operation in a
"simplex fashion": a FIN is sent and further SENDs are no longer allowed,
but RECEIVEs are allowed until a FIN is sent from the remote host. This
clearly corresponds to the shutdown(SHUT_WR) operation, so it doesn't
appear to define any particular behavior for shutdown(SHUT_RD).

Instead, the entire justification for this behavior lies in RFC 1122
Section 4.2.2.13:

> A host MAY implement a "half-duplex" TCP close sequence, so
> that an application that has called CLOSE cannot continue to
> read data from the connection.  If such a host issues a
> CLOSE call while received data is still pending in TCP, or
> if new data is received after CLOSE is called, its TCP
> SHOULD send a RST to show that data was lost.

And in its Discussion:

> Some systems have not implemented half-closed
> connections, presumably because they do not fit into
> the I/O model of their particular operating system.  On
> these systems, once an application has called CLOSE, it
> can no longer read input data from the connection; this
> is referred to as a "half-duplex" TCP close sequence.

First off, this isn't a MUST but a SHOULD; I don't know where that idea
came from. Second off, we reach a bit of a conflict (IMO) between the
wording and intent of this clause. It defines the RST behavior only
following a CLOSE operation by the application, and a CLOSE still always
implies a shutdown(SHUT_WR). So at best, by a strict interpretation, the
application can be given a choice between shutdown(SHUT_WR) and
shutdown(SHUT_RDWR). Thus, Linux doesn't send any RSTs until after a
shutdown(SHUT_WR).

However, the whole point here is "to show that data was lost", and silently
dropping incoming data prior to a shutdown(SHUT_WR) is clearly contrary to
this goal. Clearly, a RST isn't very nice to either host, but neither is
lost data. So it seems at least defensible for a TCP implementation to
unconditionally reply with a RST to data received after a
shutdown(SHUT_RD). (As far as I know, this wouldn't break TCP itself from
the remote host's end, since it allows hosts to send a RST whenever they
feel like it. Higher-level protocols might be unhappy with it, though.)

But of course, the current behavior is ancient, dating back to
Linux 2.3.41pre2 from 2000. (Before then, a RST would only be sent after a
full close(2).) So there's no changing it at this point in Linux, at least
not without an explicit option. I do wonder if there are any other OSes
that have a shutdown(SHUT_RD) with different behavior, though.

Matthew House

Re: shutdown(2) is underdocumented

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4420 bytes --]

Hi Askar, Matthew,

On 2023-07-22 17:30, Matthew House wrote:
> On Sat, Jul 22, 2023 at 8:40 AM Askar Safin <safinaskar@gmail.com> wrote:
>> shutdown(2) is underdocumented. Here is a lot of more details on
>> shutdown(2): https://github.com/WebAssembly/WASI/issues/547 . I
>> discovered them by experiment. So, please, document them

I'm not competent enough to do so, I fear.  If anyone wants to prepare
a patch, please feel invited.  :-)

Cheers,
Alex

>>
>> --
>> Askar Safin
> 
> Documenting the asymmetry is probably a good idea: the TCP protocol only
> defines the equivalent of shutdown(SHUT_WR) and shutdown(SHUT_RDWR), and
> there's no natural equivalent of a shutdown(SHUT_RD), so I don't think the
> semantics themselves can easily be made more symmetric.
> 
> To expand, the current behavior, where shutdown(SHUT_RD) by itself silently
> drops incoming data received before a shutdown(SHUT_WR), but replies with a
> RST to data received after a shutdown(SHUT_WR), is definitely pretty weird,
> even looking at the relevant RFCs. tcp_rcv_state_process() in
> net/ipv4/tcp_input.c implements this behavior: a RST is sent back if and
> only if the connection is in the FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT,
> CLOSING, or LAST-ACK state (i.e., not in the ESTABLISHED state), data is
> received on the socket, and shutdown(SHUT_RD) has previously been called.
> The logic is accompanied by the comment:
> 
> /*
>  * RFC 793 says to queue data in these states,
>  * RFC 1122 says we MUST send a reset.
>  * BSD 4.4 also does reset.
>  */
> 
> Looking at RFC 793 Section 3.5, it defines the CLOSE operation in a
> "simplex fashion": a FIN is sent and further SENDs are no longer allowed,
> but RECEIVEs are allowed until a FIN is sent from the remote host. This
> clearly corresponds to the shutdown(SHUT_WR) operation, so it doesn't
> appear to define any particular behavior for shutdown(SHUT_RD).
> 
> Instead, the entire justification for this behavior lies in RFC 1122
> Section 4.2.2.13:
> 
>> A host MAY implement a "half-duplex" TCP close sequence, so
>> that an application that has called CLOSE cannot continue to
>> read data from the connection.  If such a host issues a
>> CLOSE call while received data is still pending in TCP, or
>> if new data is received after CLOSE is called, its TCP
>> SHOULD send a RST to show that data was lost.
> 
> And in its Discussion:
> 
>> Some systems have not implemented half-closed
>> connections, presumably because they do not fit into
>> the I/O model of their particular operating system.  On
>> these systems, once an application has called CLOSE, it
>> can no longer read input data from the connection; this
>> is referred to as a "half-duplex" TCP close sequence.
> 
> First off, this isn't a MUST but a SHOULD; I don't know where that idea
> came from. Second off, we reach a bit of a conflict (IMO) between the
> wording and intent of this clause. It defines the RST behavior only
> following a CLOSE operation by the application, and a CLOSE still always
> implies a shutdown(SHUT_WR). So at best, by a strict interpretation, the
> application can be given a choice between shutdown(SHUT_WR) and
> shutdown(SHUT_RDWR). Thus, Linux doesn't send any RSTs until after a
> shutdown(SHUT_WR).
> 
> However, the whole point here is "to show that data was lost", and silently
> dropping incoming data prior to a shutdown(SHUT_WR) is clearly contrary to
> this goal. Clearly, a RST isn't very nice to either host, but neither is
> lost data. So it seems at least defensible for a TCP implementation to
> unconditionally reply with a RST to data received after a
> shutdown(SHUT_RD). (As far as I know, this wouldn't break TCP itself from
> the remote host's end, since it allows hosts to send a RST whenever they
> feel like it. Higher-level protocols might be unhappy with it, though.)
> 
> But of course, the current behavior is ancient, dating back to
> Linux 2.3.41pre2 from 2000. (Before then, a RST would only be sent after a
> full close(2).) So there's no changing it at this point in Linux, at least
> not without an explicit option. I do wonder if there are any other OSes
> that have a shutdown(SHUT_RD) with different behavior, though.
> 
> Matthew House

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]