1 //! Linux-specific extensions to primitives in the [`std::fs`] module.
3 //! [`std::fs`]: crate::fs
5 #![stable(feature = "metadata_ext", since = "1.1.0")]
7 use crate::fs::Metadata;
8 use crate::sys_common::AsInner;
11 use crate::os::linux::raw;
13 /// OS-specific extensions to [`fs::Metadata`].
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.
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.
25 /// [`stat`]: struct@crate::os::linux::raw::stat
32 /// use std::os::linux::fs::MetadataExt;
34 /// fn main() -> io::Result<()> {
35 /// let meta = fs::metadata("some_file")?;
36 /// let stat = meta.as_raw_stat();
40 #[stable(feature = "metadata_ext", since = "1.1.0")]
41 #[deprecated(since = "1.8.0", note = "other methods of this trait are now preferred")]
43 fn as_raw_stat(&self) -> &raw::stat;
45 /// Returns the device ID on which this file resides.
52 /// use std::os::linux::fs::MetadataExt;
54 /// fn main() -> io::Result<()> {
55 /// let meta = fs::metadata("some_file")?;
56 /// println!("{}", meta.st_dev());
60 #[stable(feature = "metadata_ext2", since = "1.8.0")]
61 fn st_dev(&self) -> u64;
62 /// Returns the inode number.
69 /// use std::os::linux::fs::MetadataExt;
71 /// fn main() -> io::Result<()> {
72 /// let meta = fs::metadata("some_file")?;
73 /// println!("{}", meta.st_ino());
77 #[stable(feature = "metadata_ext2", since = "1.8.0")]
78 fn st_ino(&self) -> u64;
79 /// Returns the file type and mode.
86 /// use std::os::linux::fs::MetadataExt;
88 /// fn main() -> io::Result<()> {
89 /// let meta = fs::metadata("some_file")?;
90 /// println!("{}", meta.st_mode());
94 #[stable(feature = "metadata_ext2", since = "1.8.0")]
95 fn st_mode(&self) -> u32;
96 /// Returns the number of hard links to file.
103 /// use std::os::linux::fs::MetadataExt;
105 /// fn main() -> io::Result<()> {
106 /// let meta = fs::metadata("some_file")?;
107 /// println!("{}", meta.st_nlink());
111 #[stable(feature = "metadata_ext2", since = "1.8.0")]
112 fn st_nlink(&self) -> u64;
113 /// Returns the user ID of the file owner.
120 /// use std::os::linux::fs::MetadataExt;
122 /// fn main() -> io::Result<()> {
123 /// let meta = fs::metadata("some_file")?;
124 /// println!("{}", meta.st_uid());
128 #[stable(feature = "metadata_ext2", since = "1.8.0")]
129 fn st_uid(&self) -> u32;
130 /// Returns the group ID of the file owner.
137 /// use std::os::linux::fs::MetadataExt;
139 /// fn main() -> io::Result<()> {
140 /// let meta = fs::metadata("some_file")?;
141 /// println!("{}", meta.st_gid());
145 #[stable(feature = "metadata_ext2", since = "1.8.0")]
146 fn st_gid(&self) -> u32;
147 /// Returns the device ID that this file represents. Only relevant for special file.
154 /// use std::os::linux::fs::MetadataExt;
156 /// fn main() -> io::Result<()> {
157 /// let meta = fs::metadata("some_file")?;
158 /// println!("{}", meta.st_rdev());
162 #[stable(feature = "metadata_ext2", since = "1.8.0")]
163 fn st_rdev(&self) -> u64;
164 /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes.
166 /// The size of a symbolic link is the length of the pathname it contains,
167 /// without a terminating null byte.
174 /// use std::os::linux::fs::MetadataExt;
176 /// fn main() -> io::Result<()> {
177 /// let meta = fs::metadata("some_file")?;
178 /// println!("{}", meta.st_size());
182 #[stable(feature = "metadata_ext2", since = "1.8.0")]
183 fn st_size(&self) -> u64;
184 /// Returns the last access time of the file, in seconds since Unix Epoch.
191 /// use std::os::linux::fs::MetadataExt;
193 /// fn main() -> io::Result<()> {
194 /// let meta = fs::metadata("some_file")?;
195 /// println!("{}", meta.st_atime());
199 #[stable(feature = "metadata_ext2", since = "1.8.0")]
200 fn st_atime(&self) -> i64;
201 /// Returns the last access time of the file, in nanoseconds since [`st_atime`].
203 /// [`st_atime`]: Self::st_atime
210 /// use std::os::linux::fs::MetadataExt;
212 /// fn main() -> io::Result<()> {
213 /// let meta = fs::metadata("some_file")?;
214 /// println!("{}", meta.st_atime_nsec());
218 #[stable(feature = "metadata_ext2", since = "1.8.0")]
219 fn st_atime_nsec(&self) -> i64;
220 /// Returns the last modification time of the file, in seconds since Unix Epoch.
227 /// use std::os::linux::fs::MetadataExt;
229 /// fn main() -> io::Result<()> {
230 /// let meta = fs::metadata("some_file")?;
231 /// println!("{}", meta.st_mtime());
235 #[stable(feature = "metadata_ext2", since = "1.8.0")]
236 fn st_mtime(&self) -> i64;
237 /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`].
239 /// [`st_mtime`]: Self::st_mtime
246 /// use std::os::linux::fs::MetadataExt;
248 /// fn main() -> io::Result<()> {
249 /// let meta = fs::metadata("some_file")?;
250 /// println!("{}", meta.st_mtime_nsec());
254 #[stable(feature = "metadata_ext2", since = "1.8.0")]
255 fn st_mtime_nsec(&self) -> i64;
256 /// Returns the last status change time of the file, in seconds since Unix Epoch.
263 /// use std::os::linux::fs::MetadataExt;
265 /// fn main() -> io::Result<()> {
266 /// let meta = fs::metadata("some_file")?;
267 /// println!("{}", meta.st_ctime());
271 #[stable(feature = "metadata_ext2", since = "1.8.0")]
272 fn st_ctime(&self) -> i64;
273 /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`].
275 /// [`st_ctime`]: Self::st_ctime
282 /// use std::os::linux::fs::MetadataExt;
284 /// fn main() -> io::Result<()> {
285 /// let meta = fs::metadata("some_file")?;
286 /// println!("{}", meta.st_ctime_nsec());
290 #[stable(feature = "metadata_ext2", since = "1.8.0")]
291 fn st_ctime_nsec(&self) -> i64;
292 /// Returns the "preferred" block size for efficient filesystem I/O.
299 /// use std::os::linux::fs::MetadataExt;
301 /// fn main() -> io::Result<()> {
302 /// let meta = fs::metadata("some_file")?;
303 /// println!("{}", meta.st_blksize());
307 #[stable(feature = "metadata_ext2", since = "1.8.0")]
308 fn st_blksize(&self) -> u64;
309 /// Returns the number of blocks allocated to the file, 512-byte units.
316 /// use std::os::linux::fs::MetadataExt;
318 /// fn main() -> io::Result<()> {
319 /// let meta = fs::metadata("some_file")?;
320 /// println!("{}", meta.st_blocks());
324 #[stable(feature = "metadata_ext2", since = "1.8.0")]
325 fn st_blocks(&self) -> u64;
328 #[stable(feature = "metadata_ext", since = "1.1.0")]
329 impl MetadataExt for Metadata {
331 fn as_raw_stat(&self) -> &raw::stat {
332 unsafe { &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat) }
334 fn st_dev(&self) -> u64 {
335 self.as_inner().as_inner().st_dev as u64
337 fn st_ino(&self) -> u64 {
338 self.as_inner().as_inner().st_ino as u64
340 fn st_mode(&self) -> u32 {
341 self.as_inner().as_inner().st_mode as u32
343 fn st_nlink(&self) -> u64 {
344 self.as_inner().as_inner().st_nlink as u64
346 fn st_uid(&self) -> u32 {
347 self.as_inner().as_inner().st_uid as u32
349 fn st_gid(&self) -> u32 {
350 self.as_inner().as_inner().st_gid as u32
352 fn st_rdev(&self) -> u64 {
353 self.as_inner().as_inner().st_rdev as u64
355 fn st_size(&self) -> u64 {
356 self.as_inner().as_inner().st_size as u64
358 fn st_atime(&self) -> i64 {
359 let file_attr = self.as_inner();
360 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
361 if let Some(atime) = file_attr.stx_atime() {
364 file_attr.as_inner().st_atime as i64
366 fn st_atime_nsec(&self) -> i64 {
367 self.as_inner().as_inner().st_atime_nsec as i64
369 fn st_mtime(&self) -> i64 {
370 let file_attr = self.as_inner();
371 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
372 if let Some(mtime) = file_attr.stx_mtime() {
375 file_attr.as_inner().st_mtime as i64
377 fn st_mtime_nsec(&self) -> i64 {
378 self.as_inner().as_inner().st_mtime_nsec as i64
380 fn st_ctime(&self) -> i64 {
381 let file_attr = self.as_inner();
382 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
383 if let Some(ctime) = file_attr.stx_ctime() {
386 file_attr.as_inner().st_ctime as i64
388 fn st_ctime_nsec(&self) -> i64 {
389 self.as_inner().as_inner().st_ctime_nsec as i64
391 fn st_blksize(&self) -> u64 {
392 self.as_inner().as_inner().st_blksize as u64
394 fn st_blocks(&self) -> u64 {
395 self.as_inner().as_inner().st_blocks as u64