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
7use crate::fs::Metadata;
8use crate::sys_common::AsInner;
9
10#[allow(deprecated)]
11use 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")]
17pub 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 #[deprecated(since = "1.8.0", note = "other methods of this trait are now preferred")]
42 #[allow(deprecated)]
43 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")]
61 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")]
78 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")]
95 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")]
112 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")]
129 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")]
146 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")]
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.
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")]
183 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")]
200 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")]
219 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")]
236 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")]
255 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")]
272 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")]
291 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")]
308 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")]
325 fn st_blocks(&self) -> u64;
326}
327
328#[stable(feature = "metadata_ext", since = "1.1.0")]
329impl MetadataExt for Metadata {
330 #[allow(deprecated)]
331 fn as_raw_stat(&self) -> &raw::stat {
332 #[cfg(target_env = "musl")]
333 unsafe {
334 &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat)
335 }
336 #[cfg(not(target_env = "musl"))]
337 unsafe {
338 &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat)
339 }
340 }
341 fn st_dev(&self) -> u64 {
342 self.as_inner().as_inner().st_dev as u64
343 }
344 fn st_ino(&self) -> u64 {
345 self.as_inner().as_inner().st_ino as u64
346 }
347 fn st_mode(&self) -> u32 {
348 self.as_inner().as_inner().st_mode as u32
349 }
350 fn st_nlink(&self) -> u64 {
351 self.as_inner().as_inner().st_nlink as u64
352 }
353 fn st_uid(&self) -> u32 {
354 self.as_inner().as_inner().st_uid as u32
355 }
356 fn st_gid(&self) -> u32 {
357 self.as_inner().as_inner().st_gid as u32
358 }
359 fn st_rdev(&self) -> u64 {
360 self.as_inner().as_inner().st_rdev as u64
361 }
362 fn st_size(&self) -> u64 {
363 self.as_inner().as_inner().st_size as u64
364 }
365 fn st_atime(&self) -> i64 {
366 let file_attr = self.as_inner();
367 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
368 if let Some(atime) = file_attr.stx_atime() {
369 return atime.tv_sec;
370 }
371 file_attr.as_inner().st_atime as i64
372 }
373 fn st_atime_nsec(&self) -> i64 {
374 self.as_inner().as_inner().st_atime_nsec as i64
375 }
376 fn st_mtime(&self) -> i64 {
377 let file_attr = self.as_inner();
378 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
379 if let Some(mtime) = file_attr.stx_mtime() {
380 return mtime.tv_sec;
381 }
382 file_attr.as_inner().st_mtime as i64
383 }
384 fn st_mtime_nsec(&self) -> i64 {
385 self.as_inner().as_inner().st_mtime_nsec as i64
386 }
387 fn st_ctime(&self) -> i64 {
388 let file_attr = self.as_inner();
389 #[cfg(all(target_env = "gnu", target_pointer_width = "32"))]
390 if let Some(ctime) = file_attr.stx_ctime() {
391 return ctime.tv_sec;
392 }
393 file_attr.as_inner().st_ctime as i64
394 }
395 fn st_ctime_nsec(&self) -> i64 {
396 self.as_inner().as_inner().st_ctime_nsec as i64
397 }
398 fn st_blksize(&self) -> u64 {
399 self.as_inner().as_inner().st_blksize as u64
400 }
401 fn st_blocks(&self) -> u64 {
402 self.as_inner().as_inner().st_blocks as u64
403 }
404}
405