sys::fs - Filesystem Operations
The sys::fs module provides functions for reading, writing, and watching files and directories.
Interface
use sys::io::{Read, Lines, Write, Close};
type FileType = [
`Dir,
`File,
`Symlink,
`SymlinkDir,
`BlockDev,
`CharDev,
`Fifo,
`Socket,
null
];
type Metadata = {
accessed: [datetime, null],
created: [datetime, null],
modified: [datetime, null],
kind: FileType,
len: u64,
permissions: [u32, `ReadOnly(bool)]
};
type DirEntry = {
path: string,
file_name: string,
depth: i64,
kind: FileType
};
type Mode = [`Read, `Write, `Append, `ReadWrite, `Create, `CreateNew];
type SeekFrom = [`Start(u64), `End(i64), `Current(i64)];
/// An open file. It reads, writes, seeks, and closes.
type File;
/// A handle with a position in a finite resource.
trait Seek {
/// Seek to a position. Returns the new position.
val seek: fn(self, pos: SeekFrom) -> Result<u64, `IOError(string)>;
};
impl Read for File;
impl Lines for File;
impl Write for File;
impl Close for File;
impl Seek for File;
mod watch;
mod tempdir;
/// Read the specified file into memory as a utf8 string and return it, or an
/// error if,
/// - path is not a file
/// - path is not valid utf8
/// - an OS specific error occurs while trying to read path
val read_all: fn(path: string) -> Result<string, `IOError(string)>;
/// Read the specified file into memory as a bytes and return it, or an
/// error if,
/// - path is not a file
/// - an OS specific error occurs while trying to read path
val read_all_bin: fn(path: string) -> Result<bytes, `IOError(string)>;
/// Write data to path. If path does not exist it will be created. If path exists it
/// will be truncated and it's contents will be replaced with data.
val write_all: fn(#path: string, data: string) -> Result<null, `IOError(string)>;
/// Write data to path. If path does not exist it will be created. If path exists it
/// will be truncated and it's contents will be replaced with data.
val write_all_bin: fn(#path: string, data: bytes) -> Result<null, `IOError(string)>;
/// if path is a file then return path
/// otherwise return an IOError.
val is_file: fn(path: string) -> Result<string, `IOError(string)>;
/// if path is a directory then return path, otherwise return an IOError.
val is_dir: fn(path: string) -> Result<string, `IOError(string)>;
/// Return the metadata for a filesystem object, or an error.
val metadata: fn(?#follow_symlinks: bool, path: string) -> Result<Metadata, `IOError(string)>;
/// readdir reads a directory and returns an array of directory entries.
val readdir: fn(
?#max_depth: i64,
?#min_depth: i64,
?#contents_first: bool,
?#follow_symlinks: bool,
?#follow_root_symlink: bool,
?#same_filesystem: bool,
path: string
) -> Result<Array<DirEntry>, `IOError(string)>;
/// create a directory. If all is true (default false) create all intermediate
/// directories as well.
val create_dir: fn(?#all: bool, path: string) -> Result<null, `IOError(string)>;
/// remove a directory. If all is true (default false) then recursively remove
/// the contents as well.
val remove_dir: fn(?#all: bool, path: string) -> Result<null, `IOError(string)>;
/// remove a file
val remove_file: fn(path: string) -> Result<null, `IOError(string)>;
/// Open a file with the specified mode.
val open: fn(mode: Mode, path: string) -> Result<File, `IOError(string)>;
/// Get metadata for the open file.
val fstat: fn(file: File) -> Result<Metadata, `IOError(string)>;
/// Truncate or extend the file to the specified length.
val truncate: fn(file: File, len: u64) -> Result<null, `IOError(string)>;
An open File reads, writes and closes through the sys::io
traits, and seeks through Seek:
use sys::{fs::{Seek, open}, io::{Close, Read, Write}};
let f = open(`Create, path)?;
let written = Write::write_exact(f, buffer::from_string("hello"))?;
let rewound = Seek::seek(f, written ~ `Start(u64:0))?;
let text = buffer::to_string(Read::read_all(rewound ~ f)?)?;
Close::close(text ~ f)?
sys::fs::watch
/// The type of file system events you are interested in.
/// The short names, e.g. `Access mean ANY kind of access event.
/// The longer names e.g. `AccessOpen mean a more specific subset
/// of the short named class event. There are sometimes multiple
/// levels of this. For example `Modify expresses interest in
/// any modification, `ModifyRename expresses interest in any
/// kind of rename operation, and `ModifyRenameTo expresses interest
/// only on rename to.
///
/// `Established is a special event that happens when the watch is
/// successfully established
type Interest = [
`Established,
`Any,
`Access,
`AccessOpen,
`AccessClose,
`AccessRead,
`AccessOther,
`Create,
`CreateFile,
`CreateFolder,
`CreateOther,
`Modify,
`ModifyData,
`ModifyDataSize,
`ModifyDataContent,
`ModifyDataOther,
`ModifyMetadata,
`ModifyMetadataAccessTime,
`ModifyMetadataWriteTime,
`ModifyMetadataPermissions,
`ModifyMetadataOwnership,
`ModifyMetadataExtended,
`ModifyMetadataOther,
`ModifyRename,
`ModifyRenameTo,
`ModifyRenameFrom,
`ModifyRenameBoth,
`ModifyRenameOther,
`ModifyOther,
`Delete,
`DeleteFile,
`DeleteFolder,
`DeleteOther,
`Other
];
type WatchEvent = {
paths: Array<string>,
event: Interest
};
/// An opaque handle to a filesystem watcher. Cleaned up when
/// no remaining references exist.
type Watcher;
/// An opaque handle to a single watch. Use path() and events()
/// to extract values from watch events.
type Watch;
/// Create a filesystem watcher.
///
/// poll_interval: How often to poll a batch, must be >= 100ms. default 1s.
/// poll_batch_size: How many files to poll per batch, must be >= 0. default 100.
val create: fn(
?#poll_interval:[duration, null],
?#poll_batch_size:[i64, null],
trigger: Any
) -> Result<Watcher, `WatchError(string)>;
/// Watch path for events matching #interest using the given watcher.
/// watch updates when,
/// - an event occurs that matches interest
/// - an error occurs when trying to establish the watch
///
/// If you wish to know when the watch is established, you must express interest
/// in the `Established event (which is in the default set). If you do so, you will
/// also get a new established event if you change the interest or the path.
///
/// If path is a directory the watch will report events about immediate children.
/// If the watch could not be established establishement will be retried every
/// time path updates
///
/// Filesystem watches are a limited operating system resource, like file
/// descriptors, or handles.
val watch: fn(?#interest: Array<Interest>, watcher: Watcher, path: string)
-> Result<Watch, `WatchError(string)>;
/// The path of the filesystem object involved in the most recent
/// watch event. Updates reactively when new events arrive.
/// Accepts a single Watch, an Array of Watches, or a Map with Watch values.
/// When given a collection, flattens to a single stream — fires when
/// any watch in the collection fires.
val path: fn(@args: [Watch, Array<Watch>, Map<'k, Watch>]) -> Result<string, `WatchError(string)>;
/// The full watch event including all paths and the event type.
/// Updates reactively when new events arrive.
/// Same collection handling as path().
val events: fn(@args: [Watch, Array<Watch>, Map<'k, Watch>]) -> Result<WatchEvent, `WatchError(string)>;
sys::fs::tempdir
/// An opaque handle to a temporary directory. The directory is
/// automatically deleted when there are no remaining references
/// to the TempDir value.
type T;
/// Get the filesystem path of a TempDir as a string.
val path: fn(td: T) -> string;
/// Create a temporary directory and return a tempdir::T handle.
/// The directory will be cleaned up when the tempdir::T value is
/// no longer referenced.
///
/// if `in` is specified, the temporary directory will be created as a child of `in`
///
/// if `name` is specified, the temporary directory will have either a prefix of name
/// or a suffix of name.
val create: fn(
?#in:[null, string],
?#name:[null, `Prefix(string), `Suffix(string)],
trigger: Any
) -> Result<T, `IOError(string)>;