@@ -17,17 +17,38 @@ use libc::{dirent, readdir_r};
17
17
18
18
/// An open directory.
19
19
///
20
- /// This is a lower-level interface than `std::fs::ReadDir`. Notable differences:
21
- /// * can be opened from a file descriptor (as returned by `openat`, perhaps before knowing
22
- /// if the path represents a file or directory).
23
- /// * implements `AsRawFd` , so it can be passed to `fstat`, `openat`, etc.
24
- /// The file descriptor continues to be owned by the `Dir`, so callers must not keep a `RawFd`
25
- /// after the `Dir` is dropped.
20
+ /// This is a lower-level interface than [ `std::fs::ReadDir`] . Notable differences:
21
+ /// * can be opened from a file descriptor (as returned by [ `openat`][openat],
22
+ /// perhaps before knowing if the path represents a file or directory).
23
+ /// * implements [`AsFd`][AsFd] , so it can be passed to [ `fstat`][fstat],
24
+ /// [`openat`][openat], etc. The file descriptor continues to be owned by the
25
+ /// `Dir`, so callers must not keep a `RawFd` after the `Dir` is dropped.
26
26
/// * can be iterated through multiple times without closing and reopening the file
27
27
/// descriptor. Each iteration rewinds when finished.
28
28
/// * returns entries for `.` (current directory) and `..` (parent directory).
29
- /// * returns entries' names as a `CStr` (no allocation or conversion beyond whatever libc
29
+ /// * returns entries' names as a [ `CStr`][cstr] (no allocation or conversion beyond whatever libc
30
30
/// does).
31
+ ///
32
+ /// [AsFd]: std::os::fd::AsFd
33
+ /// [fstat]: crate::sys::stat::fstat
34
+ /// [openat]: crate::fcntl::openat
35
+ /// [cstr]: std::ffi::CStr
36
+ ///
37
+ /// # Examples
38
+ ///
39
+ /// Traverse the current directory, and print entries' names:
40
+ ///
41
+ /// ```
42
+ /// use nix::dir::Dir;
43
+ /// use nix::fcntl::OFlag;
44
+ /// use nix::sys::stat::Mode;
45
+ ///
46
+ /// let mut cwd = Dir::open(".", OFlag::O_RDONLY | OFlag::O_CLOEXEC, Mode::empty()).unwrap();
47
+ /// for res_entry in cwd.iter() {
48
+ /// let entry = res_entry.unwrap();
49
+ /// println!("File name: {}", entry.file_name().to_str().unwrap());
50
+ /// }
51
+ /// ```
31
52
#[ derive( Debug , Eq , Hash , PartialEq ) ]
32
53
pub struct Dir ( ptr:: NonNull < libc:: DIR > ) ;
33
54
@@ -75,6 +96,19 @@ impl Dir {
75
96
}
76
97
77
98
/// Converts from a file descriptor, closing it on failure.
99
+ ///
100
+ /// # Examples
101
+ ///
102
+ /// `ENOTDIR` would be returned if `fd` does not refer to a directory:
103
+ ///
104
+ /// ```should_panic
105
+ /// use std::os::fd::OwnedFd;
106
+ /// use nix::dir::Dir;
107
+ ///
108
+ /// let temp_file = tempfile::tempfile().unwrap();
109
+ /// let temp_file_fd: OwnedFd = temp_file.into();
110
+ /// let never = Dir::from_fd(temp_file_fd).unwrap();
111
+ /// ```
78
112
#[ doc( alias( "fdopendir" ) ) ]
79
113
pub fn from_fd ( fd : std:: os:: fd:: OwnedFd ) -> Result < Self > {
80
114
// take the ownership as the constructed `Dir` is now the owner
0 commit comments