Struct FSBlockDeviceResource

#[repr(C)]
pub struct FSBlockDeviceResource { /* private fields */ }

Available on crate feature FSResource only.

A resource that represents a block storage disk partition.

A FSBlockDeviceResource can exist in either a proxied or nonproxied version. Only the fskitd daemon creates “real” (nonproxied) instances of this class. Client applications and daemons create proxy objects for requests, and fskitd opens the underlying device during the processing of the request.

This class wraps a file descriptor for a disk device or partition. Its fundamental identifier is the BSD disk name (bsdName) for the underlying IOMedia object. However, FSBlockDeviceResource-c.class doesn’t expose the underlying file descriptor. Instead, it provides accessor methods that can read from and write to the partition, either directly or using the kernel buffer cache.

When you use a FSBlockDeviceResource, your file system implementation also conforms to a maintenance operation protocol. These protocols add support for checking, repairing, and optionally formatting file systems. The system doesn’t mount block device file systems until they pass a file system check. For an FSUnaryFileSystem that uses FSBlockDeviceResource, conform to FSManageableResourceMaintenanceOperations.

See also Apple’s documentation

Implementations

impl FSBlockDeviceResource

pub unsafe fn BSDName(&self) -> Retained<NSString>

The device name of the resource.

pub unsafe fn isWritable(&self) -> bool

A Boolean property that indicates whether the resource can write data to the device.

pub unsafe fn blockSize(&self) -> u64

The logical block size, the size of data blocks used by the file system.

This is equivalent to the DKIOCGETBLOCKSIZE device parameter.

pub unsafe fn blockCount(&self) -> u64

The block count on this resource.

pub unsafe fn physicalBlockSize(&self) -> u64

The sector size of the device.

This is equivalent to the DKIOCGETPHYSICALBLOCKSIZE device parameter.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn readInto_startingAt_length_completionHandler( &self, buffer: NonNull<c_void>, offset: off_t, length: usize, completion_handler: &DynBlock<dyn Fn(usize, *mut NSError)>, )

Available on crate features block2 and libc only.

Reads data from the resource into a buffer and executes a block afterwards.

For the read to succeed, requests must conform to any transfer requirements of the underlying resource. Disk drives typically require sector (physicalBlockSize) addressed operations of one or more sector-aligned offsets.

• Parameters:
• buffer: A buffer to receive the data.
• offset: The offset into the resource from which to start reading.
• length: A maximum number of bytes to read. The completion handler receives a parameter with the actual number of bytes read.
• completionHandler: A block that executes after the read operation completes. If successful, the first parameter contains the number of bytes actually read. In the case of an error, the second parameter contains a non-nil error. This value is EFAULT if buffer is NULL, or errno if reading from the resource failed.

pub unsafe fn writeFrom_startingAt_length_completionHandler( &self, buffer: NonNull<c_void>, offset: off_t, length: usize, completion_handler: &DynBlock<dyn Fn(usize, *mut NSError)>, )

Available on crate features block2 and libc only.

Writes data from from a buffer to the resource and executes a block afterwards.

For the write to succeed, requests must conform to any transfer requirements of the underlying resource. Disk drives typically require sector (physicalBlockSize) addressed operations of one or more sector-aligned offsets.

• Parameters:
• buffer: A buffer to provide the data.
• offset: The offset into the resource from which to start writing.
• length: A maximum number of bytes to write. The completion handler receives a parameter with the actual number of bytes write.
• completionHandler: A block that executes after the write operation completes. If successful, the first parameter contains the number of bytes actually written. In the case of an error, the second parameter contains a non-nil error. This value is EFAULT if buffer is NULL, or errno if writing to the resource failed.

pub unsafe fn metadataReadInto_startingAt_length_error( &self, buffer: NonNull<c_void>, offset: off_t, length: usize, ) -> Result<(), Retained<NSError>>

Available on crate feature libc only.

Synchronously reads file system metadata from the resource into a buffer.

This method provides access to the Kernel Buffer Cache, which is the primary system cache for file system metadata. Unlike equivalent kernel APIs, this method doesn’t hold any kernel-level claim to the underlying buffers.

For the read to succeed, requests must conform to any transfer requirements of the underlying resource. Disk drives typically require sector (physicalBlockSize) addressed operations of one or more sector-aligned offsets.

This method doesn’t support partial reading of metadata.

• Parameters:

• buffer: A buffer to receive the data.

• offset: The offset into the resource from which to start reading.

• length: The number of bytes to read.

• error: On return, any error encountered while reading data, or nil if no error occurred.

• Returns: A Boolean value indicating whether the metadata read succeeded.

pub unsafe fn metadataWriteFrom_startingAt_length_error( &self, buffer: NonNull<c_void>, offset: off_t, length: usize, ) -> Result<(), Retained<NSError>>

Available on crate feature libc only.

Synchronously writes file system metadata from a buffer to the resource.

This method provides access to the Kernel Buffer Cache, which is the primary system cache for file system metadata. Unlike equivalent kernel APIs, this method doesn’t hold any kernel-level claim to the underlying buffers.

For the write to succeed, requests must conform to any transfer requirements of the underlying resource. Disk drives typically require sector (physicalBlockSize) addressed operations of one or more sector-aligned offsets.

This method doesn’t support partial writing of metadata.

• Parameters:

• buffer: A buffer to provide the data.

• offset: The offset into the resource from which to start writing.

• length: The number of bytes to writing.

• error: On return, any error encountered while writing data, or nil if no error occurred.

• Returns: A Boolean value indicating whether the metadata write succeeded.

pub unsafe fn delayedMetadataWriteFrom_startingAt_length_error( &self, buffer: NonNull<c_void>, offset: off_t, length: usize, ) -> Result<(), Retained<NSError>>

Available on crate feature libc only.

Writes file system metadata from a buffer to a cache, prior to flushing it to the resource.

This method provides access to the Kernel Buffer Cache, which is the primary system cache for file system metadata. Unlike equivalent kernel APIs, this method doesn’t hold any kernel-level claim to the underlying buffers.

This method is equivalent to metadataWriteFrom:startingAt:length:error:, except that it writes data to the resource’s buffer cache instead of writing to disk immediately. To ensure writing data to disk, the client must flush the metadata by calling metadataFlushWithError: or asynchronousMetadataFlushWithError:.

Delayed writes offer two significant advantages:

• Delayed writes are more performant, since the file system can avoid waiting for the actual write, reducing I/O latency.
• When writing to a specific range repeatedly, delayed writes allow the file system to flush data to the disk only when necessary. This reduces disk usage by eliminating unnecessary writes.

For the write to succeed, requests must conform to any transfer requirements of the underlying resource. Disk drives typically require sector (physicalBlockSize) addressed operations of one or more sector-aligned offsets.

This method doesn’t support partial writing of metadata.

• Parameters:

• buffer: A buffer to provide the data.

• offset: The offset into the resource from which to start writing.

• length: The number of bytes to writing.

• error: On return, any error encountered while writing data, or nil if no error occurred.

• Returns: A Boolean value indicating whether the metadata write succeeded.

pub unsafe fn metadataFlushWithError(&self) -> Result<(), Retained<NSError>>

Synchronously flushes the resource’s buffer cache.

This method flushes data previously written with delayedMetadataWriteFrom:startingAt:length:error: to the resource.

• Parameter error: On return, any error encountered while writing data, or nil if no error occurred.

• Returns: A Boolean value indicating whether the metadata flush succeeded.

pub unsafe fn asynchronousMetadataFlushWithError( &self, ) -> Result<(), Retained<NSError>>

Asynchronously flushes the resource’s buffer cache.

This method schedules a flush of data previously written with delayedMetadataWriteFrom:startingAt:length:error: to the resource and returns immediately without blocking. This method doesn’t wait to check the flush’s status. If an error prevents the flush from being scheduled, the error is indicated by the in-out error parameter.

• Parameter error: On return, any error encountered while writing data, or nil if no error occurred.

• Returns: A Boolean value indicating whether scheduling the metadata flush succeeded.

pub unsafe fn metadataClear_withDelayedWrites_error( &self, ranges_to_clear: &NSArray<FSMetadataRange>, with_delayed_writes: bool, ) -> Result<(), Retained<NSError>>

Clears the given ranges within the buffer cache.

This method clears the specified ranges in the resource’s buffer cache by writing zeroes into them.

• Parameters:

• rangesToClear: The metadata ranges to clear.

• withDelayedWrites: A Boolean value that determines whether to perform the clear operation with delayed writes. The delay works in the same manner as delayedMetadataWriteFrom:startingAt:length:error:. When using delayed writes, the client can flush the metadata with metadataFlushWithError: or asynchronousMetadataFlushWithError:. The system also flushes stale data in the buffer cache periodically.

• error: On return, any error encountered while writing data, or nil if no error occurred. This value is EINVAL if rangesToClear is invalid.

• Returns: A Boolean value indicating whether clearing the metadata succeeded.

pub unsafe fn metadataPurge_error( &self, ranges_to_purge: &NSArray<FSMetadataRange>, ) -> Result<(), Retained<NSError>>

Synchronously purges the given ranges from the buffer cache.

This method removes the given ranges from the resource’s buffer cache. This process drops any dirty data in the cache, preventing the data from reaching the device.

• Parameters:

• rangesToPurge: The metadata ranges to purge.

• error: On return, any error encountered while writing data, or nil if no error occurred. This value is EINVAL if rangesToPurge is invalid.

• Returns: A Boolean value indicating whether purging the metadata succeeded.

impl FSBlockDeviceResource

Methods declared on superclass NSObject.

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = FSResource>

pub unsafe fn isRevoked(&self) -> bool

A Boolean value that indicates whether the resource is revoked.

If this is a proxy resource, the value of this property is always true (Swift) or YES (Objective-C).

pub unsafe fn makeProxy(&self) -> Retained<Self>

Creates a proxy object of this resource.

If you create a proxy from a proxy resource, this method returns a copy of the proxy.

pub unsafe fn revoke(&self)

Revokes the resource.

This method works by stripping away any underlying privileges associated with the resource. This effectively disconnects this object from its underlying resource.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for FSBlockDeviceResource

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<FSBlockDeviceResource> for FSBlockDeviceResource

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<FSResource> for FSBlockDeviceResource

fn as_ref(&self) -> &FSResource

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for FSBlockDeviceResource

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for FSBlockDeviceResource

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<FSResource> for FSBlockDeviceResource

fn borrow(&self) -> &FSResource

Immutably borrows from an owned value.

impl Borrow<NSObject> for FSBlockDeviceResource

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for FSBlockDeviceResource

const NAME: &'static str = "FSBlockDeviceResource"

The name of the Objective-C class that this type represents.

type Super = FSResource

The superclass of this class.

type ThreadKind = <<FSBlockDeviceResource as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for FSBlockDeviceResource

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for FSBlockDeviceResource

type Target = FSResource

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for FSBlockDeviceResource

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for FSBlockDeviceResource

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for FSBlockDeviceResource

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl NSSecureCoding for FSBlockDeviceResource

unsafe fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for FSBlockDeviceResource

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for FSBlockDeviceResource

const ENCODING_REF: Encoding = <FSResource as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for FSBlockDeviceResource

impl Eq for FSBlockDeviceResource

impl NSCoding for FSBlockDeviceResource