Trait fs2::FileExt
[−]
[src]
pub trait FileExt {
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<()>;
}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
Fileinstance 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
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.
fn allocated_size(&self) -> Result<u64>
Returns the amount of physical space allocated for a file.
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.
Locks the file for shared usage, blocking if the file is currently locked exclusively.
fn lock_exclusive(&self) -> Result<()>
Locks the file for exclusive usage, blocking if the file is currently locked.
Locks the file for shared usage, or returns a an error if the file is
currently locked (see lock_contended_error).
fn try_lock_exclusive(&self) -> Result<()>
Locks the file for shared usage, or returns a an error if the file is
currently locked (see lock_contended_error).
fn unlock(&self) -> Result<()>
Unlocks the file.