library/std/src/os/linux/fs.rs

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