file

import std::fs::file; · source

File#

type struct File {
    fd: i32;

    static open(p: Path) -> Result<File, IoError>;
    static create(p: Path) -> Result<File, IoError>;
    static open_with(p: Path, options: &OpenOptions) -> Result<File, IoError>;
    seek_set(mut &this, offset: i64) -> Result<u64, IoError>;
    seek_cur(mut &this, offset: i64) -> Result<u64, IoError>;
    seek_end(mut &this, offset: i64) -> Result<u64, IoError>;
    stream_position(mut &this) -> Result<u64, IoError>;
}

function read(p: Path) -> Result<Array<u8>, IoError>;
function read_to_string(p: Path) -> Result<String, IoError>;
function write(p: Path, bytes: Slice<u8>) -> Result<(), IoError>;
function copy(from: Path, to: Path) -> Result<u64, IoError>;

import std::fs::file;
import std::fs::path;

match (File::open(Path::from(Str::new("config.json")))) {
    Result::Ok(f)  => { /* f is Read + Write + Seek */ }
    Result::Err(e) => { /* NotFound, PermissionDenied, ... */ }
}

Constructor	Notes
open(p)	Open for reading.
create(p)	Create or truncate for writing, mode 0644.
open_with(p, options)	Full control.

File implements Read, Write, and Seek, plus the inherent seek_set, seek_cur, seek_end, and stream_position helpers for direct use.

A File wraps a raw fd, and the obligations are the POSIX ones: every open pairs with exactly one drop, which closes it. Calling drop twice is a bug the kernel may not catch — the second close could race an unrelated open that reused the descriptor.

OpenOptions#

type struct OpenOptions {
    read:       boolean;
    write:      boolean;
    append:     boolean;
    truncate:   boolean;
    create:     boolean;
    create_new: boolean;

    static new() -> OpenOptions;
    read(mut &this, value: boolean) -> OpenOptions;
    write(mut &this, value: boolean) -> OpenOptions;
    append(mut &this, value: boolean) -> OpenOptions;
    truncate(mut &this, value: boolean) -> OpenOptions;
    create(mut &this, value: boolean) -> OpenOptions;
    create_new(mut &this, value: boolean) -> OpenOptions;
    open(&this, p: Path) -> Result<File, IoError>;
    to_flags(&this) -> i32;
}

A builder. Each setter takes a boolean and returns the options, so they chain; open(p) finishes. to_flags is the O_* bitmask the options translate to, for handing to libc::open directly.

mut opts: OpenOptions = OpenOptions::new();
mut log: File = opts.write(true).create(true).append(true).open(p)?;

Whole-file helpers#

Function	Notes
read(p)	The whole file as bytes.
read_to_string(p)	Bytes taken verbatim, no UTF-8 validation.
write(p, bytes)	Creates or truncates.
copy(from, to)	Bytes copied.

copy creates to if missing, truncates it if present, then applies the source's Unix permission bits, mirroring cp. The source must be a regular file — copying a directory fails with InvalidInput. On a mid-copy failure the partially written destination is left in place and the error is returned as-is.

Trait implementations#

implement trait Seek for struct File

implement trait Drop for struct File

implement trait Read for struct File

implement trait Write for struct File

flush is a no-op: the file is unbuffered at this layer, and write_some goes straight to write(2).