.\" 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_poll_multishot (3)
behaves identically in terms of events, but it persists 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)