ioctl_eventpoll(2) System Calls Manual ioctl_eventpoll(2)
NAME
ioctl_eventpoll, EPIOCSPARAMS, EPIOCGPARAMS - ioctl() operations for
epoll file descriptors
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <sys/epoll.h> /* Definition of EPIOC* constants */
#include <sys/ioctl.h>
int ioctl(int fd, EPIOCSPARAMS, const struct epoll_params *argp);
int ioctl(int fd, EPIOCGPARAMS, struct epoll_params *argp);
#include <sys/epoll.h>
struct epoll_params {
uint32_t busy_poll_usecs; /* Number of usecs to busy poll */
uint16_t busy_poll_budget; /* Max packets per poll */
uint8_t prefer_busy_poll; /* Boolean preference */
/* pad the struct to a multiple of 64bits */
uint8_t __pad; /* Must be zero */
};
DESCRIPTION
EPIOCSPARAMS
Set the epoll_params structure to configure the operation of
epoll. Refer to the structure description below to learn what
configuration is supported.
EPIOCGPARAMS
Get the current epoll_params configuration settings.
All operations documented above must be performed on an epoll file de-
scriptor, which can be obtained with a call to epoll_create(2) or
epoll_create1(2).
The epoll_params structure
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 INT_MAX.
argp.busy_poll_budget denotes the maximum number of packets that the
network stack will retrieve on each poll attempt. This value cannot ex-
ceed NAPI_POLL_WEIGHT (which is 64 as of Linux 6.9), unless the process
is run with CAP_NET_ADMIN.
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 pro-
cessing via the normal method of IRQs triggering softIRQ and NAPI.
argp.__pad must be zero.
RETURN VALUE
On success, 0 is returned. On failure, -1 is returned, and errno is set
to indicate the error.
ERRORS
EOPNOTSUPP
The kernel was not compiled with busy poll support.
EINVAL fd is not a valid file descriptor.
EINVAL argp.__pad is not zero.
EINVAL argp.busy_poll_usecs exceeds INT_MAX.
EINVAL argp.prefer_busy_poll is not 0 or 1.
EPERM The process is being run without CAP_NET_ADMIN and the specified
argp.busy_poll_budget exceeds NAPI_POLL_WEIGHT.
EFAULT argp is an invalid address.
STANDARDS
Linux.
HISTORY
Linux 6.9. glibc 2.40.
EXAMPLES
/* 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(¶ms, 0, sizeof(struct epoll_params));
params.busy_poll_usecs = 25;
params.busy_poll_budget = 8;
params.prefer_busy_poll = 1;
if (ioctl(epollfd, EPIOCSPARAMS, ¶ms) == -1) {
perror("ioctl");
exit(EXIT_FAILURE);
}
/* Code to show how to retrieve the current settings */
memset(¶ms, 0, sizeof(struct epoll_params));
if (ioctl(epollfd, EPIOCGPARAMS, ¶ms) == -1) {
perror("ioctl");
exit(EXIT_FAILURE);
}
/* params struct now contains the current parameters */
fprintf(stderr, "epoll usecs: %lu\n", params.busy_poll_usecs);
fprintf(stderr, "epoll packet budget: %u\n", params.busy_poll_budget);
fprintf(stderr, "epoll prefer busy poll: %u\n", params.prefer_busy_poll);
SEE ALSO
ioctl(2), epoll_create(2), epoll_create1(2), epoll(7)
linux.git/Documentation/networking/napi.rst
linux.git/Documentation/admin-guide/sysctl/net.rst
Linux man-pages 6.9.1 2024-06-17 ioctl_eventpoll(2)
Generated by dwww version 1.16 on Tue Dec 16 05:00:22 CET 2025.