From 08e6338d239b15ccd5e8ae4733569e8fc653d1bb Mon Sep 17 00:00:00 2001
From: leitner <leitner>
Date: Thu, 11 Apr 2024 21:06:17 +0000
Subject: [PATCH] update iom_add man page, add iom_requeue man page

---
 io/iom_add.3     |  9 ++++-----
 io/iom_requeue.3 | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 5 deletions(-)
 create mode 100644 io/iom_requeue.3

diff --git a/io/iom_add.3 b/io/iom_add.3
index 760a7d5..77ff032 100644
--- a/io/iom_add.3
+++ b/io/iom_add.3
@@ -12,12 +12,11 @@ iom_add adds an event you are interested in to an I/O multiplexer.
 in, and \fIevents\fR is the operation you want to do. It can be IOM_READ
 or IOM_WRITE.
 
-If that operation becomes possible on that descriptor, and some thread
-is calling \fIiom_wait\fR at the time, it will return and tell you the
-fd and the event.
+If that operation becomes possible on that descriptor, \fIiom_wait\fR
+will return and tell you the fd and the event.
 
 Note that the event registration is removed from the iomux_t context if
-it occurs. You will have to call \fIiom_wait\fR again after you handled
+it occurs. You will have to call \fIiom_requeue\fR after you handled
 the event, if you are still interested in it.
 
 Closing a file descriptor with registered events will discard the event
@@ -30,4 +29,4 @@ step.
 .SH "RETURN VALUE"
 iom_add returns 0 on success and -1 on error, setting errno.
 .SH "SEE ALSO"
-iom_init, iom_wait, iom_abort
+iom_init, iom_requeue, iom_wait, iom_abort
diff --git a/io/iom_requeue.3 b/io/iom_requeue.3
new file mode 100644
index 0000000..999b4cb
--- /dev/null
+++ b/io/iom_requeue.3
@@ -0,0 +1,35 @@
+.TH iom_requeue 3
+.SH NAME
+iom_requeue \- re-add event to I/O multiplexer
+.SH SYNTAX
+.B #include <libowfat/io.h>
+
+int \fBiom_requeue\fP(iomux_t* c, int64 fd, unsigned int events);
+.SH DESCRIPTION
+iom_requeue adds an event you are interested in to an I/O multiplexer.
+
+\fIfd\fR is the file descriptor (usually a socket) you are interested
+in, and \fIevents\fR is the operation you want to do. It can be IOM_READ
+or IOM_WRITE.
+
+If that operation becomes possible on that descriptor, \fIiom_wait\fR
+will return and tell you the fd and the event.
+
+Note that the event registration is removed from the iomux_t context if
+it occurs. You will have to call \fIiom_requeue\fR again if you are
+interested in more events for this descriptor. Do this only after you
+are done handling this event, otherwise \fIiom_wait\fR might indicate a
+new event to another thread while this thread is still working on the
+descriptor, leading to unexpected behavior.
+
+Closing a file descriptor with registered events will discard the event
+registration.
+
+.SH "LINKING"
+You may have to add \fI-lpthread\fR to the command line in the linking
+step.
+
+.SH "RETURN VALUE"
+iom_requeue returns 0 on success and -1 on error, setting errno.
+.SH "SEE ALSO"
+iom_init, iom_add, iom_wait, iom_abort