Trait fs2::FileExt

source ·

pub trait FileExt {
    // Required methods
    fn duplicate(&self) -> Result<File>;
    fn allocated_size(&self) -> Result<u64>;
    fn allocate(&self, len: u64) -> Result<()>;
    fn lock_shared(&self) -> Result<()>;
    fn lock_exclusive(&self) -> Result<()>;
    fn try_lock_shared(&self) -> Result<()>;
    fn try_lock_exclusive(&self) -> Result<()>;
    fn unlock(&self) -> Result<()>;
}

Expand description

Extension trait for std::fs::File which provides allocation, duplication and locking methods.

Notes on File Locks

This library provides whole-file locks in both shared (read) and exclusive (read-write) varieties.

File locks are a cross-platform hazard since the file lock APIs exposed by operating system kernels vary in subtle and not-so-subtle ways.

The API exposed by this library can be safely used across platforms as long as the following rules are followed:

Multiple locks should not be created on an individual File instance concurrently.
Duplicated files should not be locked without great care.
Files to be locked should be opened with at least read or write permissions.
File locks may only be relied upon to be advisory.

See the tests in lib.rs for cross-platform lock behavior that may be relied upon; see the tests in unix.rs and windows.rs for examples of platform-specific behavior. File locks are implemented with flock(2) on Unix and LockFile on Windows.

Required Methods§

source

fn duplicate(&self) -> Result<File>

Returns a duplicate instance of the file.

The returned file will share the same file position as the original file.

If using rustc version 1.9 or later, prefer using File::try_clone to this.

Notes

This is implemented with dup(2) on Unix and DuplicateHandle on Windows.

source

fn allocated_size(&self) -> Result<u64>

Returns the amount of physical space allocated for a file.

source

fn allocate(&self, len: u64) -> Result<()>

Ensures that at least len bytes of disk space are allocated for the file, and the file size is at least len bytes. After a successful call to allocate, subsequent writes to the file within the specified length are guaranteed not to fail because of lack of disk space.

source