-
Notifications
You must be signed in to change notification settings - Fork 522
FSKit macOS xcode16.3 b3
Rolf Bjarne Kvinge edited this page Mar 18, 2025
·
1 revision
#FSKit.framework
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSEntityIdentifier.h 2025-03-13 05:31:30
@@ -20,15 +20,32 @@
FSKIT_API_AVAILABILITY_V1
@interface FSEntityIdentifier : NSObject <NSCopying, NSSecureCoding>
-- (instancetype)init; // Generates a random UUID as the identifier
+/// Creates an entity identifier with a random UUID.
+- (instancetype)init;
+/// Creates an entity identifier with the given UUID.
+///
+/// - Parameter uuid: The UUID to use for this identifier.
- (instancetype)initWithUUID:(NSUUID *)uuid;
+
+/// Creates an entity identifier with the given UUID and qualifier data as a 64-bit unsigned integer.
+/// - Parameters:
+/// - uuid: The UUID to use for this identifier.
+/// - qualifier: The data to distinguish entities that otherwise share the same UUID.
- (instancetype)initWithUUID:(NSUUID *)uuid
qualifier:(uint64_t)qualifier;
+
+/// Creates an entity identifier with the given UUID and qualifier data.
+///
+/// - Parameters:
+/// - uuid: The UUID to use for this identifier.
+/// - qualifierData: The data to distinguish entities that otherwise share the same UUID.
- (instancetype)initWithUUID:(NSUUID *)uuid
data:(NSData *)qualifierData;
+/// A UUID to uniquely identify this entity.
@property (copy) NSUUID *uuid;
+/// An optional piece of data to distinguish entities that otherwise share the same UUID.
@property (copy, nullable) NSData *qualifier;
@end
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSItem.h 2025-03-13 05:31:30
@@ -10,28 +10,51 @@
NS_ASSUME_NONNULL_BEGIN
+/// A value that indicates a set of item attributes to get or set.
+///
+/// This type is an option set in Swift.
+/// In Objective-C, you use the cases of this enumeration to create a bit field.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSInteger, FSItemAttribute) {
+ /// The type attribute.
FSItemAttributeType = 1UL << 0,
+ /// The mode attribute.
FSItemAttributeMode = 1UL << 1,
+ /// The link count attribute.
FSItemAttributeLinkCount = 1UL << 2,
+ /// The user ID (uid) attribute.
FSItemAttributeUID NS_SWIFT_NAME(uid) = 1UL << 3,
+ /// The group ID (gid) attribute.
FSItemAttributeGID NS_SWIFT_NAME(gid) = 1UL << 4,
+ /// The flags attribute.
FSItemAttributeFlags = 1UL << 5,
+ /// The size attribute.
FSItemAttributeSize = 1UL << 6,
+ /// The allocated size attribute.
FSItemAttributeAllocSize = 1UL << 7,
+ /// The file ID attribute.
FSItemAttributeFileID = 1UL << 8,
+ /// The parent ID attribute.
FSItemAttributeParentID = 1UL << 9,
+ /// The last-accessed time attribute.
FSItemAttributeAccessTime = 1UL << 10,
+ /// The last-modified time attribute.
FSItemAttributeModifyTime = 1UL << 11,
+ /// The last-changed time attribute.
FSItemAttributeChangeTime = 1UL << 12,
+ /// The creation time attribute.
FSItemAttributeBirthTime = 1UL << 13,
+ /// The backup time attribute.
FSItemAttributeBackupTime = 1UL << 14,
+ /// The time added attribute.
FSItemAttributeAddedTime = 1UL << 15,
+ /// The supports limited extended attributes attribute.
FSItemAttributeSupportsLimitedXAttrs = 1UL << 16,
+ /// The inhibit kernel offloaded I/O attribute.
FSItemAttributeInhibitKernelOffloadedIO = 1UL << 17,
} NS_SWIFT_NAME(FSItem.Attribute);
+/// An enumeration of item types, such as file, directory, or symbolic link.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSInteger, FSItemType) {
FSItemTypeUnknown = 0,
@@ -62,12 +85,11 @@
/// You test an attribute's validity with the the method ``FSItem/Attributes/isValid(_:)``.
/// If the value is `true` (Swift) or `YES` (Objective-C), it's safe to use the attribute.
///
-/// To request attributes from the module, the ``FSItem/GetAttributesRequest`` provides the ``FSItem/GetAttributesRequest/isAttributeWanted(_:)`` method as a way to check whether the module should retrieve an atribute's value.
-/// This class also provides a ``FSItem/GetAttributesRequest/wantedAttributes`` property to allow a calling app to set all wanted attributes in a single command.
+/// Methods that get or set an item's attribute use ``FSItemGetAttributesRequest`` or ``FSItemSetAttributesRequest``, respectively.
+/// Both are subclasses of ``FSItemAttributes``.
+/// An ``FSItemGetAttributesRequest`` contains a ``FSItemGetAttributesRequest/wantedAttributes`` property to indicate the attributes a file system provides for the request.
+/// Similarly, ``FSItemSetAttributesRequest`` uses the property ``FSItemSetAttributesRequest/consumedAttributes`` for a file system to signal back which attributes it successfully used.
///
-/// When setting attributes, ``FSItem/SetAttributesRequest`` provides the ``FSItem/SetAttributesRequest/wasAttributeConsumed(_:)`` method to verify whether the module successfully used an attribute.
-/// To work with several attributes at once, use the ``FSItem/SetAttributesRequest/consumedAttributes`` property.
-///
/// `FSItem` is the FSKit equivelant of a vnode in the kernel.
/// For every FSKit vnode in the kernel, the `FSModule` hosting the volume has an instantiated `FSItem`.
FSKIT_API_AVAILABILITY_V1
@@ -75,61 +97,106 @@
@end
+/// Attributes of an item, such as size, creation and modification times, and user and group identifiers.
FSKIT_API_AVAILABILITY_V1 NS_SWIFT_NAME(FSItem.Attributes)
@interface FSItemAttributes : NSObject <NSSecureCoding>
--(void)invalidateAllProperties; // mark all attributes inactive
+/// Marks all attributes inactive.
+-(void)invalidateAllProperties;
+/// The user identifier.
@property (nonatomic) uint32_t uid;
+/// The group identifier.
@property (nonatomic) uint32_t gid;
+/// The mode of the item.
+///
+/// The mode is often used for `setuid`, `setgid`, and `sticky` bits.
@property (nonatomic) uint32_t mode;
+/// The item type, such as a regular file, directory, or symbolic link.
@property (nonatomic) FSItemType type;
+/// The number of hard links to the item.
@property (nonatomic) uint32_t linkCount;
-/** Flags are reported to applications as `stat.st_flags` and use the definitions there-of */
+/// The item's behavior flags.
+///
+/// See `st_flags` in `stat.h` for flag definitions.
@property (nonatomic) uint32_t flags;
+/// The item's size.
@property (nonatomic) uint64_t size;
+/// The item's allocated size.
@property (nonatomic) uint64_t allocSize;
+/// The item's file identifier.
@property (nonatomic) FSItemID fileID;
+/// The identifier of the item's parent.
@property (nonatomic) FSItemID parentID;
-/**
- * supportsLimitedXAttrs - the item natively supports a limited set of xattrs
- *
- * Some file systems only support a limited set of xatts, for example msdosfs,
- * where only the root item supports a single xattr.
- */
+/// A Boolean value that indicates whether the item supports a limited set of extended attributes.
@property (nonatomic) BOOL supportsLimitedXAttrs;
-/**
- * inhibitKernelOffloadedIO
- * Allows the file system to override the per file system Kernel Offloaded IO
- * settings for a specific file.
- */
+/// A Boolean value that indicates whether the file system overrides the per-volume settings for kernel offloaded I/O for a specific file.
+///
+/// This property has no meaning if the volume doesn't conform to ``FSVolumeKernelOffloadedIOOperations``.
@property (nonatomic) BOOL inhibitKernelOffloadedIO;
-
+/// The item's last-modified time.
+///
+/// This property represents `mtime`, the last time the item's contents changed.
@property (nonatomic) struct timespec modifyTime;
+/// The item's added time.
+///
+/// This property represents the time the file system added the item to its parent directory.
@property (nonatomic) struct timespec addedTime;
+/// The item's last-changed time.
+///
+/// This property represents `ctime`, the last time the item's metadata changed.
@property (nonatomic) struct timespec changeTime;
+/// The item's last-accessed time.
@property (nonatomic) struct timespec accessTime;
+/// The item's creation time.
@property (nonatomic) struct timespec birthTime;
+/// The item's last-backup time.
@property (nonatomic) struct timespec backupTime;
+/// Returns a Boolean value that indicates whether the attribute is valid.
+///
+/// If the value returned by this method is `YES` (Objective-C) or `true` (Swift), a caller can safely use the given attribute.
-(BOOL)isValid:(FSItemAttribute)attribute;
@end
+/// A request to set attributes on an item.
+///
+/// Methods that take attributes use this type to receive attribute values and to indicate which attributes they support.
+/// The various members of the parent type, ``FSItemAttributes``, contain the values of the attributes to set.
+///
+/// Modify the ``consumedAttributes`` property to indicate which attributes your file system successfully used.
+/// FSKit calls the ``wasAttributeConsumed(_:)`` method to determine whether the file system successfully used a given attribute.
+/// Only set the attributes that your file system supports.
FSKIT_API_AVAILABILITY_V1 NS_SWIFT_NAME(FSItem.SetAttributesRequest)
@interface FSItemSetAttributesRequest : FSItemAttributes
+/// The attributes successfully used by the file system.
+///
+/// This property is a bit field in Objective-C and an <doc://com.apple.documentation/documentation/Swift/OptionSet> in Swift.
@property (nonatomic) FSItemAttribute consumedAttributes;
+/// A method that indicates whether the file system used the given attribute.
+///
+/// - Parameter attribute: The ``FSItemAttribute`` to check.
-(BOOL)wasAttributeConsumed:(FSItemAttribute)attribute;
@end
+/// A request to get attributes from an item.
+///
+/// Methods that retrieve attributes use this type and inspect the ``wantedAttributes`` property to determine which attributes to provide. FSKit calls the ``isAttributeWanted(_:)`` method to determine whether the request requires a given attribute.
FSKIT_API_AVAILABILITY_V1 NS_SWIFT_NAME(FSItem.GetAttributesRequest)
@interface FSItemGetAttributesRequest : NSObject <NSSecureCoding>
+/// The attributes requested by the request.
+///
+/// This property is a bit field in Objective-C and an <doc://com.apple.documentation/documentation/Swift/OptionSet> in Swift.
@property (nonatomic) FSItemAttribute wantedAttributes;
+/// A method that indicates whether the request wants given attribute.
+///
+/// - Parameter attribute: The ``FSItemAttribute`` to check.
-(BOOL)isAttributeWanted:(FSItemAttribute)attribute;
@end
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitTypes.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitTypes.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitTypes.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSKitTypes.h 2025-03-13 05:31:30
@@ -9,16 +9,4 @@
#define FSKitTypes_h
-/*
- * FSTaskParameters - argument array of parameters for an operation
- *
- * Directly maps to `argc`/`argv` passed to a command line tool. Consists
- * of a sequence of strings formatted as per CLI arguments. Exact squence
- * and syntax is left to the receiver, but two examples are:
- *
- * "force" => @[ @"--force" ]
- * "read only" => @[ @"-o", "rdonly" ]
- */
-typedef NSArray <NSString *> FSTaskParameters;
-
#endif /* FSKitTypes_h */
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSMutableFileDataBuffer.h 2025-03-13 05:31:29
@@ -10,20 +10,20 @@
NS_ASSUME_NONNULL_BEGIN
-/*
- * FSMutableFileDataBuffer - wrapper object for a data buffer
- *
- * This object class wraps data buffers, and behaves
- * in a way similar to a uio in the kernel.
- */
-
+/// A wrapper object for a data buffer.
+///
+/// This object provides a "zero-copy" buffer, for use when reading data from files.
+/// By not requiring additional buffer copying, this object reduces the extension's memory footprint and improves performance.
+/// The `FSMutableFileDataBuffer` behaves similarly to a `uio` in the kernel.
FSKIT_API_AVAILABILITY_V1
@interface FSMutableFileDataBuffer : NSObject
+/// The data length of the buffer.
@property (readonly) NSUInteger length FSKIT_API_AVAILABILITY_V1;
- (instancetype)init NS_UNAVAILABLE;
+/// The byte data.
-(void *)mutableBytes FSKIT_API_AVAILABILITY_V1 NS_SWIFT_UNAVAILABLE("Use withMutableBytes instead.");
@end
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSResource.h 2025-03-13 05:31:30
@@ -14,15 +14,22 @@
NS_ASSUME_NONNULL_BEGIN
+/// A type that represents the recognition and usability of a probed resource.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSInteger, FSMatchResult) {
- // No match
+ /// The probe doesn't recognize the resource.
+ ///
+ /// This match result is appropriate when the file system module determines that the resource uses a completely different format.
FSMatchResultNotRecognized = 0,
- // Probe recognizes this resource but is unable to use
+ /// The probe recognizes the resource but can't use it.
+ ///
+ /// This match result is appropriate when the file system module identifies the resource's format but can't use it. For example, if the resource uses a newer version than the module supports, the module can name the resource but can't safely do anything with it.
FSMatchResultRecognized,
- // Probe recognizes this resource and is ready to use, but in a limited capacity
+ /// The probe recognizes the resource and is ready to use it, but only in a limited capacity.
+ ///
+ /// This match result is appropriate when the file system module identifies the resource's format but also identifies incompatibilities. For example, if the module determines the resource uses new features that the module doesn't support, the module may only offer read-only access.
FSMatchResultUsableButLimited,
- // Probe recognizes this resource and is ready to use
+ /// The probe recognizes the resource and is ready to use it.
FSMatchResultUsable,
};
@@ -70,31 +77,51 @@
#pragma mark - FSBlockDeviceResource class and helpers
-/** FSMetadataRange - A range describing contiguous metadata segments on disk. Consists of a startOffset, segmentLength and segmentCount.
- It represents the following range of bytes in disk: `[startOffset, startOffset + segmentLength * segmentCount)`.
- It is split into segments, as each segment represents a single block in the resource's buffer cache.
-
- Each metadata segment must represent range which is already present in the resource's buffer cache.
- Each segment's offset and length must match the offset and length of the corresponding block in the buffer cache.
-
- For example, in the case of startOffset = 0, segmentLength = 512, segmentCount = 8,
- this range represents 8 segments with the following ranges in disk: `[0, 512), [512, 1024), [1024, 1536), ..., [3584, 4096)`.
- */
+/// A range that describes contiguous metadata segments on disk.
+///
+/// This type represents a range that begins at `startOffset` and ends at `startOffset + segmentLength * segmentCount`.
+/// Each segment in the range represents a single block in the resource's buffer cache.
+///
+/// For example, given an `FSMetadataRange` with the following properties:
+///
+/// * `startOffset = 0`
+/// * `segmentLength = 512`
+/// * `segmentCount = 8`
+///
+/// The range represents eight segments: from 0 to 511, then from 512 to 1023, and so on until a final segment of 3584 to 4095.
+///
+/// Ensure that each metadata segment represents a range that's already present in the resource's buffer cache.
+/// Similarly, ensure that each segment's offset and length matches the offset and length of the corresponding block in the buffer cache.
@interface FSMetadataRange : NSObject
-/** Start offset of the range in bytes, must be a multiple of the corresponding resource blockSize */
+/// The start offset of the range in bytes.
+///
+/// Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
@property (readonly) off_t startOffset;
-/** Segment length in bytes, must be a multiple of the corresponding resource blockSize */
+/// The segment length in bytes.
+///
+/// Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
@property (readonly) uint64_t segmentLength;
-/** Segment count */
+/// The number of segments in the range.
@property (readonly) uint64_t segmentCount;
+/// Initializes a metadata range with the given properties.
+///
+/// - Parameters:
+/// - startOffset: The start offset of the range in bytes. Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
+/// - segmentLength: The segment length in bytes. Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
+/// - segmentCount: The number of segments in the range.
-(instancetype)initWithOffset:(off_t)startOffset
segmentLength:(uint64_t)segmentLength
segmentCount:(uint64_t)segmentCount;
+/// Creates a metadata range with the given properties.
+/// - Parameters:
+/// - startOffset: The start offset of the range in bytes. Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
+/// - segmentLength: The segment length in bytes. Ensure this value is a multiple of the corresponding resource's ``FSBlockDeviceResource-c.class/blockSize``.
+/// - segmentCount: The number of segments in the range.
+(instancetype)rangeWithOffset:(off_t)startOffset
segmentLength:(uint64_t)segmentLength
segmentCount:(uint64_t)segmentCount;
@@ -374,58 +401,73 @@
@end
-/** FSProbeResult object holding result of a specific probe
-
- @discussion Name and containerID must be non-nil for results other than .NotRecognized. Some container or volume formats may
- lack a name. Return an empty string (`@""`). Likewise, if the format supports a name but one is not set. Some container
- or volume formats may lack a durable UUID on which to base a container identifier. Such formats are only valid for Unary
- file systems. In such cases, return a random UUID. In BlockDeviceResource file system cases where the probe operation
- succeeds at determining the probe result but there is an error reading either the name or the UUID, return whatever information
- is available and an empty string/random UUID for the missing information.
- */
+/// An object that represents the results of a specific probe.
+///
+/// For any ``result`` value other than ``FSMatchResult/notRecognized``, ensure the ``name`` and ``containerID`` values are non-`nil`.
+/// When a container or volume format doesn't use a name, return an empty string.
+/// Also use an empty string in the case in which the format supports a name, but the value isn't set yet.
+///
+/// Some container or volume formats may lack a durable UUID on which to base a container identifier.
+/// This situation is only valid for unary file systems.
+/// In such a case, return a random UUID.
+///
+/// With a block device resource, a probe operation may successfully get a result but encounter an error reading the name or UUID.
+/// If this happens, use whatever information is available, and provide an empty string or random UUID for the name or container ID, respectively.
FSKIT_API_AVAILABILITY_V1
@interface FSProbeResult : NSObject <NSSecureCoding>
-/**
- @property result match result, one of .NotRecognized, .Recognized, .UsableButLimited, or .Usable.
- @property name resource name found during probe. nil if .NotRecognized, non-nil otherwise
- @property containerID container identifier found during probe. nil if .NotRecognized, non-nil otherwise
- @discussion
- name and containerID must be non-nil for results other than .NotRecognized. Some container or volume formats may
- lack a name. Return an empty string (`@""`). Likewise if the format supports a name but one is not set. Some container
- or volume formats may lack a durable UUID on which to base a container identifier. Such formats are only valid for Unary
- file systems. In such cases, return a random UUID. In BlockDeviceResource file system cases where the probe operation
- succeeds at determining the probe result but there is an error reading either the name or the uuid, return whatever information
- is available and an empty string/random UUID for the missing information.
- */
+/// The match result, representing the recognition and usability of a probed resource.
@property (readonly) FSMatchResult result;
-/** Resource name found during probe. nil if .NotRecognized, non-nil otherwise */
+/// The resource name, as found during the probe operation.
+///
+/// This value is non-`nil` unless the ``FSProbeResult/result`` is ``FSMatchResult/notRecognized`.
+/// For formats that lack a name, this value may be an empty string.
+/// This value can also be an empty string if the format supports a name, but the value isn't set yet.
@property (readonly, copy, nullable) NSString *name;
-/** Container identifier found during probe. nil if .NotRecognized, non-nil otherwise */
+/// The container identifier, as found during the probe operation.
+///
+/// This value is non-`nil` unless the ``FSProbeResult/result`` is ``FSMatchResult/notRecognized`.
+/// For formats that lack a durable UUID on which to base a container identifier --- which is only legal for a ``FSUnaryFileSystem`` --- this value may be a random UUID.
@property (readonly, nullable) FSContainerIdentifier *containerID;
- (instancetype)init NS_UNAVAILABLE;
-/** Probe result of not recognized */
+/// A probe result for an unrecognized file system.
+///
+/// An unrecognized probe result contains `nil` for its ``FSProbeResult/name`` and ``FSProbeResult/containerID`` properties.
@property (class, readonly) FSProbeResult * notRecognizedProbeResult;
-/** This probe result indicates that the file system format is recognized, but not usable. The name and containerID are both included with the result. */
+/// Creates a probe result for a recognized file system.
+///
+/// - Parameters:
+/// - name: The resource name, as found during the probe operation. If the file system doesn't support names, or is awaiting naming, use an empty string.
+/// - containerID: The container identifier, as found during the probe operation. If the file system doesn't support durable identifiers, use a random UUID.
+ (instancetype)recognizedProbeResultWithName:(NSString *)name
containerID:(FSContainerIdentifier *)containerID
NS_SWIFT_NAME(recognized(name:containerID:));
-/** This probe result indicates that the file system format is known and is usable with limited capabilities, however the name and/or containerID were unavailable due to limitations on the probed resource.
- This result must never be returned as the result from probing a reslurce which is not limited. */
+/// A probe result for a recognized file system that is usable, but with limited capabilities.
+///
+/// This kind of probe result lacks the ``FSProbeResult/name``, ``FSProbeResult/containerID``, or both.
+/// Don't return this result from probing a resource that isn't limited.
@property (class, readonly) FSProbeResult * usableButLimitedProbeResult;
-/** This probe result indicates that the file system format is known and is usable with limited capabilities. The name and containerID are both included with the result. */
+/// Creates a probe result for a recognized file system that is usable, but with limited capabilities.
+///
+/// - Parameters:
+/// - name: The resource name, as found during the probe operation. If the file system doesn't support names, or is awaiting naming, use an empty string.
+/// - containerID: The container identifier, as found during the probe operation. If the file system doesn't support durable identifiers, use a random UUID.
+ (instancetype)usableButLimitedProbeResultWithName:(NSString *)name
containerID:(FSContainerIdentifier *)containerID
NS_SWIFT_NAME(usableButLimited(name:containerID:));
-/** This probe result indicates that the file system format is known and is usable. The name and containerID are both included with the result. */
+/// Creates a probe result for a recognized and usable file system.
+///
+/// - Parameters:
+/// - name: The resource name, as found during the probe operation. If the file system doesn't support names, or is awaiting naming, use an empty string.
+/// - containerID: The container identifier, as found during the probe operation. If the file system doesn't support durable identifiers, use a random UUID.
+ (instancetype)usableProbeResultWithName:(NSString *)name
containerID:(FSContainerIdentifier *)containerID
NS_SWIFT_NAME(usable(name:containerID:));
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolume.h 2025-03-13 05:31:30
@@ -16,94 +16,81 @@
NS_ASSUME_NONNULL_BEGIN
+/// A value that indicates a location in a directory from which to enumerate.
+///
+/// Your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
FSKIT_API_AVAILABILITY_V1
typedef uint64_t FSDirectoryCookie NS_TYPED_EXTENSIBLE_ENUM;
+/// The constant initial value for the directory-enumeration cookie.
FSKIT_API_AVAILABILITY_V1
FS_EXPORT FSDirectoryCookie const FSDirectoryCookieInitial;
+/// A tool to detect whether the directory contents changed since the last call to enumerate a directory.
+///
+/// Your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)`` defines the semantics of this value; it's opaque to FSKit.
FSKIT_API_AVAILABILITY_V1
typedef uint64_t FSDirectoryVerifier NS_TYPED_EXTENSIBLE_ENUM;
+/// The constant initial value for the directory-enumeration verifier.
FSKIT_API_AVAILABILITY_V1
FS_EXPORT FSDirectoryVerifier const FSDirectoryVerifierInitial;
+/// Options that affect the behavior of deactivate methods.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSInteger, FSDeactivateOptions) {
+ /// An option to force deactivation.
FSDeactivateOptionsForce = 1 << 0
};
-/**
- * @typedef FSSyncFlags
- * Flags for synchronizeWithFlags based on the flags defined in mount.h
- * More flags which are not a part of this API can be used in the kernel, so
- * the flags are defined as options rather than an enum.
- */
+/// Behavior flags for use with synchronization calls.
+///
+/// These values are based on flags defined in `mount.h`. Since there are system-defined flags that are valid in the kernel but not in FSKit, this type defines its members as options rather than use an enumeration.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSInteger, FSSyncFlags) {
- FSSyncFlagsWait = 1, /* synchronized I/O file integrity completion */
- FSSyncFlagsNoWait = 2, /* start all I/O, but do not wait for it */
- FSSyncFlagsDWait = 4, /* synchronized I/O data integrity completion */
+ /// A flag for synchronized I/O with file-integrity completion.
+ FSSyncFlagsWait = 1,
+ /// A flag for synchronized I/O that starts I/O but doesn't wait for it.
+ FSSyncFlagsNoWait = 2,
+ /// A flag for synchronized I/O with data-integrity completion.
+ FSSyncFlagsDWait = 4,
};
-/*
- * FSVolumeIdentifier - data identifying a volume
- *
- * For most volumes, these data are the bytes of the UUID
- * identifying the volume. Network file systems may access the same
- * underlying volume using different authentication credentials. As
- * such, volume identifiers for those volumes add qualifying data indicative
- * of the specific container. Developers should not subclass this class.
- */
+/// A type that identifies a volume.
+///
+/// For most volumes, the volume identifier is the UUID identifying the volume.
+///
+/// Network file systems may access the same underlying volume using different authentication credentials.
+/// To handle this situation, add qualifying data to identify the specific container, as discussed in the superclass, ``FSEntityIdentifier``.
+///
+/// > Important: Don't subclass this class.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.Identifier)
@interface FSVolumeIdentifier : FSEntityIdentifier
@end
-
-/**
- * For each item found during directory enumeration, we always require a few pieces of information (item's
- * name, type, identifier (inode number), enumeration cookie).
- * Some directory enumerations also require other attributes, and those calls will supply an FSItemGetAttributesRequest.
- * These pieces of information are reported to FSKit by the volume implementation making a call to the packer object,
- * passing in the needed information. The cookie is an identifier which an enumerating application can use to
- * resume an enumeration. Specifically, for each enumerated item, the cookie is the value to pass into a future
- * enumeration to resume it with the item NEXT AFTER the current one.
- */
+/// An object used to provide items during a directory enumeration.
+///
+/// You use this type in your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``.
+///
+/// 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.
FSKIT_API_AVAILABILITY_V1
@interface FSDirectoryEntryPacker : NSObject
-(instancetype)init NS_UNAVAILABLE;
-/**
- * @method packEntryWithName:itemType:itemID:nextCookie:attributes:
- * This method should be called during the enumerateDirectory method, for each directory entry that the file system would like to return.
- * @param name item's name.
- * @param itemType item's type.
- * @param itemID item's ID.
- * @param nextCookie indicates the cookie value appropriate for resuming the enumeration at the next entry
- * @param attributes item's attributes. Should be nil if no attributes were requested.
- * @return YES Continue to the next entry, else NO.
- *
- * Example usage (an example how to pack multiple directory entries in a for loop)
-```
- -(void)packDirectoryEntries:(FSDirectoryEntryPacker *)packer
- withEntries:(NSArray <FSFileName *> *)entries
- {
- FSItemAttributes *attrs = [[FSItemAttributes alloc] init];
- for (FSFileName *name in entries) {
- if([packer packEntryWithName:name
- itemType:FSItemTypeFile
- itemID:0
- nextCookie:0
- attributes:attrs] == NO) {
- break;
- }
- }
- }
-```
- *
- */
+/// Provides a directory entry during enumeration.
+///
+/// You call this method in your implementation of ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``, for each directory entry you want to provide to the enumeration.
+///
+/// - Parameters:
+/// - name: The item's name.
+/// - itemType: The type of the item.
+/// - itemID: The item's identifier.
+/// - nextCookie: A value to indicate the next entry in the directory to enumerate. FSKit passes this value as the `cookie` parameter on the next call to ``FSVolume/Operations/enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)``. Use whatever value is appropriate for your implementation; the value is opaque to FSKit.
+/// - 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
itemType:(FSItemType)itemType
itemID:(FSItemID)itemID
@@ -114,88 +101,107 @@
@end
-/**
- * @typedef FSVolumeCaseFormat
- * Case-sensitivity status reported as part of FSVolumeSupportedCapabilities.
- * (A case-sensitive volume is a volume which treats upper and lower case characters in file and directory
- * names as different).
- */
+/// An enumeration of case-sensitivity support types.
+///
+/// A case-sensitive volume is a volume that treats upper and lower case characters in file and directory names as being distinct from each other. For example, `FILE.TXT` and `file.TXT` are different names in a case-sensitive volume, and the same name in a case-insensitive volume.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSInteger, FSVolumeCaseFormat) {
- /** Volume is case sensitive */
+ /// The volume is case sensitive.
FSVolumeCaseFormatSensitive = 0,
- /** Volume is NOT case sensitive */
+ /// The volume isn't case sensitive.
FSVolumeCaseFormatInsensitive = 1,
- /** Volume is NOT case sensitive, but supports preserving the case of file and directory names. */
+ /// The volume isn't case sensitive, but supports preserving the case of file and directory names.
FSVolumeCaseFormatInsensitiveCasePreserving = 2
} NS_SWIFT_NAME(FSVolume.CaseFormat);
-/**
- * @interface FSVolumeSupportedCapabilities
- * An object to group all volume capabilities.
- */
+
+/// A type that represents capabillities supported by a volume, such as hard and symbolic links, journaling, and large file sizes.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.SupportedCapabilities)
@interface FSVolumeSupportedCapabilities : NSObject<NSSecureCoding>
-/** Supports persistent object identifiers and can look up file system objects by their IDs. */
+/// A Boolean property that indicates whether the volume supports persistent object identifiers and can look up file system objects by their IDs.
@property (nonatomic) BOOL supportsPersistentObjectIDs;
-/** Supports symbolic links */
+/// A Boolean property that indicates whether the volume supports symbolic links.
@property (nonatomic) BOOL supportsSymbolicLinks;
-/** Supports hard links */
+/// A Boolean property that indicates whether the volume supports hard links.
@property (nonatomic) BOOL supportsHardLinks;
-/** Supports a journal used to speed recovery in case of unplanned restart (such as a power outage or crash). This does not necessarily mean the volume is actively using a journal. */
+/// A Boolean property that indicates whether the volume supports a journal used to speed recovery in case of unplanned restart, such as a power outage or crash.
+///
+/// This property doesn't necessarily mean the volume is actively using a journal.
@property (nonatomic) BOOL supportsJournal;
-/** Supports active journal using a journal for speedy recovery after an unplanned restart. */
+/// A Boolean property that indicates whether the volume currently uses a journal for speeding recovery after an unplanned shutdown.
@property (nonatomic) BOOL supportsActiveJournal;
-/** Does not store reliable times for the root directory */
+/// A Boolan property that indicates the volume doesn't store reliable times for the root directory.
+///
+/// If this value is `true` (Swift) or `YES` (Objective-C), the volume doesn't store reliable times for the root directory.
@property (nonatomic) BOOL doesNotSupportRootTimes;
-/** Supports sparse files, that is, files which can have 'holes' that have never been written to, and thus do not consume space on disk. */
+/// A Boolean property that indicates whether the volume supports sparse files.
+///
+/// A sparse file is a file that can have "holes" that the file system has never written to, and as a result don't consume space on disk.
@property (nonatomic) BOOL supportsSparseFiles;
-/** Supports zero runs, the volume keeps track of allocated but unwritten runs of a file so that it can substitute zeroes without actually writing zeroes to the media. */
+/// A Boolean property that indicates whether the volume supports zero runs
+///
+/// If this value is true, the volume keeps track of allocated but unwritten runs of a file so that it can substitute zeroes without actually writing zeroes to the media.
@property (nonatomic) BOOL supportsZeroRuns;
-/** Supports fast statFS, hints to upper layers to indicate that statfs(2) is fast enough that its results need not be cached by the caller. */
+/// A Boolean property that indicates whether the volume supports fast results when fetching file system statistics.
+///
+/// A true value means this volume hints to upper layers to indicate that `statfs(2)` is fast enough that its results need not be cached by the caller.
@property (nonatomic) BOOL supportsFastStatFS;
-/** Supports file sizes larger than 4GB, and potentially up to 2TB */
+/// A Boolean property that indicates whether the volume supports file sizes larger than 4GB, and potentially up to 2TB.
@property (nonatomic) BOOL supports2TBFiles;
-/** Supports open deny modes (e.g., "open for read write, deny write"). */
+/// A Boolean property that indicates whether the volume supports open deny modes.
+///
+/// These are modes such as "open for read write, deny write".
@property (nonatomic) BOOL supportsOpenDenyModes;
-/** Supports the `UF_HIDDEN` file flag */
+/// A Boolean property that indicates whether the volume supports hidden files.
+///
+/// A `true` value means the volume supports the `UF_HIDDEN` file flag.
@property (nonatomic) BOOL supportsHiddenFiles;
-/** Does not support determining values for total data blocks, available blocks, or free blocks, as in f_blocks, f_bavail, and f_bfree in the struct statFS returned by statfs(2). */
+/// A Boolean property that indicates the volume doesn't support certain volume size reports.
+///
+/// A true value means the volume doesn't support determining values for total data blocks, available blocks, or free blocks, as in `f_blocks`, `f_bavail`, and `f_bfree` in the struct `statFS` returned by `statfs(2)`.
@property (nonatomic) BOOL doesNotSupportVolumeSizes;
-/** Supports 64-bit object IDs, Uses object IDs that are 64-bit. */
+/// A Boolean property that indicates whether the volume supports 64-bit object IDs.
@property (nonatomic) BOOL supports64BitObjectIDs;
-/** Supports document IDs (an ID which persists across object ID changes) for document revisions. */
+/// A Boolean property that indicates whether the volume supports document IDs for document revisions.
+///
+/// A document ID is an identifier that persists across object ID changes.
@property (nonatomic) BOOL supportsDocumentID;
-/** Does not support setting the UF_IMMUTABLE flag */
+/// A Boolean property that indicates the volume doesn't support immutable files.
+///
+/// A `true` value means this volume doesn't support setting the `UF_IMMUTABLE` flag.
@property (nonatomic) BOOL doesNotSupportImmutableFiles;
-/** Does not support setting file permissions */
+/// A Boolean property that indicates the volume doesn't set file permissions.
+///
+/// If this value is `true` (Swift) or `YES` (Objective-C), the volume doesn't support setting file permissions.
@property (nonatomic) BOOL doesNotSupportSettingFilePermissions;
-/** Supports having multiple logical file systems in a single "partition" which share space. */
+/// A Boolean property that indicates whether the volume supports multiple logical file systems that share space in a single "partition."
@property (nonatomic) BOOL supportsSharedSpace;
-/** Supports having multiple logical file systems which may be mounted and unmounted together and may present common file system identifier information. */
+/// A Boolean property that indicates whether the volume supports volume groups.
+///
+/// Volume groups involve multiple logical file systems that the system can mount and unmount together, and for which the system can present common file system identifier information.
@property (nonatomic) BOOL supportsVolumeGroups;
-/** Whether the volume is case sensitive or not. */
+/// A value that indicates the volume's support for case sensitivity.
@property (nonatomic) FSVolumeCaseFormat caseFormat;
@end
@@ -205,219 +211,220 @@
/// A file system, depending on its type, provides one or more volumes to clients.
/// The ``FSUnaryFileSystem`` by definition provides only one volume, while an ``FSFileSystem`` supports multiple volumes.
///
-/// You implement a volume for your file system type by subclassing this class, and also conforming to the ``FSVolume/Operations`` protocol.
+/// You implement a volume for your file system type by subclassing this class, and also conforming to the ``FSVolume/Operations`` 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.
/// 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
+/// An identifier that uniquely identifies the volume.
@property (strong, readonly) FSVolumeIdentifier *volumeID;
+/// The name of the volume.
@property (copy) FSFileName *name;
-(instancetype)init NS_UNAVAILABLE;
+/// Creates a volume with the given identifier and name.
+/// - Parameters:
+/// - volumeID: An ``FSVolumeIdentifier`` to uniquely identify the volume. For a network file system that supports multiple authenticated users, disambiguate the users by using qualifying data in the identifier.
+/// - volumeName: A name for the volume.
-(instancetype)initWithVolumeID:(FSVolumeIdentifier *)volumeID
volumeName:(FSFileName *)volumeName NS_DESIGNATED_INITIALIZER;
@end
-/*
- * FSVolumePathConfOperations
- *
- * This protocol gathers properties related to the pathfonf and fpathconf
- * system calls. They are included in FSVolumeOperations and are gathered here as
- * they behave differently than the operations added in FSVolumeOperations. These
- * properties return the value imposed by the file system for the given property. For
- * files, this value applies to the file. For directories, this value applies to
- * all of the items in the directory.
- *
- * Some values are booleans while other values are numeric. Numeric limits
- * use -1 to represent no limit.
- *
- */
+/// Properties implemented by volumes that support providing the values of system limits or options.
+///
+/// This protocol gathers properties related to the `pathconf` and `fpathconf` system calls.
+///
+/// For a file, the value of a property applies to just that file; for a directory, the value applies to all items in the directory.
+///
+/// Properties that represent limits and have a numeric type use `-1` to represent no limit.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.PathConfOperations)
@protocol FSVolumePathConfOperations <NSObject>
-// The maximum number of hard links to the object.
+/// A property that represents the maximum number of hard links to the object.
@property (readonly) NSInteger maximumLinkCount;
-// The maximum length of a component of a filename.
+/// A property that represents the maximum length of a component of a filename.
@property (readonly) NSInteger maximumNameLength;
-// if TRUE, file system will reject chown(2) calls if not superuser.
+/// A Boolean property that indicates whether the volume restricts ownership changes based on authorization.
+///
+/// If this value is true, the volume rejects a `chown(2)` from anyone other than the superuser.
@property (readonly) BOOL restrictsOwnershipChanges;
-// If TRUE, file system will truncate the filename to maximumNameLength if filename is longer than maximumNameLength.
-// If FALSE, file system will return ENAMETOOLONG if filename is longer than maximumNameLength.
+/// A property that indicates whether the volume truncates files longer than its maximum supported length.
+///
+/// If this value is `true`, the volume truncates the filename to ``maximumNameLength`` if the filename is longer than that.
+/// If this value is false, the file system responds with the error code `ENAMETOOLONG` if the filename is longer than ``maximumNameLength``.
@property (readonly) BOOL truncatesLongNames;
@optional
-/*
- * maximum xattr size properties:
- * One of maximumXattrSize, maximumXattrSizeInBits must be implemented. FSKit
- * will convert from one to another if needed. In case both maximumXattrSize
- * and maximumXattrSizeInBits are implemented, FSKit will only use the
- * maximumXattrSizeInBits implementation.
- */
-
-// The maximum extended attribute size in bytes.
+/// The maximum extended attribute size in bytes.
+///
+/// Implement at least one of `maximumXattrSize` or ``maximumXattrSizeInBits``.
+/// FSKit automatically converts from one to another if needed.
+/// If you implement both, FSKit uses only the `maximumXattrSizeInBits` implementation.
@property (readonly) NSInteger maximumXattrSize;
-// The number of bits used to store maximum extended attribute size in bytes.
+/// The maximum extended attribute size in bits.
+///
+/// Implement at least one of ``maximumXattrSize`` or `maximumXattrSizeInBits`.
+/// FSKit automatically converts from one to another if needed.
+/// If you implement both, FSKit uses only the `maximumXattrSizeInBits` implementation.
@property (readonly) NSInteger maximumXattrSizeInBits;
-/*
- * maximum file size properties:
- * One of maximumFileSize, maximumFileSizeInBits must be implemented. FSKit
- * will convert from one to another if needed. In case both maximumFileSize
- * and maximumFileSizeInBits are implemented, FSKit will only use the
- * maximumFileSizeInBits implementation.
- */
-
-// The maximum size of a regular file allowed in the volume.
+/// The maximum size of a regular file allowed in the volume.
+///
+/// Implement at least one of `maximumFileSize` or ``maximumFileSizeInBits``.
+/// FSKit automatically converts from one to another if needed.
+/// If you implement both, FSKit uses only the `maximumFileSizeInBits` implementation.
@property (readonly) uint64_t maximumFileSize;
-/*
- * The minimum number of bits needed to represent, as a signed integer value,
- * the maximum size of a regular file allowed in the volume.
- * The maximum file size is 2^(maximumFileSizeInBits - 1).
- *
- * Maximum file size (bytes) Maximum (in hex) Unsigned bits Signed bits
- * 65,535 0xFFFF 16 17
- * 2,147,483,647 0x7FFFFFFF 31 32
- * 4,294,967,295 0xFFFFFFFF 32 33
- * 18,446,744,073,709,551,615 0xFFFFFFFFFFFFFFFF 64 65
- */
+/// The minimum number of bits needed to represent, as a signed integer value, the maximum size of a regular file allowed in the volume.
+///
+/// The maximum file size is `2^(maximumFileSizeInBits - 1)`.
+///
+/// | Maximum file size (bytes) | Maximum (in hex) | Unsigned bits | Signed bits |
+/// | -------------------------: | -------------------: | ------------: | ----------: |
+/// | 65,535 | `0xFFFF` | 16 | 17 |
+/// | 2,147,483,647 | `0x7FFFFFFF` | 31 | 32 |
+/// | 4,294,967,295 | `0xFFFFFFFF` | 32 | 33 |
+/// | 18,446,744,073,709,551,615 | `0xFFFFFFFFFFFFFFFF` | 64 | 65 |
+///
+/// Implement at least one of ``maximumFileSize`` or `maximumFileSizeInBits`.
+/// FSKit automatically converts from one to another if needed.
+/// If you implement both, FSKit uses only the `maximumFileSizeInBits` implementation.
@property (readonly) NSInteger maximumFileSizeInBits;
@end
-/**
- * FSStatFSResult - An interface used to report `volumeStatistics`.
- * Names are taken from `struct statfs` in `statfs(2)`.
- * These values will be reported to `statfs(2)` result.
- * All properties have a default value of 0. The file system should override these values, unless it has no
- * meaningful values to override with.
- * One exception is the fileSystemTypeName, which is readonly, and should be set using the designated initializer.
- */
+/// A type used to report a volume's statistics.
+///
+/// The names of this type's properties match those in the `statfs` structure in `statfs(2)`, which reports these values for an FSKit file system.
+/// All numeric properties default to `0`.
+/// Override these values, unless a given property has no meaningful value to provide.
+///
+/// > Note: Available space, free space, total space, and used space have properties to express their values either as a number of blocks or a number of bytes.
+/// Your module may supply both of these values by setting both the relevant block or byte property.
+/// Alternatively, a module may set only one of the two properties.
+/// When you do this, FSKit calculates the matching value based on ``blockSize``.
+///
+/// For the read-only ``fileSystemTypeName``, set this value with the designated initializer.
FSKIT_API_AVAILABILITY_V1
@interface FSStatFSResult : NSObject <NSSecureCoding>
-/** Block size, in bytes, of the volume */
+/// A property for the volume's block size, in bytes.
+///
+/// This value defaults to `4096`. Zero isn't a valid block size.
@property NSInteger blockSize;
-/** Optimal block size to perform I/O with.
- * Should be an even multiple of the block size. */
+/// A property for the optimal block size with which to perform I/O.
+///
+/// For best performance, specify an `ioSize` that's an even multiple of ``blockSize``.
@property NSInteger ioSize;
-/** Total data blocks in volume */
+/// A property for the volume's total data block count.
@property uint64_t totalBlocks;
-/** Free blocks avail to non-superuser */
+/// A property for the number of free blocks available to a non-superuser on the volume.
@property uint64_t availableBlocks;
-/** Free blocks in volume */
+/// A property for the number of free blocks in the volume.
@property uint64_t freeBlocks;
-/** Used blocks in volume */
+/// A property for the number of used blocks in the volume.
@property uint64_t usedBlocks;
-/** Total size, in bytes, of the volume */
+/// A property for the total size, in bytes, of the volume.
@property uint64_t totalBytes;
-/** The amount of space available to users, in bytes, in the volume */
+/// A property for the amount of space available to users, in bytes, in the volume.
@property uint64_t availableBytes;
-/** The amount of free space, in bytes, in the volume */
+/// A property for the amount of free space, in bytes, in the volume.
@property uint64_t freeBytes;
-/** The amount of used space, in bytes, in the volume */
+/// A property for the amount of used space, in bytes, in the volume.
@property uint64_t usedBytes;
-/** The total number of file slots in the volume */
+/// A property for the total number of file slots in the volume,
@property uint64_t totalFiles;
-/** The total number of free file slots in the volume */
+/// A property for the total number of free file slots in the volume.
@property uint64_t freeFiles;
-/** File system sub-type (flavor).
- * Should match the FSPersonalities's FSSubType attribute, if exists (within the EXAppExtensionAttributes
- * dictionary of the module\`s Info.plist). */
+/// A property for the file system's subtype or flavor.
+///
+/// Match this value to the `FSPersonalities`'s `FSSubType` attribute, if it exists within the `EXAppExtensionAttributes` dictionary of the module's `Info.plist`.
@property NSInteger fileSystemSubType;
-/** File system type name.
- * Should match the FSShortName attribute within the EXAppExtensionAttributes dictionary of the module\`s
- * Info.plist. Maximal allowed length is `MFSTYPENAMELEN`, including NUL. */
+/// A property for the file system type name.
+///
+/// Match this value to the `FSShortName` attribute within the `EXAppExtensionAttributes` dictionary of the module's `Info.plist`.
+/// The maximum allowed length is `MFSTYPENAMELEN`, including the terminating `NUL` character.
@property (readonly, copy) NSString * fileSystemTypeName;
+/// Creates an statistics result instance, using the given file system type name.
+///
+/// - Parameters fileSystemTypeName: A type name for the file system. The maximum allowed length is `MFSTYPENAMELEN`, including the terminating `NUL` character.
- (instancetype)initWithFileSystemTypeName:(NSString *)fileSystemTypeName;
- (instancetype)init NS_UNAVAILABLE;
@end
+/// Methods that all volumes implement to provide required capabilities.
+///
+/// Conform to this protocol in your subclass of ``FSVolume``.
+/// To provide additional capabilities, conform to the other `FSVolume` operations protocols, like ``FSVolumeOpenCloseOperations`` and ``FSVolumeReadWriteOperations``.
+///
+/// > Note: This protocol extends ``FSVolumePathConfOperations``, so your volume implementation must also conform to that protocol.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.Operations)
@protocol FSVolumeOperations <NSObject, FSVolumePathConfOperations>
-/**
- * supportedVolumeCapabilities
- *
- * report FSVolumeSupportedCapabilities data.
- * @return an FSVolumeSupportedCapabilities object, with the volume's supported capabilities.
- */
+/// A property that provides the supported capabilities of the volume.
@property (readonly, nonatomic) FSVolumeSupportedCapabilities *supportedVolumeCapabilities;
-/**
- * volumeStatistics
- *
- * report FSKitStatFSResult data.
- * @return an FSKitStatFSResult object, with up-to-date volume statistics.
- */
+/// A property that provides up-to-date statistics of the volume.
@property (readonly, nonatomic) FSStatFSResult * volumeStatistics;
-/**
- * mountWithOptions:replyHandler:
- *
- * @brief Some process is trying to mount this volume.
- * @param reply In case of success, should be called with the newly created root item and error = nil.
- * Otherwise, should be called with the relevant error. In that case, rootItem is ignored.
- */
+/// Mounts this volume, using the specified options.
+///
+/// FSKit calls this method as a signal that some process is trying to mount this volume.
+/// Your file system receives a call to ``activate(options:replyHandler:)`` prior to receiving any mount calls.
+///
+/// - Parameters:
+/// - options: Options to apply to the mount. These can include security-scoped file paths. There are no defined options currently.
+/// - reply: A block or closure to indicate success or failure. If mounting fails, pass an error as the one parameter to the reply handler. If mounting succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply return normally.
-(void)mountWithOptions:(FSTaskOptions *)options
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(mount(options:replyHandler:));
-/**
- * unmountWithReplyHandler:
- *
- * @brief file system is being unmounted. All cached state should be cleaned and flushed.
- * @param reply should be called with the relevant error, or nil in case of success.
- */
+/// Unmounts this volume.
+///
+/// Clear and flush all cached state in your implementation of this method.
+///
+/// - Parameters:
+/// - reply: A block or closure to indicate success or failure. If unmounting fails, pass an error as the one parameter to the reply handler. If unmounting succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply return normally.
-(void)unmountWithReplyHandler:(void(^)(void))reply
NS_SWIFT_NAME(unmount(replyHandler:));
-/**
- * synchronizeWithFlags:replyHandler:
- *
- * @brief sync the volume.
- * After calling this method, FSKit assumes that the volume
- * has sent all pending IOs or metadata to the underlying resource.
- * @param flags Waitfor flags as defined in mount.h. These flags let the
- * backend know whether to run the operation in a blocking or a
- * non blocking way.
- * @param reply should be called with the relevant error, or nil in case of success.
- */
+/// Synchronizes the volume with its underlying resource.
+///
+/// After calling this method, FSKit assumes that the volume has sent all pending I/O or metadata to its resource.
+///
+/// - Parameters:
+/// - flags: Timing flags, as defined in `mount.h.` These flags let the file system know whether to run the operation in a blocking or nonblocking fashion.
+/// - reply: A block or closure to indicate success or failure. If synchronization fails, pass an error as the one parameter to the reply handler. If synchronization succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)synchronizeWithFlags:(FSSyncFlags)flags
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(synchronize(flags:replyHandler:));
-/**
- * getAttributes:ofItem:replyHandler:
- *
- * @brief Fetch the item attributes for the given FSItem.
- * @param desiredAttributes requested set of attributes to get.
- * A given attribute, ATTR, is requested In case <ATTR>Wanted is set.
- * @param item item to get the attributes for.
- * @param reply In case of success, should be called with the requested attrs and error = nil.
- * Otherwise, should be called with the relevant error. In that case, attributes is ignored.
- * @discussion For file systems that do not support hard links,
- * linkCount should be 1 for regular files and symbolic links.
- * In case the item's bsdFlags contain the UF_COMPRESSED flag,
- * the file system should return the uncompressed size of the file.
- */
+/// Fetches attributes for the given item.
+///
+/// For file systems that don't support hard links, set ``FSItemAttributes/linkCount`` to `1` for regular files and symbolic links.
+///
+/// If the item's `bsdFlags` contain the `UF_COMPRESSED` flag, your file system returns the uncompressed size of the file.
+///
+/// - Parameters:
+/// - desiredAttributes: A requested set of attributes to get. The implementation inspects the request's ``FSItemGetAttributesRequest/wantedAttributes`` to determine which attributes to populate.
+/// - item: The item to get attributes for.
+/// - reply: A block or closure to indicate success or failure. If getting attributes succeeds, pass an ``FSItemAttributes`` with the requested attributes populated and a `nil` error. If getting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
-(void)getAttributes:(FSItemGetAttributesRequest *)desiredAttributes
ofItem:(FSItem *)item
replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
@@ -425,46 +432,41 @@
NS_SWIFT_NAME(getAttributes(_:of:replyHandler:))
NS_SWIFT_ASYNC_NAME(attributes(_:of:));
-/**
- * setAttributes:onItem:replyHandler:
- *
- * @brief Set the given set of item attributes to the given FSItem.
- * @param newAttributes FSItemSetAttributesRequest including the attributes to set
- * @param item item to set the attributes for.
- * @param reply In case of success, should be called with the item's updated attrs
- * (using the same semantics as the getItemAttributes call) and error = nil.
- * Otherwise, should be called with the relevant error. In that case, attributes is ignored.
- * @discussion Note that several attributes are considered to be "read-only",
- * and attempts to set those attributes should result in an error of EINVAL being returned.
- * If "size" is set beyond the end of file and the underlying file system does not support
- * sparse files, space to fulfill the new file size must be allocated and either zero-filled
- * or otherwise configured to read as zeros.
- * If "size" is set below the current end of file, the file shall be truncated and any space
- * no longer required to fulfill the new file size must be returned to the file system as
- * free space. Attempts to set "size" on directories and symbolic links must
- * be ignored (and no error should be returned). If the caller attempts to set
- * an attribute not supported by the on-disk file system format, no error should
- * be returned; instead, that situation will be detected by the upper layers.
- */
+/// Sets the given attributes on an item.
+///
+/// Several attributes are considered "read-only", and an attempt to set these attributes results in an error with the code `EINVAL`.
+///
+/// A request may set ``FSItem/Attributes/size`` beyond the end of the file.
+/// If the underlying file system doesn't support sparse files, allocate space to fill the new file size.
+/// Either fill this space with zeroes, or configure it to read as zeroes.
+///
+/// If a request sets the file size below the current end-of-file, truncate the file and return any unused space to the file system as free space.
+///
+/// Ignore attempts to set the size of directories or symbolic links; don't produce an error.
+///
+/// If the caller attepts to sest an attribute not supported by the on-disk file system format, don't produce an error.
+/// The upper layers of the framework will detect this situation.
+///
+/// - Parameters:
+/// - newAttributes: A request containing the attributes to set.
+/// - item: The item on which to set the attributes.
+/// - reply: A block or closure to indicate success or failure. If setting attributes succeeds, pass an ``FSItemAttributes`` with the item's updated attributes and a `nil` error. If setting attributes fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItemAttributes`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItemAttributes`` or throw an error.
-(void)setAttributes:(FSItemSetAttributesRequest *)newAttributes
onItem:(FSItem *)item
replyHandler:(void(^)(FSItemAttributes * _Nullable attributes,
NSError * _Nullable error))reply
NS_SWIFT_NAME(setAttributes(_:on:replyHandler:));
-/**
- * lookupItemNamed:inDirectory:replyHandler:
- *
- * @brief Lookup an item within a directory.
- * @param name item name to lookup.
- * @param directory directory to look the item in.
- * @param reply In case of success, should be called with the found item,
- * the item name (as it's saved within the file system), and error = nil.
- * Otherwise, should be called with the relevant error. In that case, theItem and itemName are ignored.
- * If the entry does not exist, complete the request with an error
- * with a domain of NSPOSIXErrorDomain and a code of ENOENT.
-
- */
+/// Looks up an item within a directory.
+///
+/// If no item matching `name` exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `ENOENT`.
+///
+/// > Tip: The ``FSFileName`` sent back to the caller may differ from the `name` parameter. This flexibility allows your implementation to handle case-insensitive and case-sensitive file systems. It might also be the case that `name` uses a composed Unicode string, but the name maintained by the file system and provided to the caller is uncomposed Unicode.
+///
+/// - Parameters:
+/// - name: The name of the item to look up.
+/// - directory: The directory in which to look up the item.
+/// - reply: A block or closure to indicate success or failure. If lookup succeeds, pass the found ``FSItem`` and its ``FSFileName`` (as saved within the file system), along with a `nil` error. If lookup fails, pass the relevant error as the third parameter; any ``FSItem`` or ``FSFileName`` are ignored in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItem`` and ``FSFileName`` as a tuple or throw an error.
-(void)lookupItemNamed:(FSFileName *)name
inDirectory:(FSItem *)directory
replyHandler:(void(^)(FSItem * _Nullable theItem,
@@ -472,59 +474,38 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(lookupItem(named:inDirectory:replyHandler:));
-/**
- * reclaimItem:replyHandler:
- *
- * @brief Reclaim an item. Releases any resources allocated for the item.
- * @param item item to reclaim.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- * Anyway, the resources allocated for this item should be released.
- * @discussion FSKit guarantees that for every FSItem returned by the volume,
- * a corresponding reclaim operation will occur once the upper layers no longer
- * reference that item.
- *
- * Note: block device file systems may wish to assess if the underlying resource has been terminated
- * before processing reclaim operations. On Unary file systems, it is especially easy to assess. When such
- * resources are disconnected from the system, the associated volumes are unmounted. Unmount triggers
- * reclaiming of all items, and some implementations have benefited greatly from short-circuiting reclaim
- * in such cases. As the resource has been terminated, all I/O will report an error, and it's easiest to just
- * avoid the work.
- */
+/// Reclaims an item, releasing any resources allocated for the item.
+///
+/// FSKit guarantees that for every ``FSItem`` returned by the volume, a corresponding reclaim operation occurs after the upper layers no longer reference that item.
+///
+/// > Note: Block device file systems may assess whether an underyling resource terminates before processing reclaim operations. On unary file systems, for example, the associated volumes unmount when such resources disconnect from the system. The unmount triggers a reclaiming of all items. Some implementations benefit greatly from short-circuiting in such cases. With a terminated resource, all I/O results in an error, making short-circuiting the most efficient response.
+///
+/// - Parameters:
+/// - item: The item to reclaim.
+/// - reply: A block or closure to indicate success or failure. If removal fails, pass an error as the one parameter to the reply handler. If removal succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)reclaimItem:(FSItem *)item
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(reclaimItem(_:replyHandler:));
-/**
- * readSymbolicLink:replyHandler:
- *
- * Read a symbolic link.
- *
- * @param item symbolic link item to read from. Guaranteed to be of type FSItemTypeSymlink.
- * @param reply In case of success, should be called with the link's contents
- * and error = nil. Otherwise, should be called with the relevant
- * error. In that case, contents is ignored.
- */
+/// Reads a symbolic link.
+///
+/// - Parameters:
+/// - item: The symbolic link to read from. FSKit guarantees this item is of type ``FSItem/ItemType/symlink``.
+/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass the link's contents as an ``FSFileName`` and a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores any ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSFileName`` or throw an error.
-(void)readSymbolicLink:(FSItem *)item
replyHandler:(void(^)(FSFileName * _Nullable contents,
NSError * _Nullable error))reply;
-/**
- * createItemNamed:type:inDirectory:attributes:replyHandler:
- *
- * @brief Create a new file or directory item.
- * @param name new item's name.
- * @param type new item's type. Valid options are FSItemTypeFile, FSItemTypeDirectory.
- * @param directory directory to create the item in.
- * @param newAttributes Desired set of attributes for the new item.
- * @param reply In case of success, should be called with the created item, the
- * item name (as it's saved within the file system), and error = nil.
- * Otherwise, should be called with the relevant error. In that
- * case, newItem and newItemName are ignored. In case there's
- * already an item named "name" in the directory, complete the
- * request with an error with a domain of NSPOSIXErrorDomain and a
- * code of EEXIST.
- */
+/// Creates a new file or directory item.
+///
+/// If an item named `name` already exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `EEXIST`.
+///
+/// - Parameters:
+/// - name: The new item's name.
+/// - type: The new item's type. Valid values are ``FSItem/ItemType/file`` or ``FSItem/ItemType/directory``.
+/// - directory: The directory in which to create the item.
+/// - newAttributes: Attributes to apply to the new item.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass the newly-created ``FSItem`` and its ``FSFileName``, along with a `nil` error. If creation fails, pass the relevant error as the third parameter; FSKit ignores any ``FSItem`` or ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; simply return a tuple of the ``FSItem`` and its ``FSFileName`` or throw an error.
-(void)createItemNamed:(FSFileName *)name
type:(FSItemType)type
inDirectory:(FSItem *)directory
@@ -534,22 +515,16 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(createItem(named:type:inDirectory:attributes:replyHandler:));
-/**
- * createSymbolicLinkNamed:inDirectory:attributes:linkContents:replyHandler:
- *
- * @brief Create a new symbolic link.
- * @param name new item's name.
- * @param directory directory to create the item in.
- * @param newAttributes Desired set of attributes for the new item.
- * @param contents Contents of the new symbolic link.
- * @param reply In case of success, should be called with the created item, the
- * item name (as it's saved within the file system), and error = nil.
- * Otherwise, should be called with the relevant error. In that
- * case, newItem and newItemName are ignored. In case there's
- * already an item named "name" in the directory, complete the
- * request with an error with a domain of NSPOSIXErrorDomain and a
- * code of EEXIST.
- */
+/// Creates a new symbolic link.
+///
+/// If an item named `name` already exists in the directory indicated by `directory`, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `EEXIST`.
+///
+/// - Parameters:
+/// - name: The new item's name.
+/// - directory: The directory in which to create the item.
+/// - newAttributes: Attributes to apply to the new item.
+/// - contents: The contents of the new symbolic link.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass the newly-created ``FSItem`` and a `nil` error. If creation fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItem`` in this case. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItem`` or throw an error.
-(void)createSymbolicLinkNamed:(FSFileName *)name
inDirectory:(FSItem *)directory
attributes:(FSItemSetAttributesRequest *)newAttributes
@@ -559,86 +534,77 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(createSymbolicLink(named:inDirectory:attributes:linkContents:replyHandler:));
-/**
- * createLinkToItem:named:inDirectory:replyHandler:
- *
- * @brief Create a new hard link.
- * @param item existing item to link to.
- * @param name new link name.
- * @param directory directory to create the link in.
- * @param reply In case of success, should be called with the link name (as it's saved within the
- * file system) with error = nil. Otherwise, complete the request with linkName = nil, and an
- * error with a domain of NSPOSIXErrorDomain, and the following error code:
- * EEXIST, in case there's already an item named "name" in the directory.
- * EMLINK, if creating the hard link would result in exceeding the maximum number of hard
- * links supported on item.
- * ENOTSUP, if the file system does not support creating hard links to the type of file system
- * object represented by item.
- */
+/// Creates a new hard link.
+///
+/// If creating the link fails, complete the request with an error with a domain of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and the following error codes:
+///
+/// * `EEXIST` if there's already an item named `name` in the directory.
+/// * `EMLINK` if creating the link would exceed the maximum number of hard links supported on `item`.
+/// * `ENOTSUP` if the file system doesn't support creating hard links to the type of file system object that `item` represents.
+///
+/// - Parameters:
+/// - item: The existing item to which to link.
+/// - name: The name for the new link.
+/// - directory: The directory in which to create the link.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass an ``FSFileName`` of the newly-created link and a `nil` error. If creation 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)createLinkToItem:(FSItem *)item
named:(FSFileName *)name
inDirectory:(FSItem *)directory
replyHandler:(void(^)(FSFileName * _Nullable linkName,
NSError * _Nullable error))reply;
-/**
- * removeItem:named:inDirectory:replyHandler:
- *
- * @brief Remove an existing item.
- * @param item item to remove.
- * @param name item name.
- * @param directory directory to remove the item from.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- * @discussion This method shouldn't actually remove the item object itself, but
- * only remove the given item name from the given directory.
- * The item object should be removed (=deallocated) on reclaimItem.
- */
+/// Removes an existing item from a given directory.
+///
+/// Don't actually remove the item object itself in your implementation; instead, only remove the given item name from the given directory.
+/// Remove and deallocate the item in ``reclaimItem(_:replyHandler:)``.
+///
+/// - Parameters:
+/// - item: The item to remove.
+/// - name: The name of the item to remove.
+/// - directory: The directory from which to remove the item.
+/// - reply: A block or closure to indicate success or failure. If removal fails, pass an error as the one parameter to the reply handler. If removal succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)removeItem:(FSItem *)item
named:(FSFileName *)name
fromDirectory:(FSItem *)directory
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(removeItem(_:named:fromDirectory:replyHandler:));
-/**
- * renameItem:inDirectory:named:toNewName:inDirectory:overItem:replyHandler:
- *
- * @brief This method is used to rename a file system object from one path in the file system to another.
- * @param item The actual file system object being renamed.
- * @param sourceDirectory The directory that currently contains the file system object being renamed.
- * @param sourceName The name within sourceDirectory of the file system object being renamed.
- * @param destinationName The new name of the file system object being renamed within destinationDirectory.
- * @param destinationDirectory The directory that will contain the renamed file system object.
- * Note that this *may* be equal to sourceDirectory.
- * @param overItem The file system object if destination exists and has been looked-up before. Could be nil.
- * In case it is non-nil, it should be marked as 'deleted', so we would free its allocated
- * space on the next reclaim. After doing so, the operation must finish without errors.
- * @param reply In case of success, should be called with the item name (as it's saved within the file system), and error = nil.
- * Otherwise, should be called with the relevant error. In that case, newName is ignored.
- * @discussion The basic algorithm is as follows:
- *
- * If a file move:
- * -- If the destination file exists:
- * -- Remove the destination file.
- * -- If source and destination are in the same directory:
- * -- Rewrite name in existing directory entry.
- * else:
- * -- Write new entry in destination directory.
- * -- Clear old directory entry.
- *
- * If a directory move:
- * -- If destination directory exists:
- * -- If destination directory is not empty, fail the operation
- * with an error with a domain of NSPOSIXErrorDomain and a code of ENOTEMPTY.
- * -- Remove the destination directory.
- * -- If source and destination are in the same directory:
- * -- Rewrite name in existing directory entry.
- * else:
- * -- Be sure the destination is not a child of the source.
- * -- Write new entry in destination directory.
- * -- Update "." and ".." in the moved directory.
- * -- Clear old directory entry.
- */
+/// Renames an item from one path in the file system to another.
+///
+/// Implement renaming along the lines of this algorithm:
+///
+/// - If `item` is a file:
+/// - If the destination file exists:
+/// - Remove the destination file.
+/// - If the source and destination directories are the same:
+/// - Rewrite the name in the existing directory.
+/// - Else:
+/// - Write the new entry in the destination directory.
+/// - Clear the old directory entry.
+/// - If `item` is a directory:
+/// - If the destination directory exists:
+/// - If the destination directory isn't empty:
+/// - Fail the operation with an error of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and a code of `ENOTEMPTY`.
+/// - Else:
+/// - Remove the destination directory.
+/// - If the source and destination directories are the same:
+/// - Rewrite the name in the existing directory.
+/// - Else:
+/// - If the destination is a child of the source directory:
+/// - Fail the operation with an error.
+/// - Else:
+/// - Write the new entry in the destination directory.
+/// - Update `"."` and `".."` in the moved directory.
+/// - Clear the old directory entry.
+///
+/// - Parameters:
+/// - item: The file system object being renamed.
+/// - sourceDirectory: The directory that currently contains the item to rename.
+/// - sourceName: The name of the item within the source directory.
+/// - destinationName: The new name of the item as it appears in `destinationDirectory`.
+/// - destinationDirectory: The directory to contain the renamed object, which may be the same as `sourceDirectory`.
+/// - overItem: The file system object if the destination exists, as discovered in a prior lookup. If this parameter is non-`nil`, mark `overItem` as deleted, so the file system can free its allocated space on the next call to ``reclaimItem(_:replyHandler:)``. After doing so, ensure the operation finishes without errors.
+/// - 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
named:(FSFileName *)sourceName
@@ -649,46 +615,27 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(renameItem(_:inDirectory:named:to:inDirectory:overItem:replyHandler:));
-/**
- * enumerateDirectory:startingAtCookie:verifier:providingAttributes:usingPacker:replyHandler:
- *
- * @brief Enumerate the given directory. Called on readdir(3) and getattrlistbulk(2).
- * Directory entries are returned using the packer's packEntryWithName method.
- * Look at FSDirectoryEntryPacker's definition for further explanation.
- * @param directory directory to enumerate. Guaranteed to be of type FSItemTypeDirectory.
- * @param cookie used to indicate the location within the directory to enumerate from. The cookie values
- * are chosen by the developer; they're opaque to FSKit. The first enumerateDirectory
- * call will have cookie = FSDirectoryCookieInitial. The following calls will have
- * cookie = the "nextCookie" of the last directory entry packed in the previous call.
- * @param verifier a tool with which the developer can use to detect if the directory has been changed
- * since the previous call to enumerateDirectory. The verifier values are chosen by the
- * developer; they're opaque to FSKit. The first enumerateDirectory call will have
- * verifier = FSDirectoryVerifierInitial. The following calls will have verifier = the
- * "currentVerifier" returned from the previous call.
- * @param attributes desired set of attributes to provide. Nil in case no attributes are required.
- * @param packer packer object to pack the directory entries with.
- * @param reply In case of success, should be called with the current verifier and error = nil.
- * Otherwise, should be called with the relevant error. In that case, currentVerifier is ignored.
- * @discussion The general flow of a enumerateDirectory is as follows:
- * When an enumeration is started, enumerateDirectory will be called with initial cookie and
- * verifier values. After packing the initial set of directory entries, enumerateDirectory replies
- * with the new verifier, a non-zero value that reflects the directory's current version.
- * When next called, the next set of directory entries should be packed, starting with the entry
- * associated with cookie. If cookie does not resolve to a valid directory entry, complete the
- * request with an error with a domain of FSKitErrorDomain and a code of
- * FSErrorInvalidDirectoryCookie.
- *
- * The volume implementation must ensure that the directory entries' names packed
- * are acceptable and unambiguous input to all file operations that take names
- * (like lookupName) without additional normalization.
- *
- * Note: In case providingAttributes is nil, there should always be at least two
- * entries in a directory: "." (an entry representing the current directory)
- * and ".." (an entry representing the parent directory).
- * These entries' type is FSItemTypeDirectory. In the case of the root directory
- * of the file system, the returned "." and ".." should have identical contents.
- * In case providingAttributes is not nil, "." and ".." should not be returned.
- */
+/// Enumerates the contents of the given directory.
+///
+/// This method uses the ``FSDirectoryEntryPacker/packEntry(name:itemType:itemID:nextCookie:attributes:)`` method of the `packer` parameter to deliver the enumerated items to the caller.
+/// The general flow of an enumeration implementation follows these steps:
+///
+/// 1. Enumeration starts with a call to `enumerateDirectory` using the initial next-cookie and verifier values ``FSDirectoryCookieInitial`` and ``FSDirectoryVerifierInitial``, respectively.
+/// 2. The implementation uses `packer` to pack the initial set of directory entries. Packing also sets a `nextCookie` to use on the next call.
+/// 3. The implementation replies with a new verifier value, a nonzero value that reflects the directory's current version.
+/// 4. On the next call the implementation packs the next set of entries, starting with the item indicated by `cookie`. If `cookie` doesn't resolve to a valid directory entry, complete the request with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code ``FSError/Code/invalidDirectoryCookie``.
+///
+/// When packing, make sure to use acceptable directory entry names and unambiguous input to all file operations that take names without additional normalization, such as`lookupName`.
+///
+/// > Tip: If the `attributes` parameter is `nil`, include at least two entries in a directory: `"."` and `".."`, which represent the current and parent directories, respectively. Both of these items have type ``FSItem/ItemType/directory``. For the root directory, `"."` and `".."` have identical contents. Don't pack `"."` and `".."` if `attributes` isn't `nil`.
+///
+/// - Parameters:
+/// - directory: The item to enumerate. FSKit guarantees this item is of type ``FSItem/ItemType/directory``.
+/// - cookie: A value that indicates the location within the directory from which to enumerate. Your implementation defines the semantics of the cookie values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryCookieInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `nextCookie` parmeter.
+/// - verifier: A tool to detect whether the directory contents changed since the last call to `enumerateDirectory`. Your implementation defines the semantics of the verifier values; they're opaque to FSKit. The first call to the enumerate method passes ``FSDirectoryVerifierInitial`` for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer's `currentVerifier` parmeter.
+/// - attributes: The desired attributes to provide, or `nil` if the caller doesn't require attributes.
+/// - packer: An object that your implementation uses to enumerate directory items, packing one item per callback to `enumerateDirectory`.
+/// - reply: A block or closure to indicate success or failure. If enumeration succeeds, pass the current verifier and a `nil` error. If enumeration fails, pass the relevant error as the second parameter; FSKit ignores any verifier in this case. For an `async` Swift implementation, there's no reply handler; simply return the current verifier or throw an error.
-(void)enumerateDirectory:(FSItem *)directory
startingAtCookie:(FSDirectoryCookie)cookie
verifier:(FSDirectoryVerifier)verifier
@@ -698,99 +645,87 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:));
-/**
- * activateWithOptions:replyHandler:
- *
- * @brief This method is used to activate this volume instance.
- * @param options activation options. None are currently defined.
- * @param reply In case of success, should be called with the root FSItem, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, rootItem is ignored.
- * @discussion The volume should allocate any in-memory state required to represent the file system.
- * The volume should allocate an item for the root directory of the file system, and pass it to
- * the reply block. FSKit will cache the root item for the lifetime of the volume instance and
- * use it as the jumping off point for all file lookups.
- */
+/// Activates the volume using the specified options.
+///
+/// When FSKit calls this method, allocate any in-memory state required to represent the file system.
+/// Also allocate an ``FSItem`` for the root directory of the file system, and pass it to the reply block.
+/// FSKit caches this root item for the lifetime of the volume, and uses it as a starting point for all file look-ups.
+///
+/// Volume activation occurs prior to any call to mount the volume.
+///
+/// - Parameters:
+/// - options: Options to apply to the activation. These can include security-scoped file paths. There are no defined options currently.
+/// - reply: A block or closure to indicate success or failure. If activation succeeds, pass the root ``FSItem`` and a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores any ``FSItem`` in this case. In Swift, `reply` takes only the ``FSItem`` as the parameter; you signal any error with a `throw`. For an `async` Swift implementation, there's no reply handler; simply return the ``FSItem`` or throw an error.
-(void)activateWithOptions:(FSTaskOptions *)options
replyHandler:(void (^)(FSItem * _Nullable rootItem,
NSError * _Nullable err))reply
NS_SWIFT_NAME(activate(options:replyHandler:));
-/**
- * deactivateWithOptions:replyHandler:
- *
- * @brief This method is used to tear down a previously-initialized volume instance.
- * @param options de-activation options. None are currently defined.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- * @discussion The volume should release any resources allocated for the volume instance.
- * FSKit will guarantee that all other file nodes associated with this file system
- * instance will have been released by a reclaim call. This method should not
- * need to perform any I/O; in cases where that is desired, FSKit will have
- * already issued a sync call to perform cleanup-related I/O.
- */
+/// Tears down a previously initialized volume instance.
+///
+/// Set up your implementation to release any resources allocated for the volume instance.
+/// By the time you receive this callback, FSKit has already performed a reclaim call to release all other file nodes associated with this file system instance.
+///
+/// Avoid performing any I/O in this method.
+/// Prior to calling this method, FSKit has already issued a sync call to perform any
+/// cleanup-related I/O.
+///
+/// FSKit unmounts any mounted volume with a call to ``unmount(replyHandler:)`` prior to the deactivate callback.
+///
+/// - Parameters:
+/// - options: Options to apply to the deactivation.
+/// - reply: A block or closure to indicate success or failure. If activation fails, pass an error as the one parameter to the reply handler. If activation succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)deactivateWithOptions:(FSDeactivateOptions)options
replyHandler:(void (^)(NSError * _Nullable err))reply
NS_SWIFT_NAME(deactivate(options:replyHandler:));
@end
-/**
- * @typedef FSSetXattrPolicy
- * Different flags to dictate the setxattr policy.
- */
+/// Flags to specify the policy when setting extended file attributes.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSUInteger, FSSetXattrPolicy) {
- FSSetXattrPolicyAlwaysSet = 0, /* set the value regardless of previous state */
- FSSetXattrPolicyMustCreate = 1, /* set the value, fail if xattr already exists */
- FSSetXattrPolicyMustReplace = 2, /* set the value, fail if xattr does not exist */
- FSSetXattrPolicyDelete = 3 /* delete the value, fail if xattr does not exist */
+ /// Set the value, regardless of previous state.
+ FSSetXattrPolicyAlwaysSet = 0,
+ /// Set the value, but fail if the extended attribute already exists.
+ FSSetXattrPolicyMustCreate = 1,
+ /// Set the value, but fail if the extended attribute doesn't already exist.
+ FSSetXattrPolicyMustReplace = 2,
+ /// Delete the value, failing if the extended attribute doesn't exist.
+ FSSetXattrPolicyDelete = 3
} NS_SWIFT_NAME(FSVolume.SetXattrPolicy);
-/**
- * @protocol FSVolumeXattrOperations
- * A protocol for volumes which natively (or partially) support extended attributes.
- */
+/// Methods and properties implemented by volumes that natively or partially support extended attributes.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.XattrOperations)
@protocol FSVolumeXattrOperations <NSObject>
-/**
- * @property xattrOperationsInhibited
- * Should be set to 'true' to prevent FSKit from calling this protocol's
- * methods, even though the volume conforms to it.
- * FSKit reads this value (if implemented) after the file system module replies to `loadResource:`.
- * Changing it during the runtime of the volume won't have an effect.
- */
@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property BOOL xattrOperationsInhibited;
-/**
- * supportedXattrNamesForItem:
- * @brief Returns an array that specifies the Xattr names supported by the given item.
- * If the given item does not support any Xattrs, nil should be returned.
- * @param item item to get the info for.
- * @discussion Should only be implemented by volumes which want to have "limited" extended attributes
- * support (volumes which fundamentally do not support extended attributes, but use
- * the extended attribute APIs to expose specific file system data).
- * Note: If implemented, FSKit would assume that there's a partial xattr support, and would
- * only call this protocol's methods for xattr names returned by this method (for each item).
- */
+/// Returns an array that specifies the extended attribute names the given item supports.
+///
+/// If `item` supports no extended attributes, this method returns `nil`.
+///
+/// Only implement this method if your volume works with "limited" extended attributes.
+/// For purposes of this protocol, "limited" support means the volume doesn't support extended attributes generally, but uses these APIs to expose specific file system data.
+///
+/// > Note: If a file system implements this method, FSKit assumes limited support for extended attributes exists. In this mode, FSkit only calls this protocol's methods for the extended attribute names this method returns.
+///
+/// - Parameter item: The item for which to get information.
-(NSArray<FSFileName *> *)supportedXattrNamesForItem:(FSItem *)item;
@required
-/**
- * getXattrNamed:ofItem:replyHandler:
- *
- * @brief Get the specified extended attribute of the given item.
- * @param name extended attribute name.
- * @param item item to get the extended attribute of.
- * @param reply In case of success, should be called with the xattr value, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, value is ignored.
- * In case the given attribute does not exist, complete the request with an error with
- * a domain of NSPOSIXErrorDomain and a code of ENOATTR.
- * @discussion Will only be called for extended attributes supported by the given item.
- */
+/// Gets the specified extended attribute of the given item.
+///
+/// - Parameters:
+/// - name: The extended attribute name.
+/// - item: The item for which to get the extended attribute.
+/// - reply: A block or closure to indicate success or failure. If getting the attribute succeeds, pass an data instance containing the extended attribute data and a `nil` error. If getting the attribute fails, pass the relevant error as the second parameter; FSKit ignores any data in this case. For an `async` Swift implementation, there's no reply handler; simply return the data or throw an error.
-(void)getXattrNamed:(FSFileName *)name
ofItem:(FSItem *)item
replyHandler:(void (^)(NSData * _Nullable value,
@@ -798,17 +733,14 @@
NS_SWIFT_NAME(getXattr(named:of:replyHandler:))
NS_SWIFT_ASYNC_NAME(xattr(named:of:));
-/**
- * setXattrNamed:toData:onItem:policy:replyHandler:
- *
- * @brief Set the specified extended attribute to item.
- * @param name extended attribute name.
- * @param value extended attribute value. It can only be nil in case policy = FSSetXattrPolicyDeleteXattr.
- * @param item item to set the extended attribute to.
- * @param policy creation policy. See FSSetXattrPolicy for further documentation.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- */
+/// Sets the specified extended attribute data on the given item.
+///
+/// - Parameters:
+/// - name: The extended attribute name.
+/// - value: The extended attribute value to set. This can't be `nil`, unless the policy is ``FSVolume/SetXattrPolicy/delete``.
+/// - item: The item on which to set the extended attribute.
+/// - policy: The policy to apply when setting the attribute. See ``FSSetXattrPolicy`` for possible values.
+/// - reply: A block or closure to indicate success or failure. If setting the attribute fails, pass an error as the one parameter to the reply handler. If setting the attribute succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)setXattrNamed:(FSFileName *)name
toData:(NSData * _Nullable)value
onItem:(FSItem *)item
@@ -816,16 +748,12 @@
replyHandler:(void (^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(setXattr(named:to:on:policy:replyHandler:));
-/**
- * listXattrsOfItem:replyHandler:
- *
- * @brief Get the list of extended attributes currently set on the given item.
- * @param item item to get the xattr list for.
- * @param reply In case of success, should be called with the xattr list, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, value is ignored.
- * In case the item doesn't have any extended attributes, reply should be called with an
- * empty array, and error = nil.
- */
+/// Gets the list of extended attributes currently set on the given item.
+///
+/// - Parameters:
+/// - item: The item from which to get extended attributes.
+/// - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass the xattrs as an array of ``FSFileName`` instances and a `nil` error. If getting the attriubtes fails, pass `nil` along with the relevant error. For an `async` Swift implementation, there's no reply handler; simply return the byte count or throw an error.
+
-(void)listXattrsOfItem:(FSItem *)item
replyHandler:(void (^)(NSArray <FSFileName *> * _Nullable value,
NSError * _Nullable error))reply
@@ -833,60 +761,56 @@
@end
+/// Defined modes for opening a file.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSVolumeOpenModes) {
+ /// The read mode.
+ ///
+ /// This mode is equivalent to POSIX `FREAD`.
FSVolumeOpenModesRead = FREAD,
+ /// The write mode.
+ ///
+ /// This mode is equivalent to POSIX `FRWITE`.
FSVolumeOpenModesWrite = FWRITE
} NS_SWIFT_NAME(FSVolume.OpenModes);
-/**
- * @protocol FSVolumeOpenCloseOperations
- * A protocol for open/close. File systems which want to receive open and
- * close calls for each item should conform to this protocol. If this protocol is not
- * implemented, the kernel layer is free to skip making such calls to the volume.
- * When this protocol is implemented, the kernel layer issues an open call to
- * indicate the desired access and a close call to indicate what access to
- * retain. A file is fully closed when the kernel layer issues a close call
- * with no retained open modes. Upon receipt of this close, the file system
- * should remove all accesses to the item. When all memory mappings to the item
- * are released, a final close will be issued by the kernel layer.
- */
+/// Methods and properties implemented by volumes that want to receive open and close calls for each item.
+///
+/// When a file system volume conforms to this protocol, the kernel layer issues an open call to indicate desired access, and a close call to indicate what access to retain.
+/// A file is fully closed when the kernel layer issues a close call with no retained open nodes.
+/// When a file system receives the close call, it removes all access to the item.
+/// When all memory mappings to the item release, the kernel layer issues a final close.
+///
+/// If a file system volume doesn't conform to this protocol, the kernel layer can skip making such calls to the volume.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.OpenCloseOperations)
@protocol FSVolumeOpenCloseOperations <NSObject>
-/**
- * @property openCloseInhibited
- * Should be set to 'true' to prevent FSKit from calling this protocol's
- * methods, even though the volume conforms to it.
- * FSKit reads this value (if implemented) after the file system module replies to `loadResource:`.
- * Changing it during the runtime of the volume won't have an effect.
- */
@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property (getter = isOpenCloseInhibited) BOOL openCloseInhibited;
@required
-/**
- * openItem:withMode:replyHandler:
- *
- * @brief open a file for access.
- * @param modes The set of mode flags to open the item with.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- */
+/// Opens a file for access.
+///
+/// - Parameters:
+/// - item: The item to open.
+/// - modes: The set of mode flags to open the item with.
+/// - reply: A block or closure to indicate success or failure. If opening fails, pass an error as the one parameter to the reply handler. If opening succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)openItem:(FSItem *)item
withModes:(FSVolumeOpenModes)modes
replyHandler:(void (^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(openItem(_:modes:replyHandler:));
-/**
- * closeItem:keepingMode:replyHandler:
- *
- * @brief close a file access
- * @param modes The set of mode flags to keep after this close.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error.
- */
+/// Closes a file from further access.
+///
+/// - Parameters:
+/// - item: The item to close.
+/// - modes: The set of mode flags to keep after this close.
+/// - reply: A block or closure to indicate success or failure. If closing fails, pass an error as the one parameter to the reply handler. If closing succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)closeItem:(FSItem *)item
keepingModes:(FSVolumeOpenModes)modes
replyHandler:(void (^)(NSError * _Nullable error))reply
@@ -894,30 +818,27 @@
@end
-/**
- * @protocol FSVolumeReadWriteOperations
- * A protocol for read and write operations where we deliver data to/from the extension.
- */
+/// Methods implemented for read and write operations that deliver data to and from the extension.
+///
+/// Most volumes conform to either this protocol or ``FSVolumeKernelOffloadedIOOperations``.
+/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
+/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use this protocol, and those without it use ``FSVolumeKernelOffloadedIOOperations``.
+/// A volume that doesn't conform to either protocol can't support any I/O operation.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.ReadWriteOperations)
@protocol FSVolumeReadWriteOperations <NSObject>
-/**
- * readFromFile:offset:length:intoBuffer:replyHandler:
- *
- * @brief Read the contents of the given file item.
- * @param item item to read the contents of. Guaranteed to be of type FSItemTypeFile.
- * @param offset offset in file to start reading from.
- * @param length amount of bytes to read.
- * @param buffer buffer to store the result in.
- * @param reply In case of success, should be called with the amount of bytes read, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, actuallyRead should
- * still contain the amount of bytes read before the error.
- * @discussion If the number of bytes requested exceeds the number of bytes available
- * before the end of the file, then only those bytes are returned. If offset points
- * beyond the last valid byte of the file, the method exit with error = nil and
- * actuallyRead = 0.
- */
+/// Reads the contents of the given file item.
+///
+/// If the number of bytes requested exceeds the number of bytes available before the end of the file, then the call copies only those bytes to `buffer`.
+/// If `offset` points past the last valid byte of the file, don't reply with an error but set `actuallyRead` to `0`.
+///
+/// - Parameters:
+/// - item: The item from which to read. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
+/// - offset: The offset in the file from which to start reading.
+/// - length: The number of bytes to read.
+/// - buffer: A buffer to receive the bytes read from the file.
+/// - reply: A block or closure to indicate success or failure. If reading succeeds, pass the number of bytes read and a `nil` error. If reading fails, pass the number of bytes read prior to the error along with the relevant error. For an `async` Swift implementation, there's no reply handler; simply return the byte count or throw an error.
-(void)readFromFile:(FSItem *)item
offset:(off_t)offset
length:(size_t)length
@@ -926,25 +847,17 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(read(from:at:length:into:replyHandler:));
-/**
- * writeContents:toFile:atOffset:replyHandler:
- *
- * @brief Write contents to the given file item.
- * @param item item to write contents to. Guaranteed to be of type FSItemTypeFile.
- * @param offset offset in file to start writing from.
- * @param contents buffer containing the contents.
- * @param reply In case of success, should be called with the amount of bytes
- * written, and error = nil. Otherwise, should be called with the
- * relevant error. In that case, actuallyWritten should still
- * contain the amount of bytes written before the error. In case
- * no part of the range was successfully written in an out-of-space
- * condition, complete the request with an error with a domain of
- * NSPOSIXErrorDomain and an error code of ENOSPC.
- * @discussion This routine is expected to allocate space in the file system to extend the file as necessary.
- * If the file system runs out of space, but succeeds in writing any part of the requested range,
- * the method should succeed and actuallyWritten should reflect the number of bytes successfully
- * written before space was exhausted.
- */
+/// Writes contents to the given file item.
+///
+/// FSKit expects this routine to allocate space in the file system to extend the file as necessary.
+///
+/// If the volume experiences an out-of-space condition, reply with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code `ENOSPC`.
+///
+/// - Parameters:
+/// - contents: A buffer containing the data to write to the file.
+/// - item: The item to which to write. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
+/// - offset: The offset in the file from which to start writing.
+/// - reply: A block or closure to indicate success or failure. If writing succeeds, pass the number of bytes written and a `nil` error. If writing fails, pass the number of bytes written prior to the error along with the relevant error. For an `async` Swift implementation, there's no reply handler; simply return the byte count or throw an error.
- (void)writeContents:(NSData *)contents
toFile:(FSItem *)item
atOffset:(off_t)offset
@@ -954,61 +867,65 @@
@end
-/**
- * @typedef FSAccessMask
- * A bitmask of access rights.
- */
+/// A bitmask of access rights.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSAccessMask) {
+ /// The file system allows reading data.
FSAccessReadData = (1<<1),
+ /// The file system allows listing directory contents.
FSAccessListDirectory = FSAccessReadData,
+ /// The file system allows writing data.
FSAccessWriteData = (1<<2),
+ /// The file system allows adding files.
FSAccessAddFile = FSAccessWriteData,
+ /// The file system allows file executuion.
FSAccessExecute = (1<<3),
+ /// The file system allows searching files.
FSAccessSearch = FSAccessExecute,
+ /// The file system allows deleting a file.
FSAccessDelete = (1<<4),
+ /// The file system allows appending data to a file.
FSAccessAppendData = (1<<5),
+ /// The file system allows adding subdirectories.
FSAccessAddSubdirectory = FSAccessAppendData,
+ /// The file system allows deleting subdirectories.
FSAccessDeleteChild = (1<<6),
+ /// The file system allows reading file attributes.
FSAccessReadAttributes = (1<<7),
+ /// The file system allows writing file attributes.
FSAccessWriteAttributes = (1<<8),
+ /// The file system allows reading extended file attributes.
FSAccessReadXattr = (1<<9),
+ /// The file system allows writing extended file attributes.
FSAccessWriteXattr = (1<<10),
+ /// The file system allows reading a file's security descriptors.
FSAccessReadSecurity = (1<<11),
+ /// The file system allows writing a file's security descriptors.
FSAccessWriteSecurity = (1<<12),
+ /// The file system allows taking ownership of a file.
FSAccessTakeOwnership = (1<<13),
} NS_SWIFT_NAME(FSVolume.AccessMask);
-/**
- * @protocol FSVolumeAccessCheckOperations
- * A protocol for access check operations.
- */
+/// Methods and properties implemented by volumes that want to enforce access check operations.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.AccessCheckOperations)
@protocol FSVolumeAccessCheckOperations <NSObject>
-/**
- * @property accessCheckInhibited
- * Should be set to 'true' to prevent FSKit from calling this protocol's
- * methods, even though the volume conforms to it.
- * FSKit reads this value (if implemented) after the file system module replies to `loadResource:`.
- * Changing it during the runtime of the volume won't have an effect.
- */
@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property (getter = isAccessCheckInhibited) BOOL accessCheckInhibited;
@required
-/**
- * checkAccessToItem:requestedAccess:replyHandler:
- *
- * @brief Check if the requested access for the given item is allowed.
- * @param theItem item to check access for.
- * @param access requested set of access types to check.
- * @param reply In case of success, should be called with the result, and error = nil.
- * result = 0: access is allowed
- * result = EACCES: access is denied.
- * Otherwise, should be called with the relevant error. In that case, result is ignored.
- */
+
+/// Checks whether the file system allows access to the given item.
+///
+/// - Parameters:
+/// - theItem: The item for which to check access.
+/// - access: A mask indicating a set of access types for which to check.
+/// - reply: A block or closure to indicate success or failure. If the access check succeeds, pass a Boolean value to indicate whether the file system grants access, followed by a `nil` error. If the access check fails, pass the relevant error as the second parameter; FSKit ignores the Boolean parameter in this case. For an `async` Swift implementation, there's no reply handler; simply return the `Bool` or throw an error.
-(void)checkAccessToItem:(FSItem *)theItem
requestedAccess:(FSAccessMask)access
replyHandler:(void(^)(BOOL shouldAllowAccess,
@@ -1016,86 +933,76 @@
@end
-/**
- * @protocol FSVolumeRenameOperations
- * A protocol for volume rename operations.
- */
+/// Methods and properties implemented by volumes that support renaming the volume.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.RenameOperations)
@protocol FSVolumeRenameOperations <NSObject>
-/**
- * @property volumeRenameInhibited
- * Should be set to 'true' to prevent FSKit from calling this protocol's
- * methods, even though the volume conforms to it.
- * FSKit reads this value (if implemented) after the file system module replies to `loadResource:`.
- * Changing it during the runtime of the volume won't have an effect.
- */
@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property (getter = isVolumeRenameInhibited) BOOL volumeRenameInhibited;
@required
-/**
- * setVolumeName:replyHandler:
- *
- * @brief Set a new name for the volume.
- * @param name New volume name.
- * @param reply In case of success, should be called with the new name, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, newName is ignored.
- */
+/// Sets a new name for the volume.
+///
+/// - Parameters:
+/// - name: The new volume name.
+/// - reply: A block or closure to indicate success or failure. If renaming succeeds, pass an ``FSFileName`` of the new volume name 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)setVolumeName:(FSFileName *)name
replyHandler:(void(^)(FSFileName *newName,
NSError * _Nullable error))reply;
@end
-/**
- * @typedef FSPreallocateFlags
- * Different flags for the preallocate operations.
- */
+/// Behavior flags for preallocation operations.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSPreallocateFlags) {
- /** Allocate contiguous space */
+ /// Allocates contiguous space.
FSPreallocateFlagsContiguous = 0x00000002,
- /** Allocate all requested space or no space at all */
+ /// Allocates all requested space or no space at all.
FSPreallocateFlagsAll = 0x00000004,
- /** Allocate space that is not freed when close(2) is called. */
+ /// Allocates space that isn't freed when deleting the descriptor.
+ ///
+ /// This space remains allocated even after calling `close(2)`.
FSPreallocateFlagsPersist = 0x00000008,
- /** Allocate from the physical end of file. Offset should be ignored in this case.
- Currently set for all `preallocateSpaceForItem` calls. */
+ /// Allocates space from the physical end of file.
+ ///
+ /// When implementing this behavior, ignore any offset in the preallocate call.
+ /// This flag is currently set for all ``FSVolume/PreallocateOperations/preallocateSpace(for:at:length:flags:replyHandler:)`` calls.
FSPreallocateFlagsFromEOF = 0x00000010,
} NS_SWIFT_NAME(FSVolume.PreallocateFlags);
-/**
- * @protocol FSVolumePreallocateOperations
- * A protocol for preallocate operations.
- */
+/// Methods and properties implemented by volumes that want to offer preallocation functions.
+///
+/// A preallocation operation allocates space for a file without writing to it yet.
+/// A file system may use reallocation to avoid performing space allocation while in the midst of I/O; this strategy improves performance.
+/// Also, if the expected I/O pattern is many small writes, preallocating contiguous chunks may prevent fragmenting the file system.
+/// This process can improve performance later.
+///
+/// In a kernel-based file system, you typically preallocate space with the `VNOP_ALLOCATE` operation, called from `fcntl(F_PREALLOCATE)`.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.PreallocateOperations)
@protocol FSVolumePreallocateOperations <NSObject>
-/**
- * @property preallocateInhibited
- * Should be set to 'true' to prevent FSKit from calling this protocol's
- * methods, even though the volume conforms to it.
- * FSKit reads this value (if implemented) after the filesystem module replies to `loadResource:`.
- * Changing it during the runtime of the volume won't have an effect.
- */
@optional
+/// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property (getter = isPreallocateInhibited) BOOL preallocateInhibited;
-/**
- * preallocateSpaceForItem:atOffset:length:flags:replyHandler:
- *
- * @brief Preallocate disk space for an item.
- * @param item The item for which to preallocate space
- * @param offset The offset from which to allocate
- * @param length The length of the space in bytes
- * @param flags Preallocate flags
- * @param reply In case of success, should be called with the amount of bytes allocated, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, bytesAllocated is ignored.
- */
@required
+/// Prealocates disk space for the given item.
+///
+/// - Parameters:
+/// - item: The item for which to preallocate space.
+/// - offset: The offset from which to allocate.
+/// - length: The length of the space in bytes.
+/// - flags: Flags that affect the preallocation behavior.
+/// - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass the amount of bytes allocated and a `nil` error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores any byte count in this case. For an `async` Swift implementation, there's no reply handler; simply return the allocated byte count or throw an error.
-(void)preallocateSpaceForItem:(FSItem *)item
atOffset:(off_t)offset
length:(size_t)length
@@ -1106,59 +1013,54 @@
@end
-/**
- * @typedef FSItemDeactivationOptions
- * Options to communicate the FSVolumeItemDeactivation policy. `deactivateItem:` processing blocks
- * the kernel, to enable the file system to take action at a definitive point in the item's life cycle.
- * FSItemDeactivationOptions allows the file system to instruct the FSKit kernel which circumstances require
- * the expense of a round trip call to the module.
- * - `FSItemDeactivationNever` causes FSKit to not issue `deactivateItem:` calls at all, even
- * though the volume conforms to `FSVolumeItemDeactivation`.
- * - `FSItemDeactivationAlways` supports cases when the file system needs `deactivateItem:`
- * calls in all circumstances. These circumstances may include ones added to FSKit in the future.
- * - `FSItemDeactivationForRemovedItems` supports processing for open-unlinked items at the
- * moment of last close.
- * - `FSItemDeactivationForPreallocatedItems` supports processing for files with preallocated
- * space, facilitating a form of trim-on-close. Only has a meaning for volumes which conform to
- * `FSVolumePreallocateOperations`.
- */
+/// Options to specify the item deactivation policy.
+///
+/// Callers may want to set a deactivation policy because ``FSVolume/ItemDeactivation/deactivateItem(_:replyHandler:)`` 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.
+///
+/// > Note: To avoid performing deactivation calls, Objective-C developers use the value `FSItemDeactivationNever`. In Swift, use an empty option set (`[]`).
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSItemDeactivationOptions) {
+ /// An option to never perform deactivation.
+ ///
+ /// With this deactivation option, FSKit never issues `deactivateItem` calls, even though the volume conforms to ``FSVolume/ItemDeactivation``.
FSItemDeactivationNever = 0,
+ /// An option to always perform deactivation calls.
+ ///
+ /// Use this option if the file system needs `deactivateItem` calls in circumstances beyond those covered by ``forRemovedItems`` and ``forPreallocatedItems``.
FSItemDeactivationAlways = NSUIntegerMax, // all bits
+ /// An option to process deactivation for open-unlinked items at the moment of last close.
FSItemDeactivationForRemovedItems = (1 << 0),
+ /// An option to process deactivation for for files with preallocated space.
+ ///
+ /// This option facilitates a sort of trim-on-close behavior.
+ /// It is only meaningful for volumes that conform to ``FSVolume/PreallocateOperations``.
FSItemDeactivationForPreallocatedItems = (1 << 1),
} NS_SWIFT_NAME(FSVolume.ItemDeactivationOptions);
-/**
- * @protocol FSVolumeItemDeactivation
- * A protocol for the item deactivation operation.
- */
+/// Methods and properties implemented by volumes that support deactivating items.
FSKIT_API_AVAILABILITY_V1
NS_SWIFT_NAME(FSVolume.ItemDeactivation)
@protocol FSVolumeItemDeactivation <NSObject>
-/**
- * @property itemDeactivationPolicy
- * Tell FSKit for which type of items (if at all) `deactivateItem:` should be called.
- * FSKit reads this value after the file system module replies to `loadResource:`. Changing it during the
- * runtime of the volume won't have an effect.
- */
+/// A property that tells FSKit to which types of items the deactivation applies, if any.
+///
+/// FSKit reads this value after the file system replies to the `loadResource` message.
+/// Changing the returned value during the runtime of the volume has no effect.
@property (readonly) FSItemDeactivationOptions itemDeactivationPolicy;
-/**
- * deactivateItem:replyHandler:
- *
- * @brief Notify the file system that the given item is no longer in immediate use by the kernel.
- * @param item item to deactivate.
- * @param reply In case of success, should be called with error = nil.
- * Otherwise, should be called with the relevant error. The error
- * will be logged and ignored.
- * @discussion This method gives a file system a chance to release resources associated with an item, but
- * no action is prescribed; it is acceptable to defer all reclamation until reclaimItem. This call is the FSKit's
- * equivalent of VFS's `VNOP_INACTIVE`. Will be called according to the chosen
- * FSVolumeDeactivationOptions policy.
- */
+/// Notifies the file system that the kernel is no longer making immediate use of the given item.
+///
+/// This method gives a file system a chance to release resources associated wtih an item.
+/// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Operations/reclaimItem(_:replyHandler:)``.
+/// This method is the equivalent of VFS's `VNOP_INACTIVE`.
+///
+/// FSKit restricts calls to this method based on the current value of ``FSVolume/ItemDeactivation/itemDeactivationPolicy``.
+///
+/// - Parameters:
+/// - item: The item to deactivate.
+/// - reply: A block or closure to indicate success or failure. If deactivation fails, pass an error as the one parameter to the reply handler. If deactivation succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
-(void)deactivateItem:(FSItem *)item
replyHandler:(void(^)(NSError * _Nullable error))reply
NS_SWIFT_NAME(deactivateItem(_:replyHandler:));
diff -ruN /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h
--- /Applications/Xcode_16.3.0-beta2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h 2025-02-26 06:45:24
+++ /Applications/Xcode_16.3.0-beta3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/Headers/FSVolumeExtent.h 2025-03-13 05:31:30
@@ -28,25 +28,29 @@
FSKIT_API_AVAILABILITY_V1
FS_EXPORT FSOperationID const FSOperationIDUnspecified;
-/**
- * @typedef FSBlockmapFlags
- * Different flags for the blockmap operation.
- */
+/// Flags that describe the behavior of a blockmap operation.
+///
+/// This type is an option set in Swift.
+/// In Objective-C, you use the cases of this enumeration to create a bit field.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSBlockmapFlags) {
+ /// A flag that describes a read operation.
FSBlockmapFlagsRead = 0x000100,
+ /// A flag that describes a write operation.
FSBlockmapFlagsWrite = 0x000200,
};
-/**
- * @typedef FSCompleteIOFlags
- * Different flags for the completeIO operation.
- */
+/// Flags that describe the behavior of an I/O completion operation.
+///
+/// This type is an option set in Swift.
+/// In Objective-C, the cases of this enumeration combine to create a bit field.
FSKIT_API_AVAILABILITY_V1
typedef NS_OPTIONS(NSUInteger, FSCompleteIOFlags) {
+ /// A flag that describes a read operation.
FSCompleteIOFlagsRead = FSBlockmapFlagsRead,
+ /// A flag that describes a write operation.
FSCompleteIOFlagsWrite = FSBlockmapFlagsWrite,
- /* Requests the file system module to flush the metadata IO asynchronously */
+ /// A flag that requests that the file system module flush metadata I/O asynchronously.
FSCompleteIOFlagsAsync = 0x000400,
};
@@ -54,69 +58,42 @@
* @typedef FSExtentType
* Possible extent types.
*/
+
+/// An enumeration of types of extents.
FSKIT_API_AVAILABILITY_V1
typedef NS_ENUM(NSInteger, FSExtentType) {
- /**
- * The extent contains valid data.
- * For file systems which do not support sparse files, all extents should be of type FSExtentTypeData.
- * The kernel keeps track of EOF, so it knows that the range of [EOF, allocated space] is uninitialized.
- * So it is valid to pass an extent type of FSExtentTypeData for this range.
- */
+ /// An extent type to indicate valid data.
+ ///
+ /// Use this type for all extents on a file system that doesn't support sparse files.
+ ///
+ /// > Tip: The kernel keeps track of the end of file, so it knows a range of `[EOF, allocated space]` is uninitialized. Because of this behavior, it's valid to pass the data extent type for such a range.
FSExtentTypeData = 0,
- /**
- * The extent contains uninitialized data.
- * Should be in use only for file systems which support sparse files, for ranges in the file were not
- * allocated yet.
- */
+
+ /// An extent type to indicate uninitialized data.
+ ///
+ /// Only use this extent type in file systems that support sparse files, and only then to represent ranges in the file that aren't allocated yet.
FSExtentTypeZeroFill = 1,
};
-/**
- * @interface FSExtentPacker
- * Extents are used to describe to the kernel parts of the space on disk assigned to a specific file.
- * That space is described by a physical offset on disk, a length and a logical offset within the file.
- * The extent packer takes this information and packs the extent so FSKit can pass it to the kernel.
- */
+/// A type that directs the kernel to map space on disk to a specific file managed by this file system.
+///
+/// _Extents_ provide the kernel the logical-to-physical mapping of a given file.
+/// An extent describes a physical offset on disk, and a length and a logical offset within the file.
+/// Rather than working with extents directly, you use this type's methods to provide or "pack" extent information, which FSKit then passes to the kernel.
FSKIT_API_AVAILABILITY_V1
@interface FSExtentPacker : NSObject
- (instancetype)init NS_UNAVAILABLE;
-/**
- * @method packExtentWithResource:type:logicalOffset:physicalOffset:length:
- *
- * @brief Pack a single extent to be sent to the kernel.
- * @param resource volume's resource to perform the IO from/to
- * @param type extent type
- * @param logicalOffset extent offset, in bytes, within the file
- * @param physicalOffset extent offset, in bytes, on disk
- * @param length extent length in bytes
- * @return YES if more extents can be packed, else NO.
- *
- * Example usage (an example how to pack multiple extents in a for loop)
- ```
- - (void)packExtentsExample:(FSExtentPacker *)packer
- resource:(FSBlockDeviceResource *)resource
- {
- size_t length = 0;
- off_t logOffset = 0;
- off_t phyOffset = 1000;
- for (int i = 0; i < 10; i++) {
- length = (i+1)*100;
- if([packer packExtentWithResource:resource
- type:FSExtentTypeData
- logicalOffset:logOffset
- physicalOffset:phyOffset
- length:length] == NO) {
- break;
- }
- logOffset += length;
- phyOffset += length;
- }
- }
- ```
- *
- */
+/// Packs a single extent to send to the kernel.
+///
+/// - Parameters:
+/// - resource: The resource on which to perform I/O.
+/// - type: The type of extent, indicating whether it contains valid data.
+/// - logicalOffset: The extent offset within the file, in bytes.
+/// - physicalOffset: The extent offset on disk, in bytes.
+/// - length: The extent length, in bytes.
+/// - Returns: A Boolean value that indicates whether the packer can pack more extents.
- (BOOL)packExtentWithResource:(FSBlockDeviceResource *)resource
type:(FSExtentType)type
logicalOffset:(off_t)logicalOffset
@@ -126,38 +103,43 @@
@end
-/**
- * @protocol FSVolumeKernelOffloadedIOOperations
- * A protocol of Kernel Offloaded IO operations.
- */
+/// Methods and properties implemented by volumes that use kernel-offloaded I/O to achieve higher file transfer performance.
+///
+/// A volume that conforms to this protocol supplies file extent mappings to FSKit, which allows file transfers to take place in the kernel.
+/// This approach provides higher-performance file transfer than transferring data between the module and kernel, while still allowing the file system to run in user space.
+///
+/// This protocol uses _extents_ to provide the kernel the logical-to-physical mapping of a given file.
+/// An extent describes a physical offset on disk, and a length and a logical offset within the file.
+/// You don't manage extents directly.
+/// Instead, FSKit provides you with an ``FSExtentPacker`` to define and pack the extents in your implementations of this protocol's methods.
+///
+/// Most volumes conform to either this protocol or ``FSVolumeReadWriteOperations``.
+/// You can conform to both if you need to provide kernel-offloaded I/O only for certain files.
+/// In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO`` attribute set use ``FSVolumeReadWriteOperations``, and those without it use this protocol.
+/// A volume that doesn't conform to either protocol can't support any I/O operation.
FSKIT_API_AVAILABILITY_V1
@protocol FSVolumeKernelOffloadedIOOperations <NSObject>
#pragma mark - Kernel Offloaded IO operations
-/**
- * @method blockmapFile:range:flags:operationID:packer:replyHandler:
- *
- * @brief Map a file's disk space into extents for the kernel to perform I/O on.
- * @param file The file whose disk space will be mapped.
- * @param offset Starting logical offset of the range to be mapped (in bytes).
- * @param length Length of the range to be mapped (in bytes).
- * @param flags Different flags for the blockmap operation.
- * @param operationID A unique identifier of the blockmap call.
- * operationID != FSOperationIDUnspecified means an I/O operation is beginning,
- * for which we need to map the file. completeIO will be issued with the same ID
- * supplied in the operationID parameter.
- * operationID == FSOperationIDUnspecified means that the kernel maps the file
- * without issuing an I/O. There will not be a corresponding completeIO call in this
- * case, as no I/O is done. In both cases the mapping will be retained in the kernel.
- * In the case where satisfying a block map request requires more extents than can
- * be packed, subsequent request(s) will be issued with the same operation ID for
- * the remainder.
- * @param packer An extent packer to pack the requested range of the file's allocated disk space.
- * FSKit will send all of the packed extents to the kernel when reply is called.
- * @param reply In case of success, should be called with error = nil. Otherwise, should be called
- * with the relevant error.
- */
+/// Maps a file's disk space into extents, allowing the kernel to perform I/O with that space.
+///
+/// FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file's data.
+/// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of a `fcntl(F_LOG2PHYS)` system call.
+/// In the case of an I/O operation on the file, `operationID` has a nonzero value; a future call to ``completeIO(for:offset:length:status:flags:operationID:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
+/// In the case of a `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
+/// In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.
+///
+/// If satisfying a blockmap request requires more extents than `packer` can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.
+///
+/// - Parameters:
+/// - file: The file for which to map disk space.
+/// - offset: The starting logical offset of the range to be mapped (in bytes).
+/// - length: The length of the range to be mapped (in bytes).
+/// - flags: Flags that affect the behavior of the blockmap operation.
+/// - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) indicates the beginning of an I/O operation. A value of `0` or ``FSOperationID/unspecified`` indicates the kernel maps the file without performing I/O. In this case, FSKit doesn't perform a corresponding call to ``completeIO(for:offset:length:status:flags:operationID: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 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
offset:(off_t)offset
length:(size_t)length
@@ -166,24 +148,21 @@
packer:(FSExtentPacker *)packer
replyHandler:(void (^)(NSError * _Nullable error))reply;
-/**
- * @method completeIOForFile:range:status:flags:operationID:replyHandler:
- *
- * @brief Complete the I/O operation.
- * Called to update the file's metadata, such as its size and modification time, once the I/O operation is done.
- * @param file The file for which I/O was done
- * @param offset logical byte offset at which I/O started
- * @param length length of I/O range in bytes
- * @param status If nil, I/O was successful. Else, it indicates the error
- * @param flags Different flags for the completeIO operation.
- * @param operationID A unique identifier of the specific I/O operation
- * @param reply In case of success, should be called with error = nil. Otherwise, should be called
- * with the relevant error.
- * @discussion Note that completeIO is not necessarily coupled with a blockmap operation. completeIO
- * can be called for I/O completion on a range previously supplied to the kernel. In that case, operationID
- * will be FSOperationIDUnspecified. A different operationID means that an I/O operation begun via
- * blockmapFile with the same operationID has been completed.
- */
+/// Completes an I/O operation for a given file.
+///
+/// Implement this method by updating a file's metadata, such as its size and modification time.
+///
+/// FSKit may call this method without an earlier call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// In this case, the `operationID` is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
+///
+/// - Parameters:
+/// - file: The file for which the I/O operation completed.
+/// - offset: The starting logical offset at which I/O started.
+/// - length: The length of the I/O range (in bytes).
+/// - status: Any error that occurred during the operation. If no error occurred, this parameter is `nil`.
+/// - flags: Flags that affect the behavior of the complete I/O operation.
+/// - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) corresponds to a previous call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)`` with the same `operationID`.
+/// - 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
length:(size_t)length
@@ -201,22 +180,22 @@
* method.
*/
-/**
- * @method createFileNamed:inDirectory:attributes:packer:replyHandler:
- *
- * @brief Create a new file item, and map its disk-space
- * @param name new file's name
- * @param directory directory to create the file in
- * @param attributes Desired set of attributes for the new file
- * @param packer An extent packer to pack the file's allocated disk space
- * @param reply In case of success, should be called with the created file, the file's name (as it's saved
- * within the file system), and error = nil. Otherwise, should be called with the relevant error.
- * In that case, newFile and newFileName are ignored. In case there's already an item
- * named "name" in the directory, complete the request with an error with a domain of
- * NSPOSIXErrorDomain and a code of EEXIST.
- * @discussion Packing extents in this method is only possible if `attributes` define a size > 0.
- * It should be done opportunistically; Do not perform additional IO to fetch extent data.
- */
+/// Creates a new file item and map its disk space.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// Only perform this technique opportunistically.
+/// In particular, don't perform additional I/O to fetch extent data.
+///
+/// Packing extents in this method requires that `attributes` defines a size greater than 0.
+///
+/// An implementation that doesn't supply the extents can ignore the packer and call the corresponding method in the ``FSVolume/Operations`` protocol, ``FSVolume/Operations/createItem(named:type:inDirectory:attributes:replyHandler:)``.
+///
+/// - Parameters:
+/// - name: The new file's name.
+/// - directory: The directory in which to create the file.
+/// - attributes: Attributes to apply to the new file.
+/// - packer: An extent packer you use to pack the file's allocated disk space.
+/// - reply: A block or closure to indicate success or failure. If creation succeeds, pass the newly created ``FSItem`` and its ``FSFileName``, along with a `nil` error. If creation fails, pass the relevant error as the third parameter; FSKit ignores any ``FSItem`` or ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; instead, return a tuple of the ``FSItem`` and its ``FSFileName`` or throw an error.
- (void)createFileNamed:(FSFileName *)name
inDirectory:(FSItem *)directory
attributes:(FSItemSetAttributesRequest *)attributes
@@ -226,21 +205,17 @@
NSError * _Nullable error))reply
NS_SWIFT_NAME(createFile(name:in:attributes:packer:replyHandler:));
-/**
- * @method lookupItemNamed:inDirectory:packer:replyHandler:
- *
- * @brief Lookup an item within a directory, and map its disk-space
- * @param name item name to lookup
- * @param directory directory to look the item in
- * @param packer An extent packer to pack the item's allocated disk space
- * @param reply In case of success, should be called with the found item,
- * the item name (as it's saved within the file system), and error = nil.
- * Otherwise, should be called with the relevant error. In that case, theItem and itemName are ignored.
- * If the entry does not exist, complete the request with an error
- * with a domain of NSPOSIXErrorDomain and a code of ENOENT.
- * @discussion Packing extents in this method should be done opportunistically; Do not perform additional
- * IO to fetch extent data.
- */
+/// Looks up an item within a directory and maps its disk space.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+/// Only perform this technique opportunistically.
+/// In particular, don't perform additional I/O to fetch extent data.
+///
+/// - Parameters:
+/// - name: The name of the file to look up.
+/// - directory: The directory in which to look up the file.
+/// - packer: An extent packer you use to pack the file's allocated disk space.
+/// - reply: A block or closure to indicate success or failure. If lookup succeeds, pass the found ``FSItem`` and its ``FSFileName``, along with a `nil` error. If lookup fails, pass the relevant error as the third parameter; FSKit ignores any ``FSItem`` or ``FSFileName`` in this case. For an `async` Swift implementation, there's no reply handler; instead, return a tuple of the ``FSItem`` and its ``FSFileName`` or throw an error.
- (void)lookupItemNamed:(FSFileName *)name
inDirectory:(FSItem *)directory
packer:(FSExtentPacker *)packer
@@ -251,21 +226,21 @@
#pragma mark - extent-supplying version of preallocate
-/* Should only be implemented for volumes which conform to FSVolumePreallocateOperations. */
@optional
-/**
- * @method preallocateSpaceForFile:atOffset:length:flags:packer:replyHandler:
- *
- * @brief Preallocate disk space for a file.
- * @param file The file for which to preallocate space
- * @param offset The offset from which to allocate
- * @param length The length of the space in bytes
- * @param flags Preallocate flags
- * @param packer An extent packer to pack the preallocated space
- * @param reply In case of success, should be called with the amount of bytes allocated, and error = nil.
- * Otherwise, should be called with the relevant error. In that case, bytesAllocated is ignored.
- * @discussion This method should only be implemented for volumes which conform to FSVolumePreallocateOperations.
- */
+
+/// Preallocates and maps disk space for the given file.
+///
+/// This method allows the module to opportunistically supply extents, avoiding future calls to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
+///
+/// > Important: Only implement this method if your file system conforms to ``FSVolume/PreallocateOperations``.
+///
+/// - Parameters:
+/// - file: The item for which to preallocate space.
+/// - offset: The offset from which to allocate.
+/// - length: The length of the space in bytes.
+/// - flags: Flags that affect the preallocation behavior.
+/// - packer: An extent packer you use to pack the file's preallocated disk space.
+/// - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass the amount of bytes allocated and a nil error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores any byte count in this case. For an `async` Swift implementation, there’s no reply handler; simply return the allocated byte count or throw an error.
- (void)preallocateSpaceForFile:(FSItem *)file
atOffset:(off_t)offset
length:(size_t)length