.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_prep_poll_update 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
.SH NAME
io_uring_prep_poll_update \- update an existing poll request
.SH SYNOPSIS
.nf
.B #include <poll.h>
.B #include <liburing.h>
.PP
.BI "void io_uring_prep_poll_update(struct io_uring_sqe *" sqe ","
.BI "                               __u64 " old_user_data ","
.BI "                               __u64 " new_user_data ","
.BI "                               unsigned " poll_mask ","
.BI "                               unsigned " flags ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_prep_poll_update (3)
function prepares a poll update request. The submission queue entry
.I sqe
is setup to update a poll request identified by
.IR old_user_data ,
replacing it with the
.I new_user_data
information. The
.I poll_mask
arguments contains the new mask to use for the poll request, and
.I flags
argument contains modifier flags telling io_uring what fields to update.

The
.I flags
modifier flags is a bitmask and may contain and OR'ed mask of:
.TP
.B IORING_POLL_UPDATE_EVENTS
If set, the poll update request will replace the existing events being waited
for with the ones specified in the
.I poll_mask
argument to the function. Note that only the lower 16 bits of events can
be updated. This includes things like
.B EPOLLIN
and
.B EPOLLOUT .
Higher order masks/settings are included as internal state, and cannot be
modified. That includes settings like
.B EPOLLONESHOT ,
.B EPOLLEXCLUSIVE ,
and
.B EPOLLET .
If an application wishes to modify these, it must cancel/remove the existing
poll request and arm a new one.
.TP
.B IORING_POLL_UPDATE_USER_DATA
If set, the poll update request will update the existing user_data of the
request with the value passed in as the
.I new_user_data
argument.
.TP
.B IORING_POLL_ADD_MULTI
If set, this will change the poll request from a singleshot to a multishot
request. This must be used along with
.B IORING_POLL_UPDATE_EVENTS
as the event field must be updated to enable multishot.

.SH RETURN VALUE
None
.SH ERRORS
These are the errors that are reported in the CQE
.I res
field. On success,
.B 0
is returned.
.TP
.B -ENOENT
The request identified by
.I user_data
could not be located. This could be because it completed before the cancelation
request was issued, or if an invalid identifier is used.
.TP
.B -EINVAL
One of the fields set in the SQE was invalid.
.TP
.B -EALREADY
The execution state of the request has progressed far enough that cancelation
is no longer possible. This should normally mean that it will complete shortly,
either successfully, or interrupted due to the cancelation.
.TP
.B -ECANCELED
.B IORING_POLL_UPDATE_EVENTS
was set and an error occurred re-arming the poll request with the new mask.
The original poll request is terminated if this happens, and that termination
CQE will contain the reason for the error re-arming.
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
.BR io_uring_prep_poll_add (3),
.BR io_uring_prep_poll_multishot (3)