FSYNC(3POSIX)

💾 FSYNC(3POSIX) 💾

okay bestie, buckle UP, because we're about to talk about fsync from the POSIX Programmer's Manual and honestly? she's that girl. she makes sure your data actually lands on disk. main character energy fr fr. 🌸

---

🎀 PROLOG 🎀

okay so first things first, this manual page is part of the POSIX Programmer's Manual. but heads up bestie — the Linux implementation of this interface may differ, so if you're on Linux you gotta consult the corresponding Linux manual page for the details of Linux behavior. or, plot twist, the interface might not even be implemented on Linux at all. 🙈 vibe check accordingly.

---

✨ NAME ✨

fsync — synchronize changes to a file. that's it. that's the whole job. she's synchronizing. slay. 💅

---

🦋 SYNOPSIS 🦋

#include <unistd.h>

int fsync(int fildes);

look at her. simple. elegant. iconic. 👑

---

💖 DESCRIPTION 💖

okay so the fsync() function shall request that all data for the open file descriptor named by fildes is to be transferred to the storage device associated with the file described by fildes. the nature of that transfer? implementation-defined, bestie, we don't get to know. 🙈 and here's the important part — fsync() shall not return until the system has completed that action or until an error is detected. she doesn't ghost you. she waits. 🫶

now, if _POSIX_SYNCHRONIZED_IO is defined, then fsync() shall force all currently queued I/O operations associated with the file indicated by file descriptor fildes to the synchronized I/O completion state. and all I/O operations shall be completed as defined for synchronized I/O file integrity completion. periodt. 🔥

---

🍓 RETURN VALUE 🍓

upon successful completion, fsync() shall return 0. no cap. otherwise, -1 shall be returned and errno set to indicate the error. 😭

and if the fsync() function fails? outstanding I/O operations are not guaranteed to have been completed. so like. be careful bestie. 💀

---

🌈 ERRORS 🌈

the fsync() function shall fail if:

• EBADF — the fildes argument is not a valid descriptor. rude. not a real fd, not getting served. 🙅
• EINTR — the fsync() function was interrupted by a signal. someone cut her off mid-sentence. 😤
• EINVAL — the fildes argument does not refer to a file on which this operation is possible. she literally cannot do the thing on this file, so don't ask. 💅
• EIO — an I/O error occurred while reading from or writing to the file system. the disk said "no <3". 💀

and in the event that any of the queued I/O operations fail, fsync() shall return the error conditions defined for read() and write(). so go look those up too, bestie. iykyk. 📚

the following sections are informative. 🧚

---

🌸 EXAMPLES 🌸

None.

literally nothing. an empty girl. we respect her for it. 🫶

---

💜 APPLICATION USAGE 💜

the fsync() function should be used by programs which require modifications to a file to be completed before continuing. for example, a program which contains a simple transaction facility might use it to ensure that all modifications to a file or files caused by a transaction are recorded. so basically: if you need your writes to actually be done done before you move on, this is your girl. 🔥

---

🧠 RATIONALE 🧠

okay so the fsync() function is intended to force a physical write of data from the buffer cache, and to assure that after a system crash or other failure, all data up to the time of the fsync() call is recorded on the disk. because apparently we're just out here trusting disks. 💀

but here's the thing — since the concepts of buffer cache'', system crash'', physical write'', and non-volatile storage'' are not defined here, the wording has to be more abstract. so it's vague on purpose, bestie. it's not being shady, it's being portable. ✨

now, if _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on the conformance document to tell the user what can be expected from the system. and it is explicitly intended that a null implementation is permitted. 😳 this could be valid in the case where the system cannot assure non-volatile storage under any circumstances, or when the system is highly fault-tolerant and the functionality is not required. so like, sometimes she does nothing and that's legal. wild. 🙈

in the middle ground between these extremes, fsync() might or might not actually cause data to be written where it is safe from a power failure. the conformance document should identify at least that one configuration exists (and how to obtain that configuration) where this can be assured for at least some files that the user can select to use for critical data. it is not intended that an exhaustive list is required, but rather sufficient information is provided so that if critical data needs to be saved, the user can determine how the system is to be configured to allow the data to be written to non-volatile storage. so yeah, read the docs, bestie. always read the docs. 📖

and it is reasonable to assert that the key aspects of fsync() are unreasonable to test in a test suite. that does not make the function any less valuable, just more difficult to test. not her fault she's hard to test, she's just built different. 💅 a formal conformance test should probably force a system crash (power shutdown) during the test for this condition, but it needs to be done in such a way that automated testing does not require this to be done except when a formal record of the results is being made. yeah they're suggesting you literally pull the plug. iconic honestly. 🔌 it would also not be unreasonable to omit testing for fsync(), allowing it to be treated as a quality-of-implementation issue. so like, no pressure. 🎀

---

🦄 FUTURE DIRECTIONS 🦄

None.

nothing coming. she's staying exactly like this. periodt. 💅

---

👑 SEE ALSO 👑

• sync()
• the Base Definitions volume of POSIX.1‐2017, <unistd.h>

go read those too bestie, they're part of the lore. 📚✨

---

📜 COPYRIGHT 📜

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. so if they fight, the original wins, no cap. 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 cutie came to you courtesy of IEEE/The Open Group, 2017, and her name in the footer is FSYNC(3POSIX). go forth and synchronize responsibly. 💖✨🦋🎀💅🫶