io-util: document EINTR situation a bit

diff --git a/src/basic/io-util.c b/src/basic/io-util.c
index cdad939aa68a7df55bc41db72aa6c379eb488e93..f642beca3a94ff7303e405dee2f3f9f2a34c6bef 100644 (file)
--- a/src/basic/io-util.c
+++ b/src/basic/io-util.c
@@ -161,6 +161,21 @@ int ppoll_usec(struct pollfd *fds, size_t nfds, usec_t timeout) {
 
         assert(fds || nfds == 0);
 
+        /* This is a wrapper around ppoll() that does primarily two things:
+         *
+         *  ✅ Takes a usec_t instead of a struct timespec
+         *
+         *  ✅ Guarantees that if an invalid fd is specified we return EBADF (i.e. converts POLLNVAL to
+         *     EBADF). This is done because EBADF is a programming error usually, and hence should bubble up
+         *     as error, and not be eaten up as non-error POLLNVAL event.
+         *
+         *  ⚠️ ⚠️ ⚠️ Note that this function does not add any special handling for EINTR. Don't forget
+         *  poll()/ppoll() will return with EINTR on any received signal always, there is no automatic
+         *  restarting via SA_RESTART available. Thus, typically you want to handle EINTR not as an error,
+         *  but just as reason to restart things, under the assumption you use a more appropriate mechanism
+         *  to handle signals, such as signalfd() or signal handlers. ⚠️ ⚠️ ⚠️
+         */
+
         if (nfds == 0)
                 return 0;
 
@@ -188,6 +203,9 @@ int fd_wait_for_event(int fd, int event, usec_t timeout) {
         };
         int r;
 
+        /* ⚠️ ⚠️ ⚠️ Keep in mind you almost certainly want to handle -EINTR gracefully in the caller, see
+         * ppoll_usec() above! ⚠️ ⚠️ ⚠️ */
+
         r = ppoll_usec(&pollfd, 1, timeout);
         if (r <= 0)
                 return r;