POSIX_FALLOCATE(3P)

👑 POSIX_FALLOCATE(3P) 👑

hiii bestie 💖 welcome to the POSIX Programmer's Manual — yes, the whole entire thing, and this page right here is posix_fallocate(3P). buckle up, we're allocating some disk space and it's gonna be iconic.

---

💜 PROLOG 💜

okay so first things first, no skipping: this manual page is part of the POSIX Programmer's Manual. that's the vibe.

⚠️ real talk though — the Linux implementation of this interface may differ, so pls go consult the corresponding Linux manual page for the details on Linux behavior. or honestly? the interface might just not be implemented on Linux at all. 😭 i know. tragic. check before you ship, fr fr.

---

✨ NAME ✨

posix_fallocate — file space control (ADVANCED REALTIME)

like the name says, she controls your file space. main character energy, obviously. 💅

---

🦋 SYNOPSIS 🦋

#include <fcntl.h>

int posix_fallocate(int fd, off_t offset, off_t len);

three little args, one big slay. 🌈

---

🌸 DESCRIPTION 🌸

okay so what does she actually do? the posix_fallocate() function shall ensure that any required storage for regular file data starting at offset and continuing for len bytes is allocated on the file system storage media. periodt. and here's the best part: if posix_fallocate() returns successfully, subsequent writes to the specified file data shall not fail due to the lack of free space on the file system storage media. no more "oops i ran out of space mid-write" jumpscare. we love to see it. 🫶

now, about your file size — it's giving ✨ conditional ✨:

• if offset+len is beyond the current file size, then posix_fallocate() shall adjust the file size to offset+len.
• otherwise, the file size shall not be changed. not even a little. leave her alone.

and here's a lil mystery for you: it is implementation-defined whether a previous posix_fadvise() call influences allocation strategy. so like… maybe it does, maybe it doesn't, that's between you and your implementation. 🙈

lastly, the freeing rules, because nothing lasts forever bestie:

• space allocated via posix_fallocate() shall be freed by a successful call to creat() or open() that truncates the size of the file.
• space allocated via posix_fallocate() may be freed by a successful call to ftruncate() that reduces the file size to a size smaller than offset+len.

note the shall vs may — that distinction is doing so much work and i respect it deeply. 💅

---

⭐ RETURN VALUE ⭐

upon successful completion, posix_fallocate() shall return zero. slay.

otherwise, an error number shall be returned to indicate the error. not a vibe, but at least she tells you why. 😭

---

💀 ERRORS 💀

the posix_fallocate() function shall fail if:

• EBADF — the fd argument is not a valid file descriptor.
• EBADF — the fd argument references a file that was opened without write permission. (yes, there are two EBADFs. yes, that's on purpose. they're different problems, bestie.)
• EFBIG — the value of offset+len is greater than the maximum file size.
• EINTR — a signal was caught during execution.
• EINVAL — the len argument is less than zero, or the offset argument is less than zero, or the underlying file system does not support this operation.
• EIO — an I/O error occurred while reading from or writing to a file system.
• ENODEV — the fd argument does not refer to a regular file.
• ENOSPC — there is insufficient free space remaining on the file system storage media.
• ESPIPE — the fd argument is associated with a pipe or FIFO.

the posix_fallocate() function may fail if:

• EINVAL — the len argument is zero.

🫠 yeah, that last one is a may — so a zero-length request is not guaranteed to blow up. keep it in mind. no cap.

the following sections are informative. 🎀

---

🌈 EXAMPLES 🌈

None.

(i know. i wanted examples too. she said no. iconic of her honestly. 💀)

---

🧚 APPLICATION USAGE 🧚

the posix_fallocate() function is part of the Advisory Information option and need not be provided on all implementations. so like — vibe check your platform before you assume she's there, bestie. 💖

---

🎀 RATIONALE 🎀

None.

---

🔥 FUTURE DIRECTIONS 🔥

None.

---

💖 SEE ALSO 💖

• creat()
• ftruncate()
• open()
• unlink()
• The Base Definitions volume of POSIX.1‐2017, <fcntl.h>

iykyk. go read those next, they're all linked in spirit. 🌸

---

👑 COPYRIGHT 👑

okay bestie, legal moment, but make it cute:

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. 📜 the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page, bestie!! 🦋💅 this one came to you courtesy of IEEE/The Open Group, 2017 — yeah, that's the source and the date, and yes i'm putting it in the sign-off because we give credit in this house. now go allocate responsibly, mwah. 💖✨🎀