epoll_pwait - Linux


epoll_pwait() is a Linux system call that monitors multiple file descriptors for events. It is an enhanced version of epoll_wait() with support for persistent event notifications. It is primarily used in high-performance server applications that need to handle a large number of concurrent connections.


int epoll_pwait(int epfd, struct epoll_event *events, int maxevents, int timeout, const sigset_t *sigmask, size_t sigsetsize);


  • epfd: File descriptor of the epoll instance.
  • events: Pointer to an array of epoll_event structures to receive event notifications.
  • maxevents: Maximum number of events to be returned.
  • timeout: Timeout in milliseconds. Negative values indicate infinite timeout.
  • sigmask: Pointer to a signal set. If not NULL, signals in the set are blocked until epoll_pwait() returns.
  • sigsetsize: Size of the signal set in bytes.


Simple Usage:

int epfd = epoll_create1(0);
struct epoll_event event;
epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &event);
epoll_pwait(epfd, &event, 1, -1, NULL, 0);

Persistent Event Notifications:

int epfd = epoll_create1(EPOLL_CLOEXEC);
struct epoll_event event;
epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &event);
epoll_event events[100];
while (true) {
    int n = epoll_pwait(epfd, events, 100, -1, NULL, 0);
    for (int i = 0; i < n; i++) {
        // Process events...

Common Issues

  • EPERM: The caller does not have permission to access the file descriptor.
  • EFAULT: The events or sigmask pointers are invalid.
  • EINVAL: epfd is not a valid epoll file descriptor.
  • EINTR: A signal was caught while waiting for events.


epoll_pwait() can be combined with other Linux commands to monitor multiple file descriptors. For example, it can be used with select() or poll() to handle a mix of epoll and non-epoll file descriptors.

Related Commands

  • epoll_create(): Creates an epoll instance.
  • epoll_ctl(): Adds, modifies, or removes file descriptors from an epoll instance.
  • epoll_wait(): Waits for events on file descriptors.
  • select(): Monitors multiple file descriptors for I/O events.
  • poll(): Monitors multiple file descriptors for events.