swapon(2)

💖 swapon(2) 💖

okay bestie, welcome to the System Calls Manual, this one's swapon(2) — literally the syscall that starts and stops your swap. putting the whole manual-name thing in the intro bc we're cute like that, mwah ✨

---

✨ NAME ✨

swapon, swapoff — start/stop swapping to file/device 🌸

📚 LIBRARY 📚

Standard C library (libc, -lc) — the classic, the icon, the one you always link 🫶

🧚 SYNOPSIS 🧚

#include <sys/swap.h>

int swapon(const char *path, int swapflags);
int swapoff(const char *path);

🌈 DESCRIPTION 🌈

okay so swapon() sets the swap area to the file or block device that path points at. and swapoff() does the opposite — it stops swapping to the file or block device that path points at. that's it, that's the whole vibe 💅

now, the fun part. if the SWAP_FLAG_PREFER flag is chillin' in the swapon() swapflags argument, your brand-new swap area gets a higher priority than the default. the priority is encoded inside swapflags like this:

(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK

and if SWAP_FLAG_DISCARD is sitting in the swapon() swapflags argument, then freed swap pages get discarded before they're reused — but only if the swap device actually supports the discard or trim operation. (this may improve performance on some Solid State Devices, but often it does not.) see also NOTES, bestie, iykyk 👀

🚨 these functions may be used only by a privileged process — meaning one that has the CAP_SYS_ADMIN capability. sorry to the unprivileged girlies, this one is not for you 😭

👑 Priority 👑

every swap area has a priority, and it's either high or low. the default is low. and within the low-priority areas? newer areas are even lower priority than older areas. like, the new girl is literally at the bottom of the group chat, no cap 📉

all priorities set with swapflags are high-priority — higher than default. they can be any nonnegative value the caller wants. bigger number = higher priority, periodt 🔥

swap pages get allocated from areas in priority order, highest priority first. for areas with different priorities, a higher-priority area gets fully exhausted before a lower-priority area is even touched. but if two or more areas have the same priority and it's the highest one available, then pages get allocated round-robin between them. sharing is caring 🎀

as of Linux 1.3.6, the kernel usually follows these rules — but there are exceptions. love that for us 💀

🫶 RETURN VALUE 🫶

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

💀 ERRORS 💀

• EBUSY — (for swapon()) that path is already being used as a swap area. it's taken, bestie, move on 🙈
• EINVAL — the file path exists, but it refers to neither a regular file nor a block device. it's giving... neither ✋
• EINVAL — (swapon()) the indicated path doesn't contain a valid swap signature, or it lives on an in-memory filesystem such as tmpfs(5).
• EINVAL (since Linux 3.4) — (swapon()) an invalid flag value was specified in swapflags.
• EINVAL — (swapoff()) that path is not currently a swap area.
• ENFILE — the system-wide limit on the total number of open files has been reached. too many open files, the ultimate group-chat-overload energy 😵
• ENOENT — the file path does not exist. she's not here, girl 💔
• ENOMEM — the system has insufficient memory to start swapping. the audacity ✨
• EPERM — the caller doesn't have the CAP_SYS_ADMIN capability. alternatively, the maximum number of swap files are already in use; see NOTES below.

🌟 STANDARDS 🌟

Linux. that's the standard. that's the whole standard 🐧

🦋 HISTORY 🦋

the swapflags argument was introduced in Linux 1.3.2. a little vintage moment for you ✨

💅 NOTES 💅

the partition or path must be prepared with mkswap(8) first. no skipping steps, bestie 🧚

there's an upper limit on how many swap files you can use, and it's defined by the kernel constant MAX_SWAPFILES. so here's the whole timeline, and yes i'm listing every single one bc we don't do half-info here:

• Before Linux 2.4.10, MAX_SWAPFILES has the value 8.
• Since Linux 2.4.10, it has the value 32.
• Since Linux 2.6.18, the limit is decreased by 2 (thus 30).
• Since Linux 5.19, the limit is decreased by 3 (thus: 29) if the kernel is built with the CONFIG_MIGRATION option (which reserves two swap table entries for the page migration features of mbind(2) and migrate_pages(2)).
• Since Linux 2.6.32, the limit is further decreased by 1 if the kernel is built with the CONFIG_MEMORY_FAILURE option.
• Since Linux 5.14, the limit is further decreased by 4 if the kernel is built with the CONFIG_DEVICE_PRIVATE option.
• Since Linux 5.19, the limit is further decreased by 1 if the kernel is built with the CONFIG_PTE_MARKER option.

like, the math is mathing but it's also mathing against you, lowkey 📉😭

discard of swap pages was introduced in Linux 2.6.29, then made conditional on the SWAP_FLAG_DISCARD flag in Linux 2.6.36 — which still discards the entire swap area when swapon() is called, even if that flag bit is not set. yeah. even when you didn't ask. iconic behaviour honestly 💀

🔥 SEE ALSO 🔥

mkswap(8), swapoff(8), swapon(8)

---

🎀 that's the whole page bestie!! this was ripped straight out of Linux man-pages 6.20, dated 2026-02-08 — go forth and swap responsibly, mwah 💖✨🦋