SystemFileHandle
An implementation of FileHandleProtocol which is backed by system calls and a file descriptor.
This declaration is gated by at least one @_spi attribute.
- iOS
- 13.0+
- macOS
- 10.15+
- tvOS
- 13.0+
- watchOS
- 6.0+
final class SystemFileHandleAn implementation of FileHandleProtocol which is backed by system calls and a file descriptor.
This declaration is gated by at least one @_spi attribute.
final class SystemFileHandleimport _NIOFileSystemprotocol FileHandleProtocolA handle for a file system object.
protocol CopyableA type whose values can be implicitly or explicitly copied.
protocol DirectoryFileHandleProtocol : FileHandleProtocolA handle suitable for directories.
protocol Escapableprotocol ReadableFileHandleProtocol : FileHandleProtocolA handle for reading data from an open file.
protocol SendableA thread-safe type whose values can be shared across arbitrary concurrent contexts without introducing a risk of data races. Values of the type may have no shared mutable state, or they may protect that state with a lock or by forcing it to only be accessed from a specific actor.
protocol WritableFileHandleProtocol : FileHandleProtocolA file handle suitable for writing.
init(takingOwnershipOf descriptor: FileDescriptor, path: FilePath, materialization: SystemFileHandle.Materialization? = nil, threadPool: NIOThreadPool) Creates a handle which takes ownership of the provided descriptor.
static func syncOpenWithMaterialization(atPath path: FilePath, mode: FileDescriptor.AccessMode, options originalOptions: FileDescriptor.OpenOptions, permissions: FilePermissions?, threadPool: NIOThreadPool, useTemporaryFileIfPossible: Bool = true) -> Result<SystemFileHandle, FileSystemError> let sendableView: SystemFileHandle.SendableViewfunc addPermissions(_ permissions: FilePermissions) async throws -> FilePermissions func attributeNames() async throws -> [String] func close() async throws func close(makeChangesVisible: Bool) async throws func detachUnsafeFileDescriptor() throws -> FileDescriptor func info() async throws -> FileInfo func listContents(recursive: Bool) -> DirectoryEntries func openDirectory(atPath path: FilePath, options: OpenOptions.Directory) async throws -> SystemFileHandle func openFile(forReadingAndWritingAt path: FilePath, options: OpenOptions.Write) async throws -> SystemFileHandle func openFile(forReadingAt path: FilePath, options: OpenOptions.Read) async throws -> SystemFileHandle func openFile(forWritingAt path: FilePath, options: OpenOptions.Write) async throws -> SystemFileHandle func readChunk(fromAbsoluteOffset offset: Int64, length: ByteCount) async throws -> ByteBuffer func readChunks(in range: Range<Int64>, chunkLength size: ByteCount) -> FileChunks func removePermissions(_ permissions: FilePermissions) async throws -> FilePermissions func removeValueForAttribute(_ name: String) async throws func replacePermissions(_ permissions: FilePermissions) async throws func resize(to size: ByteCount) async throws func setTimes(lastAccess: FileInfo.Timespec?, lastDataModification: FileInfo.Timespec?) async throws func synchronize() async throws func updateValueForAttribute(_ bytes: some RandomAccessCollection<UInt8> & Sendable, attribute name: String) async throws func valueForAttribute(_ name: String) async throws -> [UInt8] func withUnsafeDescriptor<R>(_ execute: @escaping (FileDescriptor) throws -> R) async throws -> R where R : Sendable @discardableResult func write(contentsOf bytes: some Sendable & Sequence<UInt8>, toAbsoluteOffset offset: Int64) async throws -> Int64 struct Materializationstruct SendableViewThe file handle may be for a non-seekable file, so it shouldn’t be ‘Sendable’, however, most of the work performed on behalf of the handle is executed in a thread pool which means that its state must be ‘Sendable’.
enum UpdatePermissionsOperationtypealias ReadFileHandle = SystemFileHandletypealias ReadWriteFileHandle = SystemFileHandletypealias WriteFileHandle = SystemFileHandlefunc bufferedReader(startingAtAbsoluteOffset initialOffset: Int64 = 0, capacity: ByteCount = .kibibytes(512)) -> BufferedReader<Self> Creates a new BufferedReader for this file handle.
func bufferedWriter(startingAtAbsoluteOffset initialOffset: Int64 = 0, capacity: ByteCount = .kibibytes(512)) -> BufferedWriter<Self> Creates a new BufferedWriter for this file handle.
func listContents() -> DirectoryEntries Returns an AsyncSequence of entries in the open directory.
func readChunks(chunkLength: ByteCount = .kibibytes(128)) -> FileChunks Returns an asynchronous sequence of chunks read from the file.
func readToEnd(fromAbsoluteOffset offset: Int64 = 0, maximumSizeAllowed: ByteCount) async throws -> ByteBuffer Returns the contents of a file by loading it into memory.
func setLastAccessTime(to time: FileInfo.Timespec) async throws Sets the file’s last access time to the given time.
func setLastDataModificationTime(to time: FileInfo.Timespec) async throws Sets the file’s last data modification time to the given time.
func touch() async throws Sets the file’s last access and last data modification times to the current time.
func withBufferedWriter<Result>(startingAtAbsoluteOffset initialOffset: Int64 = 0, capacity: ByteCount = .kibibytes(512), execute body: (inout BufferedWriter<Self>) async throws -> Result) async throws -> Result Convenience function that creates a buffered reader, executes the closure that writes the contents into the buffer and calls ‘flush()’.
func withDirectoryHandle<Result>(atPath path: FilePath, options: OpenOptions.Directory = OpenOptions.Directory(), execute body: (Self) async throws -> Result) async throws -> Result Opens the directory at the given path and provides scoped access to it.
func withFileHandle<Result>(forReadingAndWritingAt path: FilePath, options: OpenOptions.Write = .newFile(replaceExisting: false), execute body: (Self.ReadWriteFileHandle) async throws -> Result) async throws -> Result Opens the file at the given path and provides scoped read-write access to it.
func withFileHandle<Result>(forReadingAt path: FilePath, options: OpenOptions.Read = OpenOptions.Read(), execute body: (Self.ReadFileHandle) async throws -> Result) async throws -> Result Opens the file at the given path and provides scoped read access to it.
func withFileHandle<Result>(forWritingAt path: FilePath, options: OpenOptions.Write = .newFile(replaceExisting: false), execute body: (Self.WriteFileHandle) async throws -> Result) async throws -> Result Opens the file at the given path and provides scoped write access to it.
@discardableResult func write(contentsOf buffer: ByteBuffer, toAbsoluteOffset offset: Int64) async throws -> Int64 Write the readable bytes of the ByteBuffer to the open file.