@@ -24,9 +24,25 @@ pub trait MetadataExt {
2424 /// Gain a reference to the underlying `stat` structure which contains
2525/// the raw information returned by the OS.
2626///
27- /// The contents of the returned `stat` are **not** consistent across
27+ /// The contents of the returned [ `stat`] are **not** consistent across
2828/// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the
2929/// cross-Unix abstractions contained within the raw stat.
30+ ///
31+ /// [`stat`]: ../../../../std/os/linux/raw/struct.stat.html
32+ ///
33+ /// # Examples
34+ ///
35+ /// ```
36+ /// use std::fs;
37+ /// use std::os::linux::fs::MetadataExt;
38+ ///
39+ /// # use std::io;
40+ /// # fn f() -> io::Result<()> {
41+ /// let meta = fs::metadata("some_file")?;
42+ /// let stat = meta.as_raw_stat();
43+ /// # Ok(())
44+ /// # }
45+ /// ```
3046#[ stable( feature = "metadata_ext" , since = "1.1.0" ) ]
3147 #[ rustc_deprecated( since = "1.8.0" ,
3248 reason = "deprecated in favor of the accessor \
@@ -35,54 +51,278 @@ pub trait MetadataExt {
3551 fn as_raw_stat ( & self ) -> & raw:: stat ;
3652
3753 /// Returns the device ID on which this file resides.
54+ ///
55+ /// # Examples
56+ ///
57+ /// ```
58+ /// use std::fs;
59+ /// use std::os::linux::fs::MetadataExt;
60+ ///
61+ /// # use std::io;
62+ /// # fn f() -> io::Result<()> {
63+ /// let meta = fs::metadata("some_file")?;
64+ /// println!("{}", meta.st_dev());
65+ /// # Ok(())
66+ /// # }
67+ /// ```
3868#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
3969 fn st_dev ( & self ) -> u64 ;
4070 /// Returns the inode number.
71+ ///
72+ /// # Examples
73+ ///
74+ /// ```
75+ /// use std::fs;
76+ /// use std::os::linux::fs::MetadataExt;
77+ ///
78+ /// # use std::io;
79+ /// # fn f() -> io::Result<()> {
80+ /// let meta = fs::metadata("some_file")?;
81+ /// println!("{}", meta.st_ino());
82+ /// # Ok(())
83+ /// # }
84+ /// ```
4185#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
4286 fn st_ino ( & self ) -> u64 ;
4387 /// Returns the file type and mode.
88+ ///
89+ /// # Examples
90+ ///
91+ /// ```
92+ /// use std::fs;
93+ /// use std::os::linux::fs::MetadataExt;
94+ ///
95+ /// # use std::io;
96+ /// # fn f() -> io::Result<()> {
97+ /// let meta = fs::metadata("some_file")?;
98+ /// println!("{}", meta.st_mode());
99+ /// # Ok(())
100+ /// # }
101+ /// ```
44102#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
45103 fn st_mode ( & self ) -> u32 ;
46104 /// Returns the number of hard links to file.
105+ ///
106+ /// # Examples
107+ ///
108+ /// ```
109+ /// use std::fs;
110+ /// use std::os::linux::fs::MetadataExt;
111+ ///
112+ /// # use std::io;
113+ /// # fn f() -> io::Result<()> {
114+ /// let meta = fs::metadata("some_file")?;
115+ /// println!("{}", meta.st_nlink());
116+ /// # Ok(())
117+ /// # }
118+ /// ```
47119#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
48120 fn st_nlink ( & self ) -> u64 ;
49121 /// Returns the user ID of the file owner.
122+ ///
123+ /// # Examples
124+ ///
125+ /// ```
126+ /// use std::fs;
127+ /// use std::os::linux::fs::MetadataExt;
128+ ///
129+ /// # use std::io;
130+ /// # fn f() -> io::Result<()> {
131+ /// let meta = fs::metadata("some_file")?;
132+ /// println!("{}", meta.st_uid());
133+ /// # Ok(())
134+ /// # }
135+ /// ```
50136#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
51137 fn st_uid ( & self ) -> u32 ;
52138 /// Returns the group ID of the file owner.
139+ ///
140+ /// # Examples
141+ ///
142+ /// ```
143+ /// use std::fs;
144+ /// use std::os::linux::fs::MetadataExt;
145+ ///
146+ /// # use std::io;
147+ /// # fn f() -> io::Result<()> {
148+ /// let meta = fs::metadata("some_file")?;
149+ /// println!("{}", meta.st_gid());
150+ /// # Ok(())
151+ /// # }
152+ /// ```
53153#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
54154 fn st_gid ( & self ) -> u32 ;
55155 /// Returns the device ID that this file represents. Only relevant for special file.
156+ ///
157+ /// # Examples
158+ ///
159+ /// ```
160+ /// use std::fs;
161+ /// use std::os::linux::fs::MetadataExt;
162+ ///
163+ /// # use std::io;
164+ /// # fn f() -> io::Result<()> {
165+ /// let meta = fs::metadata("some_file")?;
166+ /// println!("{}", meta.st_rdev());
167+ /// # Ok(())
168+ /// # }
169+ /// ```
56170#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
57171 fn st_rdev ( & self ) -> u64 ;
58172 /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes.
59173///
60174/// The size of a symbolic link is the length of the pathname it contains,
61175/// without a terminating null byte.
176+ ///
177+ /// # Examples
178+ ///
179+ /// ```
180+ /// use std::fs;
181+ /// use std::os::linux::fs::MetadataExt;
182+ ///
183+ /// # use std::io;
184+ /// # fn f() -> io::Result<()> {
185+ /// let meta = fs::metadata("some_file")?;
186+ /// println!("{}", meta.st_size());
187+ /// # Ok(())
188+ /// # }
189+ /// ```
62190#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
63191 fn st_size ( & self ) -> u64 ;
64192 /// Returns the last access time.
193+ ///
194+ /// # Examples
195+ ///
196+ /// ```
197+ /// use std::fs;
198+ /// use std::os::linux::fs::MetadataExt;
199+ ///
200+ /// # use std::io;
201+ /// # fn f() -> io::Result<()> {
202+ /// let meta = fs::metadata("some_file")?;
203+ /// println!("{}", meta.st_atime());
204+ /// # Ok(())
205+ /// # }
206+ /// ```
65207#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
66208 fn st_atime ( & self ) -> i64 ;
67209 /// Returns the last access time, nano seconds part.
210+ ///
211+ /// # Examples
212+ ///
213+ /// ```
214+ /// use std::fs;
215+ /// use std::os::linux::fs::MetadataExt;
216+ ///
217+ /// # use std::io;
218+ /// # fn f() -> io::Result<()> {
219+ /// let meta = fs::metadata("some_file")?;
220+ /// println!("{}", meta.st_atime_nsec());
221+ /// # Ok(())
222+ /// # }
223+ /// ```
68224#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
69225 fn st_atime_nsec ( & self ) -> i64 ;
70226 /// Returns the last modification time.
227+ ///
228+ /// # Examples
229+ ///
230+ /// ```
231+ /// use std::fs;
232+ /// use std::os::linux::fs::MetadataExt;
233+ ///
234+ /// # use std::io;
235+ /// # fn f() -> io::Result<()> {
236+ /// let meta = fs::metadata("some_file")?;
237+ /// println!("{}", meta.st_mtime());
238+ /// # Ok(())
239+ /// # }
240+ /// ```
71241#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
72242 fn st_mtime ( & self ) -> i64 ;
73243 /// Returns the last modification time, nano seconds part.
244+ ///
245+ /// # Examples
246+ ///
247+ /// ```
248+ /// use std::fs;
249+ /// use std::os::linux::fs::MetadataExt;
250+ ///
251+ /// # use std::io;
252+ /// # fn f() -> io::Result<()> {
253+ /// let meta = fs::metadata("some_file")?;
254+ /// println!("{}", meta.st_mtime_nsec());
255+ /// # Ok(())
256+ /// # }
257+ /// ```
74258#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
75259 fn st_mtime_nsec ( & self ) -> i64 ;
76260 /// Returns the last status change time.
261+ ///
262+ /// # Examples
263+ ///
264+ /// ```
265+ /// use std::fs;
266+ /// use std::os::linux::fs::MetadataExt;
267+ ///
268+ /// # use std::io;
269+ /// # fn f() -> io::Result<()> {
270+ /// let meta = fs::metadata("some_file")?;
271+ /// println!("{}", meta.st_ctime());
272+ /// # Ok(())
273+ /// # }
274+ /// ```
77275#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
78276 fn st_ctime ( & self ) -> i64 ;
79277 /// Returns the last status change time, nano seconds part.
278+ ///
279+ /// # Examples
280+ ///
281+ /// ```
282+ /// use std::fs;
283+ /// use std::os::linux::fs::MetadataExt;
284+ ///
285+ /// # use std::io;
286+ /// # fn f() -> io::Result<()> {
287+ /// let meta = fs::metadata("some_file")?;
288+ /// println!("{}", meta.st_ctime_nsec());
289+ /// # Ok(())
290+ /// # }
291+ /// ```
80292#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
81293 fn st_ctime_nsec ( & self ) -> i64 ;
82294 /// Returns the "preferred" blocksize for efficient filesystem I/O.
295+ ///
296+ /// # Examples
297+ ///
298+ /// ```
299+ /// use std::fs;
300+ /// use std::os::linux::fs::MetadataExt;
301+ ///
302+ /// # use std::io;
303+ /// # fn f() -> io::Result<()> {
304+ /// let meta = fs::metadata("some_file")?;
305+ /// println!("{}", meta.st_blksize());
306+ /// # Ok(())
307+ /// # }
308+ /// ```
83309#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
84310 fn st_blksize ( & self ) -> u64 ;
85311 /// Returns the number of blocks allocated to the file, 512-byte units.
312+ ///
313+ /// # Examples
314+ ///
315+ /// ```
316+ /// use std::fs;
317+ /// use std::os::linux::fs::MetadataExt;
318+ ///
319+ /// # use std::io;
320+ /// # fn f() -> io::Result<()> {
321+ /// let meta = fs::metadata("some_file")?;
322+ /// println!("{}", meta.st_blocks());
323+ /// # Ok(())
324+ /// # }
325+ /// ```
86326#[ stable( feature = "metadata_ext2" , since = "1.8.0" ) ]
87327 fn st_blocks ( & self ) -> u64 ;
88328}
0 commit comments