src/libstd/os/linux/fs.rs

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