_NIOFileSystem

Overview

This module implements a file system library for Swift, providing ways to interact with and manage files. It provides a concrete FileSystem for interacting with the local file system in addition to a set of protocols for creating other file system implementations.

_NIOFileSystem is cross-platform with the following caveats:

• Platforms don’t have feature parity or system-level API parity. Where this is the case these implementation details are documented. One example is copying files, on Apple platforms files are cloned if possible.

• Features may be disabled on some systems. One example is extended attributes.

• Some types have platform specific representations. These include the following:

  • File paths on Apple platforms and Linux (e.g. "/Users/hal9000/") are different to paths on Windows ("C:\Users\hal9000").

  • Information about files is different on different platforms. See FileInfo for further details.

A Brief Tour

The following sample code demonstrates a number of the APIs offered by this module:

// NIOFileSystem provides access to the local file system via the FileSystem
// type which is available as a global shared instance.
let fileSystem = FileSystem.shared

// Files can be inspected by using 'info':
if let info = try await fileSystem.info(forFileAt: "/Users/hal9000/demise-of-dave.txt") {
    print("demise-of-dave.txt has type '\(info.type)'")
} else {
    print("demise-of-dave.txt doesn't exist")
}

// Let's find out what's in that file.
do {
    // Reading a whole file requires a limit. If the file is larger than the limit
    // then an error is thrown. This avoids accidentally consuming too much memory
    // if the file is larger than expected.
    let plan = try await ByteBuffer(
        contentsOf: "/Users/hal9000/demise-of-dave.txt",
        maximumSizeAllowed: .mebibytes(1)
    )
    print("Plan for Dave's demise:", String(decoding: plan.readableBytesView, as: UTF8.self))
} catch let error as FileSystemError where error.code == .notFound {
    // All errors thrown by the module have type FileSystemError (or
    // Swift.CancellationError). It looks like the file doesn't exist. Let's
    // create it now.
    //
    // The code above for reading the file is shorthand for opening the file in
    // read-only mode and then reading its contents. The FileSystemProtocol
    // has a few different 'withFileHandle' methods for opening a file in different
    // modes. Let's open a file for writing, creating it at the same time.
    try await fileSystem.withFileHandle(
        forWritingAt: "/Users/hal9000/demise-of-dave.txt",
        options: .newFile(replaceExisting: false)
    ) { file in
        let plan = ByteBuffer(string: "TODO...")
        try await file.write(contentsOf: plan.readableBytesView, toAbsoluteOffset: 0)
    }
}

// Directories can be opened like regular files but they cannot be read from or
// written to. However, their contents can be listed:
let path: FilePath? = try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Music") { directory in
    for try await entry in directory.listContents() {
        if entry.name.extension == "mp3", entry.name.stem.contains("daisy") {
            // Found it!
            return entry.path
        }
    }
    // No luck.
    return nil
}

if let path = path {
    print("Found file at '\(path)'")
}

// The file system can also be used to perform the following operations on files
// and directories:
// - copy,
// - remove,
// - rename, and
// - replace.
//
// Here's an example of copying a directory:
try await fileSystem.copyItem(at: "/Users/hal9000/Music", to: "/Volumes/Tardis/Music")

// Symbolic links can also be created (and read with 'destinationOfSymbolicLink(at:)').
try await fileSystem.createSymbolicLink(at: "/Users/hal9000/Backup", withDestination: "/Volumes/Tardis")

// Opening a symbolic link opens its destination so in most cases there's no
// need to read the destination of a symbolic link:
try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Backup") { directory in
    // Beyond listing the contents of a directory, the directory handle provides a
    // number of other functions, many of which are also available on regular file
    // handles.
    //
    // This includes getting information about a file, such as its permissions, last access time,
    // and last modification time:
    let info = try await directory.info()
    print("The directory has permissions '\(info.permissions)'")

    // Where supported, the extended attributes of a file can also be accessed, read, and modified:
    for attribute in try await directory.attributeNames() {
        let value = try await directory.valueForAttribute(attribute)
        print("Extended attribute '\(attribute)' has value '\(value)'")
    }

    // Once this closure returns the file system will close the directory handle freeing
    // any resources required to access it such as file descriptors. Handles can also be opened
    // with the 'openFile' and 'openDirectory' APIs but that places the onus you to close the
    // handle at an appropriate time to avoid leaking resources.
}

In depth documentation can be found in the following sections.

Interacting with the Local File System

• struct FileSystem

  A file system which interacts with the local system. The file system uses a thread pool to perform system calls.

• struct FileHandle

  Implements FileHandleProtocol by making system calls to interact with the local file system.

• struct ReadFileHandle

  Implements ReadableFileHandleProtocol by making system calls to interact with the local file system.

• struct WriteFileHandle

  Implements WritableFileHandleProtocol by making system calls to interact with the local file system.

• struct ReadWriteFileHandle

  Implements ReadableAndWritableFileHandleProtocol by making system calls to interact with the local file system.

• struct DirectoryFileHandle

  Implements DirectoryFileHandleProtocol by making system calls to interact with the local file system.

• func withFileSystem<Result>(numberOfThreads: Int, (FileSystem) async throws -> Result) async throws -> Result

  Provides temporary scoped access to a FileSystem with the given number of threads.

File and Directory Information

• struct FileInfo

  Information about a file system object.

• struct FileType

  The type of a file system object.

Reading Files

• struct FileChunks

  An AsyncSequence of ordered chunks read from a file.

• struct BufferedReader<Handle>

  A reader which maintains a buffer of bytes read from the file.

Writing Files

• struct BufferedWriter<Handle>

  A writer which buffers bytes in memory before writing them to the file system.

Listing Directories

• struct DirectoryEntry

  Information about an item within a directory.

• struct DirectoryEntries

  An AsyncSequence of entries in a directory.

Errors

FileSystemError is the only top-level error type thrown by the package (apart from Swift’s CancellationError).

• struct FileSystemError

  An error thrown as a result of interaction with the file system.

• struct SystemCallError

  An error resulting from a system call.

Creating a File System

Custom file system’s can be created by implementing FileSystemProtocol which depends on a number of other protocols. These include the following:

• protocol FileSystemProtocol

  The interface for interacting with a file system.

• protocol FileHandleProtocol

  A handle for a file system object.

• protocol ReadableFileHandleProtocol

  A handle for reading data from an open file.

• protocol WritableFileHandleProtocol

  A file handle suitable for writing.

• typealias ReadableAndWritableFileHandleProtocol

  A file handle which is suitable for reading and writing.

• protocol DirectoryFileHandleProtocol

  A handle suitable for directories.