docs: update docs of xxat() fns (#2444)

src/fcntl.rs

@@ -41,7 +41,8 @@ use crate::{sys::stat::Mode, NixPath, Result};
 #[cfg(feature = "fs")]
 pub use self::posix_fadvise::{posix_fadvise, PosixFadviseAdvice};
 
-/// A file descriptor referring to the working directory of the current process.
+/// A file descriptor referring to the working directory of the current process
+/// **that should be ONLY passed to the `dirfd` argument of those `xxat()` functions**.
 ///
 /// # Examples
 ///
@@ -262,7 +263,7 @@ pub fn open<P: ?Sized + NixPath>(
 ///
 /// The `openat` function is equivalent to the [`open`] function except in the case where the path
 /// specifies a relative path.  In that case, the file to be opened is determined relative to the
-/// directory associated with the file descriptor `fd`.
+/// directory associated with the file descriptor `dirfd`.
 ///
 /// # See Also
 /// [`openat`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/openat.html)
@@ -324,9 +325,11 @@ cfg_if::cfg_if! {
             }
         }
 
-        /// Specifies how [openat2] should open a pathname.
+        /// Specifies how [`openat2()`] should open a pathname.
         ///
-        /// See <https://man7.org/linux/man-pages/man2/open_how.2type.html>
+        /// # Reference
+        ///
+        /// * [Linux](https://man7.org/linux/man-pages/man2/open_how.2type.html)
         #[repr(transparent)]
         #[derive(Clone, Copy, Debug)]
         pub struct OpenHow(libc::open_how);
@@ -666,8 +669,9 @@ pub fn readlink<P: ?Sized + NixPath>(path: &P) -> Result<OsString> {
 
 /// Read value of a symbolic link.
 ///
-/// Equivalent to [`readlink` ] except where `path` specifies a relative path.  In that case,
-/// interpret `path` relative to open file specified by `dirfd`.
+/// Equivalent to [`readlink` ] except for the case where `path` specifies a
+/// relative path, `path` will be interpreted relative to the path specified
+/// by `dirfd`. (Use [`AT_FDCWD`] to make it relative to the working directory).
 ///
 /// # See Also
 /// * [`readlink`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html)

src/sys/stat.rs

@@ -292,12 +292,12 @@ pub enum FchmodatFlags {
 ///
 /// The file to be changed is determined relative to the directory associated
 /// with the file descriptor `dirfd` or the current working directory
-/// if `dirfd` is `None`.
+/// if `dirfd` is [`AT_FDCWD`](crate::fcntl::AT_FDCWD).
 ///
 /// If `flag` is `FchmodatFlags::NoFollowSymlink` and `path` names a symbolic link,
 /// then the mode of the symbolic link is changed.
 ///
-/// `fchmodat(None, path, mode, FchmodatFlags::FollowSymlink)` is identical to
+/// `fchmodat(AT_FDCWD, path, mode, FchmodatFlags::FollowSymlink)` is identical to
 /// a call `libc::chmod(path, mode)`. That's why `chmod` is unimplemented
 /// in the `nix` crate.
 ///
@@ -416,12 +416,12 @@ pub enum UtimensatFlags {
 ///
 /// The file to be changed is determined relative to the directory associated
 /// with the file descriptor `dirfd` or the current working directory
-/// if `dirfd` is `None`.
+/// if `dirfd` is [`AT_FDCWD`](crate::fcntl::AT_FDCWD).
 ///
 /// If `flag` is `UtimensatFlags::NoFollowSymlink` and `path` names a symbolic link,
 /// then the mode of the symbolic link is changed.
 ///
-/// `utimensat(None, path, times, UtimensatFlags::FollowSymlink)` is identical to
+/// `utimensat(AT_FDCWD, path, times, UtimensatFlags::FollowSymlink)` is identical to
 /// `utimes(path, times)`. The latter is a deprecated API so prefer using the
 /// former if the platforms you care about support it.
 ///
@@ -458,17 +458,25 @@ pub fn utimensat<Fd: std::os::fd::AsFd, P: ?Sized + NixPath>(
     Errno::result(res).map(drop)
 }
 
+/// Create a directory at the path specified by `dirfd` and `path`.
+///
+/// If `path` is a relative path, then it is interpreted relative to the directory
+/// referred to by the file descriptor `dirfd`. (One can use [`AT_FDCWD`][link] to
+/// specify the current working directory in `dirfd`). If `path` is absolute,
+/// then `dirfd` is ignored.
+///
+/// [link]: crate::fcntl::AT_FDCWD
 #[cfg(not(target_os = "redox"))]
 pub fn mkdirat<Fd: std::os::fd::AsFd, P: ?Sized + NixPath>(
-    fd: Fd,
+    dirfd: Fd,
     path: &P,
     mode: Mode,
 ) -> Result<()> {
     use std::os::fd::AsRawFd;
 
     let res = path.with_nix_path(|cstr| unsafe {
         libc::mkdirat(
-            fd.as_fd().as_raw_fd(),
+            dirfd.as_fd().as_raw_fd(),
             cstr.as_ptr(),
             mode.bits() as mode_t,
         )

src/unistd.rs

@@ -773,7 +773,7 @@ pub fn mkdir<P: ?Sized + NixPath>(path: &P, mode: crate::sys::stat::Mode) -> Res
     Errno::result(res).map(drop)
 }
 
-/// Creates new fifo special file (named pipe) with path `path` and access rights `mode`.
+/// Creates new FIFO special file (named pipe) with path `path` and access rights `mode`.
 ///
 /// # Errors
 ///
@@ -812,7 +812,8 @@ pub fn mkfifo<P: ?Sized + NixPath>(path: &P, mode: crate::sys::stat::Mode) -> Re
     Errno::result(res).map(drop)
 }
 
-/// Creates new fifo special file (named pipe) with path `path` and access rights `mode`.
+/// Creates new FIFO special file (named pipe) with access rights set to `mode`
+/// in the path specified by `dirfd` and `path`.
 ///
 /// # Examples
 ///
@@ -851,11 +852,12 @@ pub fn mkfifoat<Fd: std::os::fd::AsFd, P: ?Sized + NixPath>(
     Errno::result(res).map(drop)
 }
 
-/// Creates a symbolic link at `path2` which points to `path1`.
+/// Creates a symbolic link to `path1` in the path specified by `dirfd` and
+/// `path2`.
 ///
 /// # Examples
 ///
-/// Assume file foo exists in the current working directory, create a symlink
+/// Assume file `foo` exists in the current working directory, create a symlink
 /// to it:
 ///
 /// ```no_run
@@ -1585,9 +1587,10 @@ impl LinkatFlags {
 /// Creates a new hard link (directory entry) at `newpath` for the existing file
 /// at `oldpath`. In the case of a relative `oldpath`, the path is interpreted
 /// relative to the directory associated with file descriptor `olddirfd` instead
-/// of the current working directory and similarly for `newpath` and file
-/// descriptor `newdirfd`. If either `oldpath` or `newpath` is absolute, then
-/// `dirfd` is ignored.
+/// of the current working directory, use [`AT_FDCWD`](crate::fcntl::AT_FDCWD)
+/// if you want to make it relative to the current working directory. Similarly
+/// for `newpath` and file descriptor `newdirfd`. If either `oldpath` or `newpath`
+/// is absolute, then `dirfd` is ignored.
 ///
 /// In case `flag` is `AtFlags::AT_SYMLINK_FOLLOW` and `oldpath` names a symoblic
 /// link, a new link for the target of the symbolic link is created.
@@ -1639,10 +1642,12 @@ pub enum UnlinkatFlags {
 /// Remove a directory entry
 ///
 /// In the case of a relative path, the directory entry to be removed is determined
-/// relative to the directory associated with the file descriptor `dirfd`. In the
-/// case of an absolute `path` `dirfd` is ignored. If `flag` is
-/// `UnlinkatFlags::RemoveDir` then removal of the directory entry specified by
-/// `dirfd` and `path` is performed.
+/// relative to the directory associated with the file descriptor `dirfd` (Use
+/// [`AT_FDCWD`](crate::fcntl::AT_FDCWD) if you want to specify the current working
+/// directory in `dirfd`). In the case of an absolute path, `dirfd` is ignored.
+///
+/// If `flag` is `UnlinkatFlags::RemoveDir` then removal of the directory entry
+/// specified by `dirfd` and `path` is performed.
 ///
 /// # References
 /// See also [unlinkat(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/unlinkat.html)