APFS directory-entry durability after creating an Application Support subdirectory

On macOS 15.7.2 with a local APFS volume and App Sandbox, which supported filesystem operations and synchronization order make a newly created directory entry and a new database filename durable after an OS crash or sudden power loss?

DTS asked me to post this question here for review.

This is a design-stage API-contract question, not a report of a reproduced failure. The proposed sequence has not been implemented or tested. I have no focused reproducer, crash report, or power-loss test results for this question. The platform in question is macOS, not iOS.

Context

The proposed initialization sequence is:

  1. Obtain the Application Support directory using Foundation. Call this directory P.
  2. Create a new app-specific directory R directly under P, without replacing an existing object.
  3. Create a SQLite catalog at R/start.sqlite and commit its initial record.

The proposed SQLite configuration is SQLite 3.47.2, the standard Unix VFS, journal_mode=DELETE, and synchronous=EXTRA. These are design assumptions, not verified runtime settings.

The filesystem synchronization operations and their ordering relative to directory creation, database-file creation, and the initial transaction are what I need to establish.

The specific concern is the durability of the directory entries needed to resolve P/R/start.sqlite. I need to distinguish the persistence of the database contents from the persistence of the names used to reach that database. I am not assuming that a successful SQLite commit, by itself, establishes every parent-directory durability requirement.

Questions

  1. Is fsync supported on APFS directory file descriptors on macOS 15.7.2? If so, what does successful return guarantee about directory entries created before the call?

  2. Does fcntl(fd, F_FULLFSYNC) apply to directory descriptors? If not, what supported operation, if any, should an application use to establish the required directory-entry durability?

  3. Which objects need to be synchronized, and in what order: the database file, R, P, or P's parent? Please distinguish the case where P already existed from the case where P was newly created during initialization.

  4. What guarantees differ between an OS crash and sudden power loss? What assumptions about the local storage device, write caches, or flush support are required?

  5. Is there authoritative documentation applicable to macOS 15.7.2 that describes this contract? If part of the requested guarantee is unspecified or unsupported, please identify that boundary. If the answer differs on later macOS versions, please distinguish that from the 15.7.2 contract.

I am asking about supported public filesystem APIs and their documented guarantees, not validation of an application-specific recovery protocol or guarantees against arbitrary hardware failure.

Thank you.

Answered by DTS Engineer in 916083022

The specific concern is the durability of the directory entries needed to resolve P/R/start.sqlite. I need to distinguish the persistence of the database contents from the persistence of the names used to reach that database. I am not assuming that a successful SQLite commit, by itself, establishes every parent-directory durability requirement.

So, one thing to understand here is that the file system considers the proper handling of filesystem structure data to be significantly more important than than the commitment of individual file data. Structurally, APFS (like virtually every modern file system) is designed to "guarantee" that its file system state is ALWAYS coherent under ALL circumstances. I mean that quite literally. Twenty+ years ago I put together a rig designed to intentionally destroy volumes. It worked by:

  1. Starting the machine up and starting up a whole bunch of long-running copies.

  2. Letting the copies run for a few minutes.

  3. Using an external hardware device to cut power to the device.

  4. Restoring power to the machine, looping the entire process back to #1.

On a standard HFS+ file system (no journal), it would render the drive unmountable in ~4 hours. With a journaled HFS+ volume... it didn't work, even when allowed to run for "days". This was pre-APFS, but APFS would do just as well.

That then leads to here:

I need to distinguish the persistence of the database contents from the persistence of the names used to reach that database. I am not assuming that a successful SQLite commit, by itself, establishes every parent-directory durability requirement.

I THINK what you're worried about here is that the file's data will somehow be written to disk but the directory and file record entries won't be. If so, then the answer is basically "no, that won't happen". First off, as noted above, the file system is significantly more concerned about pushing out metadata/structure data than it is about file-level data.

However, the bigger issue is tied to what a "file" actually is at the file system level. As far as the file system is concerned, "a file" is a particular type of record within its data structures. That happens to point to a location on disk where the actual data blocks are stored, but the record itself IS the file, NOT the data blocks on disk. If the file record doesn't exist, then the data blocks are irrelevant, as that file record is the only tool it has to find them.

Putting that another way, if a catastrophic event (crash, power loss, etc.) occurs, then the file system will be in one of these four states when it's mounted again:

  1. None of your content is there.

  2. The directory exists and nothing else.

  3. The directory and file both exist, but the file's contents are incomplete or missing.

  4. Everything is there.

Those are the only states the file system will mount in because it's designed such that IF it happens to be in any transition state other than those, it will force itself to one of those 4 states so that it guarantees its own integrity.

The question that then leads to is "how do I guarantee that I'm at #4" and the answer is, unfortunately, you can't. All you can do is "ask nicely" and "hope". The reason for that is exactly why both "fsync" and "F_FULLFSYNC" exist.

Starting with fsync, its man page says:

fsync() causes all modified data and attributes of fildes to be moved to a permanent storage device. This normally results in all in-core modified copies of buffers for the associated file to be written to a disk.

On the surface, "moved to a permanent storage device" makes it sound like you'd now be "done", as the data has been sent to the storage device. Unfortunately, the problem here is caching. Over time, the performance gap between the overall system and mass storage has gotten larger and larger, so mass storage devices responded by using more and more memory to reduce/mask that gap. That works great, except power loss means the cache is destroyed and your data is gone. That leads to "F_FULLFSYNC":

"Does the same thing as fsync(2) then asks the drive to flush all buffered data to the permanent storage device (arg is ignored). As this drains the entire queue of the device and acts as a barrier, data that had been fsync'd on the same device before is guaranteed to be persisted when this call returns. This is currently implemented on HFS, MS-DOS (FAT), Universal Disk Format (UDF) and APFS file systems. The operation may take quite a while to complete. Certain FireWire drives have also been known to ignore the request to flush their buffered data."

...and the problem there is the words "asks the drive". We do not control the final I/O target, so we've got no way to GUARANTEE it will do what it's told. If you're writing to our devices, then F_FULLFSYNC will ensure that your changes have made it all the way to disk. If it's not one of our devices... then I can't promise anything. F_FULLFSYNC should and generally is sufficient, but that's the strongest promise I can give.

Which objects need to be synchronized, and in what order: the database file, R, P, or P's parent? Please distinguish the case where P already existed from the case where P was newly created during initialization.

An F_FULLFSYNC to a file at the bottom of a newly created hierarchy will implicitly flush the data of newly created parents. Any other behavior would implicitly "encourage" file system corruption. For maximum safety, you could:

  1. Issue an fsync to all objects.

  2. (optional) Issue an F_BARRIERFSYNC to one file. (This is a new command and not supported on all hardware. See man fcntl for details.)

  3. Issue an F_FULLFSYNC to the same file.

Note that issuing multiple F_FULLFSYNCs is pointless, nor does it matter which object you issue the F_FULLFSYNC on. The command is being sent to the drive itself and applies to the entire drive cache.

What guarantees differ between an OS crash and sudden power loss?

The guarantee itself doesn't change but the likelihood of failure does. Using F_FULLFSYNC as an example, it doesn't actually matter what happens to the machine as long as the command itself reached the storage device. The storage device is still going to finish flushing its buffers, even if the machine itself panics. However, if the same drive loses power then, yes, it will lose data.

Is there authoritative documentation applicable to macOS 15.7.2 that describes this contract?

Everything I've discussed here is in the man pages for fsync and fcntl.

Finally, a warning here:

guarantees against arbitrary hardware failure.

The problem here is that "arbitrary hardware failures" ARE the problem. If you assume the target hardware behaves "perfectly", then fsync is all that's required—it sends the data to the drive and the drive writes it out. The problem, and the reason F_FULLFSYNC was created, is that you CAN'T trust the hardware.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Accepted Answer

The specific concern is the durability of the directory entries needed to resolve P/R/start.sqlite. I need to distinguish the persistence of the database contents from the persistence of the names used to reach that database. I am not assuming that a successful SQLite commit, by itself, establishes every parent-directory durability requirement.

So, one thing to understand here is that the file system considers the proper handling of filesystem structure data to be significantly more important than than the commitment of individual file data. Structurally, APFS (like virtually every modern file system) is designed to "guarantee" that its file system state is ALWAYS coherent under ALL circumstances. I mean that quite literally. Twenty+ years ago I put together a rig designed to intentionally destroy volumes. It worked by:

  1. Starting the machine up and starting up a whole bunch of long-running copies.

  2. Letting the copies run for a few minutes.

  3. Using an external hardware device to cut power to the device.

  4. Restoring power to the machine, looping the entire process back to #1.

On a standard HFS+ file system (no journal), it would render the drive unmountable in ~4 hours. With a journaled HFS+ volume... it didn't work, even when allowed to run for "days". This was pre-APFS, but APFS would do just as well.

That then leads to here:

I need to distinguish the persistence of the database contents from the persistence of the names used to reach that database. I am not assuming that a successful SQLite commit, by itself, establishes every parent-directory durability requirement.

I THINK what you're worried about here is that the file's data will somehow be written to disk but the directory and file record entries won't be. If so, then the answer is basically "no, that won't happen". First off, as noted above, the file system is significantly more concerned about pushing out metadata/structure data than it is about file-level data.

However, the bigger issue is tied to what a "file" actually is at the file system level. As far as the file system is concerned, "a file" is a particular type of record within its data structures. That happens to point to a location on disk where the actual data blocks are stored, but the record itself IS the file, NOT the data blocks on disk. If the file record doesn't exist, then the data blocks are irrelevant, as that file record is the only tool it has to find them.

Putting that another way, if a catastrophic event (crash, power loss, etc.) occurs, then the file system will be in one of these four states when it's mounted again:

  1. None of your content is there.

  2. The directory exists and nothing else.

  3. The directory and file both exist, but the file's contents are incomplete or missing.

  4. Everything is there.

Those are the only states the file system will mount in because it's designed such that IF it happens to be in any transition state other than those, it will force itself to one of those 4 states so that it guarantees its own integrity.

The question that then leads to is "how do I guarantee that I'm at #4" and the answer is, unfortunately, you can't. All you can do is "ask nicely" and "hope". The reason for that is exactly why both "fsync" and "F_FULLFSYNC" exist.

Starting with fsync, its man page says:

fsync() causes all modified data and attributes of fildes to be moved to a permanent storage device. This normally results in all in-core modified copies of buffers for the associated file to be written to a disk.

On the surface, "moved to a permanent storage device" makes it sound like you'd now be "done", as the data has been sent to the storage device. Unfortunately, the problem here is caching. Over time, the performance gap between the overall system and mass storage has gotten larger and larger, so mass storage devices responded by using more and more memory to reduce/mask that gap. That works great, except power loss means the cache is destroyed and your data is gone. That leads to "F_FULLFSYNC":

"Does the same thing as fsync(2) then asks the drive to flush all buffered data to the permanent storage device (arg is ignored). As this drains the entire queue of the device and acts as a barrier, data that had been fsync'd on the same device before is guaranteed to be persisted when this call returns. This is currently implemented on HFS, MS-DOS (FAT), Universal Disk Format (UDF) and APFS file systems. The operation may take quite a while to complete. Certain FireWire drives have also been known to ignore the request to flush their buffered data."

...and the problem there is the words "asks the drive". We do not control the final I/O target, so we've got no way to GUARANTEE it will do what it's told. If you're writing to our devices, then F_FULLFSYNC will ensure that your changes have made it all the way to disk. If it's not one of our devices... then I can't promise anything. F_FULLFSYNC should and generally is sufficient, but that's the strongest promise I can give.

Which objects need to be synchronized, and in what order: the database file, R, P, or P's parent? Please distinguish the case where P already existed from the case where P was newly created during initialization.

An F_FULLFSYNC to a file at the bottom of a newly created hierarchy will implicitly flush the data of newly created parents. Any other behavior would implicitly "encourage" file system corruption. For maximum safety, you could:

  1. Issue an fsync to all objects.

  2. (optional) Issue an F_BARRIERFSYNC to one file. (This is a new command and not supported on all hardware. See man fcntl for details.)

  3. Issue an F_FULLFSYNC to the same file.

Note that issuing multiple F_FULLFSYNCs is pointless, nor does it matter which object you issue the F_FULLFSYNC on. The command is being sent to the drive itself and applies to the entire drive cache.

What guarantees differ between an OS crash and sudden power loss?

The guarantee itself doesn't change but the likelihood of failure does. Using F_FULLFSYNC as an example, it doesn't actually matter what happens to the machine as long as the command itself reached the storage device. The storage device is still going to finish flushing its buffers, even if the machine itself panics. However, if the same drive loses power then, yes, it will lose data.

Is there authoritative documentation applicable to macOS 15.7.2 that describes this contract?

Everything I've discussed here is in the man pages for fsync and fcntl.

Finally, a warning here:

guarantees against arbitrary hardware failure.

The problem here is that "arbitrary hardware failures" ARE the problem. If you assume the target hardware behaves "perfectly", then fsync is all that's required—it sends the data to the drive and the drive writes it out. The problem, and the reason F_FULLFSYNC was created, is that you CAN'T trust the hardware.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thank you for the explanation, especially the clarification about F_FULLFSYNC and newly created parent directories. I have one follow-up about a directory's state after a deletion.

For the same macOS 15.7.2 / local APFS scenario, please consider this proposed, untested sequence. The paths below are illustrative. Assume all relevant files and directories are on the same device, the device correctly honors flush requests, and no concurrent writes, deletions, or replacements occur.

  1. SQLite has unlinked R/start.sqlite-journal as part of committing the initial catalog transaction in rollback-journal mode DELETE, and COMMIT has returned successfully. The catalog and journal are in the same directory R. I do not assume that the COMMIT return alone establishes power-loss durability.

  2. All SQLite connections and other SQLite use of this catalog have actually ended. No uncommitted transaction or outstanding SQLite operation remains.

  3. Native code opens the same existing R/start.sqlite without creating or truncating it, calls fcntl(fd, F_FULLFSYNC), and directly receives a successful return from that call. A failed call is not treated as successful by substituting a fallback synchronization result.

For this question, we do not rely on a separate successful directory fsync after the journal unlink. In particular, please consider the case where that directory sync was skipped or did not succeed.

Does the successful F_FULLFSYNC on the catalog file also make R's updated directory state after the unlink durable, so that the journal deletion survives an OS crash or sudden power loss occurring after that successful return, under the assumptions above? This includes any relevant unlink metadata still in filesystem memory, rather than only data already in the device's cache.

If this is not covered or requires additional conditions, please identify the documented, supported operation and ordering, if any, needed for this directory update, together with any applicability limits. If the guarantee is unspecified for this configuration, please distinguish that from an unsupported operation.

I am asking only about this filesystem synchronization boundary, not validation of the application's overall recovery protocol. I am not asking about interruptions before the successful F_FULLFSYNC return or arbitrary hardware failure. The proposed sequence has not been implemented or tested.

Thank you.

Does the successful F_FULLFSYNC on the catalog file also make R's updated directory state after the unlink durable, so that the journal deletion survives an OS crash or sudden power loss occurring after that successful return, under the assumptions above?

Two answer:

  1. Strictly speaking, no.

  2. In practice, maybe?

The issue is with #3 here:

  1. Native code opens the same existing R/start.sqlite without creating or truncating it, calls fcntl(fd, F_FULLFSYNC), and directly receives a successful return from that call.

Simply opening a file has no effect on the file system and, presumably, nothing has changed on the file itself. That means that, in theory, fsync didn't push anything out to the drives buffer, so the F_FULLFSYNC flushed a buffer that didn't have anything in it.

That means the critical question here is whether this change:

SQLite has unlinked R/start.sqlite-journal

...happened to already be in the drives buffer or not. In pure API terms, nothing requires it to be there however, in practice, the most file system tend to flush more that it "has" to. However, the right answer here would be to call fsync on the directory itself.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

ok

ok