Debian Codegraph @

upstream/debian-unstable/man2/ioctl_eventpoll.2

raw
1 .\" Copyright 2024, Joe Damato <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH ioctl_eventpoll 2 2026-02-11 "Linux man-pages 6.18"
7 .SH NAME
8 ioctl_eventpoll,
9 EPIOCSPARAMS,
10 EPIOCGPARAMS
11 \-
12 ioctl() operations for epoll file descriptors
13 .SH LIBRARY
14 Standard C library
15 .RI ( libc ,\~ \-lc )
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <sys/epoll.h>" " /* Definition of " EPIOC* " constants */"
19 .B "#include <sys/ioctl.h>"
20 .P
21 .BI "int ioctl(int " fd ", EPIOCSPARAMS, const struct epoll_params *" argp );
22 .BI "int ioctl(int " fd ", EPIOCGPARAMS, struct epoll_params *" argp );
23 .P
24 .B "#include <sys/epoll.h>"
25 .P
26 .fi
27 .EX
28 .B struct epoll_params {
29 .BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */"
30 .BR " uint16_t busy_poll_budget;" " /* Max packets per poll */"
31 .BR " uint8_t prefer_busy_poll;" " /* Boolean preference */"
32 \&
33 /* pad the struct to a multiple of 64bits */
34 .BR " uint8_t __pad;" " /* Must be zero */"
35 .B };
36 .EE
37 .SH DESCRIPTION
38 .TP
39 .B EPIOCSPARAMS
40 Set the
41 .I epoll_params
42 structure to configure the operation of epoll.
43 Refer to the structure description below
44 to learn what configuration is supported.
45 .TP
46 .B EPIOCGPARAMS
47 Get the current
48 .I epoll_params
49 configuration settings.
50 .P
51 All operations documented above must be performed on an epoll file descriptor,
52 which can be obtained with a call to
53 .BR epoll_create (2)
54 or
55 .BR epoll_create1 (2).
56 .SS The epoll_params structure
57 .I argp.busy_poll_usecs
58 denotes the number of microseconds that the network stack will busy poll.
59 During this time period,
60 the network device will be polled repeatedly for packets.
61 This value cannot exceed
62 .BR INT_MAX .
63 .P
64 .I argp.busy_poll_budget
65 denotes the maximum number of packets that the network stack will retrieve
66 on each poll attempt.
67 This value cannot exceed
68 .B NAPI_POLL_WEIGHT
69 (which is 64 as of Linux 6.9), unless the process is run with
70 .BR CAP_NET_ADMIN .
71 .P
72 .I argp.prefer_busy_poll
73 is a boolean field and
74 must be either 0 (disabled) or 1 (enabled).
75 If enabled,
76 this indicates to the network stack that
77 busy poll is the preferred method of processing network data
78 and the network stack should give the application the opportunity to busy poll.
79 Without this option,
80 very busy systems may continue to do network processing
81 via the normal method of IRQs triggering softIRQ and NAPI.
82 .P
83 .I argp.__pad
84 must be zero.
85 .SH RETURN VALUE
86 On success, 0 is returned.
87 On failure, \-1 is returned, and
88 .I errno
89 is set to indicate the error.
90 .SH ERRORS
91 .TP
92 .B EOPNOTSUPP
93 The kernel was not compiled with busy poll support.
94 .TP
95 .B EINVAL
96 .I fd
97 is not a valid file descriptor.
98 .TP
99 .B EINVAL
100 .I argp.__pad
101 is not zero.
102 .TP
103 .B EINVAL
104 .I argp.busy_poll_usecs
105 exceeds
106 .BR INT_MAX .
107 .TP
108 .B EINVAL
109 .I argp.prefer_busy_poll
110 is not 0 or 1.
111 .TP
112 .B EPERM
113 The process is being run without
114 .B CAP_NET_ADMIN
115 and the specified
116 .I argp.busy_poll_budget
117 exceeds
118 .BR NAPI_POLL_WEIGHT .
119 .TP
120 .B EFAULT
121 .I argp
122 is an invalid address.
123 .SH STANDARDS
124 Linux.
125 .SH HISTORY
126 .\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61
127 .\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
128 Linux 6.9,
129 glibc 2.40.
130 .SH EXAMPLES
131 .EX
132 /* Code to set the epoll params to enable busy polling */
133 \&
134 int epollfd = epoll_create1(0);
135 struct epoll_params params;
136 \&
137 if (epollfd == \-1) {
138 perror("epoll_create1");
139 exit(EXIT_FAILURE);
140 }
141 \&
142 memset(&params, 0, sizeof(struct epoll_params));
143 \&
144 params.busy_poll_usecs = 25;
145 params.busy_poll_budget = 8;
146 params.prefer_busy_poll = 1;
147 \&
148 if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
149 perror("ioctl");
150 exit(EXIT_FAILURE);
151 }
152 \&
153 /* Code to show how to retrieve the current settings */
154 \&
155 memset(&params, 0, sizeof(struct epoll_params));
156 \&
157 if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-1) {
158 perror("ioctl");
159 exit(EXIT_FAILURE);
160 }
161 \&
162 /* params struct now contains the current parameters */
163 \&
164 fprintf(stderr, "epoll usecs: %lu\[rs]n", params.busy_poll_usecs);
165 fprintf(stderr, "epoll packet budget: %u\[rs]n", params.busy_poll_budget);
166 fprintf(stderr, "epoll prefer busy poll: %u\[rs]n", params.prefer_busy_poll);
167 .SH SEE ALSO
168 .BR ioctl (2),
169 .BR epoll_create (2),
170 .BR epoll_create1 (2),
171 .BR epoll (7)
172 .P
173 .I linux.git/Documentation/networking/napi.rst
174 .P
175 .I linux.git/Documentation/admin-guide/sysctl/net.rst