epoll_create(2)

✨ epoll_create(2) ✨ — the System Calls Manual, but make it cute 💅

okay so bestie, this is epoll_create and epoll_create1 from section 2 of the manual. System calls, babes. Let's get into it 🦋

---

🎀 NAME 🎀

epoll_create, epoll_create1 — open an epoll file descriptor 👑

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🌸 SYNOPSIS 🌸

#include <sys/epoll.h>

int epoll_create(int size);
int epoll_create1(int flags);

---

💖 DESCRIPTION 💖

epoll_create() makes you a brand new epoll(7) instance. it's giving new beginnings ✨

ngl the tea on size: since Linux 2.6.8 it's literally just… ignored 🙈 but bestie it must still be greater than zero or it's a whole thing. check HISTORY for the lore.

epoll_create() hands you back a file descriptor pointing at your new epoll instance. that fd is your main character for every subsequent call into the epoll interface. and when you're done with it?? close it with close(2), periodt 💅 once all the file descriptors pointing at an epoll instance are closed, the kernel destroys the instance and releases all the associated resources so they can be reused. so clean, so iconic 🌈

🧚 epoll_create1() 🧚

if flags is 0, then epoll_create1() is the same as epoll_create() — except the obsolete size argument is just dropped, no big deal, we don't talk about her anymore 💀

you can stick the following value in flags to get different behavior:

• EPOLL_CLOEXEC — sets the close-on-exec (FD_CLOEXEC) flag on your shiny new file descriptor. for the why-is-this-even-useful of it all, go read about the O_CLOEXEC flag in open(2). iykyk 🫶

---

🔥 RETURN VALUE 🔥

on success, these system calls return a file descriptor (a nonnegative integer). slay. 💖

on error, -1 is returned and errno is set to tell you what went wrong 😭

---

💀 ERRORS 💀

• EINVAL — size is not positive. she said "must be greater than zero" and you said "no" 😔
• EINVAL — (epoll_create1() only) invalid value specified in flags.
• EMFILE — the per-process limit on the number of open file descriptors has been reached. that's a lot of fds, bestie 🫠
• ENFILE — the system-wide limit on the total number of open files has been reached. the whole machine said enough.
• ENOMEM — there was insufficient memory to create the kernel object. no thoughts, no memory, head empty 🙈

---

⭐ STANDARDS ⭐

Linux. 🐧

---

📜 HISTORY 📜

• epoll_create() — Linux 2.6, glibc 2.3.2.
• epoll_create1() — Linux 2.6.27, glibc 2.9.

so the lore 👇

in the initial epoll_create() implementation, that size argument actually told the kernel how many file descriptors the caller expected to add to the epoll instance. the kernel used that as a hint for how much space to initially allocate in its internal data structures describing events. and if the caller's usage ended up exceeding the hint in size, the kernel would just allocate more space as needed. no stress. ✨

these days that hint is not required anymore — the kernel dynamically sizes the required data structures all by itself, no hint needed, she's independent 💅 — but size still has to be greater than zero, and that's purely for backward compatibility so that new epoll applications can still run on older kernels. respect the elders 👑

also: prior to Linux 2.6.29, there was a /proc/sys/fs/epoll/max_user_instances kernel parameter that limited live epolls for each real user ID, and it caused epoll_create() to fail with EMFILE when you overran it. rip to her, she's gone now 😭

---

👀 SEE ALSO 👀

close(2), epoll_ctl(2), epoll_wait(2), ioctl_eventpoll(2), epoll(7)

---

and that's the whole page, bestie — brought to you by Linux man-pages 6.20, dated 2026-02-08, and yes that's epoll_create(2) because we stay in section 2 around here 🎀✨ go forth and file-descriptor responsibly 💖