.\" Copyright 2024, Joe Damato <jdamato@fastly.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH ioctl_eventpoll 2 2024-06-17 "Linux man-pages 6.9.1"
.SH NAME
ioctl_eventpoll,
EPIOCSPARAMS,
EPIOCGPARAMS
\-
ioctl() operations for epoll file descriptors
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.BR "#include <sys/epoll.h>" "  /* Definition of " EPIOC* " constants */"
.B "#include <sys/ioctl.h>"
.P
.BI "int ioctl(int " fd ", EPIOCSPARAMS, const struct epoll_params *" argp );
.BI "int ioctl(int " fd ", EPIOCGPARAMS, struct epoll_params *" argp );
.P
.B "#include <sys/epoll.h>"
.P
.fi
.EX
.B struct epoll_params {
.BR "    uint32_t  busy_poll_usecs;" "   /* Number of usecs to busy poll */"
.BR "    uint16_t  busy_poll_budget;" "  /* Max packets per poll */"
.BR "    uint8_t   prefer_busy_poll;" "  /* Boolean preference  */"
\&
    /* pad the struct to a multiple of 64bits */
.BR "    uint8_t   __pad;" "             /* Must be zero */"
.B };
.EE
.SH DESCRIPTION
.TP
.B EPIOCSPARAMS
Set the
.I epoll_params
structure to configure the operation of epoll.
Refer to the structure description below
to learn what configuration is supported.
.TP
.B EPIOCGPARAMS
Get the current
.I epoll_params
configuration settings.
.P
All operations documented above must be performed on an epoll file descriptor,
which can be obtained with a call to
.BR epoll_create (2)
or
.BR epoll_create1 (2).
.SS The epoll_params structure
.I argp.busy_poll_usecs
denotes the number of microseconds that the network stack will busy poll.
During this time period,
the network device will be polled repeatedly for packets.
This value cannot exceed
.BR INT_MAX .
.P
.I argp.busy_poll_budget
denotes the maximum number of packets that the network stack will retrieve
on each poll attempt.
This value cannot exceed
.B NAPI_POLL_WEIGHT
(which is 64 as of Linux 6.9), unless the process is run with
.BR CAP_NET_ADMIN .
.P
.I argp.prefer_busy_poll
is a boolean field and
must be either 0 (disabled) or 1 (enabled).
If enabled,
this indicates to the network stack that
busy poll is the preferred method of processing network data
and the network stack should give the application the opportunity to busy poll.
Without this option,
very busy systems may continue to do network processing
via the normal method of IRQs triggering softIRQ and NAPI.
.P
.I argp.__pad
must be zero.
.SH RETURN VALUE
On success, 0 is returned.
On failure, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EOPNOTSUPP
The kernel was not compiled with busy poll support.
.TP
.B EINVAL
.I fd
is not a valid file descriptor.
.TP
.B EINVAL
.I argp.__pad
is not zero.
.TP
.B EINVAL
.I argp.busy_poll_usecs
exceeds
.BR INT_MAX .
.TP
.B EINVAL
.I argp.prefer_busy_poll
is not 0 or 1.
.TP
.B EPERM
The process is being run without
.B CAP_NET_ADMIN
and the specified
.I argp.busy_poll_budget
exceeds
.BR NAPI_POLL_WEIGHT .
.TP
.B EFAULT
.I argp
is an invalid address.
.SH STANDARDS
Linux.
.SH HISTORY
.\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61
.\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
Linux 6.9.
glibc 2.40.
.SH EXAMPLES
.EX
/* Code to set the epoll params to enable busy polling */
\&
int epollfd = epoll_create1(0);
struct epoll_params params;
\&
if (epollfd == \-1) {
    perror("epoll_create1");
    exit(EXIT_FAILURE);
}
\&
memset(&params, 0, sizeof(struct epoll_params));
\&
params.busy_poll_usecs = 25;
params.busy_poll_budget = 8;
params.prefer_busy_poll = 1;
\&
if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
    perror("ioctl");
    exit(EXIT_FAILURE);
}
\&
/* Code to show how to retrieve the current settings */
\&
memset(&params, 0, sizeof(struct epoll_params));
\&
if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-1) {
    perror("ioctl");
    exit(EXIT_FAILURE);
}
\&
/* params struct now contains the current parameters */
\&
fprintf(stderr, "epoll usecs: %lu\[rs]n", params.busy_poll_usecs);
fprintf(stderr, "epoll packet budget: %u\[rs]n", params.busy_poll_budget);
fprintf(stderr, "epoll prefer busy poll: %u\[rs]n", params.prefer_busy_poll);
.SH SEE ALSO
.BR ioctl (2),
.BR epoll_create (2),
.BR epoll_create1 (2),
.BR epoll (7)
.P
.I linux.git/Documentation/networking/napi.rst
.P
.I linux.git/Documentation/admin-guide/sysctl/net.rst