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>
 
 short 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);
 }
   
 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 always return the following events:

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

[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

== FreeBSD ==
FreeBSD 13.1 POLLIN|POLLHUP always set:

POLLIN: 1 POLLOUT: 4 POLLHUP: 10

do_test events 0 data 0x0: 10

do_test events 1 data 0x0: 11

do_test events 4 data 0x0: 10

do_test events 5 data 0x0: 11

do_test events 3f data 0x0: 11

do_test events 0 data 0x20072e: 10

do_test events 1 data 0x20072e: 11

do_test events 4 data 0x20072e: 10

do_test events 5 data 0x20072e: 11

do_test events 3f data 0x20072e: 11

== NetBSD ==
NetBSD 9.3

localhost$ ./a.out

POLLIN: 1 POLLOUT: 4 POLLHUP: 10

poll err 0

do_test events 1 data 0x0: 1

do_test events 4 data 0x0: 4

do_test events 5 data 0x0: 5

do_test events 3f data 0x0: 5

poll err 0

do_test events 1 data 0x400dec: 1

do_test events 4 data 0x400dec: 4

do_test events 5 data 0x400dec: 5

do_test events 3f data 0x400dec: 5

???

== BSDs ==
- openbsd

- illumos

- macos??

== Windows ==
cygwin:

$ ./a.exe

POLLIN: 1 POLLOUT: 4 POLLHUP: 10

poll err 0

do_test events 1 data 0x0: 1

do_test events 4 data 0x0: 4

do_test events 5 data 0x0: 5

do_test events 3f data 0x0: 5

poll err 0

do_test events 1 data 0x10040307c: 1

do_test events 4 data 0x10040307c: 4

do_test events 5 data 0x10040307c: 5

do_test events 3f data 0x10040307c: 5


wsapoll

== Emulation ==
wine?

cygwin

minix

my dosbox code :(