Skip to content

Commit ec5444f

Browse files
committed
docs: more examples
1 parent 5bf789c commit ec5444f

File tree

2 files changed

+67
-7
lines changed

2 files changed

+67
-7
lines changed

src/dir.rs

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,38 @@ use libc::{dirent, readdir_r};
1717

1818
/// An open directory.
1919
///
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.
2626
/// * can be iterated through multiple times without closing and reopening the file
2727
/// descriptor. Each iteration rewinds when finished.
2828
/// * 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
3030
/// 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+
/// ```
3152
#[derive(Debug, Eq, Hash, PartialEq)]
3253
pub struct Dir(ptr::NonNull<libc::DIR>);
3354

@@ -75,6 +96,19 @@ impl Dir {
7596
}
7697

7798
/// 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+
/// ```
78112
#[doc(alias("fdopendir"))]
79113
pub fn from_fd(fd: std::os::fd::OwnedFd) -> Result<Self> {
80114
// take the ownership as the constructed `Dir` is now the owner

src/fcntl.rs

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,32 @@ use crate::{sys::stat::Mode, NixPath, Result};
4444
pub use self::posix_fadvise::{posix_fadvise, PosixFadviseAdvice};
4545

4646
/// A file descriptor referring to the working directory of the current process.
47+
///
48+
/// # Examples
49+
///
50+
/// Use it in [`openat()`]:
51+
///
52+
/// ```no_run
53+
/// use nix::fcntl::AT_FDCWD;
54+
/// use nix::fcntl::openat;
55+
/// use nix::fcntl::OFlag;
56+
/// use nix::sys::stat::Mode;
57+
///
58+
/// let fd = openat(AT_FDCWD, "foo", OFlag::O_RDONLY | OFlag::O_CLOEXEC, Mode::empty()).unwrap();
59+
/// ```
60+
///
61+
/// # WARNING
62+
///
63+
/// Do NOT pass this symbol to non-`xxat()` functions, it won't work:
64+
///
65+
/// ```should_panic
66+
/// use nix::errno::Errno;
67+
/// use nix::fcntl::AT_FDCWD;
68+
/// use nix::sys::stat::fstat;
69+
/// use std::os::fd::AsRawFd;
70+
///
71+
/// let never = fstat(AT_FDCWD.as_raw_fd()).unwrap();
72+
/// ```
4773
//
4874
// SAFETY:
4975
// 1. `AT_FDCWD` is usable for the whole process life, so it is `'static`.

0 commit comments

Comments
 (0)