1.\" $NetBSD: epoll.2,v 1.2 2023/07/28 23:41:16 wiz Exp $ 2.\" 3.\" Copyright (c) 2023 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Theodore Preduta. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd July 19, 2023 31.Dt EPOLL 2 32.Os 33.Sh NAME 34.Nm epoll , 35.Nm epoll_event , 36.Nm epoll_data , 37.Nm epoll_data_t , 38.Nm epoll_create , 39.Nm epoll_create1 , 40.Nm epoll_ctl , 41.Nm epoll_wait , 42.Nm epoll_pwait , 43.Nm epoll_pwait2 44.Nd event notification mechanism 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In sys/epoll.h 49.Bd -literal 50union epoll_data { 51 void *ptr; 52 int fd; 53 uint32_t u32; 54 uint64_t u64; 55}; 56 57typedef union epoll_data epoll_data_t; 58 59struct epoll_event { 60 uint32_t events; 61 epoll_data_t data; 62}; 63.Ed 64.Pp 65.Ft int 66.Fn epoll_create "int size" 67.Ft int 68.Fn epoll_create1 "int flags" 69.Ft int 70.Fn epoll_ctl "int epfd" "int op" "int fd" "struct epoll_event *event" 71.Ft int 72.Fn epoll_wait "int epfd" "struct epoll_event *events" "int maxevents" "int timeout" 73.Ft int 74.Fn epoll_pwait "int epfd" "struct epoll_event *events" "int maxevents" "int timeout" "const sigset_t *sigmask" 75.Ft int 76.Fn epoll_pwait2 "int epfd" "struct epoll_event *events" "int maxevents" "const struct timespec *timeout" "const sigset_t *sigmask" 77.Sh DESCRIPTION 78.Nm 79provides a similar facility to both 80.Xr select 2 81and 82.Xr kqueue 2 : 83it allows for the examination of file descriptors to see if they are available 84for reading/writing. 85.Pp 86The 87.Va epoll_event 88structure consists of two fields, 89.Va events 90and 91.Va data . 92The 93.Va data 94field is passed through the kernel and is intended to be used to identify the 95event. 96When used with 97.Fn epoll_ctl , 98the 99.Va events 100field consists of a mask of the events that the 101.Nm 102instance should watch for, and when being used with 103.Fn epoll_wait , 104.Fn epoll_pwait , 105and 106.Fn epoll_pwait2 107consists of a mask of the events that occurred. 108The following are possible values for 109.Va events : 110.Bl -tag -width EPOLLONESHOT 111.It Dv EPOLLIN 112Watch for 113.Xr read 2 114operations. 115.It Dv EPOLLOUT 116Watch for 117.Xr write 2 118operations. 119.It Dv EPOLLRDHUP 120Watch for a peer closed connection. 121.It Dv EPOLLERR 122Watch for error conditions. 123.It Dv EPOLLET 124This option modifies the other set bits of 125.Va events . 126When set, the events described by other bits in 127.Va events 128are only triggered when the state change. 129Otherwise the events are considered triggered whenever the condition is true. 130.It Dv EPOLLONESHOT 131Remove this event once it is retrieved once. 132.El 133.Pp 134.Fn epoll_create 135and 136.Fn epoll_create1 137both create an 138.Nm 139instance. 140The 141.Fa size 142argument specified for 143.Fn epoll_create 144exists so that the 145.Nx 146function has the same signature as the Linux system call of the same name. 147.Fa size 148must be positive, but is otherwise unused. 149Additionally, optionally, 150.Dv EPOLL_CLOEXEC 151may be specified in the 152.Fa flags 153of 154.Fn epoll_create1 155to set the 156.Xr close 2 157on 158.Xr exec 3 159flag. 160.Pp 161.Fn epoll_ctl 162is used to make changes to the given 163.Nm 164instance based on the provided 165.Fa op . 166Possible values for 167.Fa op 168are: 169.Bl -tag -width EPOLL_CTL_ADD 170.It Dv EPOLL_CTL_ADD 171Register interest of 172.Fa fd 173on the 174.Fa epfd 175for the events specified in 176.Fa event . 177.It Dv EPOLL_CTL_MOD 178Modify the events registered for 179.Fa fd 180to those specified in 181.Fa event . 182.It Dv EPOLL_CTL_DEL 183Deregister 184.Fa fd 185from the 186.Nm 187instance specified in 188.Fa epfd . 189Note that 190.Fa event 191is completely ignored in this case. 192.El 193.Pp 194.Fn epoll_wait , 195.Fn epoll_pwait , 196and 197.Fn epoll_pwait2 198provide the ability to wait for up to 199.Fa maxevents 200which are stored in the buffer pointed to by 201.Fa events . 202For 203.Fn epoll_wait 204and 205.Fn epoll_pwait , 206a timeout may be specified in 207.Fa timeout 208in milliseconds. 209If no timeout is desired, -1 should be specified in 210.Fa timeout . 211For 212.Fn epoll_pwait2 213if no timeout is desired 214.Fa timeout 215should be specified as 216.Dv NULL . 217Additionally, 218a sigmask may be specified to 219.Fn epoll_pwait 220and 221.Fn epoll_pwait2 222in 223.Fa sigmask 224to set the sigmask while 225.Nm 226waits for events. 227.Pp 228Note that 229.Nm 230is not intended to be used by native 231.Nx 232applications. 233Instead it is only intended to used as a means to help port software originally 234written for Linux to 235.Nx . 236.Sh RETURN VALUES 237.Fn epoll_create 238and 239.Fn epoll_create1 240both return a file descriptor when successful. 241.Pp 242.Fn epoll_ctl 243returns zero when successful. 244.Pp 245.Fn epoll_wait , 246.Fn epoll_pwait , 247and 248.Fn epoll_pwait2 249return the number of events written to 250.Fa events 251when successful. 252Note that zero is written to when 253.Fa timeout 254expires and no events were available. 255.Pp 256When any of the above fail, -1 is returned and 257.Fa errno 258is set. 259.Sh ERRORS 260The 261.Fn epoll_create 262and 263.Fn epoll_create1 264functions fail if: 265.Bl -tag -width Er 266.It Bq Er EINVAL 267.Fa size 268is not positive. 269.Pp 270Bits other than 271.Dv EPOLL_CLOEXEC 272are provided in 273.Fa flags . 274.It Bq Er EMFILE 275The per-process descriptor table is full. 276.It Bq Er ENFILE 277The system file table is full. 278.It Bq Er ENOMEM 279The kernel failed to allocate enough memory for a 280.Nm 281instance. 282.El 283.Pp 284The 285.Fn epoll_ctl 286function fails if: 287.Bl -tag -width Er 288.It Bq Er EBADF 289.Fa epfd 290or 291.Fa fd 292is not a valid file descriptor. 293.It Bq Er EEXIST 294.Fa op 295is 296.Dv EPOLL_CTL_ADD 297and 298.Fa fd 299was already previously added via 300.Dv EPOLL_CTL_ADD . 301.It Bq Er EINVAL 302.Fa epfd 303is not a file descriptor for an 304.Nm 305instance. 306.Pp 307.Fa epfd 308and 309.Fa fd 310represent the same 311.Nm 312instance. 313.It Bq Er ELOOP 314.Fa op 315is 316.Dv EPOLL_CTL_ADD 317and adding 318.Fa fd 319would result in a circular loop of 320.Nm 321instances. 322.It Bq Er ENOENT 323.Fa op 324is 325.Dv EPOLL_CTL_MOD 326or 327.Dv EPOLL_CTL_DEL 328and 329.Fa fd 330was not previously added with 331.Dv EPOLL_CTL_ADD . 332.It Bq Er ENOMEM 333The kernel failed to allocate enough memory for 334.Fa op . 335.It Bq Er EPERM 336.Fa fd 337does not support 338.Nm epoll . 339.El 340.Pp 341The 342.Fn epoll_wait , 343.Fn epoll_pwait , 344and 345.Fn epoll_pwait2 346functions fail if: 347.Bl -tag -width Er 348.It Bq Er EBADF 349.Fa epfd 350is not a valid file descriptor. 351.It Bq Er EFAULT 352The area provided in 353.Fa events 354failed to be written to. 355.It Bq Er EINTR 356A signal was delivered before any events became available and 357.Fa timeout 358expired. 359.It Bq Er EINVAL 360.Fa epfd 361is not a valid 362.Nm 363file descriptor. 364.Pp 365.Fa maxevents 366is less than or equal to zero. 367.El 368.Sh SEE ALSO 369.Xr kqueue 2 , 370.Xr poll 2 , 371.Xr select 2 372.Sh HISTORY 373The 374.Nm 375functions and types are designed to be compatible with the Linux system calls of 376the same name. 377.Sh CAVEATS 378The 379.Nm 380facility is not intended to be used in conjunction with 381.Xr kqueue 2 . 382.Pp 383Unlike Linux's 384.Nm , 385the 386.Nx 387version does not survive a 388.Xr fork 2 . 389