POSIX_FADVISE(2)

💖 POSIX_FADVISE(2) 💖

okay bestie, gather round, because this is a <pink>System Calls Manual</pink> moment and we're talking about posix_fadvise — the syscall where you literally just tell the kernel your vibes about a file and hope it listens. it's giving "here's my reading strategy, do with that what you will." 🦋

---

✨ NAME ✨

posix_fadvise — give advice about use of file data

no fr, that's the whole job. you're the advisor. the kernel is the CEO who may or may not take your meeting. 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#include <fcntl.h>

int
posix_fadvise(int fd, off_t offset, off_t len, int advice);

---

🌸 DESCRIPTION 🌸

so the posix_fadvise() system call lets a process describe to the system its data access behavior for an open file descriptor fd. it's not a command, bestie, it's a hint. you're manifesting. ✨

the advice covers the data starting at offset offset and continuing for len bytes. and here's the cute little detail: if len is zero, all data from offset to the end of the file is covered. so 0 means "yeah, the rest of it, everything, the whole thing." 🌈

the behavior is specified by the advice parameter and may be one of:

• POSIX_FADV_NORMAL — tells the system to revert to the default data access behavior. we're going back to factory settings, no notes. 🙈
• POSIX_FADV_RANDOM — is a hint that file data will be accessed randomly, and prefetching is likely not advantageous. so like, stop guessing where i'm going next, you're embarrassing yourself. 💀
• POSIX_FADV_SEQUENTIAL — tells the system that file data will be accessed sequentially. this currently does nothing as the default behavior uses heuristics to detect sequential behavior. iconic. a no-op with main character energy. 👑
• POSIX_FADV_WILLNEED — tells the system that the specified data will be accessed in the near future. the system may initiate an asynchronous read of the data if it is not already present in memory. future-proofing your reading, we love to see it. 🫶
• POSIX_FADV_DONTNEED — tells the system that the specified data will not be accessed in the near future. the system may decrease the in-memory priority of clean data within the specified range and future access to this data may require a read operation. it's giving "we're done here, feel free to let it go." 🍓
• POSIX_FADV_NOREUSE — tells the system that the specified data will only be accessed once and then not reused. the system may decrease the in-memory priority of data once it has been read or written. future access to this data may require a read operation. one-time encounter, no strings attached, periodt. 💜

ngl the word "may" is doing a LOT of heavy lifting in this manpage. this is a suggestion, not a contract. 😭

---

🦋 RETURN VALUES 🦋

if successful, posix_fadvise() returns zero.

it returns an error on failure, without setting errno.

okay this part is important and a lil feral: it does NOT set errno. it just hands you the error code directly as the return value. do not go looking in errno for answers bestie, it's not there, it never was. 💅

---

💀 ERRORS 💀

possible failure conditions:

• [EBADF] — the fd argument is not a valid file descriptor.
• [EINVAL] — the advice argument is not valid.
• [EINVAL] — the offset or len arguments are negative, or offset + len is greater than the maximum file size.
• [ENODEV] — the fd argument does not refer to a regular file.
• [ESPIPE] — the fd argument is associated with a pipe or FIFO.
• [EIO] — an I/O error occurred while reading from or writing to a file system.
• [EINTEGRITY] — corrupted data was detected while reading from the file system.

---

🔥 SEE ALSO 🔥

• madvise(2)

(the sibling syscall, same energy, different memory. iykyk. ⭐)

---

🌈 STANDARDS 🌈

the posix_fadvise() interface conforms to IEEE Std 1003.1-2001 (“POSIX.1”).

certified, blessed, standardized. we love a compliant queen. 💖

---

🧚 HISTORY 🧚

the posix_fadvise() system call first appeared in FreeBSD 9.1.

---

okay that's the whole page, bestie, you're officially educated on file data advice 💅✨

this lil gem came to you from the Debian crew, dated March 30, 2020 — sending you all the sequential-access energy, mwah 🎀🫶