Debian Codegraph @

upstream/debian-trixie/man2/ioctl_eventpoll.2

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