Editing POLLHUP polling

'''This page is a work in progress'''

Recently I've been trying to listen on multiple sockets at once for events like reading or writing. This has worked fine, but as I've tried to listen for a socket close event I've found the documentation poor and often contradictory. This page is my attempt to figure this topic out.

== POSIX ==
POSIX specifies two functions for waiting on multiple file descriptors:

* [https://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html select] which originates from the BSD sockets API

* [https://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html poll] which originates from the System V STREAMS API

select doesn't specify anything to do with sockets being closed, so that's not too useful.

poll initially looks like it's better but it leaves a lot of questions after reading:

* Does POLLHUP apply to sockets?
* Can the events field be 0 and still get POLLHUP events?
* Under what conditions do we even get return events?

I highly recommend trying to read the poll standard and sussing out these details.

As far as I can tell nobody has brought up either of these questions during the standards process. At least in these sources:

* [https://www.opengroup.org/austin/aardvark/latest/ Aardvark defect reports for The Austin Group Specification]
* [https://austingroupbugs.net/view_all_bug_page.php Austin Group Defect Tracker]
* [https://www.opengroup.org/austin/docreg.html Austin Group Document Register]
* [https://www.mail-archive.com/austin-group-l@opengroup.org/maillist.html austin-group-l mailing list]

The only talk of this issue I've found online is the 2001 email "[https://groups.google.com/g/comp.unix.programmer/c/bNNadBIEpTo/m/G5gs1mqNhbIJ poll() and events==0]" which has no clear answers.

== Existing lore ==

Richard Kettlewell's [https://www.greenend.org.uk/rjk/tech/poll.html poll() and EOF] has a test results for the case of setting POLLIN and closing a socket with no data to read. This is the most common case of POLLHUP use I see online. 

The test results give us some interesting data: 

* The first is that POLLIN is often set if a socket is closed. If set alone this means a POLLIN poll without any return events may mean you still can't read from the socket 
* The second is that POLLHUP is often not set on older systems. This means programs polling POLLOUT may miss socket closures altogether. This is one reason why systems are moving to set POLLHUP instead of just POLLIN 
* The third is that neither are always set. Cygwin and very early Linux systems only set POLLHUP. This seems like a bug to me especially as most online advice recommend watching POLLIN for socket closures when writing portable programs 

This data doesn't check what poll returns if there's still data in the socket to read but the connection has closed. That case may have entirely different results. 

Another issue is what to return if a socket was never connected in the first place? 

* [https://jira.mongodb.org/browse/CDRIVER-2996 AIX returned POLLOUT in 2019] 
* [https://freebsd-net.freebsd.narkive.com/zJxZYQdq/pollhup-on-never-connected-socket FreeBSD returned POLLHUP in 2011] 

== Test code ==

I wrote this quick program that tests what happens when you poll a closed socket with or without data with various event flags.

 /* compile and run with gcc test.c -oTEST && ./TEST */
 
 #include <stdio.h>
 #include <errno.h>
 #include <poll.h>
 #include <sys/socket.h>
 #include <unistd.h>
 #include <string.h>
 
 int do_test(short events, const char *data) {
   /* create a socket pair, one end for parent, one end for child */
   int sockets[2];
   int rc;
   rc = socketpair(AF_UNIX, SOCK_STREAM, 0, sockets);
   if(rc == -1) { printf("socket err %i\n", errno); return 1; }
   if(data) {
     rc = write(sockets[1], data, strlen(data));
     if(rc == -1) { printf("write err %i\n", errno); return 1; }
   }
   rc = close(sockets[1]); /* close one end */
   if(rc == -1) { printf("close err %i\n", errno); return 1; }
   /* poll for events */
   struct pollfd fd;
   fd.fd = sockets[0]; /* watch other end */
   fd.events = events;
   fd.revents = 0;
   rc = poll(&fd, 1, 10000);
   if(rc < 1) { printf("poll err %i\n", errno); return 1; }
   printf("do_test events %x data %p: %0x\n", events, data, fd.revents);
   return 0;
 }
   
 void do_multitest(const char* str) {
   do_test(0, str);
   do_test(POLLIN, str);
   do_test(POLLOUT, str);
   do_test(POLLIN|POLLOUT, str);
   do_test(POLLIN|POLLOUT|POLLPRI|POLLHUP|POLLERR|POLLNVAL, str);
 }
 
 int main(void) {
   printf("POLLIN: %x POLLOUT: %x POLLHUP: %x\n", POLLIN, POLLOUT, POLLHUP);
   do_multitest(NULL);
   do_multitest("hello world");
   return 0;
 }

It's a bit nasty but it seems to get the job done to verify behaviour.

== Linux ==
On Linux 5.19 it seems that polling a closed socket will return:

* POLLIN if checking
* POLLOUT if checking
* POLLHUP always, even if checking for no events

This is regardless of whether there is data in the socket to read.

This behaviour is not POSIX compatible as POLLHUP and POLLOUT are supposedly mutually exclusive. The source code notes this is to prevent stuck sockets.

[https://man7.org/linux/man-pages/man2/poll.2.html The Linux poll man page] specifies the following:

* POLLIN means there is data to read
* POLLOUT means data can be written
* POLLHUP indicates a pipe or socket has the peer end closed
* The events bitmask can be empty
The history for Linux's behaviour is as follows:

* 1997: Linux 2.1.23pre1 added the poll system call, with no AF_UNIX socket support
* 1998: Linux 2.1.106pre added AF_UNIX socket support. POLLHUP is returned on socket close
* 2000: Linux 2.3.41pre2 returns POLLIN on empty socket close

== FreeBSD ==
On FreeBSD 13.1 it seems that polling a closed socket will return:

* POLLIN if checking
* POLLHUP always, even when checking for no events

This is regardless of whether there is data in the socket to read.

The [https://www.freebsd.org/cgi/man.cgi?sektion=2&query=poll FreeBSD poll man page] has less information than the POSIX standard.

It's not documented but the events bitmask can be empty.

The history of FreeBSD's behaviour is as follows:

* 1997: [https://svnweb.freebsd.org/base?view=revision&revision=29351 FreeBSD r29351 implements poll] based on NetBSD's code. POLLHUP is not returned by sockets
* 2009: [https://svnweb.freebsd.org/base?view=revision&revision=195423 FreeBSD r195423 adds POLLHUP for sockets]
* 2009: [https://svnweb.freebsd.org/base?view=revision&revision=196460 FreeBSD r196460 improves poll conformance for sockets] by returning POLLHUP more often instead of POLLIN 
* 2009: [https://svnweb.freebsd.org/base?view=revision&revision=196556 FreeBSD r196556 fixes POLLHUP on half-closed sockets] by only returning POLLHUP on fully closed sockets and returning POLLIN on empty buffers

== OpenBSD ==
On OpenBSD 7.1 it seems that polling a closed socket will return:

* POLLIN if checking
* POLLHUP always, even when checking for no events

This is regardless of whether there is data in the socket to read.

This behavior is identical to FreeBSD's behaviour.

The [https://man.openbsd.org/poll.2 OpenBSD poll man page] specifically notes that POLLERR can indicate a socket disconnection.

It's not documented but the events bitmask can be empty.

The history of OpenBSD's behaviour is as follows:

* 1996 may 18: poll() as a system call def0fdca14684753dfcf5932f90c11d82dd5c6da
* 2013 oct 4: 1dd598610a0d79ae84da34f1e0d0f8bebdd38ecd
* 2013 oct 6: 8e5efd0e12529b9c3820f5399c9da6a63281c34f
* 2013 sep 28: 54beff47b69a9978611dfbe9f827c01d91357417
* 2015 may 10: b7b44fe5796e416f560eb15867dc757db11a47d6 POLLHUP?
* 2020 jun 15: 2b88cdafd374c425bef518b6071e7ccde4677902 EVHUP
* 2003 sep 23: 154dfaaa7e8e replace select backends
* 2020 jun 15: 2b88cdafd374c425bef518b6071e7ccde4677902 match POLLHUP
* 2022 feb 8: c5e59ae303d9 final switch to kqueue

== NetBSD ==
On NetBSD 9.3 it seems that polling a closed socket will return:

* POLLIN if checking
* POLLOUT if checking

This is regardless of whether there is data in the socket to read.

The [https://man.netbsd.org/poll.2 NetBSD poll man page] specifically notes that "Sockets produce POLLIN rather than POLLHUP when the remote end is closed".

Leaving the events bitmask empty causes poll to timeout.

The history of NetBSD's behaviour is as follows:

* 1996: [http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/kern/sys_generic.c.diff?r1=1.27&r2=1.28&only_with_tag=MAIN NetBSD implements poll] and [http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/kern/sys_socket.c.diff?r1=1.14&r2=1.15&only_with_tag=MAIN NetBSD implements poll support for sockets] at the same time. No POLLHUP is implemented for sockets, existing select behaviour is kept

== MSYS2 on Windows ==
On MSYS2 in 2022 polling a closed socket will return:

* POLLIN if checking
* POLLOUT if checking

This is regardless of whether there is data in the socket to read.

MSYS2 does not have any specific man pages.

Leaving the events bitmask empty causes poll to timeout. This makes sense because the implementation is emulating select using poll. The history for MSYS2's behaviour is as follows:

* 2000: [https://www.cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=afb7e7196a6dc16c145a455d6cf0761cbaeb7a48 Cygwin implements the poll system call]. POLLHUP is set as a single event if a file descriptor is closed
* 2002: [https://www.cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=7382e593a01ee81cea5df91a77a9868281de8c04 Cygwin peeks sockets]. POLLHUP is now set if a socket is closed
* 2005: [https://www.cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=6ba3f6bb2d088c7b5ffc84a6ed74ad3d525fde37 Cygwin switches to POLLIN when peeking]. POLLHUP is now only set if a file descriptor is closed
*2011: [https://www.cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=0077cd1016c8414f6175f8e94f97be9ea4506bea Cygwin checks socket shutdown status]. POLLHUP is now generated if a socket is shutdown
*2018: [https://www.cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=b79018ee3a36140a82e2dfa2d7a71fc0bf15d892 Cygwin only detects Winsock socket shutdowns]. Now POLLHUP no longer applies to AF_UNIX sockets

== poll emulation ==
Many applications that run on systems without poll will attempt to emulate it using the select function.

A naive emulation works like this:

* Map pollfds with POLLIN to select's readfds
* Map pollfds with POLLOUT to select's writefds
* Map pollfds with POLLPRI to select's errorfds
* Call select
* Map the readfds to the pollfds POLLIN return events
* Map the writefds to the pollfds POLLIN return events
* Map the errorfds to the pollfds POLLPRI return events

This has two problems:

* POLLHUP and POLLERR are not returned
* pollfds with no events are not mapped at all

Usually select will trigger a read event if the socket closes, so POLLHUP can be emulated using a peek. But this doesn't work if a pollfd has no events at all to check.

== Conclusions ==
Linux is the only system that documents the behaviour of polling only for POLLHUP. Next to that are FreeBSD and OpenBSD where the behaviour works and probably won't be changed as applications in the wild depend on it. Outside those systems I have no clue if this is a viable solution to this problem.

In general I have a sour feeling towards poll. It mixes up the task select does of waiting for system calls to not block with reporting a vague status of a file descriptors that you would learn about anyway by using system calls. POLLHUP feels like and reads like an afterthought.

In the future I'm definitely going to be using epoll or kqueue for my work. These tools have proper documentation and give concrete guarantees about how my program is going to work.
[[Category:Research]]