1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
//! Extended utilities for working with files and filesystems in Rust. // Only allow libtest features on nightly, where they are accessible. #![cfg_attr(all(nightly, test), feature(test))] #[cfg(windows)] extern crate winapi; #[cfg(unix)] mod unix; #[cfg(unix)] use unix as sys; #[cfg(windows)] mod windows; #[cfg(windows)] use windows as sys; use std::fs::File; use std::io::{Error, Result}; use std::path::Path; /// 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)`](http://man7.org/linux/man-pages/man2/flock.2.html) on Unix and /// [`LockFile`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365202(v=vs.85).aspx) /// on Windows. pub trait FileExt { /// 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)`](http://man7.org/linux/man-pages/man2/dup.2.html) on Unix and /// [`DuplicateHandle`](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724251(v=vs.85).aspx) /// on Windows. fn duplicate(&self) -> Result<File>; /// Returns the amount of physical space allocated for a file. fn allocated_size(&self) -> Result<u64>; /// 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. fn allocate(&self, len: u64) -> Result<()>; /// Locks the file for shared usage, blocking if the file is currently /// locked exclusively. fn lock_shared(&self) -> Result<()>; /// Locks the file for exclusive usage, blocking if the file is currently /// locked. fn 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 try_lock_shared(&self) -> Result<()>; /// Locks the file for exclusive usage, or returns a an error if the file is /// currently locked (see `lock_contended_error`). fn try_lock_exclusive(&self) -> Result<()>; /// Unlocks the file. fn unlock(&self) -> Result<()>; } impl FileExt for File { fn duplicate(&self) -> Result<File> { sys::duplicate(self) } fn allocated_size(&self) -> Result<u64> { sys::allocated_size(self) } fn allocate(&self, len: u64) -> Result<()> { sys::allocate(self, len) } fn lock_shared(&self) -> Result<()> { sys::lock_shared(self) } fn lock_exclusive(&self) -> Result<()> { sys::lock_exclusive(self) } fn try_lock_shared(&self) -> Result<()> { sys::try_lock_shared(self) } fn try_lock_exclusive(&self) -> Result<()> { sys::try_lock_exclusive(self) } fn unlock(&self) -> Result<()> { sys::unlock(self) } } /// Returns the error that a call to a try lock method on a contended file will /// return. pub fn lock_contended_error() -> Error { sys::lock_error() } /// `FsStats` contains some common stats about a file system. #[derive(Clone, Debug, PartialEq, Eq, Hash)] pub struct FsStats { free_space: u64, available_space: u64, total_space: u64, allocation_granularity: u64, } impl FsStats { /// Returns the number of free bytes in the file system containing the provided /// path. pub fn free_space(&self) -> u64 { self.free_space } /// Returns the available space in bytes to non-priveleged users in the file /// system containing the provided path. pub fn available_space(&self) -> u64 { self.available_space } /// Returns the total space in bytes in the file system containing the provided /// path. pub fn total_space(&self) -> u64 { self.total_space } /// Returns the filesystem's disk space allocation granularity in bytes. /// The provided path may be for any file in the filesystem. /// /// On Posix, this is equivalent to the filesystem's block size. /// On Windows, this is equivalent to the filesystem's cluster size. pub fn allocation_granularity(&self) -> u64 { self.allocation_granularity } } /// Get the stats of the file system containing the provided path. pub fn statvfs<P>(path: P) -> Result<FsStats> where P: AsRef<Path>, { sys::statvfs(path.as_ref()) } /// Returns the number of free bytes in the file system containing the provided /// path. pub fn free_space<P>(path: P) -> Result<u64> where P: AsRef<Path>, { statvfs(path).map(|stat| stat.free_space) } /// Returns the available space in bytes to non-priveleged users in the file /// system containing the provided path. pub fn available_space<P>(path: P) -> Result<u64> where P: AsRef<Path>, { statvfs(path).map(|stat| stat.available_space) } /// Returns the total space in bytes in the file system containing the provided /// path. pub fn total_space<P>(path: P) -> Result<u64> where P: AsRef<Path>, { statvfs(path).map(|stat| stat.total_space) } /// Returns the filesystem's disk space allocation granularity in bytes. /// The provided path may be for any file in the filesystem. /// /// On Posix, this is equivalent to the filesystem's block size. /// On Windows, this is equivalent to the filesystem's cluster size. pub fn allocation_granularity<P>(path: P) -> Result<u64> where P: AsRef<Path>, { statvfs(path).map(|stat| stat.allocation_granularity) } #[cfg(test)] mod test;