.\"
.\"  epoll by Davide Libenzi ( efficient event notification retrieval )
.\"  Copyright (C) 2002  Davide Libenzi
.\"
.\"  This program is free software; you can redistribute it and/or modify
.\"  it under the terms of the GNU General Public License as published by
.\"  the Free Software Foundation; either version 2 of the License, or
.\"  (at your option) any later version.
.\"
.\"  This program is distributed in the hope that it will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"
.\"  You should have received a copy of the GNU General Public License
.\"  along with this program; if not, write to the Free Software
.\"  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.\"
.\"  Davide Libenzi <davidel@xmailserver.org>
.\"
.\"
.TH EPOLL 2 "23 October 2002" Linux "Linux Programmer's Manual"
.SH NAME
epoll \- edge triggered asynchronous I/O facility
.SH SYNOPSIS
.B #include <poll.h>
.br
.B #include <eventpoll.h>
.SH DESCRIPTION
Edge based variant of 
.BR poll (2)
which scales well to large numbers of watched fds. To set up and control an
epoll set, three calls are provided: 
.BR epoll_create (2) ,
.BR epoll_TTL (2) ,
.BR epoll_wait (2) .

An epoll set is connected to a file descriptor, which is created by
.BR epoll_create (2) .
Interest for certain file descriptors is then registered using 
.BR epoll_ctl(2) .
Finally, the actual wait is then started by 
.BR epoll_wait (2) .

.SH NOTES
epoll should not be regarded as a faster version of 
.BR poll (2)
because its semantics are fundamentally different. Whereas 
poll and 
.BR select (2)
return immediately if any of their fds are available for reading,
writing or have an exceptional condition, epoll only returns if a
condition changes. 

Because of this, epoll should only be used with non-blocking
file descriptors otherwise there is a risk of race conditions. The
way to use epoll is:
.SR
.TP 
.B i
with non-blocking file descriptors
.TP 
.B ii
by going to wait for an event only after
.BR read (2)
or 
.BR write (2)
return EAGAIN
.SE
.SH EXAMPLE
In this example, listener is a non-blocking socket on which
.BR listen (2)
has been called. Furthermore, the function do_use_fd() immediately 
tries to
.BR read (2)
from the fd. If it does not do so, there is a race condition with the risk of
losing an event before interest in it was registered. This read may well
return EAGAIN, which should be a cause for calling epoll_wait().

.nf
for(;;) {
    nfds = epoll_wait(kdpfd, &pfds, -1);

    for(n = 0; n < nfds; ++n) {
        if(fd = pfds[n].fd) == s) {
            client = accept(listener, (struct sockaddr*)&local, &addrlen);
            if(client < 0){
                perror("accept");
                continue;
            }
            setnonblocking(client);
            if (epoll_ctl(kdpfd, EP_CTL_ADD, client, POLLIN) < 0) {
                fprintf(stderr, "epoll set insertion error: fd=%d\n", client);
                return -1;
            }
            fd = client;
        }

        do_use_fd(fd);
    }
}
.fi

For performance reasons it is possible to add the file descriptor inside the
epoll interface ( 
.B EP_CTL_ADD
 ) once by specifying (POLLIN | POLLOUT) without having to continuously switch
between POLLIN and POLLOUT calling
.BR epoll_ctl (2)
with
.BR EP_CTL_ADD .
.SH CONFORMING TO
.BR epoll (2)
is a new API introduced in Linux kernel
.BR 2.5.44 .
.SH "SEE ALSO"
.BR epoll_create (2)
.BR epoll_ctl (2)
.BR epoll_wait (2)