Trait GenFS

pub trait GenFS: Send + Sync {
    type DirBuilder: DirBuilder;
    type DirEntry: DirEntry;
    type File: File;
    type Metadata: Metadata;
    type OpenOptions: OpenOptions;
    type Permissions: Permissions;
    type ReadDir: Iterator<Item = Result<Self::DirEntry>> + Debug;

    // Required methods
    fn canonicalize<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>;
    fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        from: P,
        to: Q,
    ) -> Result<u64>;
    fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>;
    fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>;
    fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        src: P,
        dst: Q,
    ) -> Result<()>;
    fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>;
    fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self::ReadDir>;
    fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>;
    fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>;
    fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>;
    fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>;
    fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        from: P,
        to: Q,
    ) -> Result<()>;
    fn set_permissions<P: AsRef<Path>>(
        &self,
        path: P,
        perm: Self::Permissions,
    ) -> Result<()>;
    fn symlink_metadata<P: AsRef<Path>>(
        &self,
        path: P,
    ) -> Result<Self::Metadata>;
    fn new_openopts(&self) -> Self::OpenOptions;
    fn new_dirbuilder(&self) -> Self::DirBuilder;
    fn open_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>;
    fn create_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>;
}

The single filesystem underpinning all filesystem operations.

This trait intends to be a near drop in replacement for most uses of std::fs. As with std::fs, all methods in this trait are cross-platform. Extra platform specific functionality can be found in the extension traits of rsfs::$platform_ext.

Examples

The normal, disk backed filesystem:

use rsfs::*;

let fs = rsfs::disk::FS;

An in-memory filesystem with Unix extensions:

use rsfs::*;
use rsfs::unix_ext::*;
use rsfs::mem::FS;

let fs = FS::with_mode(0o300);

Required Associated Types

type DirBuilder: DirBuilder

The DirBuilder type in the same module implementing this trait.

type DirEntry: DirEntry

The DirEntry type in the same module implementing this trait.

type File: File

The File type in the same module implementing this trait.

type Metadata: Metadata

The Metadata type in the same module implementing this trait.

type OpenOptions: OpenOptions

The OpenOptions type in the same module implementing this trait.

type Permissions: Permissions

The Permissions type in the same module implementing this trait.

type ReadDir: Iterator<Item = Result<Self::DirEntry>> + Debug

The ReadDir type in the same module implementing this trait.

Required Methods

fn canonicalize<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Returns the canonical form of a path with all intermediate components normalized and symbolic links resolved.

Errors

While there may be more error cases, this function will error in the following cases:

• path does not exist
• A component in path` is not a directory

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let path = fs.canonicalize("../a/../foo.txt")?;

fn copy<P: AsRef<Path>, Q: AsRef<Path>>(&self, from: P, to: Q) -> Result<u64>

Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.

Note that this function will overwrite the contents of to and, if from and to are the same file, the file will likely be truncated by this function.

On success, the total number of bytes copied is returned.

Errors

While there may be more error cases, this function will error in the following cases:

• from is not a file
• from does not exist
• User lacks permissions to access from or write to

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.copy("foo.txt", "bar.txt")?; // Copy foo.txt to bar.txt

fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

Creates a new, empty directory at the provided path.

Errors

While there may be more error cases, this function will error in the following cases:

• path exists
• User lacks permissions to create a directory at path

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.create_dir("/some/dir")?;

fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>

Recursively creates a directory and all its parent components if they are missing.

Errors

While there may be more error cases, this function will error in the following cases:

• User lacks permissions to create any directories in path

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.create_dir_all("/some/dir")?;

fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>( &self, src: P, dst: Q, ) -> Result<()>

Creates a new hard link on the filesystem.

The dst path will be a link pointing to the src path.

Errors

While there may be more error cases, this function will error in the following cases:

• The src path is not a file or does not exist.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.hard_link("a.txt", "b.txt")?; // Hard link a.txt to b.txt

fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>

Returns metadata information of the file or directory at path.

This function will traverse symbolic links to query a directory or file.

Errors

While there may be more error cases, this function will error in the following cases:

• User lacks permissions to call metadata on path
• path does not exist

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let attr = fs.metadata("/some/file/path.txt")?;
// inspect attr...

fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self::ReadDir>

Returns an iterator over entries within a directory.

The iterator yields instances of io::Result::DirEntry. New errors may be encountered after the iterator is initially constructed.

Errors

While there may be more error cases, this function will error in the following cases:

• path does not exist
• path is not a directory
• User lacks permissions to read the directory at path

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

for entry in fs.read_dir("/")? {
    println!("{:?}", entry?.path());
}

fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Reads a symbolic link, returning the entry the link points to.

Errors

While there may be more error cases, this function will error in the following cases:

• path does not exist
• path is not a symbolic link

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let path = fs.read_link("foo")?;

fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes an existing, empty directory.

Errors

While there may be more error cases, this function will error in the following cases:

• path is not a directory
• User lacks permissions to remove the directory at path
• The directory is not empty

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.remove_dir("/some/dir")?;

fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes a directory at path after removing all of its contents.

Errors

See remove_dir and remove_file.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.remove_dir_all("/some/dir")?;

fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes a file from the filesystem.

Errors

While there may be more error cases, this function will error in the following cases:

• path is a directory
• User lacks permissions to remove the file at path

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.remove_file("a.txt")?;

fn rename<P: AsRef<Path>, Q: AsRef<Path>>(&self, from: P, to: Q) -> Result<()>

Renames a file or directory at from to to, replacing to if it exists.

Platform-specific behavior

Behavior differs between Unix and Windows. On Unix, if from is a directory, to must also be an (empty) directory. If from is not a directory, to must not be a directory. On Windows, from can be anything, but to must not be a directory.

Errors

While there may be more error cases, this function will error in the following cases:

• from does not exist
• User lacks permissions to rename from
• from and to are on separate filesystems

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

fs.rename("a.txt", "b.txt")?;

fn set_permissions<P: AsRef<Path>>( &self, path: P, perm: Self::Permissions, ) -> Result<()>

Changes the permissions of a file or directory.

Errors

While there may be more error cases, this function will error in the following cases:

• path does not exist
• User lacks permissions to changes the attributes of the entry at path

Examples

use rsfs::*;
use rsfs::unix_ext::*;
use rsfs::mem::{FS, Permissions};
let fs = FS::new();

fs.set_permissions("foo.pem", Permissions::from_mode(0o400))?;

fn symlink_metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>

Query the metadata about a file without following symlinks.

Errors

While there may be more error cases, this function will error in the following cases:

• User lacks permissions to call symlink_metadata on path
• path does not exist

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let attr = fs.symlink_metadata("/some/file/path.txt")?;
// inspect attr...

fn new_openopts(&self) -> Self::OpenOptions

Returns a new OpenOptions for a file for this filesytem.

This method replaces std::fs::OpenOptions::new(), which now needs to be a part of this trait to ensure any new file belongs to the GenFS that created the OpenOptions.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let mut options = fs.new_openopts();
let file = options.read(true).open("foo.txt")?;

fn new_dirbuilder(&self) -> Self::DirBuilder

Returns a new DirBuilder for a directory for this filesystem.

This method replaces std::fs::DirBuilder::new(), which now needs to be a part of this trait to ensure any new directory belongs to the GenFS that created the DirBuilder.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let mut builder = fs.new_dirbuilder();

fn open_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>

Opens a file in read-only mode.

This method replaces std::fs::File::open(), which now needs to be a part of this trait to ensure that the opened file belongs to the calling GenFS.

See OpenOptions::open for more details.

Errors

This function will return an error if path does not exist. Other errors may be returned according to OpenOptions::open.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let mut file = fs.open_file("foo.txt")?;

fn create_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>

Opens a file in write-only mode.

This method replaces std::fs::File::create(), which now needs to be a part of this trait to ensure that the created file belongs to the calling GenFS.

This function will create a file if it does not exist and truncate it if it does.

See OpenOptions::create for more details.

Examples

use rsfs::*;
use rsfs::mem::FS;
let fs = FS::new();

let mut file = fs.create_file("foo.txt")?;

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl GenFS for rsfs::disk::FS

type DirBuilder = DirBuilder

type DirEntry = DirEntry

type File = File

type Metadata = Metadata

type OpenOptions = OpenOptions

type Permissions = Permissions

type ReadDir = ReadDir

impl GenFS for rsfs::mem::FS

type DirBuilder = DirBuilder

type DirEntry = DirEntry

type File = File

type Metadata = Metadata

type OpenOptions = OpenOptions

type Permissions = Permissions

type ReadDir = ReadDir

impl GenFS for rsfs::mem::unix::FS

type DirBuilder = DirBuilder

type DirEntry = DirEntry

type File = File

type Metadata = Metadata

type OpenOptions = OpenOptions

type Permissions = Permissions

type ReadDir = ReadDir