Add experimental support for FSKit on macOS 15.4 and newer releases of macOS

macFUSE supports two backends for mounting file systems. By default, the legacy VFS kernel API is used to mount volumes. When specifying the mount-time option -obackend=fskit, macFUSE will use FSKit to mount the file system. For more information, see FUSE Backends.

Drop support for macOS 10.9 to 10.14. macFUSE 5.0.0 support macOS 10.15 and later releases of macOS.

Make macFUSE.framework swift-friendlier by adding generics and nullability annotations

Add new macFUSE.framework delegate method for listing directories. The new delegate method supports returning directory entries including the name and the requested attributes of each entry. This is the first step in implementing support for FUSE_READDIRPLUS.

- (nullable NSArray<GMDirectoryEntry *> *)
    contentsOfDirectoryAtPath:(NSString *)path
   includingAttributesForKeys:(NSArray<NSString *> *)keys
                        error:(NSError * _Nullable * _Nonnull)error

Update reference file systems for macFUSE 5. For more information, see the demo repository.

Optimize build script

Invalidate a vnode's identity in case the corresponding file is removed.

When performing a remove operation, the file might not actually be removed by the user space code. libfuse renames open files, hides them and defers removing them until all open file handles have been closed (unless hard_remove is enabled). This means we might come across the vnode again, e.g. while performing a readdir(3) operation. We need to invalidate the vnode's current identity to make sure Finder does not display any outdated information.

Build script optimizations

Update libfuse 3 to version 3.17.1

Some macOS specific features require FUSE API extensions that break compatibility with the vanilla FUSE API. Setting the compile-time flag FUSE_DARWIN_ENABLE_EXTENSIONS to 0, when building a file system, disables those API extensions. By default, the macOS specific API extensions are enabled.

Please note:

• The macOS specific libfuse 3 API extensions might not be stable, yet. This means that libfuse 3 file systems that are built for macFUSE 4.10.1 might need to be updated to work with future macFUSE releases.

Add support for arbitrary file system block sizes

The macOS kernel imposes no restrictions on the block size of a file system, neither should we. macFUSE supports file system block sizes between 128 B and 1 MB. The specified I/O size (-oiosize=...) is rounded down to the next multiple of the file system block size, if necessary.

The device block size (-oblocksize=...) needs to be a power of two and may not exceed 4 KB on Intel Macs and 16 KB Apple Silicon Macs.

Address code signing issue. The bundled download helper ksurl needs to be code signed individually to make its origin transparent. In previous releases, ksurl was only code signed indirectly as component of the update tool. For details, see #1062.

Declare the maximum size of extended attributes. pathconf(..., _PC_XATTR_SIZE_BITS) returns the number of bits that are required to store the maximum extended attribute size in bytes, in our case 25, which equals a maximum extended attribute size of 33,554,431 bytes (~ 32 MB).

Add experimental support for libfuse 3

Some macOS specific features require FUSE API extensions that break compatibility with the vanilla FUSE API. Setting the compile-time flag FUSE_DARWIN_ENABLE_EXTENSIONS to 0, when building a file system, disables those API extensions. By default, the macOS specific API extensions are enabled.

Please note:

• macFUSE 4.10.0 supports FUSE ABI version 7.19 and includes patched versions of libfuse 2.9.9 and libfuse 3.17.1-rc1.
• The macOS specific libfuse 3 API might not be stable, yet. This means that libfuse 3 file systems that are built for macFUSE 4.10.0 might need to be updated to work with future macFUSE releases.

Use iconv() instead of CFStringNormalize() to normalize file names in the high level FUSE API. Calling CFStringNormalize() after daemonizing the file system process results in a crash. See File Names (Unicode Normalization Forms) for details on file name normalization.

Work around a limitation preventing a single process from mounting multiple GMUserFileSystems (macFUSE.framework) at the same time. Even though a single process can mount multiple GMUserFileSystems, it is recommended to use a separate process per virtual volume. For details, see #1059.

Do not delete intermediate Xcode build files after building a target

Fix a build script logging bug when cleaning a build target

Improve support for FUSE_NOTIFY_INVAL_ENTRY notifications and trigger Finder refresh.

A FUSE_NOTIFY_INVAL_ENTRY notification is fired to inform the kernel that the specified file has a new identity, possibly due to having been renamed remotely. As a result, the vnode is removed from the name cache, a VNODE_EVENT_RENAME event is fired and the vnode's identity is updated on its next lookup.

For details see #960 and #470.

Improve fault tolerance when looking up vnodes.

In case a vnode type change is detected during a VNOP_LOOKUP call, the original (now outdated) vnode is revoked and a new node is created automatically without returning an error. The error condition will be logged.

For details see #894.

Optimize build script

• Reset build environment before running target actions. This reduces the number of unnecessary target rebuilds.
• Remove obsolete build cache index before creating new index under the same name.

This release lays foundational groundwork for macFUSE 5.0

Decouple kernel extension version from release version. In future macFUSE releases, the kernel extension will only be updated in case there have been code changes of the macFUSE kernel code. This avoids prompting users to allow loading a new kernel extension build.

Address a race condition in the libfuse mount process. On macOS, the mount process is asynchronous. This means mount(2) will not have returned when fuse_mount() returns, but we are interested in the mount(2) return code. Therefore, we spin up a separate thread that waits for mount(2) to return.

Use dispatch source to handle signals in libfuse. Mounted volumes are unmounted on SIGHUP, SIGINT and SIGTERM. We should not assume that unmounting a volume is async-signal safe. This means we should not rely on sigaction(2) handlers to perform the unmount operation.

Add support for using Grand Central Dispatch to process file system requests in libfuse. See fuse_loop_dispatch() for details. This reduces the number of threads being created and destroyed and cuts down on resource usage. fuse_session_loop_dispatch() is a drop-in replacement for fuse_session_loop_mt().

Add high-level libfuse mount-time option loop. The loop option can be used to select the file system request processing loop implementation. Supported values are:

• single_threaded: Process requests serially
• multi_threaded: Process requests in parallel on worker threads managed by libfuse
• dispatch: Process requests in parallel using Grand Central Dispatch

The default implementation is multi_threaded. When mount option -s (single threaded) is present, option loop is ignored.

Use dispatch semaphores as fallback for unnamed POSIX semaphores in libfuse. Unnamed POSIX semaphores are not supported by macOS. Therefore, we have been using a custom fallback implementation based on POSIX threads, which is now replaced by dispatch semaphores.

Silence pthread_setugid_np() deprecation warnings in libfuse

Modernize build script

• The build script requires Bash 4.1 or a later Bash release
• Improve support for incremental builds by adding support for caching build artifacts in a global cache.
• Improve build performance.

Clean up code and improve readability

Archive loader and mounter debug symbols

Update links in release disk image

Complete move of all project resources from the osxfuse organization to the macfuse organization. See History for details.

Fix race condition in macFUSE.framework that was introduced in version 4.8.2. The race condition can be triggered by removing items from a directory while listing the directory's contents. This can lead to a segmentation fault.

Improve fault tolerance of installer and uninstaller. There are documented cases of pkgutil(1) returning invalid version numbers for installed packages. This could result in issues when installing macFUSE updates or running the uninstaller.

Work around a bug in xcodebuild resulting in SDKs being listed twice.

Improve compatibility with macOS 15

On macOS 15, Archive Utility produces empty archives when archiving directories, unless readdir(3) returns the file type for each directory entry.

In oder to address this compatibility issue, macFUSE.framework queries the attributes of each directory entry returned by the file system delegate. This change is transparent to existing file systems.

Use macOS 14.5 SDK instead of macOS 14.4 SDK to build macOS 14 kernel extension

Add support for volume names and volume icon paths (mount options volname and iconpath) that contain commas or backslashes. Commas and backslashes need to be escaped by a preceding backslash character.

Improve volicon mount option shortcut handling

Add rudimentary support for incremental builds and clean up build scripts