1 files changed, 72 insertions, 0 deletions
diff --git a/man/io_uring_prep_poll_add.3 b/man/io_uring_prep_poll_add.3
new file mode 100644
index 0000000..cb60878
--- /dev/null
+++ b/man/io_uring_prep_poll_add.3
@@ -0,0 +1,72 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_add 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_poll_add \- prepare a poll request
+.SH SYNOPSIS
+.nf
+.B #include <poll.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_poll_add(struct io_uring_sqe *" sqe ","
+.BI "                            int " fd ","
+.BI "                            unsigned " poll_mask ");"
+.PP
+.BI "void io_uring_prep_poll_multishot(struct io_uring_sqe *" sqe ","
+.BI "                                  int " fd ","
+.BI "                                  unsigned " poll_mask ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_poll_add (3)
+function prepares a poll request. The submission queue entry
+.I sqe
+is setup to use the file descriptor
+.I fd
+that should get polled, with the events desired specified in the
+.I poll_mask
+argument.
+
+The default behavior is a single-shot poll request. When the specified event
+has triggered, a completion CQE is posted and no more events will be generated
+by the poll request.
+.BR io_uring_prep_multishot (3)
+behaves identically in terms of events, but it persist across notifications
+and will repeatedly post notifications for the same registration. A CQE
+posted from a multishot poll request will have
+.B IORING_CQE_F_MORE
+set in the CQE
+.I flags
+member, indicating that the application should expect more completions from
+this request. If the multishot poll request gets terminated or experiences
+an error, this flag will not be set in the CQE. If this happens, the application
+should not expect further CQEs from the original request and must reissue a
+new one if it still wishes to get notifications on this file descriptor.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+The CQE
+.I res
+field will contain the result of the operation, which is a bitmask of the
+events notified. See the
+.BR poll (2)
+man page for details. Note that where synchronous system calls will return
+.B -1
+on failure and set
+.I errno
+to the actual error value, io_uring never uses
+.IR errno .
+Instead it returns the negated
+.I errno
+directly in the CQE
+.I res
+field.
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR poll (2),
+.BR epoll_ctl (3)