1 //! Linux-specific extensions to primitives in the [`std::fs`] module. 2 //! 3 //! [`std::fs`]: crate::fs 4 5 #![stable(feature = "metadata_ext", since = "1.1.0")] 6 7 use crate::fs::Metadata; 8 use crate::sys_common::AsInner; 9 10 #[allow(deprecated)] 11 use crate::os::linux::raw; 12 13 /// OS-specific extensions to [`fs::Metadata`]. 14 /// 15 /// [`fs::Metadata`]: crate::fs::Metadata 16 #[stable(feature = "metadata_ext", since = "1.1.0")] 17 pub trait MetadataExt { 18 /// Gain a reference to the underlying `stat` structure which contains 19 /// the raw information returned by the OS. 20 /// 21 /// The contents of the returned [`stat`] are **not** consistent across 22 /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the 23 /// cross-Unix abstractions contained within the raw stat. 24 /// 25 /// [`stat`]: struct@crate::os::linux::raw::stat 26 /// 27 /// # Examples 28 /// 29 /// ```no_run 30 /// use std::fs; 31 /// use std::io; 32 /// use std::os::linux::fs::MetadataExt; 33 /// 34 /// fn main() -> io::Result<()> { 35 /// let meta = fs::metadata("some_file")?; 36 /// let stat = meta.as_raw_stat(); 37 /// Ok(()) 38 /// } 39 /// ``` 40 #[stable(feature = "metadata_ext", since = "1.1.0")] 41 #[rustc_deprecated(since = "1.8.0", reason = "other methods of this trait are now preferred")] 42 #[allow(deprecated)] as_raw_stat(&self) -> &raw::stat43 fn as_raw_stat(&self) -> &raw::stat; 44 45 /// Returns the device ID on which this file resides. 46 /// 47 /// # Examples 48 /// 49 /// ```no_run 50 /// use std::fs; 51 /// use std::io; 52 /// use std::os::linux::fs::MetadataExt; 53 /// 54 /// fn main() -> io::Result<()> { 55 /// let meta = fs::metadata("some_file")?; 56 /// println!("{}", meta.st_dev()); 57 /// Ok(()) 58 /// } 59 /// ``` 60 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_dev(&self) -> u6461 fn st_dev(&self) -> u64; 62 /// Returns the inode number. 63 /// 64 /// # Examples 65 /// 66 /// ```no_run 67 /// use std::fs; 68 /// use std::io; 69 /// use std::os::linux::fs::MetadataExt; 70 /// 71 /// fn main() -> io::Result<()> { 72 /// let meta = fs::metadata("some_file")?; 73 /// println!("{}", meta.st_ino()); 74 /// Ok(()) 75 /// } 76 /// ``` 77 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_ino(&self) -> u6478 fn st_ino(&self) -> u64; 79 /// Returns the file type and mode. 80 /// 81 /// # Examples 82 /// 83 /// ```no_run 84 /// use std::fs; 85 /// use std::io; 86 /// use std::os::linux::fs::MetadataExt; 87 /// 88 /// fn main() -> io::Result<()> { 89 /// let meta = fs::metadata("some_file")?; 90 /// println!("{}", meta.st_mode()); 91 /// Ok(()) 92 /// } 93 /// ``` 94 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_mode(&self) -> u3295 fn st_mode(&self) -> u32; 96 /// Returns the number of hard links to file. 97 /// 98 /// # Examples 99 /// 100 /// ```no_run 101 /// use std::fs; 102 /// use std::io; 103 /// use std::os::linux::fs::MetadataExt; 104 /// 105 /// fn main() -> io::Result<()> { 106 /// let meta = fs::metadata("some_file")?; 107 /// println!("{}", meta.st_nlink()); 108 /// Ok(()) 109 /// } 110 /// ``` 111 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_nlink(&self) -> u64112 fn st_nlink(&self) -> u64; 113 /// Returns the user ID of the file owner. 114 /// 115 /// # Examples 116 /// 117 /// ```no_run 118 /// use std::fs; 119 /// use std::io; 120 /// use std::os::linux::fs::MetadataExt; 121 /// 122 /// fn main() -> io::Result<()> { 123 /// let meta = fs::metadata("some_file")?; 124 /// println!("{}", meta.st_uid()); 125 /// Ok(()) 126 /// } 127 /// ``` 128 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_uid(&self) -> u32129 fn st_uid(&self) -> u32; 130 /// Returns the group ID of the file owner. 131 /// 132 /// # Examples 133 /// 134 /// ```no_run 135 /// use std::fs; 136 /// use std::io; 137 /// use std::os::linux::fs::MetadataExt; 138 /// 139 /// fn main() -> io::Result<()> { 140 /// let meta = fs::metadata("some_file")?; 141 /// println!("{}", meta.st_gid()); 142 /// Ok(()) 143 /// } 144 /// ``` 145 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_gid(&self) -> u32146 fn st_gid(&self) -> u32; 147 /// Returns the device ID that this file represents. Only relevant for special file. 148 /// 149 /// # Examples 150 /// 151 /// ```no_run 152 /// use std::fs; 153 /// use std::io; 154 /// use std::os::linux::fs::MetadataExt; 155 /// 156 /// fn main() -> io::Result<()> { 157 /// let meta = fs::metadata("some_file")?; 158 /// println!("{}", meta.st_rdev()); 159 /// Ok(()) 160 /// } 161 /// ``` 162 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_rdev(&self) -> u64163 fn st_rdev(&self) -> u64; 164 /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. 165 /// 166 /// The size of a symbolic link is the length of the pathname it contains, 167 /// without a terminating null byte. 168 /// 169 /// # Examples 170 /// 171 /// ```no_run 172 /// use std::fs; 173 /// use std::io; 174 /// use std::os::linux::fs::MetadataExt; 175 /// 176 /// fn main() -> io::Result<()> { 177 /// let meta = fs::metadata("some_file")?; 178 /// println!("{}", meta.st_size()); 179 /// Ok(()) 180 /// } 181 /// ``` 182 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_size(&self) -> u64183 fn st_size(&self) -> u64; 184 /// Returns the last access time of the file, in seconds since Unix Epoch. 185 /// 186 /// # Examples 187 /// 188 /// ```no_run 189 /// use std::fs; 190 /// use std::io; 191 /// use std::os::linux::fs::MetadataExt; 192 /// 193 /// fn main() -> io::Result<()> { 194 /// let meta = fs::metadata("some_file")?; 195 /// println!("{}", meta.st_atime()); 196 /// Ok(()) 197 /// } 198 /// ``` 199 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_atime(&self) -> i64200 fn st_atime(&self) -> i64; 201 /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. 202 /// 203 /// [`st_atime`]: Self::st_atime 204 /// 205 /// # Examples 206 /// 207 /// ```no_run 208 /// use std::fs; 209 /// use std::io; 210 /// use std::os::linux::fs::MetadataExt; 211 /// 212 /// fn main() -> io::Result<()> { 213 /// let meta = fs::metadata("some_file")?; 214 /// println!("{}", meta.st_atime_nsec()); 215 /// Ok(()) 216 /// } 217 /// ``` 218 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_atime_nsec(&self) -> i64219 fn st_atime_nsec(&self) -> i64; 220 /// Returns the last modification time of the file, in seconds since Unix Epoch. 221 /// 222 /// # Examples 223 /// 224 /// ```no_run 225 /// use std::fs; 226 /// use std::io; 227 /// use std::os::linux::fs::MetadataExt; 228 /// 229 /// fn main() -> io::Result<()> { 230 /// let meta = fs::metadata("some_file")?; 231 /// println!("{}", meta.st_mtime()); 232 /// Ok(()) 233 /// } 234 /// ``` 235 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_mtime(&self) -> i64236 fn st_mtime(&self) -> i64; 237 /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. 238 /// 239 /// [`st_mtime`]: Self::st_mtime 240 /// 241 /// # Examples 242 /// 243 /// ```no_run 244 /// use std::fs; 245 /// use std::io; 246 /// use std::os::linux::fs::MetadataExt; 247 /// 248 /// fn main() -> io::Result<()> { 249 /// let meta = fs::metadata("some_file")?; 250 /// println!("{}", meta.st_mtime_nsec()); 251 /// Ok(()) 252 /// } 253 /// ``` 254 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_mtime_nsec(&self) -> i64255 fn st_mtime_nsec(&self) -> i64; 256 /// Returns the last status change time of the file, in seconds since Unix Epoch. 257 /// 258 /// # Examples 259 /// 260 /// ```no_run 261 /// use std::fs; 262 /// use std::io; 263 /// use std::os::linux::fs::MetadataExt; 264 /// 265 /// fn main() -> io::Result<()> { 266 /// let meta = fs::metadata("some_file")?; 267 /// println!("{}", meta.st_ctime()); 268 /// Ok(()) 269 /// } 270 /// ``` 271 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_ctime(&self) -> i64272 fn st_ctime(&self) -> i64; 273 /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. 274 /// 275 /// [`st_ctime`]: Self::st_ctime 276 /// 277 /// # Examples 278 /// 279 /// ```no_run 280 /// use std::fs; 281 /// use std::io; 282 /// use std::os::linux::fs::MetadataExt; 283 /// 284 /// fn main() -> io::Result<()> { 285 /// let meta = fs::metadata("some_file")?; 286 /// println!("{}", meta.st_ctime_nsec()); 287 /// Ok(()) 288 /// } 289 /// ``` 290 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_ctime_nsec(&self) -> i64291 fn st_ctime_nsec(&self) -> i64; 292 /// Returns the "preferred" block size for efficient filesystem I/O. 293 /// 294 /// # Examples 295 /// 296 /// ```no_run 297 /// use std::fs; 298 /// use std::io; 299 /// use std::os::linux::fs::MetadataExt; 300 /// 301 /// fn main() -> io::Result<()> { 302 /// let meta = fs::metadata("some_file")?; 303 /// println!("{}", meta.st_blksize()); 304 /// Ok(()) 305 /// } 306 /// ``` 307 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_blksize(&self) -> u64308 fn st_blksize(&self) -> u64; 309 /// Returns the number of blocks allocated to the file, 512-byte units. 310 /// 311 /// # Examples 312 /// 313 /// ```no_run 314 /// use std::fs; 315 /// use std::io; 316 /// use std::os::linux::fs::MetadataExt; 317 /// 318 /// fn main() -> io::Result<()> { 319 /// let meta = fs::metadata("some_file")?; 320 /// println!("{}", meta.st_blocks()); 321 /// Ok(()) 322 /// } 323 /// ``` 324 #[stable(feature = "metadata_ext2", since = "1.8.0")] st_blocks(&self) -> u64325 fn st_blocks(&self) -> u64; 326 } 327 328 #[stable(feature = "metadata_ext", since = "1.1.0")] 329 impl MetadataExt for Metadata { 330 #[allow(deprecated)] as_raw_stat(&self) -> &raw::stat331 fn as_raw_stat(&self) -> &raw::stat { 332 unsafe { &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat) } 333 } st_dev(&self) -> u64334 fn st_dev(&self) -> u64 { 335 self.as_inner().as_inner().st_dev as u64 336 } st_ino(&self) -> u64337 fn st_ino(&self) -> u64 { 338 self.as_inner().as_inner().st_ino as u64 339 } st_mode(&self) -> u32340 fn st_mode(&self) -> u32 { 341 self.as_inner().as_inner().st_mode as u32 342 } st_nlink(&self) -> u64343 fn st_nlink(&self) -> u64 { 344 self.as_inner().as_inner().st_nlink as u64 345 } st_uid(&self) -> u32346 fn st_uid(&self) -> u32 { 347 self.as_inner().as_inner().st_uid as u32 348 } st_gid(&self) -> u32349 fn st_gid(&self) -> u32 { 350 self.as_inner().as_inner().st_gid as u32 351 } st_rdev(&self) -> u64352 fn st_rdev(&self) -> u64 { 353 self.as_inner().as_inner().st_rdev as u64 354 } st_size(&self) -> u64355 fn st_size(&self) -> u64 { 356 self.as_inner().as_inner().st_size as u64 357 } st_atime(&self) -> i64358 fn st_atime(&self) -> i64 { 359 self.as_inner().as_inner().st_atime as i64 360 } st_atime_nsec(&self) -> i64361 fn st_atime_nsec(&self) -> i64 { 362 self.as_inner().as_inner().st_atime_nsec as i64 363 } st_mtime(&self) -> i64364 fn st_mtime(&self) -> i64 { 365 self.as_inner().as_inner().st_mtime as i64 366 } st_mtime_nsec(&self) -> i64367 fn st_mtime_nsec(&self) -> i64 { 368 self.as_inner().as_inner().st_mtime_nsec as i64 369 } st_ctime(&self) -> i64370 fn st_ctime(&self) -> i64 { 371 self.as_inner().as_inner().st_ctime as i64 372 } st_ctime_nsec(&self) -> i64373 fn st_ctime_nsec(&self) -> i64 { 374 self.as_inner().as_inner().st_ctime_nsec as i64 375 } st_blksize(&self) -> u64376 fn st_blksize(&self) -> u64 { 377 self.as_inner().as_inner().st_blksize as u64 378 } st_blocks(&self) -> u64379 fn st_blocks(&self) -> u64 { 380 self.as_inner().as_inner().st_blocks as u64 381 } 382 } 383