Help: shutdown(..., SHUT_WR) on TCP sockets

[Sergey Organov <sorganov at gmail dot com>]

Hello,

I've got a few problems properly closing TCP sockets on GLIBC/Linux/ARM,
and getting to the manual only added to the overall confusion.

First, the manual[*] doesn't even mention SHUT_WR, etc. constants,
instead it has raw numbers:

     The argument HOW specifies what action to perform:

     '0'
          Stop receiving data for this socket.  If further data arrives,
          reject it.

          [...]


That seems quite outdated.

2. The SHUT_WR (=1) specification seems to be plain wrong:

     '1'
          Stop trying to transmit data from this socket.  Discard any
          data waiting to be sent.  Stop looking for acknowledgement of
          data already sent; don't retransmit it if it is lost.


Discarding data contradicts both the intended usage of the feature and
the actual behavior (as observed by testing the state of the socket
write queue using 'ioctl(fd, TIOCOUTQ, &val)' call before and after
shutdown()).

Given the above, could please somebody clarify what is the actual
intended behavior of shutdown(..., SHUT_WR) on GLIBC/Linux nowadays?

1. Should it actually discard the data, or instead achieve something
useful? Like, say, what is described in Free-BSD manual[**]:

"Send queued data, wait for ACK, then send FIN."

2. Should it obey SO_LINGER and actually wait for data to be sent? To be
acknowledged[***]? 

3. Should it send 'FIN'?

Footnotes:

[*]  https://www.gnu.org/software/libc/manual/html_node/Closing-a-Socket.html#Closing-a-Socket

[**] https://gsp.com/cgi-bin/man.cgi?section=2&topic=shutdown

[***] My observation is that it rather neither discards the data, nor
waits for anything, no matter what SO_LINGER and ~O_NONBLOCK say, that
is not that bad as discarding the data, but still makes it virtually
impossible to properly wait for data sending or delivery before closing
the socket.

-- Sergey