-
Notifications
You must be signed in to change notification settings - Fork 571
FSKit macOS xcode27.0 b1
Alex Soto edited this page Jun 9, 2026
·
1 revision
#FSKit.framework
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSClient.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSClient.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSClient.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSClient.h 2026-05-27 04:50:09
@@ -7,6 +7,7 @@
#import <Foundation/Foundation.h>
#import <FSKit/FSModuleIdentity.h>
+#import <FSKit/FSResource.h>
NS_ASSUME_NONNULL_BEGIN
@@ -31,6 +32,29 @@
/// - Parameter completionHandler: A block or closure that executes when FSKit finishes its fetch process. If the fetch succeeds, the first parameter contains an array of ``FSModuleIdentity`` instances that identify installed modules. If the fetch fails, the second parameter contains an error detailing the failure.
-(void)fetchInstalledExtensionsWithCompletionHandler:(void(^)(NSArray<FSModuleIdentity *> *_Nullable,
NSError *_Nullable))completionHandler FSKIT_API_AVAILABILITY_V1 NS_SWIFT_ASYNC_NAME(getter:installedExtensions());
+
+/// Asynchronously mounts a single volume file system with given resource
+///
+/// This method allows a client with the `com.apple.developer.fskit.mount` entitlement to mount a single volume file system.
+/// The volume will be mounted within the `/Volumes/` directory.
+///
+/// The caller can only mount modules that are visible to them.
+///
+/// - Parameters:
+/// - resource: The resource that will be used to mount
+/// - bundleID: The bundle identifier of the file system extension
+/// - options: An array of strings containing the `mount_XXX` mount options
+/// - completionHandler: A block or closure to indicate success or failure. If mount fails, the first parameter is nil and second parameter contains an error. If mount succeeds, the first parameter contains the URL of the mount path, and second parameter is `nil`.
+- (void)mountSingleVolumeForResource:(FSResource *)resource
+ bundleID:(NSString *)bundleID
+ options:(NSArray <NSString *> *)options
+ completionHandler:(void (^)(NSURL * _Nullable mountPath,
+ NSError * _Nullable error))FSKIT_CALLED_ONCE completionHandler FSKIT_API_AVAILABILITY_V3 NS_SWIFT_NAME(mountSingleVolume(resource:bundleID:options:completionHandler:));
+
+/// Opens the File System Extensions settings in System Settings.
+///
+/// - Returns: `YES` if the settings were successfully opened, `NO` otherwise.
+-(BOOL)openFileSystemExtensionsSettings FSKIT_API_AVAILABILITY_V3;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSContext.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSContext.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSContext.h 1969-12-31 19:00:00
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSContext.h 2026-05-27 04:50:09
@@ -0,0 +1,28 @@
+//
+// Copyright (c) 2025 Apple Inc. All rights reserved.
+//
+// FSContext.h
+// FSKit
+//
+
+#import <Foundation/Foundation.h>
+#import <FSKit/FSKitDefines.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A context object that provides information about the initiator of a file system operation.
+///
+/// This object contains the user ID and group ID of the process that initiated the file system operation, allowing file systems to make authorization decisions based on the caller's identity.
+FSKIT_API_AVAILABILITY_V3
+@interface FSContext : NSObject
+
+@property (readonly) NSInteger realUserID;
+@property (readonly) NSInteger effectiveUserID;
+@property (readonly) NSInteger realGroupID;
+@property (readonly) NSInteger effectiveGroupID;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h 2026-05-27 04:50:10
@@ -40,8 +40,25 @@
/// - Parameters:
/// - uuid: The UUID to use for this identifier.
/// - qualifierData: The data to distinguish entities that otherwise share the same UUID.
+///
+/// - Warning: This initializer is annotated as returning a non-optional value but silently
+/// returns `nil` when `qualifierData` is not exactly eight bytes, which can surface as a
+/// null value in a non-optional Swift variable. Use ``initWithUUID:qualifierData:``
+/// instead, which is explicitly failable.
- (instancetype)initWithUUID:(NSUUID *)uuid
- data:(NSData *)qualifierData;
+ data:(NSData *)qualifierData
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("initWithUUID:qualifierData:");
+
+/// Creates an entity identifier with the given UUID and qualifier data.
+///
+/// - Parameters:
+/// - uuid: The UUID to use for this identifier.
+/// - qualifierData: The data to distinguish entities that otherwise share the same UUID.
+/// Must be exactly eight bytes; any other length causes this initializer to return `nil`.
+/// - Returns: A new identifier, or `nil` if `qualifierData` is not exactly eight bytes long.
+- (nullable instancetype)initWithUUID:(NSUUID *)uuid
+ qualifierData:(NSData *)qualifierData
+FSKIT_API_AVAILABILITY_V3;
/// A UUID to uniquely identify this entity.
@property (copy) NSUUID *uuid;
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSFreeSpace.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSFreeSpace.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSFreeSpace.h 1969-12-31 19:00:00
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSFreeSpace.h 2026-05-27 04:50:09
@@ -0,0 +1,31 @@
+//
+// FSFreeSpace.h
+// FSKit
+//
+// Copyright (c) 2025 Apple Inc. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+#import <FSKit/FSKitDefines.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A free space object that pairs free space values with atomic sequence numbers.
+FSKIT_API_AVAILABILITY_V3
+@interface FSFreeSpace : NSObject
+
+/// Creates an unpopulated free space instance.
+- (instancetype)init NS_DESIGNATED_INITIALIZER;
+
+/// Populates this instance with the given free space value and atomically assigns a sequence number.
+///
+/// > Important: FSKit uses internal sequencing technology within this method to determine the most up-to-date free space of the volume. To ensure correctness, this method should be called within an isolation context covering the volume's free space.
+- (void)populateWithBytes:(uint64_t)freeSpaceBytes
+NS_SWIFT_NAME(populate(bytes:));
+
+/// Returns a sentinel instance indicating no free space update occurred.
+@property (class, readonly) FSFreeSpace *noUpdate;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h 2026-05-27 04:50:09
@@ -110,6 +110,52 @@
FSKIT_API_AVAILABILITY_V1
@interface FSItem : NSObject
+/// Reclaims the `FSItem`, by executing the given `reclaimBlock`, only if conditions allow.
+///
+/// Should be invoked by the file system during the ``FSVolume/Handler/reclaimItem(_:replyHandler:)`` operation.
+///
+/// FSKit internally maintains a count of how many times each FSItem has been returned to the kernel, via either a creation operation or a lookup. The kernel file system also maintains a count of how many times a vnode has been returned by a create or a lookup operation. When the kernel reclaims the vnode associated with an FSItem, the FSItem should only get reclaimed when both the kernel and user space counts agree.
+/// This mechanism addresses a potential race condition wherein concurrent reclaim and lookup operations could lead to a lookup returning a deallocated FSItem, thereby inducing undefined behavior.
+///
+/// > Important: The caller must invoke this method within a synchronization context that ensures the FSItem is not concurrently returned by lookup operations.
+///
+/// > Note: File systems which do not invoke this method during reclaim are exposed to this race condition.
+///
+/// - Parameters:
+/// - reclaimBlock The block to execute if reclaim should proceed. Should include all required cleanup operations for reclaiming this item, excluding only the final teardown of the `FSItem` instance itself.
+///
+/// - Returns: YES if the reclaim block was executed, NO otherwise. In case it returns NO, the ``FSVolume/Handler/reclaimItem(_:replyHandler:)`` implementation should call `replyHandler(nil)`.
+///
+/// Example Usage:
+///
+/// ```objc
+/// - (void)reclaimItem:(FSItem *)item
+/// replyHandler:(void(^)(NSError * _Nullable error))reply
+/// {
+/// __block NSError *reclaimError = nil; // To be set during the reclaim block in case of an error
+///
+/// // *** CRITICAL SECTION BEGINS HERE ***
+/// // (A synchronization context that ensures the FSItem is not concurrently returned by lookup operations)
+///
+/// // Calling `tryReclaimWithBlock:` with the cleanup logic within the passed block
+/// BOOL wasReclaimed = [self tryReclaimWithBlock:^{
+/// // Includes all required cleanup operations for reclaiming this item.
+/// // Sets `reclaimError` in case of an error during the cleanup phase
+/// }];
+///
+/// // *** CRITICAL SECTION ENDS HERE ***
+///
+/// if (wasReclaimed) {
+/// // Clean up the FSItem if special teardown is needed.
+/// reply(reclaimError);
+/// } else {
+/// // Do nothing, the FSItem shouldn't get deallocated yet.
+/// reply(nil);
+/// }
+/// }
+/// ```
+- (BOOL)tryReclaimWithBlock:(void(^)(void))reclaimBlock FSKIT_API_AVAILABILITY_V3;
+
@end
/// Attributes of an item, such as size, creation and modification times, and user and group identifiers.
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKit.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKit.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKit.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKit.h 2026-05-27 04:50:09
@@ -28,6 +28,7 @@
#import <FSKit/FSEntityIdentifier.h>
#import <FSKit/FSMutableFileDataBuffer.h>
#import <FSKit/FSFileName.h>
+#import <FSKit/FSFreeSpace.h>
#import <FSKit/FSItem.h>
#import <FSKit/FSKitError.h>
#import <FSKit/FSModuleIdentity.h>
@@ -35,7 +36,9 @@
#import <FSKit/FSTask.h>
#import <FSKit/FSTaskOptions.h>
#import <FSKit/FSVolume.h>
+#import <FSKit/FSVolumeDataCacheHandler.h>
#import <FSKit/FSVolumeExtent.h>
+#import <FSKit/FSVolumeHandlerResult.h>
// These are last as they depend on classes included above
#import <FSKit/FSFileSystemBase.h>
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitDefines.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitDefines.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitDefines.h 2026-04-27 23:47:02
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitDefines.h 2026-05-27 04:50:10
@@ -39,12 +39,24 @@
// Unavailable in original API
#define FSKIT_API_UNAVAILABLE_V1 API_UNAVAILABLE(macos, ios, visionos) API_UNAVAILABLE(watchos, tvos)
-// macOS 16 API
+// macOS 26 API
#define FSKIT_API_AVAILABILITY_V2 API_AVAILABLE(macos(26.0)) \
API_UNAVAILABLE(ios, visionos) API_UNAVAILABLE(watchos, tvos)
// macOS 26.4 API
#define FSKIT_API_AVAILABILITY_V2_4 API_AVAILABLE(macos(26.4)) \
API_UNAVAILABLE(ios, visionos) API_UNAVAILABLE(watchos, tvos)
+
+// macOS 27 API
+#define FSKIT_API_AVAILABILITY_V3 API_AVAILABLE(macos(27.0)) \
+ API_UNAVAILABLE(ios, visionos) API_UNAVAILABLE(watchos, tvos)
+
+// original API that is getting deprecated in macOS 27
+#define FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT(replacement) \
+ API_DEPRECATED_WITH_REPLACEMENT(replacement, macos(15.4, 27.0)) \
+ API_UNAVAILABLE(ios, visionos) \
+ API_UNAVAILABLE(watchos, tvos)
+
+#define FSKIT_CALLED_ONCE __attribute__((called_once))
#endif /* FSKitDefines_h */
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitError.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitError.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitError.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitError.h 2026-05-27 04:50:09
@@ -47,4 +47,29 @@
FSErrorInvalidDirectoryCookie = 4506,
};
+/// Error codes specific to data cache operations.
+FSKIT_API_AVAILABILITY_V3
+typedef NS_ERROR_ENUM(FSKitErrorDomain, FSDataCacheErrorCode) {
+ /// The requested cache mode and coherency type combination is invalid.
+ FSErrorInvalidCacheModeCoherency = 4510,
+
+ /// The cache transition is not allowed.
+ ///
+ /// This error occurs when attempting an invalid transition, such as using an upgrade
+ /// method for a downgrade operation, or vice versa.
+ FSErrorInvalidCacheTransition = 4511,
+
+ /// Failed to flush dirty cached data to storage.
+ FSErrorCacheFlushFailed = 4512,
+
+ /// Failed to invalidate (clear) cached data.
+ FSErrorCacheInvalidationFailed = 4513,
+
+ /// A conflicting cache operation is in progress.
+ ///
+ /// This error occurs when multiple cache operations on the same item conflict,
+ /// such as attempting to change cache mode while I/O is active.
+ FSErrorCacheOperationConflict = 4514,
+};
+
NS_ASSUME_NONNULL_END
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h 2026-05-27 04:50:09
@@ -24,7 +24,7 @@
- (instancetype)init NS_UNAVAILABLE;
/// The byte data.
--(void *)mutableBytes FSKIT_API_AVAILABILITY_V1 NS_SWIFT_UNAVAILABLE("Use withMutableBytes instead.");
+-(void *)mutableBytes FSKIT_API_AVAILABILITY_V1 NS_SWIFT_UNAVAILABLE("Use createMutableRawSpan or withUnsafeMutableBytes instead.");
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h 2026-04-27 23:47:01
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h 2026-05-27 04:50:10
@@ -13,12 +13,19 @@
#import <FSKit/FSFileName.h>
#import <FSKit/FSResource.h>
#import <FSKit/FSMutableFileDataBuffer.h>
+#import <FSKit/FSVolumeHandlerResult.h>
+#import <FSKit/FSContext.h>
+// Forward declarations. Fully declared in ``FSVolumeDataCacheHandler.h``.
+typedef NS_ENUM(NSInteger, FSDataCacheMode);
+typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyType);
+typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyAction);
+
NS_ASSUME_NONNULL_BEGIN
/// A value that indicates a location in a directory from which to enumerate.
///
-/// Your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
+/// Your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
FSKIT_API_AVAILABILITY_V1
typedef uint64_t FSDirectoryCookie NS_TYPED_EXTENSIBLE_ENUM;
@@ -28,7 +35,7 @@
/// A tool to detect whether the directory contents changed since the last call to enumerate a directory.
///
-/// Your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
+/// Your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
FSKIT_API_AVAILABILITY_V1
typedef uint64_t FSDirectoryVerifier NS_TYPED_EXTENSIBLE_ENUM;
@@ -78,7 +85,7 @@
/// An object used to provide items during a directory enumeration.
///
-/// You use this type in your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``.
+/// You use this type in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``.
///
/// Packing allows your implementation to provide information FSKit needs, including each item's name, type, and identifier (such as an inode number).
/// Some directory enumerations require other attributes, as indicated by the ``FSItemGetAttributesRequest`` sent to the enumerate method.
@@ -89,13 +96,13 @@
/// Provides a directory entry during enumeration.
///
-/// You call this method in your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``, for each directory entry you want to provide to the enumeration.
+/// You call this method in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``, for each directory entry you want to provide to the enumeration.
///
/// - Parameters:
/// - name: The item's name.
/// - itemType: The type of the item.
/// - itemID: The item's identifier. Typically this is an inode number, or one of the constants defined by ``FSItem/Identifier`` like ``FSItem/Identifier/rootDirectory``.
-/// - nextCookie: A value to indicate the next entry in the directory to enumerate. FSKit passes this value as the `cookie` parameter on the next call to ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``. Use whatever value is appropriate for your implementation; the value is opaque to FSKit.
+/// - nextCookie: A value to indicate the next entry in the directory to enumerate. FSKit passes this value as the `cookie` parameter on the next call to ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``. Use whatever value is appropriate for your implementation; the value is opaque to FSKit.
/// - attributes: The item's attributes. Pass `nil` if the enumeration call didn't request attributes.
/// - Returns: `true` (Swift) or `YES` (Objective-C) if packing was successful and enumeration can continue with the next directory entry. If the value is `false` (Swift) or `NO` (Objective-C), stop enumerating. This result can happen when the entry is too big for the remaining space in the buffer.
-(BOOL)packEntryWithName:(FSFileName *)name
@@ -122,7 +129,7 @@
} NS_SWIFT_NAME(FSVolume.CaseFormat);
-/// A type that represents capabillities supported by a volume, such as hard and symbolic links, journaling, and large file sizes.
+/// A type that represents capabilities supported by a volume, such as hard and symbolic links, journaling, and large file sizes.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.SupportedCapabilities)
@interface FSVolumeSupportedCapabilities : NSObject<NSSecureCoding>
@@ -144,7 +151,7 @@
/// A Boolean property that indicates whether the volume currently uses a journal for speeding recovery after an unplanned shutdown.
@property (nonatomic) BOOL supportsActiveJournal;
-/// A Boolan property that indicates the volume doesn't store reliable times for the root directory.
+/// A Boolean property that indicates the volume doesn't store reliable times for the root directory.
///
/// If this value is `true` (Swift) or `YES` (Objective-C), the volume doesn't store reliable times for the root directory.
@property (nonatomic) BOOL doesNotSupportRootTimes;
@@ -218,7 +225,7 @@
/// A file system, depending on its type, provides one or more volumes to clients.
/// The ``FSUnaryFileSystem`` by definition provides only one volume, while an ``FSFileSystem`` supports multiple volumes.
///
-/// You implement a volume for your file system type by subclassing this class, and also conforming to the ``FSVolume/Operations`` and ``FSVolume/PathConfOperations`` protocols.
+/// You implement a volume for your file system type by subclassing this class, and also conforming to the ``FSVolume/Handler`` and ``FSVolume/PathConfOperations`` protocols.
/// This protocol defines the minimum set of operations supported by a volume, such as mounting, activating, creating and removing items, and more.
///
/// Your volume can provide additional functionality by conforming to other volume operations protocols.
@@ -374,13 +381,14 @@
@end
+
/// Methods that all volumes implement to provide required capabilities.
///
/// Conform to this protocol in your subclass of ``FSVolume``.
-/// To provide additional capabilities, conform to the other `FSVolume` operations protocols, like ``FSVolumeOpenCloseOperations`` and ``FSVolumeReadWriteOperations``.
+/// To provide additional capabilities, conform to the other `FSVolume` operations protocols, such as ``FSVolumeOpenCloseOperations`` and ``FSVolumeReadWriteOperations``.
///
/// > Note: This protocol extends ``FSVolumePathConfOperations``, so your volume implementation must also conform to that protocol.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeHandler")
NS_SWIFT_NAME(FSVolume.Operations)
@protocol FSVolumeOperations <NSObject, FSVolumePathConfOperations>
@@ -412,6 +420,40 @@
@required
+/// Activates the volume using the specified options.
+///
+/// When FSKit calls this method, allocate any in-memory state required to represent the file system.
+/// Also allocate an ``FSItem`` for the root directory of the file system, and pass it to the reply block.
+/// FSKit caches this root item for the lifetime of the volume, and uses it as a starting point for all file look-ups.
+///
+/// Volume activation occurs prior to any call to mount the volume.
+///
+/// - Parameters:
+/// - options: Options to apply to the activation. These can include security-scoped file paths. There are no defined options currently.
+/// - reply: A block or closure to indicate success or failure. If activation succeeds, pass the root ``FSItem`` and a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItem`` in this case. In Swift, `reply` takes only the ``FSItem`` as the parameter; you signal any error with a `throw`. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItem`` or throw an error.
+-(void)activateWithOptions:(FSTaskOptions *)options
+ replyHandler:(void (^)(FSItem * _Nullable rootItem,
+ NSError * _Nullable err))reply
+NS_SWIFT_NAME(activate(options:replyHandler:));
+
+/// Tears down a previously initialized volume instance.
+///
+/// Set up your implementation to release any resources allocated for the volume instance.
+/// By the time you receive this callback, FSKit has already performed a reclaim call to release all other file nodes associated with this file system instance.
+///
+/// Avoid performing any I/O in this method.
+/// Prior to calling this method, FSKit has already issued a sync call to perform any
+/// cleanup-related I/O.
+///
+/// FSKit unmounts any mounted volume with a call to ``unmount(replyHandler:)`` prior to the deactivate callback.
+///
+/// - Parameters:
+/// - options: Options to apply to the deactivation.
+/// - reply: A block or closure to indicate success or failure. If activation fails, pass an error as the one parameter to the reply handler. If activation succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)deactivateWithOptions:(FSDeactivateOptions)options
+ replyHandler:(void (^)(NSError * _Nullable err))reply
+NS_SWIFT_NAME(deactivate(options:replyHandler:));
+
/// Mounts this volume, using the specified options.
///
/// FSKit calls this method as a signal that some process is trying to mount this volume.
@@ -444,48 +486,6 @@
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(synchronize(flags:replyHandler:));
-/// Fetches attributes for the given item.
-///
-/// For file systems that don't support hard links, set ``FSItemAttributes/linkCount`` to `1` for regular files and symbolic links.
-///
-/// If the item's `bsdFlags` contain the `UF_COMPRESSED` flag, your file system returns the uncompressed size of the file.
-///
-/// - Parameters:
-/// - desiredAttributes: A requested set of attributes to get. The implementation inspects the request's ``FSItemGetAttributesRequest/wantedAttributes`` to determine which attributes to populate.
-/// - item: The item to get attributes for.
-/// - reply: A block or closure to indicate success or failure. If getting attributes succeeds, pass an ``FSItemAttributes`` with the requested attributes populated and a `nil` error. If getting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
--(void)getAttributes:(FSItemGetAttributesRequest *)desiredAttributes
- ofItem:(FSItem *)item
- replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
- NSError * _Nullable error))reply
-NS_SWIFT_NAME(getAttributes(_:of:replyHandler:))
-NS_SWIFT_ASYNC_NAME(attributes(_:of:));
-
-/// Sets the given attributes on an item.
-///
-/// Several attributes are considered "read-only", and an attempt to set these attributes results in an error with the code `EINVAL`.
-///
-/// A request may set ``FSItem/Attributes/size`` beyond the end of the file.
-/// If the underlying file system doesn't support sparse files, allocate space to fill the new file size.
-/// Either fill this space with zeroes, or configure it to read as zeroes.
-///
-/// If a request sets the file size below the current end-of-file, truncate the file and return any unused space to the file system as free space.
-///
-/// Ignore attempts to set the size of directories or symbolic links; don't produce an error.
-///
-/// If the caller attepts to sest an attribute not supported by the on-disk file system format, don't produce an error.
-/// The upper layers of the framework will detect this situation.
-///
-/// - Parameters:
-/// - newAttributes: A request containing the attributes to set.
-/// - item: The item on which to set the attributes.
-/// - reply: A block or closure to indicate success or failure. If setting attributes succeeds, pass an ``FSItemAttributes`` with the item's updated attributes and a `nil` error. If setting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
--(void)setAttributes:(FSItemSetAttributesRequest *)newAttributes
- onItem:(FSItem *)item
- replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
- NSError * _Nullable error))reply
-NS_SWIFT_NAME(setAttributes(_:on:replyHandler:));
-
/// Looks up an item within a directory.
///
/// If no item matching `name` exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `ENOENT`.
@@ -507,7 +507,7 @@
///
/// FSKit guarantees that for every ``FSItem`` returned by the volume, a corresponding reclaim operation occurs after the upper layers no longer reference that item.
///
-/// > Note: Block device file systems may assess whether an underyling resource terminates before processing reclaim operations. On unary file systems, for example, the associated volumes unmount when such resources disconnect from the system. The unmount triggers a reclaiming of all items. Some implementations benefit greatly from short-circuiting in such cases. With a terminated resource, all I/O results in an error, making short-circuiting the most efficient response.
+/// > Note: Block device file systems may assess whether an underlying resource terminates before processing reclaim operations. On unary file systems, for example, the associated volumes unmount when such resources disconnect from the system. The unmount triggers a reclaiming of all items. Some implementations benefit greatly from short-circuiting in such cases. With a terminated resource, all I/O results in an error, making short-circuiting the most efficient response.
///
/// - Parameters:
/// - item: The item to reclaim.
@@ -516,15 +516,6 @@
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(reclaimItem(_:replyHandler:));
-/// Reads a symbolic link.
-///
-/// - Parameters:
-/// - item: The symbolic link to read from. FSKit guarantees this item is of type ``FSItem/ItemType/symlink``.
-/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass the link's contents as an ``FSFileName`` and a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores any ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSFileName`` or throw an error.
--(void)readSymbolicLink:(FSItem *)item
- replyHandler:(void(^)(FSFileName * _Nullable contents,
- NSError * _Nullable error))reply;
-
/// Creates a new file or directory item.
///
/// If an item named `name` already exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `EEXIST`.
@@ -582,22 +573,6 @@
replyHandler:(void(^)(FSFileName * _Nullable linkName,
NSError * _Nullable error))reply;
-/// Removes an existing item from a given directory.
-///
-/// Don't actually remove the item object itself in your implementation; instead, only remove the given item name from the given directory.
-/// Remove and deallocate the item in ``reclaimItem(_:replyHandler:)``.
-///
-/// - Parameters:
-/// - item: The item to remove.
-/// - name: The name of the item to remove.
-/// - directory: The directory from which to remove the item.
-/// - reply: A block or closure to indicate success or failure. If removal fails, pass an error as the one parameter to the reply handler. If removal succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
--(void)removeItem:(FSItem *)item
- named:(FSFileName *)name
- fromDirectory:(FSItem *)directory
- replyHandler:(void(^)(NSError * _Nullable error))reply
-NS_SWIFT_NAME(removeItem(_:named:fromDirectory:replyHandler:));
-
/// Renames an item from one path in the file system to another.
///
/// Implement renaming along the lines of this algorithm:
@@ -644,6 +619,64 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(renameItem(_:inDirectory:named:to:inDirectory:overItem:replyHandler:));
+/// Removes an existing item from a given directory.
+///
+/// Don't actually remove the item object itself in your implementation; instead, only remove the given item name from the given directory.
+/// Remove and deallocate the item in ``reclaimItem(_:replyHandler:)``.
+///
+/// - Parameters:
+/// - item: The item to remove.
+/// - name: The name of the item to remove.
+/// - directory: The directory from which to remove the item.
+/// - reply: A block or closure to indicate success or failure. If removal fails, pass an error as the one parameter to the reply handler. If removal succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)removeItem:(FSItem *)item
+ named:(FSFileName *)name
+ fromDirectory:(FSItem *)directory
+ replyHandler:(void(^)(NSError * _Nullable error))reply
+NS_SWIFT_NAME(removeItem(_:named:fromDirectory:replyHandler:));
+
+/// Fetches attributes for the given item.
+///
+/// For file systems that don't support hard links, set ``FSItemAttributes/linkCount`` to `1` for regular files and symbolic links.
+///
+/// If the item's `bsdFlags` contain the `UF_COMPRESSED` flag, your file system returns the uncompressed size of the file.
+///
+/// - Parameters:
+/// - desiredAttributes: A requested set of attributes to get. The implementation inspects the request's ``FSItemGetAttributesRequest/wantedAttributes`` to determine which attributes to populate.
+/// - item: The item to get attributes for.
+/// - reply: A block or closure to indicate success or failure. If getting attributes succeeds, pass an ``FSItemAttributes`` with the requested attributes populated and a `nil` error. If getting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
+-(void)getAttributes:(FSItemGetAttributesRequest *)desiredAttributes
+ ofItem:(FSItem *)item
+ replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
+ NSError * _Nullable error))reply
+NS_SWIFT_NAME(getAttributes(_:of:replyHandler:))
+NS_SWIFT_ASYNC_NAME(attributes(_:of:));
+
+/// Sets the given attributes on an item.
+///
+/// Several attributes are considered "read-only", and an attempt to set these attributes results in an error with the code `EINVAL`.
+///
+/// A request may set ``FSItem/Attributes/size`` beyond the end of the file.
+/// If the underlying file system doesn't support sparse files, allocate space to fill the new file size.
+/// Either fill this space with zeroes, or configure it to read as zeroes.
+///
+/// If a request sets the file size below the current end-of-file, truncate the file and return any unused space to the file system as free space.
+///
+/// Ignore attempts to set the size of directories or symbolic links; don't produce an error.
+///
+/// If the caller attempts to set an attribute not supported by the on-disk file system format, don't produce an error.
+/// The upper layers of the framework will detect this situation.
+///
+/// - Parameters:
+/// - newAttributes: A request containing the attributes to set.
+/// - item: The item on which to set the attributes.
+/// - reply: A block or closure to indicate success or failure. If setting attributes succeeds, pass an ``FSItemAttributes`` with the item's updated attributes and a `nil` error. If setting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
+-(void)setAttributes:(FSItemSetAttributesRequest *)newAttributes
+ onItem:(FSItem *)item
+ replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
+ NSError * _Nullable error))reply
+NS_SWIFT_NAME(setAttributes(_:on:replyHandler:));
+
/// Enumerates the contents of the given directory.
///
/// This method uses the ``FSDirectoryEntryPacker/packEntry(name:itemType:itemID:nextCookie:attributes:)`` method of the `packer` parameter to deliver the enumerated items to the caller.
@@ -660,8 +693,8 @@
///
/// - Parameters:
/// - directory: The item to enumerate. FSKit guarantees this item is of type ``FSItem/ItemType/directory``.
-/// - cookie: A value that indicates the location within the directory from which to enumerate. Your implementation defines the semantics of the cookie values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryCookieInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `nextCookie` parmeter.
-/// - verifier: A tool to detect whether the directory contents changed since the last call to `enumerateDirectory`. Your implementation defines the semantics of the verifier values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryVerifierInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `currentVerifier` parmeter.
+/// - cookie: A value that indicates the location within the directory from which to enumerate. Your implementation defines the semantics of the cookie values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryCookieInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `nextCookie` parameter.
+/// - verifier: A tool to detect whether the directory contents changed since the last call to `enumerateDirectory`. Your implementation defines the semantics of the verifier values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryVerifierInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `currentVerifier` parameter.
/// - attributes: The desired attributes to provide, or `nil` if the caller doesn't require attributes.
/// - packer: An object that your implementation uses to enumerate directory items, packing one item per callback to `enumerateDirectory`.
/// - reply: A block or closure to indicate success or failure. If enumeration succeeds, pass the current verifier and a `nil` error. If enumeration fails, pass the relevant error as the second parameter; FSKit ignores any verifier in this case. For an `async` Swift implementation, there's no reply handler; simply return the current verifier or throw an error.
@@ -674,6 +707,58 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:));
+/// Reads a symbolic link.
+///
+/// - Parameters:
+/// - item: The symbolic link to read from. FSKit guarantees this item is of type ``FSItem/ItemType/symlink``.
+/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass the link's contents as an ``FSFileName`` and a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores any ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSFileName`` or throw an error.
+-(void)readSymbolicLink:(FSItem *)item
+ replyHandler:(void(^)(FSFileName * _Nullable contents,
+ NSError * _Nullable error))reply;
+
+@end
+
+
+/// Methods that all volumes implement to provide required capabilities.
+///
+/// Conform to this protocol in your subclass of ``FSVolume``.
+/// To provide additional capabilities, conform to the other `FSVolume` handler protocols, such as ``FSVolumeOpenCloseHandler`` and ``FSVolumeReadWriteHandler``.
+///
+/// > Note: This protocol extends ``FSVolumePathConfOperations``, so your volume implementation must also conform to that protocol.
+///
+/// > Important: This protocol replaces the ``FSVolumeOperations`` protocol. It exposes the same functionality, while using ``FSVolumeHandlerResult`` objects. These objects add the ability to reply with ``FSItemAttributes`` and free space from the relevant methods.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.Handler)
+@protocol FSVolumeHandler <NSObject, FSVolumePathConfOperations>
+
+// A property that provides the supported capabilities of the volume.
+@property (readonly, nonatomic) FSVolumeSupportedCapabilities *supportedVolumeCapabilities;
+
+/// A property that provides up-to-date statistics of the volume.
+@property (readonly, nonatomic) FSStatFSResult * volumeStatistics;
+
+@optional
+
+/// A property that allows the file system to use open-unlink emulation.
+///
+/// _Open-unlink_ functionality refers to a file system's ability to support an open file being fully unlinked from the file system namespace.
+/// If a file system doesn't support this functionality, FSKit can emulate it instead; this is called "open-unlink emulation".
+///
+/// Implement this property to return `true` (Swift) or `YES` (Objective-C) to allow FSKit to perform open-unlink emulation.
+/// If you don't implement this property at all, FSKit doesn't perform open-unlink emulation for this volume.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly) BOOL enableOpenUnlinkEmulation;
+
+/// A property that allows the file system to request for specific mount options from FSKit.
+///
+/// FSKit reads this value after the volume replies to the ``mount(options:replyHandler:)`` call.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly) FSMountOptions requestedMountOptions;
+
+@required
+
/// Activates the volume using the specified options.
///
/// When FSKit calls this method, allocate any in-memory state required to represent the file system.
@@ -684,10 +769,9 @@
///
/// - Parameters:
/// - options: Options to apply to the activation. These can include security-scoped file paths. There are no defined options currently.
-/// - reply: A block or closure to indicate success or failure. If activation succeeds, pass the root ``FSItem`` and a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItem`` in this case. In Swift, `reply` takes only the ``FSItem`` as the parameter; you signal any error with a `throw`. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItem`` or throw an error.
+/// - reply: A block or closure to indicate success or failure. If activation succeeds, pass an instance of ``FSActivateResult`` containing the root ``FSItem``, along with a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSActivateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
-(void)activateWithOptions:(FSTaskOptions *)options
- replyHandler:(void (^)(FSItem * _Nullable rootItem,
- NSError * _Nullable err))reply
+ replyHandler:(void (^)(FSActivateResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
NS_SWIFT_NAME(activate(options:replyHandler:));
/// Tears down a previously initialized volume instance.
@@ -705,9 +789,281 @@
/// - options: Options to apply to the deactivation.
/// - reply: A block or closure to indicate success or failure. If activation fails, pass an error as the one parameter to the reply handler. If activation succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)deactivateWithOptions:(FSDeactivateOptions)options
- replyHandler:(void (^)(NSError * _Nullable err))reply
+ replyHandler:(void (^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
NS_SWIFT_NAME(deactivate(options:replyHandler:));
+/// Mounts this volume, using the specified options.
+///
+/// FSKit calls this method as a signal that some process is trying to mount this volume.
+/// Your file system receives a call to ``activate(options:replyHandler:)`` prior to receiving any mount calls.
+///
+/// - Parameters:
+/// - options: Options to apply to the mount. These can include security-scoped file paths. There are no defined options currently.
+/// - reply: A block or closure to indicate success or failure. If mounting fails, pass an error as the one parameter to the reply handler. If mounting succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply return normally.
+-(void)mountWithOptions:(FSTaskOptions *)options
+ replyHandler:(void(^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(mount(options:replyHandler:));
+
+/// Unmounts this volume.
+///
+/// Clear and flush all cached state in your implementation of this method.
+///
+/// - Parameters:
+/// - reply: A block or closure to indicate success or failure. If unmounting fails, pass an error as the one parameter to the reply handler. If unmounting succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply return normally.
+-(void)unmountWithReplyHandler:(void(^)(void))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(unmount(replyHandler:));
+
+/// Synchronizes the volume with its underlying resource.
+///
+/// After calling this method, FSKit assumes that the volume has sent all pending I/O or metadata to its resource.
+///
+/// - Parameters:
+/// - flags: Timing flags, as defined in `mount.h.` These flags let the file system know whether to run the operation in a blocking or nonblocking fashion.
+/// - reply: A block or closure to indicate success or failure. If synchronization fails, pass an error as the one parameter to the reply handler. If synchronization succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)synchronizeWithFlags:(FSSyncFlags)flags
+ replyHandler:(void(^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(synchronize(flags:replyHandler:));
+
+/// Looks up an item within a directory.
+///
+/// If no item matching `name` exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `ENOENT`.
+///
+/// > Tip: The ``FSFileName`` sent back to the caller may differ from the `name` parameter. This flexibility allows your implementation to handle case-insensitive and case-sensitive file systems. It might also be the case that `name` uses a composed Unicode string, but the name maintained by the file system and provided to the caller is uncomposed Unicode.
+///
+/// - Parameters:
+/// - name: The name of the item to look up.
+/// - directory: The directory in which to look up the item.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If lookup succeeds, pass an instance of ``FSLookupItemResult`` containing the found ``FSItem``, its ``FSFileName`` (as saved within the file system), and its ``FSItemAttributes``, along with a `nil` error. If lookup fails, pass the relevant error as the second parameter; FSKit ignores the ``FSLookupItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)lookupItemNamed:(FSFileName *)name
+ inDirectory:(FSItem *)directory
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSLookupItemResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(lookupItem(named:in:context:replyHandler:));
+
+/// Reclaims an item, releasing any resources allocated for the item.
+///
+/// FSKit guarantees that for every ``FSItem`` returned by the volume, a corresponding reclaim operation occurs after the upper layers no longer reference that item.
+///
+/// > Note: Block device file systems may assess whether an underlying resource terminates before processing reclaim operations. On unary file systems, for example, the associated volumes unmount when such resources disconnect from the system. The unmount triggers a reclaiming of all items. Some implementations benefit greatly from short-circuiting in such cases. With a terminated resource, all I/O results in an error, making short-circuiting the most efficient response.
+///
+/// - Parameters:
+/// - item: The item to reclaim.
+/// - reply: A block or closure to indicate success or failure. If removal fails, pass an error as the one parameter to the reply handler. If removal succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)reclaimItem:(FSItem *)item
+ replyHandler:(void(^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(reclaimItem(_:replyHandler:));
+
+/// Creates a new file or directory item.
+///
+/// If an item named `name` already exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `EEXIST`.
+///
+/// - Parameters:
+/// - name: The new item's name.
+/// - type: The new item's type. Valid values are ``FSItem/ItemType/file`` or ``FSItem/ItemType/directory``.
+/// - directory: The directory in which to create the item.
+/// - newAttributes: Attributes to apply to the new item.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass an instance of ``FSCreateItemResult`` containing the newly-created ``FSItem``, its ``FSFileName``, its ``FSItemAttributes``, the updated ``FSItemAttributes`` of the parent directory, and the volume's updated free space, along with a `nil` error. If creation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCreateItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)createItemNamed:(FSFileName *)name
+ type:(FSItemType)type
+ inDirectory:(FSItem *)directory
+ attributes:(FSItemSetAttributesRequest *)newAttributes
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSCreateItemResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(createItem(named:type:in:attributes:context:replyHandler:));
+
+/// Creates a new symbolic link.
+///
+/// If an item named `name` already exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `EEXIST`.
+///
+/// - Parameters:
+/// - name: The new item's name.
+/// - directory: The directory in which to create the item.
+/// - newAttributes: Attributes to apply to the new item.
+/// - contents: The contents of the new symbolic link.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass an instance of ``FSCreateSymlinkResult`` containing the newly-created ``FSItem``, its ``FSFileName``, its ``FSItemAttributes``, the updated ``FSItemAttributes`` of the parent directory, and the volume's updated free space, along with a `nil` error. If creation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCreateSymlinkResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)createSymbolicLinkNamed:(FSFileName *)name
+ inDirectory:(FSItem *)directory
+ attributes:(FSItemSetAttributesRequest *)newAttributes
+ linkContents:(FSFileName *)contents
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSCreateSymlinkResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(createSymbolicLink(named:in:attributes:linkContents:context:replyHandler:));
+
+/// Creates a new hard link.
+///
+/// If creating the link fails, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and the following error codes:
+///
+/// * `EEXIST` if there's already an item named `name` in the directory.
+/// * `EMLINK` if creating the link would exceed the maximum number of hard links supported on `item`.
+/// * `ENOTSUP` if the file system doesn't support creating hard links to the type of file system object that `item` represents.
+///
+/// - Parameters:
+/// - item: The existing item to which to link.
+/// - name: The name for the new link.
+/// - directory: The directory in which to create the link.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass an instance of ``FSCreateLinkResult`` containing the ``FSFileName`` of the newly-created link, the ``FSItemAttributes`` of the linked item, the updated ``FSItemAttributes`` of the parent directory, and the volume's updated free space, along with a `nil` error. If creation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCreateLinkResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)createLinkToItem:(FSItem *)item
+ named:(FSFileName *)name
+ inDirectory:(FSItem *)directory
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSCreateLinkResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(createLink(to:named:in:context:replyHandler:));
+
+/// Renames an item from one path in the file system to another.
+///
+/// Implement renaming along the lines of this algorithm:
+///
+/// - If `item` is a file:
+/// - If the destination file exists:
+/// - Remove the destination file.
+/// - If the source and destination directories are the same:
+/// - Rewrite the name in the existing directory.
+/// - Else:
+/// - Write the new entry in the destination directory.
+/// - Clear the old directory entry.
+/// - If `item` is a directory:
+/// - If the destination directory exists:
+/// - If the destination directory isn't empty:
+/// - Fail the operation with an error of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `ENOTEMPTY`.
+/// - Else:
+/// - Remove the destination directory.
+/// - If the source and destination directories are the same:
+/// - Rewrite the name in the existing directory.
+/// - Else:
+/// - If the destination is a child of the source directory:
+/// - Fail the operation with an error.
+/// - Else:
+/// - Write the new entry in the destination directory.
+/// - Update `"."` and `".."` in the moved directory.
+/// - Clear the old directory entry.
+///
+/// - Parameters:
+/// - item: The file system object being renamed.
+/// - sourceDirectory: The directory that currently contains the item to rename.
+/// - sourceName: The name of the item within the source directory.
+/// - destinationName: The new name of the item as it appears in `destinationDirectory`.
+/// - destinationDirectory: The directory to contain the renamed object, which may be the same as `sourceDirectory`.
+/// - overItem: The file system object if the destination exists, as discovered in a prior lookup. If this parameter is non-`nil`, mark `overItem` as deleted, so the file system can free its allocated space on the next call to ``reclaimItem(_:replyHandler:)``. After doing so, ensure the operation finishes without errors.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If renaming succeeds, pass an instance of ``FSRenameItemResult`` containing the ``FSFileName`` as it exists within `destinationDirectory`, the ``FSItemAttributes`` of the renamed item, the updated ``FSItemAttributes`` of the source directory, the updated ``FSItemAttributes`` of the destination directory, the ``FSItemAttributes`` of the overwritten item (if any), and the volume's updated free space, along with a `nil` error. If renaming fails, pass the relevant error as the second parameter; FSKit ignores the ``FSRenameItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)renameItem:(FSItem *)item
+ inDirectory:(FSItem *)sourceDirectory
+ named:(FSFileName *)sourceName
+ toNewName:(FSFileName *)destinationName
+ inDirectory:(FSItem *)destinationDirectory
+ overItem:(FSItem * _Nullable)overItem
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSRenameItemResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(renameItem(_:inDirectory:named:to:inDirectory:overItem:context:replyHandler:));
+
+/// Removes an existing item from a given directory.
+///
+/// Don't actually remove the item object itself in your implementation; instead, only remove the given item name from the given directory.
+/// Remove and deallocate the item in ``reclaimItem(_:replyHandler:)``.
+///
+/// - Parameters:
+/// - item: The item to remove.
+/// - name: The name of the item to remove.
+/// - directory: The directory from which to remove the item.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If removal succeeds, pass an instance of ``FSRemoveItemResult`` containing the ``FSItemAttributes`` of the removed item, the updated ``FSItemAttributes`` of the parent directory, and the volume's updated free space, along with a `nil` error. If removal fails, pass the relevant error as the second parameter; FSKit ignores the ``FSRemoveItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)removeItem:(FSItem *)item
+ named:(FSFileName *)name
+ fromDirectory:(FSItem *)directory
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSRemoveItemResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(removeItem(_:named:from:context:replyHandler:));
+
+/// Fetches attributes for the given item.
+///
+/// For file systems that don't support hard links, set ``FSItemAttributes/linkCount`` to `1` for regular files and symbolic links.
+///
+/// If the item's `bsdFlags` contain the `UF_COMPRESSED` flag, your file system returns the uncompressed size of the file.
+///
+/// - Parameters:
+/// - desiredAttributes: A requested set of attributes to get. The implementation inspects the request's ``FSItemGetAttributesRequest/wantedAttributes`` to determine which attributes to populate.
+/// - item: The item to get attributes for.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If getting attributes succeeds, pass an instance of ``FSGetAttributesResult`` containing the requested attributes, along with a `nil` error. If getting attributes fails, pass the relevant error as the second parameter; FSKit ignores the ``FSGetAttributesResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)getAttributes:(FSItemGetAttributesRequest *)desiredAttributes
+ ofItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSGetAttributesResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(getAttributes(_:of:context:replyHandler:))
+NS_SWIFT_ASYNC_NAME(attributes(_:of:context:));
+
+/// Sets the given attributes on an item.
+///
+/// Several attributes are considered "read-only", and an attempt to set these attributes results in an error with the code `EINVAL`.
+///
+/// A request may set ``FSItem/Attributes/size`` beyond the end of the file.
+/// If the underlying file system doesn't support sparse files, allocate space to fill the new file size.
+/// Either fill this space with zeroes, or configure it to read as zeroes.
+///
+/// If a request sets the file size below the current end-of-file, truncate the file and return any unused space to the file system as free space.
+///
+/// Ignore attempts to set the size of directories or symbolic links; don't produce an error.
+///
+/// If the caller attempts to set an attribute not supported by the on-disk file system format, don't produce an error.
+/// The upper layers of the framework will detect this situation.
+///
+/// - Parameters:
+/// - newAttributes: A request containing the attributes to set.
+/// - item: The item on which to set the attributes.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If setting attributes succeeds, pass an instance of ``FSSetAttributesResult`` containing the item's updated attributes and the volume's updated free space, along with a `nil` error. If setting attributes fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSetAttributesResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)setAttributes:(FSItemSetAttributesRequest *)newAttributes
+ onItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSSetAttributesResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(setAttributes(_:on:context:replyHandler:));
+
+/// Enumerates the contents of the given directory.
+///
+/// This method uses the ``FSDirectoryEntryPacker/packEntry(name:itemType:itemID:nextCookie:attributes:)`` method of the `packer` parameter to deliver the enumerated items to the caller.
+/// The general flow of an enumeration implementation follows these steps:
+///
+/// 1. Enumeration starts with a call to `enumerateDirectory` using the initial next-cookie and verifier values ``FSDirectoryCookieInitial`` and ``FSDirectoryVerifierInitial``, respectively.
+/// 2. The implementation uses `packer` to pack the initial set of directory entries. Packing also sets a `nextCookie` to use on the next call.
+/// 3. The implementation replies with a new verifier value, a nonzero value that reflects the directory's current version.
+/// 4. On the next call the implementation packs the next set of entries, starting with the item indicated by `cookie`. If `cookie` doesn't resolve to a valid directory entry, complete the request with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code ``FSError/Code/invalidDirectoryCookie``.
+///
+/// When packing, make sure to use acceptable directory entry names and unambiguous input to all file operations that take names without additional normalization, such as`lookupName`.
+///
+/// > Tip: If the `attributes` parameter is `nil`, include at least two entries in a directory: `"."` and `".."`, which represent the current and parent directories, respectively. Both of these items have type ``FSItem/ItemType/directory``. For the root directory, `"."` and `".."` have identical contents. Don't pack `"."` and `".."` if `attributes` isn't `nil`.
+///
+/// - Parameters:
+/// - directory: The item to enumerate. FSKit guarantees this item is of type ``FSItem/ItemType/directory``.
+/// - cookie: A value that indicates the location within the directory from which to enumerate. Your implementation defines the semantics of the cookie values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryCookieInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `nextCookie` parameter.
+/// - verifier: A tool to detect whether the directory contents changed since the last call to `enumerateDirectory`. Your implementation defines the semantics of the verifier values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryVerifierInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `currentVerifier` parameter.
+/// - attributes: The desired attributes to provide, or `nil` if the caller doesn't require attributes.
+/// - packer: An object that your implementation uses to enumerate directory items, packing one item per callback to `enumerateDirectory`.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If enumeration succeeds, pass an instance of ``FSEnumerateDirectoryResult`` containing the current verifier, along with a `nil` error. If enumeration fails, pass the relevant error as the second parameter; FSKit ignores the ``FSEnumerateDirectoryResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)enumerateDirectory:(FSItem *)directory
+ startingAtCookie:(FSDirectoryCookie)cookie
+ verifier:(FSDirectoryVerifier)verifier
+ providingAttributes:(FSItemGetAttributesRequest * _Nullable)attributes
+ usingPacker:(FSDirectoryEntryPacker *)packer
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSEnumerateDirectoryResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(enumerateDirectory(_:startingAt:verifier:attributes:packer:context:replyHandler:));
+
+/// Reads a symbolic link.
+///
+/// - Parameters:
+/// - item: The symbolic link to read from. FSKit guarantees this item is of type ``FSItem/ItemType/symlink``.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass an instance of ``FSReadSymlinkResult`` containing the link's contents and attributes, along with a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores the ``FSReadSymlinkResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)readSymbolicLink:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSReadSymlinkResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(readSymbolicLink(_:context:replyHandler:));
+
@end
/// Flags to specify the policy when setting extended file attributes.
@@ -724,7 +1080,7 @@
} NS_SWIFT_NAME(FSVolume.SetXattrPolicy);
/// Methods and properties implemented by volumes that natively or partially support extended attributes.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeXattrHandler")
NS_SWIFT_NAME(FSVolume.XattrOperations)
@protocol FSVolumeXattrOperations <NSObject>
@@ -781,7 +1137,7 @@
///
/// - Parameters:
/// - item: The item from which to get extended attributes.
-/// - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass the xattrs as an array of ``FSFileName`` instances and a `nil` error. If getting the attriubtes fails, pass `nil` along with the relevant error. For an `async` Swift implementation, there's no reply handler; simply return the byte count or throw an error.
+/// - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass the xattrs as an array of ``FSFileName`` instances and a `nil` error. If getting the attributes fails, pass `nil` along with the relevant error. For an `async` Swift implementation, there's no reply handler; simply return the byte count or throw an error.
-(void)listXattrsOfItem:(FSItem *)item
replyHandler:(void (^)(NSArray <FSFileName *> * _Nullable value,
@@ -790,6 +1146,81 @@
@end
+
+/// Methods and properties implemented by volumes that natively or partially support extended attributes.
+///
+/// > Important: This protocol replaces the ``FSVolumeXattrOperations`` protocol. It exposes the same functionality, while using ``FSVolumeHandlerResult`` objects. These objects add the ability to reply with ``FSItemAttributes`` and free space from the relevant methods.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.XattrHandler)
+@protocol FSVolumeXattrHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly) BOOL xattrOperationsInhibited;
+
+/// Returns an array that specifies the extended attribute names the given item supports.
+///
+/// If `item` supports no extended attributes, this method returns `nil`.
+///
+/// Only implement this method if your volume works with "limited" extended attributes.
+/// For purposes of this protocol, "limited" support means the volume doesn't support extended attributes generally, but uses these APIs to expose specific file system data.
+///
+/// > Note: If a file system implements this method, FSKit assumes limited support for extended attributes exists. In this mode, FSkit only calls this protocol's methods for the extended attribute names this method returns.
+///
+/// - Parameter item: The item for which to get information.
+-(NSArray<FSFileName *> *)supportedXattrNamesForItem:(FSItem *)item;
+
+@required
+
+/// Gets the specified extended attribute of the given item.
+///
+/// - Parameters:
+/// - name: The extended attribute name.
+/// - item: The item for which to get the extended attribute.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If getting the attribute succeeds, pass an instance of ``FSGetXattrResult`` containing the extended attribute data, along with a `nil` error. If getting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSGetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)getXattrNamed:(FSFileName *)name
+ ofItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void (^)(FSGetXattrResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(getXattr(named:of:context:replyHandler:))
+NS_SWIFT_ASYNC_NAME(xattr(named:of:context:));
+
+/// Sets the specified extended attribute data on the given item.
+///
+/// - Parameters:
+/// - name: The extended attribute name.
+/// - value: The extended attribute value to set. This can't be `nil`, unless the policy is ``FSVolume/SetXattrPolicy/delete``.
+/// - item: The item on which to set the extended attribute.
+/// - policy: The policy to apply when setting the attribute. See ``FSSetXattrPolicy`` for possible values.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If setting the attribute succeeds, pass an instance of ``FSSetXattrResult`` containing the volume's updated free space, along with a `nil` error. If setting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)setXattrNamed:(FSFileName *)name
+ toData:(NSData * _Nullable)value
+ onItem:(FSItem *)item
+ policy:(FSSetXattrPolicy)policy
+ context:(FSContext *)context
+ replyHandler:(void (^)(FSSetXattrResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(setXattr(named:to:on:policy:context:replyHandler:));
+
+/// Gets the list of extended attributes currently set on the given item.
+///
+/// - Parameters:
+/// - item: The item from which to get extended attributes.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass an instance of ``FSListXattrsResult`` containing the xattrs as an array of ``FSFileName`` instances, along with a `nil` error. If getting the attributes fails, pass the relevant error as the second parameter; FSKit ignores the ``FSListXattrsResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+
+-(void)listXattrsOfItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void (^)(FSListXattrsResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_ASYNC_NAME(xattrs(of:context:));
+
+@end
+
+
/// Defined modes for opening a file.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSVolumeOpenModes) {
@@ -811,7 +1242,7 @@
/// When all memory mappings to the item release, the kernel layer issues a final close.
///
/// If a file system volume doesn't conform to this protocol, the kernel layer can skip making such calls to the volume.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeOpenCloseHandler")
NS_SWIFT_NAME(FSVolume.OpenCloseOperations)
@protocol FSVolumeOpenCloseOperations <NSObject>
@@ -847,13 +1278,63 @@
@end
+/// Methods and properties implemented by volumes that want to receive open and close calls for each item.
+///
+/// When a file system volume conforms to this protocol, the kernel layer issues an open call to indicate desired access, and a close call to indicate what access to retain.
+/// A file is fully closed when the kernel layer issues a close call with no retained open nodes.
+/// When a file system receives the close call, it removes all access to the item.
+/// When all memory mappings to the item release, the kernel layer issues a final close.
+///
+/// If a file system volume doesn't conform to this protocol, the kernel layer can skip making such calls to the volume.
+///
+/// > Important: This protocol replaces the ``FSVolumeOpenCloseOperations`` protocol. It exposes the same functionality, while adding the ``FSContext`` parameters.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.OpenCloseHandler)
+@protocol FSVolumeOpenCloseHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isOpenCloseInhibited) BOOL openCloseInhibited;
+
+@required
+/// Opens a file for access.
+///
+/// - Parameters:
+/// - item: The item to open.
+/// - modes: The set of mode flags to open the item with.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If opening fails, pass an error as the one parameter to the reply handler. If opening succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)openItem:(FSItem *)item
+ withModes:(FSVolumeOpenModes)modes
+ context:(FSContext *)context
+ replyHandler:(void (^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(openItem(_:modes:context:replyHandler:));
+
+/// Closes a file from further access.
+///
+/// - Parameters:
+/// - item: The item to close.
+/// - modes: The set of mode flags to keep after this close.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If closing fails, pass an error as the one parameter to the reply handler. If closing succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
+-(void)closeItem:(FSItem *)item
+ keepingModes:(FSVolumeOpenModes)modes
+ context:(FSContext *)context
+ replyHandler:(void (^)(NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(closeItem(_:modes:context:replyHandler:));
+
+@end
+
/// Methods implemented for read and write operations that deliver data to and from the extension.
///
/// Most volumes conform to either this protocol or ``FSVolumeKernelOffloadedIOOperations``.
/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use this protocol, and those without it use ``FSVolumeKernelOffloadedIOOperations``.
/// A volume that doesn't conform to either protocol can't support any I/O operation.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeReadWriteHandler")
NS_SWIFT_NAME(FSVolume.ReadWriteOperations)
@protocol FSVolumeReadWriteOperations <NSObject>
@@ -896,6 +1377,57 @@
@end
+
+/// Methods implemented for read and write operations that deliver data to and from the extension.
+///
+/// Most volumes conform to either this protocol or ``FSVolumeKernelOffloadedIOHandler``.
+/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
+/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use this protocol, and those without it use ``FSVolumeKernelOffloadedIOHandler``.
+/// A volume that doesn't conform to either protocol can't support any I/O operation.
+///
+/// > Important: This protocol replaces the ``FSVolumeReadWriteOperations`` protocol. It exposes the same functionality, while using ``FSVolumeHandlerResult`` objects. These objects add the ability to reply with ``FSItemAttributes`` and free space from the relevant methods.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.ReadWriteHandler)
+@protocol FSVolumeReadWriteHandler <NSObject>
+
+/// Reads the contents of the given file item.
+///
+/// If the number of bytes requested exceeds the number of bytes available before the end of the file, then the call copies only those bytes to `buffer`.
+/// If `offset` points past the last valid byte of the file, don't reply with an error but set `actuallyRead` to `0`.
+///
+/// - Parameters:
+/// - item: The item from which to read. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
+/// - offset: The offset in the file from which to start reading.
+/// - length: The number of bytes to read.
+/// - buffer: A buffer to receive the bytes read from the file.
+/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass an instance of ``FSReadFileResult`` containing the number of bytes read and the updated ``FSItemAttributes`` of the file, along with a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores the ``FSReadFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)readFromFile:(FSItem *)item
+ offset:(off_t)offset
+ length:(size_t)length
+ intoBuffer:(FSMutableFileDataBuffer *)buffer
+ replyHandler:(void(^)(FSReadFileResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(read(from:at:length:into:replyHandler:));
+
+/// Writes contents to the given file item.
+///
+/// FSKit expects this routine to allocate space in the file system to extend the file as necessary.
+///
+/// If the volume experiences an out-of-space condition, reply with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code `ENOSPC`.
+///
+/// - Parameters:
+/// - contents: A buffer containing the data to write to the file.
+/// - item: The item to which to write. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
+/// - offset: The offset in the file from which to start writing.
+/// - reply: A block or closure to indicate success or failure. If writing succeeds, pass an instance of ``FSWriteFileResult`` containing the number of bytes written, the updated ``FSItemAttributes`` of the file, and the volume's updated free space, along with a `nil` error. If writing fails, pass the relevant error as the second parameter; FSKit ignores the ``FSWriteFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)writeContents:(NSData *)contents
+ toFile:(FSItem *)item
+ atOffset:(off_t)offset
+ replyHandler:(void(^)(FSWriteFileResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(write(contents:to:at:replyHandler:));
+
+@end
+
+
/// A bitmask of access rights.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSAccessMask) {
@@ -907,7 +1439,7 @@
FSAccessWriteData = (1<<2),
/// The file system allows adding files.
FSAccessAddFile = FSAccessWriteData,
- /// The file system allows file executuion.
+ /// The file system allows file execution.
FSAccessExecute = (1<<3),
/// The file system allows searching files.
FSAccessSearch = FSAccessExecute,
@@ -936,7 +1468,7 @@
} NS_SWIFT_NAME(FSVolume.AccessMask);
/// Methods and properties implemented by volumes that want to enforce access check operations.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeAccessCheckHandler")
NS_SWIFT_NAME(FSVolume.AccessCheckOperations)
@protocol FSVolumeAccessCheckOperations <NSObject>
@@ -962,8 +1494,40 @@
@end
+
+/// Methods and properties implemented by volumes that want to enforce access check operations.
+///
+/// > Important: This protocol replaces the ``FSVolumeAccessCheckOperations`` protocol. It exposes the same functionality, while using the ``FSCheckAccessResult`` object, to align with all other `Handler` protocols.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.AccessCheckHandler)
+@protocol FSVolumeAccessCheckHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isAccessCheckInhibited) BOOL accessCheckInhibited;
+
+@required
+
+/// Checks whether the file system allows access to the given item.
+///
+/// - Parameters:
+/// - theItem: The item for which to check access.
+/// - access: A mask indicating a set of access types for which to check.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If the access check succeeds, pass an instance of ``FSCheckAccessResult`` containing a Boolean value to indicate whether the file system grants access, along with a `nil` error. If the access check fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCheckAccessResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)checkAccessToItem:(FSItem *)theItem
+ requestedAccess:(FSAccessMask)access
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSCheckAccessResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply;
+
+@end
+
+
/// Methods and properties implemented by volumes that support renaming the volume.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeRenameHandler")
NS_SWIFT_NAME(FSVolume.RenameOperations)
@protocol FSVolumeRenameOperations <NSObject>
@@ -986,6 +1550,35 @@
@end
+
+/// Methods and properties implemented by volumes that support renaming the volume.
+///
+/// > Important: This protocol replaces the ``FSVolumeRenameOperations`` protocol. It exposes the same functionality, while using the ``FSVolumeRenameResult`` object, to align with all other `Handler` protocols.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.RenameHandler)
+@protocol FSVolumeRenameHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isVolumeRenameInhibited) BOOL volumeRenameInhibited;
+
+@required
+/// Sets a new name for the volume.
+///
+/// - Parameters:
+/// - name: The new volume name.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If renaming succeeds, pass an instance of ``FSVolumeRenameResult`` containing the ``FSFileName`` of the new volume name, along with a `nil` error. If renaming fails, pass the relevant error as the second parameter; FSKit ignores the ``FSVolumeRenameResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)setVolumeName:(FSFileName *)name
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSVolumeRenameResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply;
+
+@end
+
+
/// Behavior flags for preallocation operations.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSPreallocateFlags) {
@@ -1000,7 +1593,7 @@
/// Allocates space from the physical end of file.
///
/// When implementing this behavior, ignore any offset in the preallocate call.
- /// This flag is currently set for all ``FSVolume/PreallocateOperations/preallocateSpace(for:at:length:flags:replyHandler:)`` calls.
+ /// This flag is currently set for all ``FSVolume/PreallocateHandler/preallocateSpace(for:at:length:flags:replyHandler:)`` calls.
FSPreallocateFlagsFromEOF = 0x00000010,
} NS_SWIFT_NAME(FSVolume.PreallocateFlags);
@@ -1012,7 +1605,7 @@
/// This process can improve performance later.
///
/// In a kernel-based file system, you typically preallocate space with the `VNOP_ALLOCATE` operation, called from `fcntl(F_PREALLOCATE)`.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumePreallocateHandler")
NS_SWIFT_NAME(FSVolume.PreallocateOperations)
@protocol FSVolumePreallocateOperations <NSObject>
@@ -1024,7 +1617,7 @@
@property (getter = isPreallocateInhibited) BOOL preallocateInhibited;
@required
-/// Prealocates disk space for the given item.
+/// Preallocates disk space for the given item.
///
/// - Parameters:
/// - item: The item for which to preallocate space.
@@ -1042,6 +1635,49 @@
@end
+
+/// Methods and properties implemented by volumes that want to offer preallocation functions.
+///
+/// A preallocation operation allocates space for a file without writing to it yet.
+/// A file system may use reallocation to avoid performing space allocation while in the midst of I/O; this strategy improves performance.
+/// Also, if the expected I/O pattern is many small writes, preallocating contiguous chunks may prevent fragmenting the file system.
+/// This process can improve performance later.
+///
+/// In a kernel-based file system, you typically preallocate space with the `VNOP_ALLOCATE` operation, called from `fcntl(F_PREALLOCATE)`.
+///
+/// > Important: This protocol replaces the ``FSVolumePreallocateOperations`` protocol. It exposes the same functionality, while using the ``FSPreallocateResult`` object. This objects adds the ability to reply with ``FSItemAttributes`` and free space from ``preallocateSpace(for:at:length:flags:replyHandler:)``.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.PreallocateHandler)
+@protocol FSVolumePreallocateHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isPreallocateInhibited) BOOL preallocateInhibited;
+
+@required
+/// Preallocates disk space for the given item.
+///
+/// - Parameters:
+/// - item: The item for which to preallocate space.
+/// - offset: The offset from which to allocate.
+/// - length: The length of the space in bytes.
+/// - flags: Flags that affect the preallocation behavior.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass an instance of ``FSPreallocateResult`` containing the amount of bytes allocated, the updated ``FSItemAttributes`` of the file and the volume's updated free space, along with a `nil` error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSPreallocateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)preallocateSpaceForItem:(FSItem *)item
+ atOffset:(off_t)offset
+ length:(size_t)length
+ flags:(FSPreallocateFlags)flags
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSPreallocateResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(preallocateSpace(for:at:length:flags:context:replyHandler:));
+
+@end
+
+
/// Options to specify the item deactivation policy.
///
/// Callers may want to set a deactivation policy because ``FSVolume/ItemDeactivation/deactivateItem(_:replyHandler:)`` processing blocks the kernel.
@@ -1064,12 +1700,12 @@
/// An option to process deactivation for for files with preallocated space.
///
/// This option facilitates a sort of trim-on-close behavior.
- /// It is only meaningful for volumes that conform to ``FSVolume/PreallocateOperations``.
+ /// It is only meaningful for volumes that conform to ``FSVolume/PreallocateHandler``.
FSItemDeactivationForPreallocatedItems = (1 << 1),
} NS_SWIFT_NAME(FSVolume.ItemDeactivationOptions);
/// Methods and properties implemented by volumes that support deactivating items.
-FSKIT_API_AVAILABILITY_V1
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeItemDeactivationHandler")
NS_SWIFT_NAME(FSVolume.ItemDeactivation)
@protocol FSVolumeItemDeactivation <NSObject>
@@ -1081,7 +1717,7 @@
/// Notifies the file system that the kernel is no longer making immediate use of the given item.
///
-/// This method gives a file system a chance to release resources associated wtih an item.
+/// This method gives a file system a chance to release resources associated with an item.
/// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Operations/reclaimItem(_:replyHandler:)``.
/// This method is the equivalent of VFS's `VNOP_INACTIVE`.
///
@@ -1093,6 +1729,121 @@
-(void)deactivateItem:(FSItem *)item
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(deactivateItem(_:replyHandler:));
+
+@end
+
+/// Methods and properties implemented by volumes that support deactivating items.
+///
+/// > Important: This protocol replaces the ``FSVolumeItemDeactivation`` protocol. It exposes the same functionality, while using the ``FSDeactivateItemResult`` object. This object adds the ability to reply with free space from ``deactivateItem(_:replyHandler:)``.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.ItemDeactivationHandler)
+@protocol FSVolumeItemDeactivationHandler <NSObject>
+
+/// A property that tells FSKit to which types of items the deactivation applies, if any.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly) FSItemDeactivationOptions itemDeactivationPolicy;
+
+/// Notifies the file system that the kernel is no longer making immediate use of the given item.
+///
+/// This method gives a file system a chance to release resources associated with an item.
+/// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Handler/reclaimItem(_:replyHandler:)``.
+/// This method is the equivalent of VFS's `VNOP_INACTIVE`.
+///
+/// FSKit restricts calls to this method based on the current value of ``FSVolume/ItemDeactivation/itemDeactivationPolicy``.
+///
+/// - Parameters:
+/// - item: The item to deactivate.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If deactivation succeeds, pass an instance of ``FSDeactivateItemResult`` containing the volume's updated free space, along with a `nil` error. If deactivation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSDeactivateItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)deactivateItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSDeactivateItemResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(deactivateItem(_:context:replyHandler:));
+
+@end
+
+/// Types of region for seek operations
+FSKIT_API_AVAILABILITY_V3
+typedef NS_ENUM(NSUInteger, FSSeekRegion) {
+ /// Seek the next hole region.
+ ///
+ /// When there are no more hole regions past the supplied `offset`,
+ /// the current file size (end-of-file offset) should be returned.
+ FSSeekRegionHole = 1,
+ /// Seek the next data region.
+ ///
+ /// When there are no more data regions past the supplied `offset`,
+ /// an error code `ENXIO` should be returned.
+ FSSeekRegionData = 2,
+} NS_SWIFT_NAME(FSVolume.SeekRegion);
+
+/// Methods and properties implemented by volumes that support seek operations
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.SeekRegionHandler)
+@protocol FSVolumeSeekRegionHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isSeekRegionInhibited) BOOL seekRegionInhibited;
+
+@required
+/// Find the next offset of hole or data region greater than or equal to the
+/// supplied offset
+///
+/// - Parameters:
+/// - item: The item for which to seek.
+/// - offset: The offset from which to seek.
+/// - region: The region to seek.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If seek succeeds, pass an instance of ``FSSeekRegionResult`` containing the offset of the requested region greater than or equal to the supplied offset, along with a `nil` error. If seek fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSeekRegionResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+-(void)seekWithinItem:(FSItem *)item
+ fromOffset:(off_t)offset
+ region:(FSSeekRegion)region
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSSeekRegionResult * _Nullable result,
+ NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(seek(within:from:region:context:replyHandler:));
+
+@end
+
+
+FSKIT_API_AVAILABILITY_V3
+@interface FSVolume (DataCacheHandler)
+
+/// Sends a synchronous cache state update request from the module to the kernel.
+///
+/// Volumes conforming to ``FSVolumeDataCacheHandler`` call this method to proactively notify
+/// the kernel about cache policy changes that need to be applied immediately.
+/// This allows module-initiated updates outside the normal open/close/upgrade/downgrade flow.
+///
+/// When downgrading coherency type, the action must be ``FSKernelCacheCoherencyAction/push``,
+/// ``FSKernelCacheCoherencyAction/pushInvalidate``, or ``FSKernelCacheCoherencyAction/invalidate``
+/// to instruct the kernel how to handle cached data.
+/// If the action (push/invalidate) fails, the cache state remains unchanged and an error is returned.
+///
+/// > Important: This method must be called without holding any module-internal locks.
+/// The kernel may issue additional operations back into the module to satisfy cache state changes,
+/// which could result in deadlock if locks are held.
+///
+/// > Note: This method is only functional for volumes that conform to ``FSVolumeDataCacheHandler``.
+/// For volumes that don't conform to the protocol, this method returns `ENOTSUP`.
+///
+/// - Parameters:
+/// - item: The item for which to update the cache state.
+/// - cacheMode: The new cache mode to apply.
+/// - coherencyType: The new coherency type to apply.
+/// - action: The action for the kernel to perform on cached data (push, invalidate, update, or revoke).
+/// - Returns: An error if the kernel was unable to complete the requested cache state change, or `nil` on success.
+- (NSError * _Nullable)setCacheStateForItem:(FSItem *)item
+ cacheMode:(FSDataCacheMode)cacheMode
+ coherencyType:(FSKernelCacheCoherencyType)coherencyType
+ coherencyAction:(FSKernelCacheCoherencyAction)action
+NS_SWIFT_NAME(setCacheState(for:cacheMode:coherencyType:action:)) FSKIT_API_AVAILABILITY_V3;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeDataCacheHandler.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeDataCacheHandler.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeDataCacheHandler.h 1969-12-31 19:00:00
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeDataCacheHandler.h 2026-05-27 04:50:09
@@ -0,0 +1,184 @@
+//
+// Copyright (c) 2025 Apple Inc. All rights reserved.
+//
+// FSVolumeDataCacheHandler.h
+// FSKit
+//
+
+#import <Foundation/Foundation.h>
+#import <FSKit/FSKitError.h>
+#import <FSKit/FSVolume.h>
+#import <FSKit/FSVolumeHandlerResult.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class FSItem;
+
+/// FSDataCacheMode defines the cache mode requested by the kernel for data operations.
+FSKIT_API_AVAILABILITY_V3
+typedef NS_ENUM(NSInteger, FSDataCacheMode) {
+ /// No active caching.
+ FSDataCacheModeNone = 0,
+ /// Read access with caching enabled.
+ FSDataCacheModeReadWithCache,
+ /// Read-write access with caching enabled.
+ FSDataCacheModeReadWriteWithCache
+} NS_SWIFT_NAME(FSVolume.DataCacheMode);
+
+/// FSKernelCacheCoherencyType defines how data is cached by the kernel.
+FSKIT_API_AVAILABILITY_V3
+typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyType) {
+ /// No caching - all I/O goes directly to storage.
+ FSKernelCacheCoherencyTypeNoCache = 0,
+ /// Cache only reads, writes bypass cache and go directly to storage.
+ FSKernelCacheCoherencyTypeReadCache,
+ /// Write-through caching: writes update both cache and storage synchronously.
+ FSKernelCacheCoherencyTypeWriteThrough,
+ /// Write-back caching: writes update cache only, deferred write to storage.
+ FSKernelCacheCoherencyTypeWriteBack
+} NS_SWIFT_NAME(FSVolume.KernelCacheCoherencyType);
+
+/// FSKernelCacheCoherencyAction defines actions for cache state changes.
+FSKIT_API_AVAILABILITY_V3
+typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyAction) {
+ /// Flush dirty data from cache to storage (preserves cache contents).
+ FSKernelCacheCoherencyActionPush = 0,
+ /// Flush dirty data to storage and invalidate (clear) the cache.
+ FSKernelCacheCoherencyActionPushInvalidate,
+ /// Invalidate (clear) cache, discarding any dirty data without writing to storage.
+ FSKernelCacheCoherencyActionInvalidate,
+ /// Update coherency mode while keeping cache valid (no push/invalidate required).
+ FSKernelCacheCoherencyActionUpdate,
+ /// Invalidate all caches, revoke all access to the item, and trigger vnode reclamation.
+ ///
+ /// This action should be used when the module determines that an item no longer exists or
+ /// should no longer be accessible. Common scenarios include:
+ /// - The item was deleted by another client (detected via server notification)
+ /// - The module received a server callback indicating the file is gone
+ FSKernelCacheCoherencyActionRevoke
+} NS_SWIFT_NAME(FSVolume.KernelCacheCoherencyAction);
+
+/// Methods and properties implemented by volumes that coordinate kernel-level data caching.
+///
+/// A volume that conforms to this protocol enables kernel data caching for improved I/O performance.
+/// This protocol allows filesystem modules to negotiate cache modes with the kernel and manage cache coherency.
+///
+/// When a file is opened, the module receives the requested ``FSDataCacheMode`` and returns a
+/// ``FSKernelCacheCoherencyType`` indicating what caching behavior it can support. The kernel then
+/// caches data according to the granted coherency type. The module can dynamically upgrade or
+/// downgrade cache modes as conditions change.
+///
+/// The kernel will request a caching mode expressed as a ``FSDataCacheMode`` value, which indicates
+/// what the kernel would like to cache (read-only data, read-write data, or no caching). The module
+/// will then reply with a specific ``FSKernelCacheCoherencyType`` value, which defines how the kernel
+/// should cache the data (no caching, read-only caching, write-through caching, or write-back caching).
+/// When the module detects an asynchronous condition requiring a change in caching mode (such as an
+/// lease break), the module will use a value from ``FSKernelCacheCoherencyAction`` to instruct the kernel
+/// how to handle any cached data (push dirty pages, invalidate cache, or update coherency mode).
+///
+/// The protocol supports deferred closing, where the kernel maintains cache state even after a file
+/// is closed, enabling improved performance for frequently accessed files. ``FSKernelCacheCoherencyType/readCache``,
+/// ``FSKernelCacheCoherencyType/writeThrough``, and ``FSKernelCacheCoherencyType/writeBack`` modes
+/// support deferred closing.
+///
+/// **Cache Mode to Coherency Type Mapping:**
+/// - ``FSDataCacheMode/none`` → ``FSKernelCacheCoherencyType/noCache`` only
+/// - ``FSDataCacheMode/readWithCache`` → ``FSKernelCacheCoherencyType/noCache``, ``FSKernelCacheCoherencyType/readCache``
+/// - ``FSDataCacheMode/readWriteWithCache`` → ``FSKernelCacheCoherencyType/noCache``, ``FSKernelCacheCoherencyType/readCache``, ``FSKernelCacheCoherencyType/writeBack``, ``FSKernelCacheCoherencyType/writeThrough``
+///
+/// **Coherency Transition Rules:**
+///
+/// Upgrades (less restrictive - use ``upgrade(_:cacheMode:context:replyHandler:)``):
+/// - Called by the kernel when transitioning to more permissive caching
+/// - Examples: ``noCache`` → ``readCache``, ``readCache`` → ``writeBack``
+/// - No flush/purge required
+///
+/// Downgrades (more restrictive - use ``FSVolume`` method ``setCacheState(for:cacheMode:coherencyType:action:)``):
+/// - Initiated by the module when conditions change
+/// - MUST use ``FSKernelCacheCoherencyAction/push``, ``FSKernelCacheCoherencyAction/pushInvalidate``, or ``FSKernelCacheCoherencyAction/invalidate`` actions
+/// - MUST handle dirty data before downgrading
+/// - Examples: ``writeBack`` → ``readCache``, ``writeThrough`` → ``noCache``
+/// - Requires flush/purge of cached data
+///
+/// > Important: Filesystems that don't conform to this protocol can still be cached by the kernel,
+/// but they have no control over caching behavior. The kernel caches data as it sees fit.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.DataCacheHandler)
+@protocol FSVolumeDataCacheHandler <NSObject>
+
+@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
+@property (readonly, getter = isDataCacheInhibited) BOOL dataCacheInhibited FSKIT_API_AVAILABILITY_V3;
+
+@required
+
+/// Opens an item with cache mode negotiation.
+///
+/// FSKit calls this method when a file is opened, providing the requested cache mode.
+/// Module implementation should determine what level of caching it can support for this item,
+/// considering factors such as server lease availability, file locking state, or other coherency requirements.
+///
+/// The granted coherency type must be compatible with the requested cache mode, as defined
+/// by the cache mode to coherency type mappings documented in this protocol. If the module grants
+/// a coherency type that exceeds the cache mode's permissions, the kernel will use downgraded valid coherency type.
+///
+/// - Parameters:
+/// - item: The item to open.
+/// - modes: The open modes (read, write, etc.).
+/// - cacheMode: The requested cache mode indicating what data can be cached.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If opening succeeds, pass an instance of ``FSOpenItemResult`` containing the granted ``FSKernelCacheCoherencyType``, along with a `nil` error. If opening fails, pass the relevant error as the second parameter; FSKit ignores the ``FSOpenItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)openItem:(FSItem *)item
+ modes:(FSVolumeOpenModes)modes
+ cacheMode:(FSDataCacheMode)cacheMode
+ context:(FSContext *)context
+ replyHandler:(void (^)(FSOpenItemResult * _Nullable result,
+ NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(open(_:modes:cacheMode:context:replyHandler:))
+FSKIT_API_AVAILABILITY_V3;
+
+/// Closes an item and releases associated cache resources.
+///
+/// FSKit calls this method when a file is being fully closed and all caching for the item
+/// has been finalized by the kernel.
+///
+/// This method is called once per item when all references are released and the kernel
+/// has completed its cache management. The module should perform any necessary cleanup
+/// operations for the item.
+///
+/// Note: This method has no error return because the OS considers the file closed regardless
+/// of whether the module encounters any issues during cleanup.
+///
+/// - Parameters:
+/// - item: The item to close.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to call when the close operation completes.
+- (void)closeItem:(FSItem *)item
+ context:(FSContext *)context
+ replyHandler:(void (^)(void))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(close(_:context:replyHandler:))
+FSKIT_API_AVAILABILITY_V3;
+
+/// Upgrades the item cache mode to a less restrictive level, allowing more caching.
+///
+/// FSKit calls this method when transitioning to a cache mode that allows more aggressive caching.
+///
+/// - Parameters:
+/// - item: The item for which to upgrade the cache mode.
+/// - cacheMode: The new (more permissive) cache mode being requested.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If successful, pass an instance of ``FSUpgradeItemResult`` containing the granted ``FSKernelCacheCoherencyType``, along with a `nil` error. If upgrading fails, pass the relevant error as the second parameter; FSKit ignores the ``FSUpgradeItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)upgradeItem:(FSItem *)item
+ cacheMode:(FSDataCacheMode)cacheMode
+ context:(FSContext *)context
+ replyHandler:(void (^)(FSUpgradeItemResult * _Nullable result,
+ NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(upgrade(_:cacheMode:context:replyHandler:))
+FSKIT_API_AVAILABILITY_V3;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h 2026-04-27 23:47:02
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h 2026-05-27 04:50:10
@@ -18,6 +18,8 @@
#import <Foundation/Foundation.h>
#import <FSKit/FSResource.h>
#import <FSKit/FSVolume.h>
+#import <FSKit/FSVolumeHandlerResult.h>
+#import <FSKit/FSContext.h>
NS_ASSUME_NONNULL_BEGIN
@@ -73,6 +75,11 @@
///
/// Only use this extent type in file systems that support sparse files, and only then to represent ranges in the file that aren't allocated yet.
FSExtentTypeZeroFill = 1,
+
+ /// An extent type to indicate read-only data.
+ ///
+ /// Use this type to represent ranges in the file that data can be read but not written to.
+ FSExtentTypeReadOnly FSKIT_API_AVAILABILITY_V3 = 2,
};
/// A type that directs the kernel to map space on disk to a specific file managed by this file system.
@@ -92,7 +99,7 @@
/// - type: The type of extent, indicating whether it contains valid data.
/// - logicalOffset: The extent offset within the file, in bytes.
/// - physicalOffset: The extent offset on disk, in bytes.
-/// - length: The extent length, in bytes.
+/// - length: The extent length, in bytes. The maximal valid length is `UINT32_MAX`.
/// - Returns: A Boolean value that indicates whether the packer can pack more extents.
- (BOOL)packExtentWithResource:(FSBlockDeviceResource *)resource
type:(FSExtentType)type
@@ -105,8 +112,8 @@
/// Methods and properties implemented by volumes that use kernel-offloaded I/O to achieve higher file transfer performance.
///
-/// A volume that conforms to this protocol supplies file extent mappings to FSKit, which allows file transfers to take place in the kernel.
-/// This approach provides higher-performance file transfer than transferring data between the module and kernel, while still allowing the file system to run in user space.
+/// A volume that conforms to this protocol supplies file extent mappings to FSKit, which allows file data transfers to take place in the kernel.
+/// This approach provides higher-performance data transfer than transferring all file data between the module and kernel, while still allowing the file system to run in user space.
///
/// This protocol uses _extents_ to provide the kernel the logical-to-physical mapping of a given file.
/// An extent describes a physical offset on disk, and a length and a logical offset within the file.
@@ -116,8 +123,8 @@
/// Most volumes conform to either this protocol or ``FSVolumeReadWriteOperations``.
/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use ``FSVolumeReadWriteOperations``, and those without it use this protocol.
-/// A volume that doesn't conform to either protocol can't support any I/O operation.
-FSKIT_API_AVAILABILITY_V1
+/// A volume that doesn't conform to either protocol can't support any file I/O operation.
+FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeKernelOffloadedIOHandler")
@protocol FSVolumeKernelOffloadedIOOperations <NSObject>
#pragma mark - Kernel Offloaded IO operations
@@ -125,9 +132,9 @@
/// Maps a file's disk space into extents, allowing the kernel to perform I/O with that space.
///
/// FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file's data.
-/// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of a `fcntl(F_LOG2PHYS)` system call.
+/// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of an `fcntl(F_LOG2PHYS)` system call.
/// In the case of an I/O operation on the file, `operationID` has a nonzero value; a future call to ``completeIO(for:offset:length:status:flags:operationID:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
-/// In the case of a `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
+/// In the case of an `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
/// In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.
///
/// If satisfying a blockmap request requires more extents than `packer` can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.
@@ -249,6 +256,163 @@
replyHandler:(void(^)(size_t bytesAllocated,
NSError * _Nullable error))reply
NS_SWIFT_NAME(preallocateSpace(for:at:length:flags:packer:replyHandler:));
+
+@end
+
+
+/// Methods and properties implemented by volumes that use kernel-offloaded I/O to achieve higher file transfer performance.
+///
+/// A volume that conforms to this protocol supplies file extent mappings to FSKit, which allows file data transfers to take place in the kernel.
+/// This approach provides higher-performance data transfer than transferring all file data between the module and kernel, while still allowing the file system to run in user space.
+///
+/// This protocol uses _extents_ to provide the kernel the logical-to-physical mapping of a given file.
+/// An extent describes a physical offset on disk, and a length and a logical offset within the file.
+/// You don't manage extents directly.
+/// Instead, FSKit provides you with an ``FSExtentPacker`` to define and pack the extents in your implementations of this protocol's methods.
+///
+/// Most volumes conform to either this protocol or ``FSVolumeReadWriteHandler``.
+/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
+/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use ``FSVolumeReadWriteHandler``, and those without it use this protocol.
+/// A volume that doesn't conform to either protocol can't support any file I/O operation.
+///
+/// > Important: This protocol replaces the ``FSVolumeKernelOffloadedIOOperations`` protocol. It exposes the same functionality, while using ``FSVolumeHandlerResult`` objects. These objects add the ability to reply with ``FSItemAttributes`` and free space from the relevant methods.
+FSKIT_API_AVAILABILITY_V3
+NS_SWIFT_NAME(FSVolume.KernelOffloadedIOHandler)
+@protocol FSVolumeKernelOffloadedIOHandler <NSObject>
+
+#pragma mark - Kernel Offloaded IO operations
+
+/// Maps a file's disk space into extents, allowing the kernel to perform I/O with that space.
+///
+/// FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file's data.
+/// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of an `fcntl(F_LOG2PHYS)` system call.
+/// In the case of an I/O operation on the file, `operationID` has a nonzero value; a future call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
+/// In the case of an `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
+/// In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.
+///
+/// If satisfying a blockmap request requires more extents than `packer` can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.
+///
+/// - Parameters:
+/// - file: The file for which to map disk space.
+/// - offset: The starting logical offset of the range to be mapped (in bytes).
+/// - length: The length of the range to be mapped (in bytes).
+/// - flags: Flags that affect the behavior of the blockmap operation.
+/// - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) indicates the beginning of an I/O operation. A value of `0` or ``FSOperationID/unspecified`` indicates the kernel maps the file without performing I/O. In this case, FSKit doesn't perform a corresponding call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)``.
+/// - packer: An extent packer you use to pack the requested range of the file's allocated disk space. FSKit sends all of the packed extents to the kernel when it invokes `reply`.
+/// - reply: A block or closure to indicate success or failure. If mapping succeeds, pass an instance of ``FSBlockmapResult`` containing the volume's updated free space, along with a `nil` error. If mapping fails, pass the relevant error as the second parameter; FSKit ignores the ``FSBlockmapResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)blockmapFile:(FSItem *)file
+ offset:(off_t)offset
+ length:(size_t)length
+ flags:(FSBlockmapFlags)flags
+ operationID:(FSOperationID)operationID
+ packer:(FSExtentPacker *)packer
+ replyHandler:(void (^)(FSBlockmapResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply;
+
+/// Completes an I/O operation for a given file.
+///
+/// Implement this method by updating a file's metadata, such as its size and modification time.
+///
+/// FSKit may call this method without an earlier call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// In this case, the `operationID` is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
+///
+/// - Parameters:
+/// - file: The file for which the I/O operation completed.
+/// - offset: The starting logical offset at which I/O started.
+/// - length: The length of the I/O range (in bytes).
+/// - status: Any error that occurred during the operation. If no error occurred, this parameter is `nil`.
+/// - flags: Flags that affect the behavior of the complete I/O operation.
+/// - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) corresponds to a previous call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)`` with the same `operationID`.
+/// - attributes: The desired set of attributes to provide with the reply.
+/// - reply: A block or closure to indicate success or failure. If completing I/O succeeds, pass an instance of ``FSCompleteIOResult`` containing the updated ``FSItemAttributes`` of the file, along with a `nil` error. If completing I/O fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCompleteIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)completeIOForFile:(FSItem *)file
+ offset:(off_t)offset
+ length:(size_t)length
+ status:(NSError *)status
+ flags:(FSCompleteIOFlags)flags
+ operationID:(FSOperationID)operationID
+ replyHandler:(void (^)(FSCompleteIOResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(completeIO(for:offset:length:status:flags:operationID:replyHandler:));
+
+#pragma mark - extent-supplying versions of create and lookup
+/*
+ * These methods allow the module to opportunistically supply extents in order
+ * to save future 'blockmapFile' calls. An implementation not supplying the
+ * extents can ignore the packer, and call the corresponding FSVolumeOperation's
+ * method.
+ */
+
+/// Creates a new file item and map its disk space.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// Only perform this technique opportunistically.
+/// In particular, don't perform additional I/O to fetch extent data.
+///
+/// Packing extents in this method requires that `attributes` defines a size greater than 0.
+///
+/// An implementation that doesn't supply the extents can ignore the packer and call the corresponding method in the ``FSVolume/Handler`` protocol, ``FSVolume/Handler/createItem(named:type:in:attributes:providing:replyHandler:)``.
+///
+/// - Parameters:
+/// - name: The new file's name.
+/// - directory: The directory in which to create the file.
+/// - newAttributes: Attributes to apply to the new file.
+/// - packer: An extent packer you use to pack the file's allocated disk space.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass an instance of ``FSCreateFileKOIOResult`` containing the newly-created ``FSItem``, its ``FSFileName``, its ``FSItemAttributes``, the updated ``FSItemAttributes`` of the parent directory, the volume's update free space, along with a `nil` error. If creation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCreateFileKOIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)createFileNamed:(FSFileName *)name
+ inDirectory:(FSItem *)directory
+ attributes:(FSItemSetAttributesRequest *)newAttributes
+ packer:(FSExtentPacker *)packer
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSCreateFileKOIOResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(createFile(named:in:attributes:packer:context:replyHandler:));
+
+/// Looks up an item within a directory and maps its disk space.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// Only perform this technique opportunistically.
+/// In particular, don't perform additional I/O to fetch extent data.
+///
+/// - Parameters:
+/// - name: The name of the file to look up.
+/// - directory: The directory in which to look up the file.
+/// - attributes: The desired set of attributes to provide with the reply.
+/// - packer: An extent packer you use to pack the file's allocated disk space.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If lookup succeeds, pass an instance of ``FSLookupItemKOIOResult`` containing the found ``FSItem`` together with its ``FSFileName`` (as saved within the file system) and its ``FSItemAttributes``, along with a `nil` error. If lookup fails, pass the relevant error as the second parameter; FSKit ignores the ``FSLookupItemKOIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)lookupItemNamed:(FSFileName *)name
+ inDirectory:(FSItem *)directory
+ packer:(FSExtentPacker *)packer
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSLookupItemKOIOResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(lookupItem(named:in:packer:context:replyHandler:));
+
+#pragma mark - extent-supplying version of preallocate
+
+@optional
+
+/// Preallocates and maps disk space for the given file.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+///
+/// > Important: Only implement this method if your file system conforms to ``FSVolume/PreallocateHandler``.
+///
+/// - Parameters:
+/// - file: The item for which to preallocate space.
+/// - offset: The offset from which to allocate.
+/// - length: The length of the space in bytes.
+/// - flags: Flags that affect the preallocation behavior.
+/// - attributes: The desired set of attributes to provide with the reply.
+/// - packer: An extent packer you use to pack the file's preallocated disk space.
+/// - context: An object that enables context-aware file system decisions throughout the operation.
+/// - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass an instance of ``FSPreallocateKOIOResult`` containing the amount of bytes allocated, the updated ``FSItemAttributes`` of the file, the volume's update free space, along with a `nil` error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSPreallocateKOIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
+- (void)preallocateSpaceForFile:(FSItem *)file
+ atOffset:(off_t)offset
+ length:(size_t)length
+ flags:(FSPreallocateFlags)flags
+ packer:(FSExtentPacker *)packer
+ context:(FSContext *)context
+ replyHandler:(void(^)(FSPreallocateKOIOResult * _Nullable result, NSError * _Nullable error))FSKIT_CALLED_ONCE reply
+NS_SWIFT_NAME(preallocateSpace(for:at:length:flags:packer:context:replyHandler:));
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeHandlerResult.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeHandlerResult.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeHandlerResult.h 1969-12-31 19:00:00
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeHandlerResult.h 2026-05-27 04:50:09
@@ -0,0 +1,555 @@
+//
+// FSVolumeHandlerResult.h
+// FSKit
+//
+// Copyright (c) 2025 Apple Inc. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+#import <FSKit/FSKitDefines.h>
+#import <FSKit/FSItem.h>
+#import <FSKit/FSFileName.h>
+#import <FSKit/FSFreeSpace.h>
+
+/// Redeclaration to avoid circular dependency. Originally declared in ``FSVolume.h``.
+typedef uint64_t FSDirectoryVerifier;
+
+/// Redeclaration to avoid circular dependency. Originally declared in ``FSVolumeDataCacheHandler.h``.
+typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyType);
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Abstract base class for all result objects in FSKit `Handler` protocols.
+///
+/// This class provides the common functionality needed for all result objects. All specialized result classes inherit from this base class.
+FSKIT_API_AVAILABILITY_V3
+@interface FSVolumeHandlerResult : NSObject
+
+/// The set of attributes that FSKit requires the file system module to populate in the ``FSItem/Attributes`` instances.
+///
+/// > Note: Different operations may require different attribute sets. Access this property through the relevant result subclass (e.g., `FSLookupItemResult.requestedAttributes`).
+///
+/// > Note: Incomplete population of requested attributes results in undefined behavior. All populated attributes are cached by FSKit and may be used in subsequent operations, regardless of whether they were explicitly requested.
+@property (nonatomic, class, strong, readonly) FSItemGetAttributesRequest *requestedAttributes;
+
+@end
+
+#pragma mark - FSVolumeHandler Result Classes
+
+/// Result class for ``FSVolume/Handler/activate(options:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSActivateResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - rootItem: The root ``FSItem`` of the volume.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithRootItem:(FSItem *)rootItem
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(rootItem:));
+
+/// Unavailable - use ``init(rootItem:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/lookupItem(named:in:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSLookupItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - foundItem: The ``FSItem`` that was found in the directory lookup.
+/// - itemName: The item's name as it exists within the file system. This may differ from the requested name to handle case-insensitive file systems or Unicode normalization.
+/// - itemAttributes: The ``FSItemAttributes`` of the found item.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithFoundItem:(FSItem *)foundItem
+ itemName:(FSFileName *)itemName
+ itemAttributes:(FSItemAttributes *)itemAttributes
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(foundItem:itemName:itemAttributes:));
+
+/// Unavailable - use ``init(foundItem:itemName:itemAttributes:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/createItem(named:type:in:attributes:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCreateItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - newItem: The newly-created ``FSItem``.
+/// - newItemName: The name of the newly-created item as it exists within the file system.
+/// - newItemAttributes: The ``FSItemAttributes`` of the newly-created item.
+/// - directoryAttributes: The updated ``FSItemAttributes`` of the parent directory.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithNewItem:(FSItem *)newItem
+ newItemName:(FSFileName *)newItemName
+ newItemAttributes:(FSItemAttributes *)newItemAttributes
+ directoryAttributes:(FSItemAttributes *)directoryAttributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(newItem:newItemName:newItemAttributes:directoryAttributes:freeSpace:));
+
+/// Unavailable - use ``init(newItem:newItemName:newItemAttributes:directoryAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/createSymbolicLink(named:in:attributes:linkContents:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCreateSymlinkResult : FSCreateItemResult
+@end
+
+/// Result class for ``FSVolume/Handler/createLink(to:named:in:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCreateLinkResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - linkName: The name of the newly-created hard link.
+/// - linkAttributes: The ``FSItemAttributes`` of the linked item (the target of the hard link).
+/// - directoryAttributes: The updated ``FSItemAttributes`` of the parent directory.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithLinkName:(FSFileName *)linkName
+ linkAttributes:(FSItemAttributes *)linkAttributes
+ directoryAttributes:(FSItemAttributes *)directoryAttributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(linkName:linkAttributes:directoryAttributes:freeSpace:));
+
+/// Unavailable - use ``init(linkName:linkAttributes:directoryAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/renameItem(_:inDirectory:named:to:inDirectory:overItem:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSRenameItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - newName: The updated item name as it exists within the destination directory.
+/// - renamedItemAttributes: The ``FSItemAttributes`` of the renamed item.
+/// - sourceDirectoryAttributes: The updated ``FSItemAttributes`` of the source directory.
+/// - destinationDirectoryAttributes: The updated ``FSItemAttributes`` of the destination directory.
+/// - overItemAttributes: The ``FSItemAttributes`` of the overwritten item, if any. Pass `nil` if no item was overwritten.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithNewName:(FSFileName *)newName
+ renamedItemAttributes:(FSItemAttributes *)renamedItemAttributes
+ sourceDirectoryAttributes:(FSItemAttributes *)sourceDirectoryAttributes
+ destinationDirectoryAttributes:(FSItemAttributes *)destinationDirectoryAttributes
+ overItemAttributes:(FSItemAttributes * _Nullable)overItemAttributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(newName:renamedItemAttributes:sourceDirectoryAttributes:destinationDirectoryAttributes:overItemAttributes:freeSpace:));
+
+/// Unavailable - use ``init(newName:renamedItemAttributes:sourceDirectoryAttributes:destinationDirectoryAttributes:overItemAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for``FSVolume/Handler/removeItem(_:named:from:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSRemoveItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - itemAttributes: The ``FSItemAttributes`` of the removed item.
+/// - directoryAttributes: The updated ``FSItemAttributes`` of the parent directory.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithItemAttributes:(FSItemAttributes *)itemAttributes
+ directoryAttributes:(FSItemAttributes *)directoryAttributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(itemAttributes:directoryAttributes:freeSpace:));
+
+/// Unavailable - use ``init(itemAttributes:directoryAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/getAttributes(_:of:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSGetAttributesResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - attributes: The requested ``FSItemAttributes`` for the item.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithAttributes:(FSItemAttributes *)attributes
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(attributes:));
+
+/// Unavailable - use ``init(attributes:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/setAttributes(_:on:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSSetAttributesResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - attributes: The updated ``FSItemAttributes`` for the item.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithAttributes:(FSItemAttributes *)attributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(attributes:freeSpace:));
+
+/// Unavailable - use ``init(attributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSEnumerateDirectoryResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - currentVerifier: An ``FSDirectoryVerifier`` value that reflects the directory's current version. This value is used to detect whether the directory contents changed since the last enumeration call.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithVerifier:(FSDirectoryVerifier)currentVerifier
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(verifier:));
+
+/// Unavailable - use ``init(verifier:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/Handler/readSymbolicLink(_:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSReadSymlinkResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - contents: The contents of the symbolic link.
+/// - attributes: The ``FSItemAttributes`` of the symbolic link.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithContents:(FSFileName *)contents
+ symlinkAttributes:(FSItemAttributes *)attributes
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(contents:symlinkAttributes:));
+
+/// Unavailable - use ``init(contents:symlinkAttributes:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeXattrHandler Result Classes
+
+/// Result class for ``FSVolume/XattrHandler/getXattr(named:of:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSGetXattrResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - value: The extended attribute value for the requested attribute name.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithXattrValue:(NSData *)value
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(xattrValue:));
+
+/// Unavailable - use ``init(xattrValue:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/XattrHandler/setXattr(named:to:on:policy:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSSetXattrResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithFreeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(freeSpace:));
+
+/// Unavailable - use ``init(freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/XattrHandler/xattrs(of:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSListXattrsResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - xattrNames: An array of ``FSFileName`` instances representing the names of all extended attributes currently set on the item.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithXattrNames:(NSArray<FSFileName *> *)xattrNames
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(xattrNames:));
+
+/// Unavailable - use ``init(xattrNames:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeReadWriteHandler Result Classes
+
+/// Result class for ``FSVolume/ReadWriteHandler/read(from:at:length:into:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSReadFileResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - actuallyRead: The number of bytes actually read from the file. This may be less than the requested length if the end of file was reached.
+/// - attributes: The updated ``FSItemAttributes`` of the file after the read operation (e.g., updated access time).
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithBytesRead:(size_t)actuallyRead
+ itemAttributes:(FSItemAttributes *)attributes
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(bytesRead:itemAttributes:));
+
+/// Unavailable - use ``init(bytesRead:itemAttributes:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/ReadWriteHandler/write(contents:to:at:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSWriteFileResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - actuallyWritten: The number of bytes actually written to the file. This should match the requested write length unless an error occurred.
+/// - attributes: The updated ``FSItemAttributes`` of the file after the write operation (e.g., updated size, modification time).
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithBytesWritten:(size_t)actuallyWritten
+ itemAttributes:(FSItemAttributes *)attributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(bytesWritten:itemAttributes:freeSpace:));
+
+/// Unavailable - use ``init(bytesWritten:itemAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeAccessCheckHandler Result Classes
+
+/// Result class for ``FSVolume/AccessCheckHandler/checkAccess(to:requestedAccess:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCheckAccessResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - accessAllowed: A Boolean value indicating whether the file system grants the requested access to the item. Pass `YES` to allow access, `NO` to deny access.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithAccessAllowed:(BOOL)accessAllowed
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(accessAllowed:));
+
+/// Unavailable - use ``init(accessAllowed:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeRenameHandler Result Classes
+
+/// Result class for ``FSVolume/RenameHandler/setVolumeName(_:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSVolumeRenameResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - newName: The new volume name.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithNewName:(FSFileName *)newName
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(newName:));
+
+/// Unavailable - use ``init(newName:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumePreallocateHandler Result Classes
+
+/// Result class for ``FSVolume/PreallocateHandler/preallocateSpace(for:at:length:flags:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSPreallocateResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - bytesAllocated: The number of bytes actually allocated for the file during the preallocation operation.
+/// - attributes: The updated ``FSItemAttributes`` of the file after the preallocation operation.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithBytesAllocated:(size_t)bytesAllocated
+ itemAttributes:(FSItemAttributes *)attributes
+ freeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(bytesAllocated:itemAttributes:freeSpace:));
+
+/// Unavailable - use ``init(bytesAllocated:itemAttributes:freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeItemDeactivationHandler Result Classes
+
+/// Result class for ``FSVolume/ItemDeactivationHandler/deactivateItem(_:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSDeactivateItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithFreeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(freeSpace:));
+
+/// Unavailable - use ``init(freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeSeekRegionHandler Result Classes
+
+/// Result class for ``FSVolume/SeekRegionHandler/seek(within:from:region:context:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSSeekRegionResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - returnedOffset: The offset of the requested region (greater than or equal to the supplied offset).
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype)initWithReturnedOffset:(off_t)returnedOffset
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(returnedOffset:));
+
+/// Unavailable - use ``init(returnedOffset:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+#pragma mark - FSVolumeKernelOffloadedIOHandler Result Classes
+
+/// Result class for ``FSVolume/KernelOffloadedIOHandler/blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSBlockmapResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space will cause FSKit to calculate the free space when the operation is done, based on the volume's ``FSVolume/Handler/volumeStatistics`` property. This behavior may lead to degraded performance.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithFreeSpace:(FSFreeSpace * _Nullable)freeSpace
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(freeSpace:));
+
+/// Unavailable - use ``init(freeSpace:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/KernelOffloadedIOHandler/completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCompleteIOResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - attributes: The updated ``FSItemAttributes`` of the file after the I/O completion operation (e.g., updated size, modification time).
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype _Nullable)initWithAttributes:(FSItemAttributes *)attributes
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(itemAttributes:));
+
+/// Unavailable - use ``init(itemAttributes:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/KernelOffloadedIOHandler/createFile(named:in:attributes:packer:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSCreateFileKOIOResult : FSCreateItemResult
+@end
+
+/// Result class for ``FSVolume/KernelOffloadedIOHandler/lookupItem(named:in:packer:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSLookupItemKOIOResult : FSLookupItemResult
+@end
+
+/// Result class for ``FSVolume/KernelOffloadedIOHandler/preallocateSpace(for:at:length:flags:packer:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSPreallocateKOIOResult : FSPreallocateResult
+@end
+
+#pragma mark - FSVolumeDataCacheHandler Result Classes
+
+/// Result class for ``FSVolume/DataCacheHandler/open(_:modes:cacheMode:context:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSOpenItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - grantedCoherency: The ``FSKernelCacheCoherencyType`` granted by the module for this item.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype)initWithGrantedCoherency:(FSKernelCacheCoherencyType)grantedCoherency
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(grantedCoherency:));
+
+/// Unavailable - use ``init(grantedCoherency:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/// Result class for ``FSVolume/DataCacheHandler/upgrade(_:cacheMode:context:replyHandler:)``
+FSKIT_API_AVAILABILITY_V3
+@interface FSUpgradeItemResult : FSVolumeHandlerResult
+
+/// Creates a result instance with all required properties populated.
+///
+/// - Parameters:
+/// - grantedCoherency: The ``FSKernelCacheCoherencyType`` granted by the module after the upgrade.
+/// - Returns: A populated result instance, or `nil` if validation fails.
+- (instancetype)initWithGrantedCoherency:(FSKernelCacheCoherencyType)grantedCoherency
+NS_DESIGNATED_INITIALIZER
+NS_SWIFT_NAME(init(grantedCoherency:));
+
+/// Unavailable - use ``init(grantedCoherency:)`` instead.
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END