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:

• select which originates from the BSD sockets API

• 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:

• Aardvark defect reports for The Austin Group Specification
• Austin Group Defect Tracker
• Austin Group Document Register
• austin-group-l mailing list

The only talk of this issue I've found online is the 2001 email "poll() and events==0" which has no clear answers.

TODO: note these

https://doxygen.postgresql.org/latch_8c.html

https://lists.freedesktop.org/archives/pulseaudio-discuss/2018-February/029491.html

https://searchcode.com/total-file/51095668/dep/gsoap/stdsoap2.cpp/

https://doxygen.postgresql.org/latch_8c.html

https://lists.freedesktop.org/archives/pulseaudio-discuss/2018-February/029491.html

"some platforms do not set POLLHUP at all"

>>>>>> Moreover, when POLLHUP was set there may be data in pipe that must be read

>>>>>> before suspend. Linux sets POLLIN in that case. Freebsd and macos sets

>>>>>> POLLIN|POLLHUP even if no any data in pipe, but no writers left. Some platforms

>>>>>> do not set POLLHUP at all. So do read() and check it return 0 must be the only

>>>>>> condition to suspend source and open pipe for writing.

https://github.com/midendian/libnbio/blob/4d4cd3d6004f29792ff69d2ec54ea701e814109f/src/poll.c

https://github.com/nh2/hatrace/blob/7258134d87915f035efd36babc685c80fb1df8cc/example-programs/poll.c

https://github.com/GregoryVds/tcpsnitch/blob/38156066c043a368e105f66f1eed4916773f8ee5/tests/c_programs/poll.c

https://github.com/GregoryVds/tcpsnitch/blob/38156066c043a368e105f66f1eed4916773f8ee5/tests/c_programs/poll_dgram.c

https://lkml.iu.edu/hypermail/linux/kernel/0605.1/1420.html

https://www.mail-archive.com/curl-library@cool.haxx.se/msg02450.html

https://jira.mongodb.org/browse/CDRIVER-2996?page=com.atlassian.streams.streams-jira-plugin%3Aactivity-stream-issue-tab

https://www.unix.com/solaris/135021-polling-socket-descriptor-does-not-return-pollhup.html

https://curl.se/mail/lib-2009-09/0149.html

https://lists.freebsd.org/pipermail/freebsd-net/2011-September/029712.html

https://cboard.cprogramming.com/linux-programming/86878-failed-get-pollhup-event.html

https://sourceware.org/bugzilla/show_bug.cgi?id=13660

https://www.illumos.org/issues/4627

https://developer.illumos.narkive.com/dUe1v0Ya/poll-not-returning-pollhup-for-tcp-sockets-closed-by-the-other-end

https://github.com/ziglang/zig/pull/8988/commits/0dfe8c934a21fc38055cb5976feab2c7a3df5970

https://github.com/ziglang/zig/pull/8988/commits/22a1b48e580d0e2392e9f751d36b043daf993864

https://bugs.dragonflybsd.org/issues/3268

Test code

With that in mind, I wrote this quick program that polls for POLLHUP and nothing else:

/* compile and run with gcc test.c -oTEST && ./TEST */

#include <stdio.h>
#include <poll.h>
#include <sys/socket.h>
#include <unistd.h>

int main(void) {
  /* 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);
  /* fork in to to a parent in child */
  int proc = fork();
  if(proc == -1) { printf("fork err\n"); return 1; }
  if(proc != 0) {
    /* parent: poll for POLLHUP */
    rc = close(sockets[1]); /* close child end to avoid holding open */
    if(rc == -1) { printf("close err 1 \n"); return 1; }
    struct pollfd fd;
    fd.fd = sockets[0]; /* watch parent end */
    fd.events = 0;
    fd.revents = 0;
    rc = poll(&fd, 1, 10000);
    if(rc < 1) { printf("poll err\n"); return 1; }
    else if(!(fd.revents & POLLHUP)) { printf("no POLLHUP?\n"); return 1; }
    printf("got POLLHUP, all good\n");
    return 0;
  } else {
    /* child: close child socket end and quit */
    rc = close(sockets[1]); /* close child end */
    if(rc == -1) { printf("close err 3\n"); return 1; }
    return 0;
  }
}

It's a bit nasty but it gets the job done.

Linux

https://man7.org/linux/man-pages/man2/poll.2.html

"The field fd contains a file descriptor for an open file."

"The field events is an input parameter, a bit mask specifying the events the application is interested in for the file descriptor fd.  This field may be specified as zero, in which case the only events that can be returned in revents are POLLHUP, POLLERR, and POLLNVAL (see below)."

"POLLHUP - Hang up (only returned in revents; ignored in events). Note that when reading from a channel such as a pipe or a stream socket, this event merely indicates that the peer closed its end of the channel."

"If none of the events requested (and no error) has occurred for any of the file descriptors, then poll() blocks until one of the events occurs."

POLLRDHUP can be ignored

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=967631f2c84a8f2adae1772334fa77be40f18131

Linux's poll implementation

when did poll get added? how does it work?

Unix

- sysv

- sunos

BSDs

- netbsd

- freebsd

- openbsd

- illumos

- macos

Windows

wsapoll

Emulation

cygwin

minix

my dosbox code :(