-
Notifications
You must be signed in to change notification settings - Fork 571
FSKit macOS xcode27.0 b2
Alex Soto edited this page Jun 23, 2026
·
2 revisions
#FSKit.framework
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSClient.h 2026-06-16 01:36:39
@@ -33,16 +33,17 @@
-(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
+/// Asynchronously mounts a single volume file system with a 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.
+/// This method allows a client with the `com.apple.developer.fskit.mount` entitlement to mount a single-volume file system.
+/// Calling this method performs the complete workflow of resource loading, volume activation, mount point creation, and actual mounting.
+/// The system mounts the volume 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
+/// - resource: The resource 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
@@ -53,7 +54,10 @@
/// Opens the File System Extensions settings in System Settings.
///
-/// - Returns: `YES` if the settings were successfully opened, `NO` otherwise.
+/// Calling this method allows someone using your app to navigate to the File System Extensions pane in System Settings.
+/// From this pane, they can view, enable, and disable file system extensions.
+///
+/// - Returns: `true` (Swift) or `YES` (Obj-C) if the settings were successfully opened; otherwise, `false` (Swift) or `NO`(Obj-C).
-(BOOL)openFileSystemExtensionsSettings FSKIT_API_AVAILABILITY_V3;
@end
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSContext.h 2026-06-16 01:36:39
@@ -13,12 +13,17 @@
/// 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.
+/// Use this context in handler methods that provide the context as a parameter.
FSKIT_API_AVAILABILITY_V3
@interface FSContext : NSObject
+/// The caller's real user ID.
@property (readonly) NSInteger realUserID;
+/// The caller's effective user ID.
@property (readonly) NSInteger effectiveUserID;
+/// The caller's real group ID.
@property (readonly) NSInteger realGroupID;
+/// The caller's effective group ID.
@property (readonly) NSInteger effectiveGroupID;
- (instancetype)init NS_UNAVAILABLE;
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSFreeSpace.h 2026-06-16 01:36:39
@@ -19,11 +19,11 @@
/// 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.
+/// > Important: FSKit uses internal sequencing technology within this method to determine the most up-to-date free space of the volume. To ensure correctness, call this method 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.
+/// A sentinel instance that indicates no free space update occurred.
@property (class, readonly) FSFreeSpace *noUpdate;
@end
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h 2026-06-16 01:36:39
@@ -110,35 +110,63 @@
FSKIT_API_AVAILABILITY_V1
@interface FSItem : NSObject
-/// Reclaims the `FSItem`, by executing the given `reclaimBlock`, only if conditions allow.
+/// Reclaims the item by executing the given block, if conditions allow.
///
-/// Should be invoked by the file system during the ``FSVolume/Handler/reclaimItem(_:replyHandler:)`` operation.
+/// Invoke this method in your implementation of 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.
+/// FSKit internally maintains a count of how many times it returns each ``FSItem`` to the kernel, via either a creation operation or a lookup. The kernel file system also maintains a count of how many times a create or a lookup operation returned a vnode. When the kernel reclaims the vnode associated with an FSItem, the FSItem is only eligible for reclaiming when both the kernel and user space counts agree.
+/// This mechanism addresses a potential race condition in which concurrent reclaim and lookup operations might lead to a lookup returning a deallocated ``FSItem``, and as a result, induce undefined behavior.
+/// File systems that don't invoke this method during reclaim are exposed to this race condition.
///
-/// > Important: The caller must invoke this method within a synchronization context that ensures the FSItem is not concurrently returned by lookup operations.
+/// > Important: The caller must invoke this method within a synchronization context that ensures the ``FSItem`` isn't 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.
+/// - reclaimBlock The closure or block to run if the reclaim can proceed. In your closure or block, 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)`.
+/// - Returns: `true` (Swift) or YES (Obj-C) if the reclaim block ran; otherwise, `false` (Swift) or `NO` (Obj-C). When your ``FSVolume/Handler/reclaimItem(_:replyHandler:)`` implementation receives a `false`/`NO` return value, call `replyHandler(nil)`.
///
/// Example Usage:
///
+///@TabNavigator {
+/// @Tab("Swift") {
+///```swift
+/// func reclaimItem(_ item: FSItem,
+/// replyHandler reply: @escaping @Sendable ((any Error)?) -> Void) {
+/// var reclaimError: NSError? = nil // To be set during the reclaim block in case of an error.
+///
+/// // *** CRITICAL SECTION BEGINS HERE ***
+/// // (A synchronization context that ensures the FSItem isn't concurrently returned by lookup operations)
+///
+/// // Calling `tryReclaim(_:)` with the cleanup logic within the passed block
+/// let wasReclaimed = item.tryReclaim( {
+/// // Closure 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 wasn't reclaimed, so it's not yet time to run cleanup.
+/// reply(nil)
+/// }
+///}
+///```
+/// }
+/// @Tab("Objective-C") {
/// ```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
+/// __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)
+/// // (A synchronization context that ensures the FSItem isn't concurrently returned by lookup operations)
///
/// // Calling `tryReclaimWithBlock:` with the cleanup logic within the passed block
-/// BOOL wasReclaimed = [self tryReclaimWithBlock:^{
+/// BOOL wasReclaimed = [item tryReclaimWithBlock:^{
/// // Includes all required cleanup operations for reclaiming this item.
/// // Sets `reclaimError` in case of an error during the cleanup phase
/// }];
@@ -149,11 +177,13 @@
/// // Clean up the FSItem if special teardown is needed.
/// reply(reclaimError);
/// } else {
-/// // Do nothing, the FSItem shouldn't get deallocated yet.
+/// // Do nothing; the FSItem wasn't reclaimed, so it's not yet time to run cleanup.
/// reply(nil);
/// }
/// }
/// ```
+/// }
+/// }
- (BOOL)tryReclaimWithBlock:(void(^)(void))reclaimBlock FSKIT_API_AVAILABILITY_V3;
@end
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h 2026-05-27 04:50:10
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h 2026-06-16 01:36:40
@@ -145,6 +145,8 @@
/// These protocols add support for checking, repairing, and optionally formatting file systems.
/// The system doesn't mount block device file systems until they pass a file system check.
/// For an ``FSUnaryFileSystem`` that uses `FSBlockDeviceResource`, conform to `FSManageableResourceMaintenanceOperations`.
+///
+/// > Important: Don't mix direct I/O operations (``read(into:startingAt:length:)`` and ``write(from:startingAt:length:)``) with metadata operations (``metadataRead(into:startingAt:length:)``, ``metadataWrite(from:startingAt:length:)``, and ``delayedMetadataWrite(from:startingAt:length:)``) on the same range. Direct I/O bypasses the buffer cache, so mixing the two may result in stale or inconsistent data.
FSKIT_API_AVAILABILITY_V1
@interface FSBlockDeviceResource : FSResource
@@ -248,7 +250,7 @@
/// For the read to succeed, requests must conform to any transfer requirements of the underlying resource.
/// Disk drives typically require sector (`physicalBlockSize`) addressed operations of one or more sector-aligned offsets.
///
-/// This method doesn't support partial reading of metadata.
+/// > Important: The Kernel Buffer Cache is keyed by offset alone and doesn't detect overlapping byte ranges between buffers. As a result, the byte ranges of any two metadata operations must never intersect. All accesses to a given disk region must use the same (offset, length) pair.
///
/// - Parameters:
/// - buffer: A buffer to receive the data.
@@ -270,7 +272,7 @@
/// For the write to succeed, requests must conform to any transfer requirements of the underlying resource.
/// Disk drives typically require sector (`physicalBlockSize`) addressed operations of one or more sector-aligned offsets.
///
-/// This method doesn't support partial writing of metadata.
+/// > Important: The Kernel Buffer Cache is keyed by offset alone and doesn't detect overlapping byte ranges between buffers. As a result, the byte ranges of any two metadata operations must never intersect. All accesses to a given disk region must use the same (offset, length) pair.
///
/// - Parameters:
/// - buffer: A buffer to provide the data.
@@ -299,7 +301,7 @@
/// For the write to succeed, requests must conform to any transfer requirements of the underlying resource.
/// Disk drives typically require sector (`physicalBlockSize`) addressed operations of one or more sector-aligned offsets.
///
-/// This method doesn't support partial writing of metadata.
+/// > Important: The Kernel Buffer Cache is keyed by offset alone and doesn't detect overlapping byte ranges between buffers. As a result, the byte ranges of any two metadata operations must never intersect. All accesses to a given disk region must use the same (offset, length) pair.
///
/// - Parameters:
/// - buffer: A buffer to provide the data.
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:10
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h 2026-06-16 01:36:40
@@ -25,7 +25,7 @@
/// A value that indicates a location in a directory from which to enumerate.
///
-/// Your implementation of ``FSVolume/Handler/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:context:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
FSKIT_API_AVAILABILITY_V1
typedef uint64_t FSDirectoryCookie NS_TYPED_EXTENSIBLE_ENUM;
@@ -85,7 +85,7 @@
/// An object used to provide items during a directory enumeration.
///
-/// You use this type in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``.
+/// You use this type in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:context: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.
@@ -96,13 +96,13 @@
/// Provides a directory entry during 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.
+/// You call this method in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:context: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/Handler/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:context: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
@@ -228,7 +228,7 @@
/// 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.
+/// Your volume can provide additional functionality by conforming to other volume handler protocols.
/// These protocols add support for operations like open and close, read and write, extended attribute (Xattr) manipulation, and more.
FSKIT_API_AVAILABILITY_V1
@interface FSVolume : NSObject
@@ -388,6 +388,8 @@
/// 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.
+///
+/// > Deprecated: Use ``FSVolume/Handler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeHandler")
NS_SWIFT_NAME(FSVolume.Operations)
@protocol FSVolumeOperations <NSObject, FSVolumePathConfOperations>
@@ -414,7 +416,7 @@
/// 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.
+/// FSKit reads this value after the volume replies to the ``mount(options:)`` call.
/// Changing the returned value during the runtime of the volume has no effect.
@property FSMountOptions requestedMountOptions FSKIT_API_AVAILABILITY_V2_4;
@@ -445,7 +447,7 @@
/// 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.
+/// FSKit unmounts any mounted volume with a call to ``unmount()`` prior to the deactivate callback.
///
/// - Parameters:
/// - options: Options to apply to the deactivation.
@@ -457,7 +459,7 @@
/// 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.
+/// Your file system receives a call to ``activate(options:)`` 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.
@@ -505,7 +507,7 @@
/// 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.
+/// FSKit guarantees that for every ``FSItem`` returned by the volume, a corresponding reclaim operation occurs after the upper layers no longer reference that item. To use this behavior, call ``FSItem/tryReclaim(_:)`` in your implementation of this method.
///
/// > 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.
///
@@ -607,7 +609,7 @@
/// - 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.
+/// - 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(_:)``. After doing so, ensure the operation finishes without errors.
/// - reply: A block or closure to indicate success or failure. If renaming succeeds, pass the ``FSFileName`` as it exists within `destinationDirectory` and a `nil` error. If renaming 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)renameItem:(FSItem *)item
inDirectory:(FSItem *)sourceDirectory
@@ -622,7 +624,7 @@
/// 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:)``.
+/// Remove and deallocate the item in ``reclaimItem(_:)``.
///
/// - Parameters:
/// - item: The item to remove.
@@ -843,7 +845,7 @@
/// 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.
+/// FSKit guarantees that for every ``FSItem`` returned by the volume, a corresponding reclaim operation occurs after the upper layers no longer reference that item. To use this behavior, call ``FSItem/tryReclaim(_:)`` in your implementation of this method.
///
/// > 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.
///
@@ -1080,6 +1082,8 @@
} NS_SWIFT_NAME(FSVolume.SetXattrPolicy);
/// Methods and properties implemented by volumes that natively or partially support extended attributes.
+///
+/// > Deprecated: Use ``FSVolume/XattrHandler``
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeXattrHandler")
NS_SWIFT_NAME(FSVolume.XattrOperations)
@protocol FSVolumeXattrOperations <NSObject>
@@ -1242,6 +1246,8 @@
/// 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.
+///
+/// > Deprecated: Use ``FSVolume/OpenCloseHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeOpenCloseHandler")
NS_SWIFT_NAME(FSVolume.OpenCloseOperations)
@protocol FSVolumeOpenCloseOperations <NSObject>
@@ -1334,6 +1340,8 @@
/// 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.
+///
+/// > Deprecated: Use ``FSVolume/ReadWriteHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeReadWriteHandler")
NS_SWIFT_NAME(FSVolume.ReadWriteOperations)
@protocol FSVolumeReadWriteOperations <NSObject>
@@ -1468,6 +1476,8 @@
} NS_SWIFT_NAME(FSVolume.AccessMask);
/// Methods and properties implemented by volumes that want to enforce access check operations.
+///
+/// > Deprecated: Use ``FSVolume/AccessCheckHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeAccessCheckHandler")
NS_SWIFT_NAME(FSVolume.AccessCheckOperations)
@protocol FSVolumeAccessCheckOperations <NSObject>
@@ -1527,6 +1537,8 @@
/// Methods and properties implemented by volumes that support renaming the volume.
+///
+/// > Deprecated: Use ``FSVolume/RenameHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeRenameHandler")
NS_SWIFT_NAME(FSVolume.RenameOperations)
@protocol FSVolumeRenameOperations <NSObject>
@@ -1593,7 +1605,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/PreallocateHandler/preallocateSpace(for:at:length:flags:replyHandler:)`` calls.
+ /// This flag is currently set for all ``FSVolume/PreallocateHandler/preallocateSpace(for:at:length:flags:context:replyHandler:)`` calls.
FSPreallocateFlagsFromEOF = 0x00000010,
} NS_SWIFT_NAME(FSVolume.PreallocateFlags);
@@ -1605,6 +1617,8 @@
/// 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)`.
+///
+/// > Deprecated: Use ``FSVolume/PreallocateHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumePreallocateHandler")
NS_SWIFT_NAME(FSVolume.PreallocateOperations)
@protocol FSVolumePreallocateOperations <NSObject>
@@ -1645,7 +1659,7 @@
///
/// 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:)``.
+/// > 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:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
NS_SWIFT_NAME(FSVolume.PreallocateHandler)
@protocol FSVolumePreallocateHandler <NSObject>
@@ -1680,7 +1694,7 @@
/// Options to specify the item deactivation policy.
///
-/// Callers may want to set a deactivation policy because ``FSVolume/ItemDeactivation/deactivateItem(_:replyHandler:)`` processing blocks the kernel.
+/// Callers may want to set a deactivation policy because ``FSVolume/ItemDeactivation/deactivateItem(_:)`` processing blocks the kernel.
/// Setting a deactivation policy allows the file system to take action at a definitive point in the item's life cycle.
/// These options allow the file system to instruct the FSKit kernel of which circumstances require the expense of a round-trip call to the module.
///
@@ -1718,7 +1732,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 with an item.
-/// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Operations/reclaimItem(_:replyHandler:)``.
+/// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Operations/reclaimItem(_:)``.
/// 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``.
@@ -1734,7 +1748,7 @@
/// 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:)``.
+/// > 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(_:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
NS_SWIFT_NAME(FSVolume.ItemDeactivationHandler)
@protocol FSVolumeItemDeactivationHandler <NSObject>
@@ -1821,10 +1835,10 @@
/// 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``
+/// When downgrading coherency type, the action must be ``FSVolume/KernelCacheCoherencyAction/push``,
+/// ``FSVolume/KernelCacheCoherencyAction/pushInvalidate``, or ``FSVolume/KernelCacheCoherencyAction/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.
+/// If the action fails, the cache state remains unchanged and the method returns an error.
///
/// > 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,
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeDataCacheHandler.h 2026-06-16 01:36:39
@@ -14,47 +14,47 @@
@class FSItem;
-/// FSDataCacheMode defines the cache mode requested by the kernel for data operations.
+/// A type that defines the cache mode requested by the kernel for data operations.
FSKIT_API_AVAILABILITY_V3
typedef NS_ENUM(NSInteger, FSDataCacheMode) {
- /// No active caching.
+ /// A mode that indicates no active caching.
FSDataCacheModeNone = 0,
- /// Read access with caching enabled.
+ /// A mode that indicates read access with caching enabled.
FSDataCacheModeReadWithCache,
- /// Read-write access with caching enabled.
+ /// A mode that indicates read-write access with caching enabled.
FSDataCacheModeReadWriteWithCache
} NS_SWIFT_NAME(FSVolume.DataCacheMode);
-/// FSKernelCacheCoherencyType defines how data is cached by the kernel.
+/// A type that defines how the kernel caches data.
FSKIT_API_AVAILABILITY_V3
typedef NS_ENUM(NSInteger, FSKernelCacheCoherencyType) {
- /// No caching - all I/O goes directly to storage.
+ /// A type that indicates all I/O goes directly to storage, without caching.
FSKernelCacheCoherencyTypeNoCache = 0,
- /// Cache only reads, writes bypass cache and go directly to storage.
+ /// A type that indicates that writes bypass the cache and go directly to storage.
FSKernelCacheCoherencyTypeReadCache,
- /// Write-through caching: writes update both cache and storage synchronously.
+ /// A type that indicates writes update cache and storage synchronously.
FSKernelCacheCoherencyTypeWriteThrough,
- /// Write-back caching: writes update cache only, deferred write to storage.
+ /// A type that indicates writes immediately update the cache only, followed by a deferred write to storage.
FSKernelCacheCoherencyTypeWriteBack
} NS_SWIFT_NAME(FSVolume.KernelCacheCoherencyType);
-/// FSKernelCacheCoherencyAction defines actions for cache state changes.
+/// A type that 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).
+ /// An action to flush dirty data from cache to storage, preserving cache contents.
FSKernelCacheCoherencyActionPush = 0,
- /// Flush dirty data to storage and invalidate (clear) the cache.
+ /// An action to flush dirty data to storage and invalidate (clear) the cache.
FSKernelCacheCoherencyActionPushInvalidate,
- /// Invalidate (clear) cache, discarding any dirty data without writing to storage.
+ /// An action to invalidate (clear) the cache, discarding any dirty data without writing to storage.
FSKernelCacheCoherencyActionInvalidate,
- /// Update coherency mode while keeping cache valid (no push/invalidate required).
+ /// An action to update the coherency mode while keeping the cache valid, requiring no push or invalidation.
FSKernelCacheCoherencyActionUpdate,
- /// Invalidate all caches, revoke all access to the item, and trigger vnode reclamation.
+ /// An action to 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
+ /// Use this action when the module determines that an item no longer exists or
+ /// is no longer accessible. Common scenarios include:
+ /// - Another client deleted the item, as detected via server notification.
+ /// - The module received a server callback indicating the file's absence.
FSKernelCacheCoherencyActionRevoke
} NS_SWIFT_NAME(FSVolume.KernelCacheCoherencyAction);
@@ -63,45 +63,54 @@
/// 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
+/// When a file opens, the module receives the requested ``FSVolume/DataCacheMode`` and returns a
+/// ``FSVolume/KernelCacheCoherencyType`` indicating the kind of 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
+/// The kernel requests a caching mode expressed as a ``FSVolume/DataCacheMode`` 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
+/// then replies with a specific ``FSVolume/KernelCacheCoherencyType`` 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
+/// lease break), the module uses a value from ``FSVolume/KernelCacheCoherencyAction`` 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
+/// is closed, enabling improved performance for frequently accessed files. The ``FSVolume/KernelCacheCoherencyType/readCache``,
+/// ``FSVolume/KernelCacheCoherencyType/writeThrough``, and ``FSVolume/KernelCacheCoherencyType/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``
+/// The following table shows the mapping of cache modes to supported coherency types.
///
-/// **Coherency Transition Rules:**
+/// | Cache mode | Coherency type |
+/// |------------|-----------------|
+/// | ``FSVolume/DataCacheMode/none`` | ``FSVolume/KernelCacheCoherencyType/noCache`` |
+/// | ``FSVolume/DataCacheMode/readWithCache`` | ``FSVolume/KernelCacheCoherencyType/noCache`` or ``FSVolume/KernelCacheCoherencyType/readCache`` |
+/// | ``FSVolume/DataCacheMode/readWriteWithCache`` | ``FSVolume/KernelCacheCoherencyType/noCache``, ``FSVolume/KernelCacheCoherencyType/readCache``, ``FSVolume/KernelCacheCoherencyType/writeBack`` or ``FSVolume/KernelCacheCoherencyType/writeThrough`` |
///
-/// 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
+/// ### Supporting coherency transitions
///
-/// 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
+/// Transitioning between coherency types requires different behaviors from your volume implementation, depending on whether the new type is more or less permissive than its current value.
+/// The following table expresses the permissiveness of the coherency types.
///
-/// > 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.
+/// | Coherency type | Permissiveness |
+/// |----------------|----------------|
+/// | ``FSVolume/KernelCacheCoherencyType/noCache`` | Least permissive |
+/// | ``FSVolume/KernelCacheCoherencyType/readCache`` | |
+/// | ``FSVolume/KernelCacheCoherencyType/writeBack`` | |
+/// | ``FSVolume/KernelCacheCoherencyType/writeThrough`` | Most permissive |
+///
+/// When transitioning to more permissive caching, kernel performs an "upgrade" by calling ``upgrade(_:cacheMode:context:replyHandler:)``.
+/// Your volume doesn't need to perform a flush or purge when upgrading to a more permissive coherency type.
+///
+/// Transitioning to a less permissive coherency type is considered a "downgrade".
+/// Your module initiates this process by calling ``FSVolume/setCacheState(for:cacheMode:coherencyType:action:)`` when conditions change.
+/// In this scenario, set the `action` to ``FSVolume/KernelCacheCoherencyAction/push``, ``FSVolume/KernelCacheCoherencyAction/pushInvalidate``, or ``FSVolume/KernelCacheCoherencyAction/invalidate``.
+/// Handle any dirty data by flushing or purging it before downgrading with this method call.
+///
+/// > Important: If a file system doesn't conform to this protocol, the kernel may still cache it.
+/// However, such a file system has 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>
@@ -117,20 +126,20 @@
/// 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,
+/// FSKit calls this method when opening a file, providing the requested cache mode.
+/// The module implementation determines 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.
+/// by the cache-mode-to-coherency-type mappings documented in the discussion of the ``FSVolume/DataCacheHandler`` protocol. If the module grants
+/// a coherency type that exceeds the cache mode's permissions, the kernel downgrades to a 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.
+/// - modes: The open modes, such as read and write.
+/// - cacheMode: The requested cache mode, indicating what data is eligible for caching.
/// - 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.
+/// - reply: A block or closure to indicate success or failure. If opening succeeds, pass an instance of ``FSOpenItemResult`` containing the granted ``FSVolume/KernelCacheCoherencyType``, 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
@@ -142,14 +151,13 @@
/// 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.
+/// FSKit calls this method when fully closing a file, and after the kernel finalizes all caching for the item.
///
-/// 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
+/// Your module receives this call once per item when all references are released and the kernel
+/// has completed its cache management. The module performs any necessary cleanup
/// operations for the item.
///
-/// Note: This method has no error return because the OS considers the file closed regardless
+/// > Note: This method doesn't return or throw an error because the OS considers the file closed regardless
/// of whether the module encounters any issues during cleanup.
///
/// - Parameters:
@@ -170,7 +178,7 @@
/// - 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.
+/// - reply: A block or closure to indicate success or failure. If successful, pass an instance of ``FSUpgradeItemResult`` containing the granted ``FSVolume/KernelCacheCoherencyType``, 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
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:10
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h 2026-06-16 01:36:40
@@ -124,6 +124,8 @@
/// 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 file I/O operation.
+///
+/// > Deprecated: Use ``FSVolume/KernelOffloadedIOHandler`` instead.
FSKIT_API_INTRODUCED_V1_DEPRECATED_V3_WITH_REPLACEMENT("FSVolumeKernelOffloadedIOHandler")
@protocol FSVolumeKernelOffloadedIOOperations <NSObject>
@@ -133,7 +135,7 @@
///
/// 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:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
+/// 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:)`` 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.
///
@@ -144,7 +146,7 @@
/// - 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:replyHandler:)``.
+/// - 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:)``.
/// - 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 fails, pass an error as the one parameter to the reply handler. If mapping succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
- (void)blockmapFile:(FSItem *)file
@@ -159,7 +161,7 @@
///
/// 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:)``.
+/// FSKit may call this method without an earlier call to ``blockmapFile(_:offset:length:flags:operationID:packer:)``.
/// In this case, the `operationID` is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
///
/// - Parameters:
@@ -168,7 +170,7 @@
/// - 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`.
+/// - 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:)`` with the same `operationID`.
/// - reply: A block or closure to indicate success or failure. If completing I/O fails, pass an error as the one parameter to the reply handler. If completing I/O succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
- (void)completeIOForFile:(FSItem *)file
offset:(off_t)offset
@@ -189,13 +191,13 @@
/// 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:)``.
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:)``.
/// 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/Operations`` protocol, ``FSVolume/Operations/createItem(named:type:inDirectory:attributes:replyHandler:)``.
+/// An implementation that doesn't supply the extents can ignore the packer and call the corresponding method in the ``FSVolume/Operations`` protocol, ``FSVolume/Operations/createItem(named:type:inDirectory:attributes:)``.
///
/// - Parameters:
/// - name: The new file's name.
@@ -214,7 +216,7 @@
/// 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:)``.
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:)``.
/// Only perform this technique opportunistically.
/// In particular, don't perform additional I/O to fetch extent data.
///
@@ -237,7 +239,7 @@
/// 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:)``.
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:)``.
///
/// > Important: Only implement this method if your file system conforms to ``FSVolume/PreallocateOperations``.
///
@@ -286,7 +288,7 @@
///
/// 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 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 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.
///
@@ -297,7 +299,7 @@
/// - 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:)``.
+/// - 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: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
@@ -322,7 +324,6 @@
/// - 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
@@ -349,7 +350,7 @@
///
/// 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:)``.
+/// 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:context:replyHandler:)``.
///
/// - Parameters:
/// - name: The new file's name.
@@ -375,7 +376,6 @@
/// - 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.
@@ -401,7 +401,6 @@
/// - 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.
diff -ruN /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_27.0.0-beta2.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 2026-05-27 04:50:09
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeHandlerResult.h 2026-06-16 01:36:39
@@ -11,7 +11,7 @@
#import <FSKit/FSFileName.h>
#import <FSKit/FSFreeSpace.h>
-/// Redeclaration to avoid circular dependency. Originally declared in ``FSVolume.h``.
+// Forward declaration to avoid circular dependency. Originally declared in `FSVolume.h`.
typedef uint64_t FSDirectoryVerifier;
/// Redeclaration to avoid circular dependency. Originally declared in ``FSVolumeDataCacheHandler.h``.
@@ -19,28 +19,32 @@
NS_ASSUME_NONNULL_BEGIN
-/// Abstract base class for all result objects in FSKit `Handler` protocols.
+/// An abstract base class for all result objects in FSKit handler-style 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.
+/// A set of attributes to populate.
///
-/// > Note: Different operations may require different attribute sets. Access this property through the relevant result subclass (e.g., `FSLookupItemResult.requestedAttributes`).
+/// Your module populates these attributes in ``FSItem/Attributes`` instances.
///
-/// > 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.
+/// Different operations may require different attribute sets. Access this property through the relevant result subclass, such as ``FSLookupItemResult.requestedAttributes`.
+///
+/// > Important: Be sure to populate all requested attributes. FSKit caches all populated attributes and may use them in subsequent operations, even if not explicitly requested.
@property (nonatomic, class, strong, readonly) FSItemGetAttributesRequest *requestedAttributes;
@end
#pragma mark - FSVolumeHandler Result Classes
-/// Result class for ``FSVolume/Handler/activate(options:replyHandler:)``
+/// The result of an activate call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/activate(options:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSActivateResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates an activate result instance.
///
/// - Parameters:
/// - rootItem: The root ``FSItem`` of the volume.
@@ -54,15 +58,17 @@
@end
-/// Result class for ``FSVolume/Handler/lookupItem(named:in:replyHandler:)``
+/// The result of an item lookup call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/lookupItem(named:in:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSLookupItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an item-lookup operation.
///
/// - 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.
+/// - foundItem: The ``FSItem`` found by the directory lookup.
+/// - itemName: The item's name as it exists within the file system. The value may differ from the requested name in order 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
@@ -76,18 +82,20 @@
@end
-/// Result class for ``FSVolume/Handler/createItem(named:type:in:attributes:replyHandler:)``
+/// The result of a create-item call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/createItem(named:type:in:attributes:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSCreateItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an item-creation operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes FSKit to calculate the free space when the operation completes, 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
@@ -102,22 +110,26 @@
@end
-/// Result class for ``FSVolume/Handler/createSymbolicLink(named:in:attributes:linkContents:replyHandler:)``
+/// The result of a create-symlink call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/createSymbolicLink(named:in:attributes:linkContents:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSCreateSymlinkResult : FSCreateItemResult
@end
-/// Result class for ``FSVolume/Handler/createLink(to:named:in:replyHandler:)``
+/// The result of a create-link call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/createLink(to:named:in:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSCreateLinkResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a link-creation operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -131,19 +143,21 @@
@end
-/// Result class for ``FSVolume/Handler/renameItem(_:inDirectory:named:to:inDirectory:overItem:replyHandler:)``
+/// The result of a rename-item call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/renameItem(_:inDirectory:named:to:inDirectory:overItem:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSRenameItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an item-renaming operation.
///
/// - 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.
+/// - overItemAttributes: The ``FSItemAttributes`` of the overwritten item, if any. Pass `nil` if the action didn't overwrite any item.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -159,16 +173,18 @@
@end
-/// Result class for``FSVolume/Handler/removeItem(_:named:from:replyHandler:)``
+/// The result of a remove-item call.
+///
+/// Use this type in your implementation of``FSVolume/Handler/removeItem(_:named:from:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSRemoveItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an item-removal operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes FSKit to calculate the free space when the operation finishes, 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
@@ -181,11 +197,13 @@
@end
-/// Result class for ``FSVolume/Handler/getAttributes(_:of:replyHandler:)``
+/// The result of a get-attributes call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/getAttributes(_:of:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSGetAttributesResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an attribute-getting operation.
///
/// - Parameters:
/// - attributes: The requested ``FSItemAttributes`` for the item.
@@ -199,15 +217,17 @@
@end
-/// Result class for ``FSVolume/Handler/setAttributes(_:on:replyHandler:)``
+/// The restlt of a set-attributes call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/setAttributes(_:on:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSSetAttributesResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an attribute-setting operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -219,14 +239,16 @@
@end
-/// Result class for ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``
+/// The result of an enumerate-directory call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/enumerateDirectory(_:startingAt:verifier:attributes:packer:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSEnumerateDirectoryResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an directory enumeration operation.
///
/// - 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.
+/// - currentVerifier: An `FSDirectoryVerifier` value that reflects the directory's current version. FSKit uses this value 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
@@ -237,11 +259,13 @@
@end
-/// Result class for ``FSVolume/Handler/readSymbolicLink(_:replyHandler:)``
+/// The result of a read-symlink call.
+///
+/// Use this type in your implementation of ``FSVolume/Handler/readSymbolicLink(_:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSReadSymlinkResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a symlink-reading operation.
///
/// - Parameters:
/// - contents: The contents of the symbolic link.
@@ -259,11 +283,13 @@
#pragma mark - FSVolumeXattrHandler Result Classes
-/// Result class for ``FSVolume/XattrHandler/getXattr(named:of:replyHandler:)``
+/// The result of a get-extended-attributes call.
+///
+/// Use this type in your implementation ``FSVolume/XattrHandler/getXattr(named:of:context:replyHandler:)``
FSKIT_API_AVAILABILITY_V3
@interface FSGetXattrResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an extended-attribute-getting operation.
///
/// - Parameters:
/// - value: The extended attribute value for the requested attribute name.
@@ -277,14 +303,16 @@
@end
-/// Result class for ``FSVolume/XattrHandler/setXattr(named:to:on:policy:replyHandler:)``
+/// The result of a set-extended-attributes call.
+///
+/// Use this type in your implementation of ``FSVolume/XattrHandler/setXattr(named:to:on:policy:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSSetXattrResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an extended-attribute-setting operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -295,7 +323,9 @@
@end
-/// Result class for ``FSVolume/XattrHandler/xattrs(of:)``
+/// The result of a list-extended-attributes call.
+///
+/// Use this type in your implementation of ``FSVolume/XattrHandler/supportedXattrNames(for:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSListXattrsResult : FSVolumeHandlerResult
@@ -315,11 +345,13 @@
#pragma mark - FSVolumeReadWriteHandler Result Classes
-/// Result class for ``FSVolume/ReadWriteHandler/read(from:at:length:into:replyHandler:)``
+/// The result of a read-file call.
+///
+/// Use this type in your implementation of ``FSVolume/ReadWriteHandler/read(from:at:length:into:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSReadFileResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a file-reading operation.
///
/// - 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.
@@ -335,16 +367,18 @@
@end
-/// Result class for ``FSVolume/ReadWriteHandler/write(contents:to:at:replyHandler:)``
+/// The result of a read-file call.
+///
+/// Use this type in your implementation of ``FSVolume/ReadWriteHandler/write(contents:to:at:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSWriteFileResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a file-writing operation.
///
/// - 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.
+/// - attributes: The updated ``FSItemAttributes`` of the file after the write operation. Examples of attributes you might need to update are the updated file size and modification time.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -359,14 +393,16 @@
#pragma mark - FSVolumeAccessCheckHandler Result Classes
-/// Result class for ``FSVolume/AccessCheckHandler/checkAccess(to:requestedAccess:replyHandler:)``
+/// The result of a check-access call.
+///
+/// Use this type in your implementation of ``FSVolume/AccessCheckHandler/checkAccess(to:requestedAccess:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSCheckAccessResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an access-checking operation.
///
/// - 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.
+/// - accessAllowed: A Boolean value indicating whether the file system grants the requested access to the item. Pass `true` (Swift) or `YES` (Obj-C) to allow access, `false` (Swift) or `NO` (Obj-C) to deny access.
/// - Returns: A populated result instance, or `nil` if validation fails.
- (instancetype _Nullable)initWithAccessAllowed:(BOOL)accessAllowed
NS_DESIGNATED_INITIALIZER
@@ -379,11 +415,13 @@
#pragma mark - FSVolumeRenameHandler Result Classes
-/// Result class for ``FSVolume/RenameHandler/setVolumeName(_:replyHandler:)``
+/// The result of a rename-volume call.
+///
+/// Use this type in your implementation of ``FSVolume/RenameHandler/setVolumeName(_:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSVolumeRenameResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a volume-renaming operation.
///
/// - Parameters:
/// - newName: The new volume name.
@@ -399,16 +437,18 @@
#pragma mark - FSVolumePreallocateHandler Result Classes
-/// Result class for ``FSVolume/PreallocateHandler/preallocateSpace(for:at:length:flags:replyHandler:)``
+/// The result of a preallocate call.
+///
+/// Use this type in your implementation of ``FSVolume/PreallocateHandler/preallocateSpace(for:at:length:flags:context:replyHandler:)``
FSKIT_API_AVAILABILITY_V3
@interface FSPreallocateResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a preallocate operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -423,14 +463,16 @@
#pragma mark - FSVolumeItemDeactivationHandler Result Classes
-/// Result class for ``FSVolume/ItemDeactivationHandler/deactivateItem(_:replyHandler:)``
+/// The result of a deactivate-item call.
+///
+/// Use this type in your implementation of ``FSVolume/ItemDeactivationHandler/deactivateItem(_:context:replyHandler:)``
FSKIT_API_AVAILABILITY_V3
@interface FSDeactivateItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an item-deactivation operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -443,14 +485,16 @@
#pragma mark - FSVolumeSeekRegionHandler Result Classes
-/// Result class for ``FSVolume/SeekRegionHandler/seek(within:from:region:context:replyHandler:)``
+/// A seek-region result.
+///
+/// Use this type in your implementation of ``FSVolume/SeekRegionHandler/seek(within:from:region:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSSeekRegionResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for a region-seeking operation.
///
/// - Parameters:
-/// - returnedOffset: The offset of the requested region (greater than or equal to the supplied offset).
+/// - 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
@@ -463,14 +507,16 @@
#pragma mark - FSVolumeKernelOffloadedIOHandler Result Classes
-/// Result class for ``FSVolume/KernelOffloadedIOHandler/blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``
+/// The result of a blockmap call.
+///
+/// Use this type in your implementation of ``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.
+/// Creates a result for a blockmap operation.
///
/// - 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.
+/// - freeSpace: An ``FSFreeSpace`` instance populated with the volume's updated free space. Passing a `nil` free space causes 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
@@ -481,11 +527,13 @@
@end
-/// Result class for ``FSVolume/KernelOffloadedIOHandler/completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)``
+/// The result of a complete-I/O call.
+///
+/// Use this type in your implementation of ``FSVolume/KernelOffloadedIOHandler/completeIO(for:offset:length:status:flags:operationID:replyHandler:)``
FSKIT_API_AVAILABILITY_V3
@interface FSCompleteIOResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates a result for an I/O-completion operation.
///
/// - Parameters:
/// - attributes: The updated ``FSItemAttributes`` of the file after the I/O completion operation (e.g., updated size, modification time).
@@ -499,28 +547,36 @@
@end
-/// Result class for ``FSVolume/KernelOffloadedIOHandler/createFile(named:in:attributes:packer:replyHandler:)``
+/// The result of a kernel-offloaded create-file call.
+///
+/// Use this type in your implementation of ``FSVolume/KernelOffloadedIOHandler/createFile(named:in:attributes:packer:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSCreateFileKOIOResult : FSCreateItemResult
@end
-/// Result class for ``FSVolume/KernelOffloadedIOHandler/lookupItem(named:in:packer:replyHandler:)``
+/// The result of a kernel-offloaded lookup-item call.
+///
+/// Use this type in your implementation of ``FSVolume/KernelOffloadedIOHandler/lookupItem(named:in:packer:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSLookupItemKOIOResult : FSLookupItemResult
@end
-/// Result class for ``FSVolume/KernelOffloadedIOHandler/preallocateSpace(for:at:length:flags:packer:replyHandler:)``
+/// The result of a kernel-offloaded preallocate call.
+///
+/// Use this type in your implementation of ``FSVolume/KernelOffloadedIOHandler/preallocateSpace(for:at:length:flags:packer:context:replyHandler:)``
FSKIT_API_AVAILABILITY_V3
@interface FSPreallocateKOIOResult : FSPreallocateResult
@end
#pragma mark - FSVolumeDataCacheHandler Result Classes
-/// Result class for ``FSVolume/DataCacheHandler/open(_:modes:cacheMode:context:replyHandler:)``
+/// The result of an open-item call.
+///
+/// Use this type in your implementation of ``FSVolume/DataCacheHandler/open(_:modes:cacheMode:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSOpenItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates an open-item result.
///
/// - Parameters:
/// - grantedCoherency: The ``FSKernelCacheCoherencyType`` granted by the module for this item.
@@ -534,11 +590,13 @@
@end
-/// Result class for ``FSVolume/DataCacheHandler/upgrade(_:cacheMode:context:replyHandler:)``
+/// The result of an upgrade-item call.
+///
+/// Use this type in your implementation of ``FSVolume/DataCacheHandler/upgrade(_:cacheMode:context:replyHandler:)``.
FSKIT_API_AVAILABILITY_V3
@interface FSUpgradeItemResult : FSVolumeHandlerResult
-/// Creates a result instance with all required properties populated.
+/// Creates an upgrade-item result.
///
/// - Parameters:
/// - grantedCoherency: The ``FSKernelCacheCoherencyType`` granted by the module after the upgrade.