Skip to content

Commit af1e4f6

Browse files
GuillaumeGomezGuillaumeGomez
committed
add missing docs for MetadataExt
1 parent 4c053db commit af1e4f6

File tree

1 file changed

+246
-0
lines changed
  • src/libstd/sys/unix/ext

1 file changed

+246
-0
lines changed

‎src/libstd/sys/unix/ext/fs.rs

+246
Original file line numberDiff line numberDiff line change
@@ -215,36 +215,282 @@ impl OpenOptionsExt for OpenOptions {
215215
// casts and rely on manual lowering to `stat` if the raw type is desired.
216216
#[stable(feature = "metadata_ext", since = "1.1.0")]
217217
pub trait MetadataExt {
218+
/// Returns the ID of the device containing the file.
219+
///
220+
/// # Examples
221+
///
222+
/// ```no_run
223+
/// use std::fs;
224+
/// use std::os::unix::fs::MetadataExt;
225+
///
226+
/// # use std::io;
227+
/// # fn f() -> io::Result<()> {
228+
/// let meta = fs::metadata("some_file")?;
229+
/// let dev_id = meta.dev();
230+
/// # Ok(())
231+
/// # }
232+
/// ```
218233
#[stable(feature = "metadata_ext", since = "1.1.0")]
219234
fn dev(&self) -> u64;
235+
/// Returns the inode number.
236+
///
237+
/// # Examples
238+
///
239+
/// ```no_run
240+
/// use std::fs;
241+
/// use std::os::unix::fs::MetadataExt;
242+
///
243+
/// # use std::io;
244+
/// # fn f() -> io::Result<()> {
245+
/// let meta = fs::metadata("some_file")?;
246+
/// let inode = meta.ino();
247+
/// # Ok(())
248+
/// # }
249+
/// ```
220250
#[stable(feature = "metadata_ext", since = "1.1.0")]
221251
fn ino(&self) -> u64;
252+
/// Returns the rights applied to this file.
253+
///
254+
/// # Examples
255+
///
256+
/// ```no_run
257+
/// use std::fs;
258+
/// use std::os::unix::fs::MetadataExt;
259+
///
260+
/// # use std::io;
261+
/// # fn f() -> io::Result<()> {
262+
/// let meta = fs::metadata("some_file")?;
263+
/// let mode = meta.mode();
264+
/// let user_has_write_access = mode & 0o200;
265+
/// let user_has_read_write_access = mode & 0o600;
266+
/// let group_has_read_access = mode & 0o040;
267+
/// let others_have_exec_access = mode & 0o001;
268+
/// # Ok(())
269+
/// # }
270+
/// ```
222271
#[stable(feature = "metadata_ext", since = "1.1.0")]
223272
fn mode(&self) -> u32;
273+
/// Returns the number of hard links pointing to this file.
274+
///
275+
/// # Examples
276+
///
277+
/// ```no_run
278+
/// use std::fs;
279+
/// use std::os::unix::fs::MetadataExt;
280+
///
281+
/// # use std::io;
282+
/// # fn f() -> io::Result<()> {
283+
/// let meta = fs::metadata("some_file")?;
284+
/// let nb_hard_links = meta.nlink();
285+
/// # Ok(())
286+
/// # }
287+
/// ```
224288
#[stable(feature = "metadata_ext", since = "1.1.0")]
225289
fn nlink(&self) -> u64;
290+
/// Returns the user ID of the owner of this file.
291+
///
292+
/// # Examples
293+
///
294+
/// ```no_run
295+
/// use std::fs;
296+
/// use std::os::unix::fs::MetadataExt;
297+
///
298+
/// # use std::io;
299+
/// # fn f() -> io::Result<()> {
300+
/// let meta = fs::metadata("some_file")?;
301+
/// let user_id = meta.uid();
302+
/// # Ok(())
303+
/// # }
304+
/// ```
226305
#[stable(feature = "metadata_ext", since = "1.1.0")]
227306
fn uid(&self) -> u32;
307+
/// Returns the group ID of the owner of this file.
308+
///
309+
/// # Examples
310+
///
311+
/// ```no_run
312+
/// use std::fs;
313+
/// use std::os::unix::fs::MetadataExt;
314+
///
315+
/// # use std::io;
316+
/// # fn f() -> io::Result<()> {
317+
/// let meta = fs::metadata("some_file")?;
318+
/// let group_id = meta.gid();
319+
/// # Ok(())
320+
/// # }
321+
/// ```
228322
#[stable(feature = "metadata_ext", since = "1.1.0")]
229323
fn gid(&self) -> u32;
324+
/// Returns the device ID of this file (if it is a special one).
325+
///
326+
/// # Examples
327+
///
328+
/// ```no_run
329+
/// use std::fs;
330+
/// use std::os::unix::fs::MetadataExt;
331+
///
332+
/// # use std::io;
333+
/// # fn f() -> io::Result<()> {
334+
/// let meta = fs::metadata("some_file")?;
335+
/// let device_id = meta.rdev();
336+
/// # Ok(())
337+
/// # }
338+
/// ```
230339
#[stable(feature = "metadata_ext", since = "1.1.0")]
231340
fn rdev(&self) -> u64;
341+
/// Returns the total size of this file in bytes.
342+
///
343+
/// # Examples
344+
///
345+
/// ```no_run
346+
/// use std::fs;
347+
/// use std::os::unix::fs::MetadataExt;
348+
///
349+
/// # use std::io;
350+
/// # fn f() -> io::Result<()> {
351+
/// let meta = fs::metadata("some_file")?;
352+
/// let file_size = meta.size();
353+
/// # Ok(())
354+
/// # }
355+
/// ```
232356
#[stable(feature = "metadata_ext", since = "1.1.0")]
233357
fn size(&self) -> u64;
358+
/// Returns the time of the last access to the file.
359+
///
360+
/// # Examples
361+
///
362+
/// ```no_run
363+
/// use std::fs;
364+
/// use std::os::unix::fs::MetadataExt;
365+
///
366+
/// # use std::io;
367+
/// # fn f() -> io::Result<()> {
368+
/// let meta = fs::metadata("some_file")?;
369+
/// let last_access_time = meta.atime();
370+
/// # Ok(())
371+
/// # }
372+
/// ```
234373
#[stable(feature = "metadata_ext", since = "1.1.0")]
235374
fn atime(&self) -> i64;
375+
/// Returns the time of the last access to the file in nanoseconds.
376+
///
377+
/// # Examples
378+
///
379+
/// ```no_run
380+
/// use std::fs;
381+
/// use std::os::unix::fs::MetadataExt;
382+
///
383+
/// # use std::io;
384+
/// # fn f() -> io::Result<()> {
385+
/// let meta = fs::metadata("some_file")?;
386+
/// let nano_last_access_time = meta.atime_nsec();
387+
/// # Ok(())
388+
/// # }
389+
/// ```
236390
#[stable(feature = "metadata_ext", since = "1.1.0")]
237391
fn atime_nsec(&self) -> i64;
392+
/// Returns the time of the last modification of the file.
393+
///
394+
/// # Examples
395+
///
396+
/// ```no_run
397+
/// use std::fs;
398+
/// use std::os::unix::fs::MetadataExt;
399+
///
400+
/// # use std::io;
401+
/// # fn f() -> io::Result<()> {
402+
/// let meta = fs::metadata("some_file")?;
403+
/// let last_modification_time = meta.mtime();
404+
/// # Ok(())
405+
/// # }
406+
/// ```
238407
#[stable(feature = "metadata_ext", since = "1.1.0")]
239408
fn mtime(&self) -> i64;
409+
/// Returns the time of the last modification of the file in nanoseconds.
410+
///
411+
/// # Examples
412+
///
413+
/// ```no_run
414+
/// use std::fs;
415+
/// use std::os::unix::fs::MetadataExt;
416+
///
417+
/// # use std::io;
418+
/// # fn f() -> io::Result<()> {
419+
/// let meta = fs::metadata("some_file")?;
420+
/// let nano_last_modification_time = meta.mtime_nsec();
421+
/// # Ok(())
422+
/// # }
423+
/// ```
240424
#[stable(feature = "metadata_ext", since = "1.1.0")]
241425
fn mtime_nsec(&self) -> i64;
426+
/// Returns the time of the last status change of the file.
427+
///
428+
/// # Examples
429+
///
430+
/// ```no_run
431+
/// use std::fs;
432+
/// use std::os::unix::fs::MetadataExt;
433+
///
434+
/// # use std::io;
435+
/// # fn f() -> io::Result<()> {
436+
/// let meta = fs::metadata("some_file")?;
437+
/// let last_status_change_time = meta.ctime();
438+
/// # Ok(())
439+
/// # }
440+
/// ```
242441
#[stable(feature = "metadata_ext", since = "1.1.0")]
243442
fn ctime(&self) -> i64;
443+
/// Returns the time of the last status change of the file in nanoseconds.
444+
///
445+
/// # Examples
446+
///
447+
/// ```no_run
448+
/// use std::fs;
449+
/// use std::os::unix::fs::MetadataExt;
450+
///
451+
/// # use std::io;
452+
/// # fn f() -> io::Result<()> {
453+
/// let meta = fs::metadata("some_file")?;
454+
/// let nano_last_status_change_time = meta.ctime_nsec();
455+
/// # Ok(())
456+
/// # }
457+
/// ```
244458
#[stable(feature = "metadata_ext", since = "1.1.0")]
245459
fn ctime_nsec(&self) -> i64;
460+
/// Returns the blocksize for filesystem I/O.
461+
///
462+
/// # Examples
463+
///
464+
/// ```no_run
465+
/// use std::fs;
466+
/// use std::os::unix::fs::MetadataExt;
467+
///
468+
/// # use std::io;
469+
/// # fn f() -> io::Result<()> {
470+
/// let meta = fs::metadata("some_file")?;
471+
/// let blocksize = meta.blksize();
472+
/// # Ok(())
473+
/// # }
474+
/// ```
246475
#[stable(feature = "metadata_ext", since = "1.1.0")]
247476
fn blksize(&self) -> u64;
477+
/// Returns the number of blocks allocated to the file, in 512-byte units.
478+
///
479+
/// Please note that this may be smaller than `st_size / 512` when the file has holes.
480+
///
481+
/// # Examples
482+
///
483+
/// ```no_run
484+
/// use std::fs;
485+
/// use std::os::unix::fs::MetadataExt;
486+
///
487+
/// # use std::io;
488+
/// # fn f() -> io::Result<()> {
489+
/// let meta = fs::metadata("some_file")?;
490+
/// let blocks = meta.blocks();
491+
/// # Ok(())
492+
/// # }
493+
/// ```
248494
#[stable(feature = "metadata_ext", since = "1.1.0")]
249495
fn blocks(&self) -> u64;
250496
}

0 commit comments

Comments
 (0)