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