readahead(2)

💖 readahead(2) — the System Calls Manual page, but make it cute ✨

okay so bestie, welcome to readahead(2) from the System Calls Manual. this is the little guy that starts reading your file before you even ask for it, so your later reads are served straight from the page cache instead of sitting there waiting on disk I/O. main character energy fr fr. 💅

---

🌸 NAME 🌸

readahead — initiate file readahead into page cache

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

✨ SYNOPSIS ✨

#define _GNU_SOURCE             /* See feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>

ssize_t readahead(int fd, off_t offset, size_t count);

🦋 DESCRIPTION 🦋

so what it does is: readahead() initiates readahead on a file, so that reads you do later on that same file get satisfied from the cache instead of blocking on disk I/O. that's assuming the readahead was kicked off early enough, and also assuming nothing else on the system went and flushed those pages out of the cache in the meantime. timing is everything, iykyk. 😌

the fd argument is a file descriptor identifying the file we're gonna read. the offset argument is the starting point from which data is to be read, and count is the number of bytes to be read. and here's the tea: I/O happens in whole pages, so offset is effectively rounded down to a page boundary, and bytes get read up to the next page boundary that's greater than or equal to (offset+count). 🫶

readahead() does not read beyond the end of the file. oh and the file offset of the open file description that fd refers to? left unchanged. not touching it. periodt. 💖

💀 RETURN VALUE 💀

slay on success: readahead() returns 0. on failure, -1 comes back and errno is set to tell you what went wrong. 😭

🌈 ERRORS 🌈

• EBADF — fd is not a valid file descriptor, or it's not open for reading. (rude.)
• EINVAL — fd doesn't refer to a file type that readahead() can actually be applied to. 💀

⭐ VERSIONS ⭐

on some 32-bit architectures, the calling signature for this system call is different — for the reasons described in syscall(2). yes it's a whole thing, no I will not elaborate, go read that one. 🙈

👑 STANDARDS 👑

Linux. that's it, that's the standard. 💅

🧚 HISTORY 🧚

Linux 2.4.13, glibc 2.3. she's been around a minute. 👑

🍓 NOTES 🍓

_FILE_OFFSET_BITS should be defined to be 64 in code that uses a pointer to readahead, if that code is meant to be portable to traditional 32-bit x86 and ARM platforms — because on those, off_t's width defaults to 32 bits. write it down bestie, portability is self-care. ✨

ngl this one bites people on old 32-bit setups. define the macro, save your future self. 🫶

😭 BUGS 😭

readahead() tries to schedule the reads in the background and return immediately. HOWEVER — it may block while it reads the filesystem metadata it needs to locate the requested blocks. and this happens frequently with ext[234] on large files that use indirect blocks instead of extents, which gives the whole thing the appearance that the call blocks until the requested data has actually been read. so like… not as background as advertised. 🙈

💜 SEE ALSO 💜

lseek(2), madvise(2), mmap(2), posix_fadvise(2), read(2)

---

okay that's the page!! this gorgeous little writeup lives in Linux man-pages 6.20, dated 2026-02-08, and the page itself is readahead(2). go forth and prefetch responsibly, bestie 🌸💖✨