Skip to content

epoll_pwait

Intro

The epoll_pwait system call - wait for an I/O event on an epoll filedescriptor with the option for user-space signal masking.

Description

epoll_pwait was added to Linux to extend the capabilities of the previous epoll_wait system call. Instead of just waiting for an I/O event to happen on an epoll file descriptor, epoll_pwait accepts an additional argument sigmask which is a pointer to a user-space signal mask. This signal mask defines which signals the process is to block while waiting for the I/O event.

This system call adds an additional level of control to the process while it's waiting, allowing to have full control over the signals it''ll receive while waiting, making it easier to control in scenarios where it needs to be woken up due to incoming signals.

The other arguments, epfd, events, maxevents and timeout are the same as the epoll_wait system call. epfd holds the epoll filedescriptor to query, events is a pointer to a memory space that will store the I/O events info, maxevents is a maximum size of events given, and timeout is the number of milliseconds the process will wait before timing out.

It's important to note that this system call is vulnerable to time-of-check/time-of-use (TOCTOU) attacks, as the signal mask used can be changed between the time it checks and the time it waits, with disastrous results in some architectures.

Arguments

  • epfd:int[K] - epoll filedescriptor to query for I/O events.
  • events:struct epoll_event*[K] - pointer to a memory space that will store the I/O events info.
  • maxevents:int[K] - maximum size of events given.
  • timeout:int[K] - number of milliseconds the process will wait before timing out.
  • sigmask:const sigset_t*[KU] - pointer to a user-space signal mask used to block certain signals.
  • sigsetsize:size_t[KU] - size of sigmask.

Available Tags

  • K - Originated from kernel-space.
  • U - Originated from user space (for example, pointer to user space memory used to get it)
  • TOCTOU - Vulnerable to TOCTOU (time of check, time of use)
  • OPT - Optional argument - might not always be available (passed with null value)

Hooks

sys_epoll_pwait

Type

Kprobes

Purpose

To monitor or trace the use of the epoll_pwait system call.

ep_poll_callback

Type

Kretprobes + Tracepoints

Purpose

To log information about the returned data from the epoll_pwait system call.

Example Use Case

When dealing with a multithreaded application, it's important to be able to control which signals the application will react to while waiting. epoll_pwait allows to have full control over the user-space signal mask, making it easy to decide which signals will be blocked while waiting.

Issues

  • Vulnerability to TOCTOU attacks - the signal mask used in the system call can be changed between the time of check and the time of use, which can lead to issues in some architectures.
  • epoll_wait - similar event but without the possibility of signal masking.

This document was automatically generated by OpenAI and needs review. It might not be accurate and might contain errors. The authors of Tracee recommend that the user reads the "events.go" source file to understand the events and their arguments better.