More miscellaneous cleanups (#554)

* Change the `dirfd` argument name of the `statx` declaration.

* Update the README.

* Remove unneeded `&`s in tests and examples.

* Add comments describing how to run the benchmarks.

* Use `cfg`s consistently in tests.

* Don't distribute the benches directory.

It isn't needed for users of the crate.

* Use top-level comment syntax for a top-level comment.

* Remove unneded `#![allow_unsafe]`s.

* Add some top-level comments.

* Remove unnecessary `.cast()`s.

Author: sunfishcode

Cargo.toml

@@ -12,7 +12,7 @@ repository = "https://github.com/bytecodealliance/rustix"
 edition = "2018"
 keywords = ["api", "file", "network", "safe", "syscall"]
 categories = ["os::unix-apis", "date-and-time", "filesystem", "network-programming"]
-include = ["src", "build.rs", "Cargo.toml", "COPYRIGHT", "LICENSE*", "/*.md", "benches"]
+include = ["src", "build.rs", "Cargo.toml", "COPYRIGHT", "LICENSE*", "/*.md"]
 rust-version = "1.48"
 
 [build-dependencies]

README.md

@@ -26,8 +26,8 @@ conveniences.
 
 `rustix` is low-level and, and while the `net` API supports Winsock2 on
 Windows, the rest of the APIs do not support Windows; for higher-level and more
-portable APIs built on this functionality, see the [`system-interface`],
-[`cap-std`], and [`fs-set-times`] crates, for example.
+portable APIs built on this functionality, see the [`cap-std`], [`memfd`],
+[`timerfd`], and [`io-streams`] crates, for example.
 
 `rustix` currently has two backends available:
 
@@ -114,14 +114,14 @@ provides them as free functions rather than associated functions of a `Dir`
 type. `rustix`'s `cwd()` function exposes the special `AT_FDCWD` value in a safe
 way, so users don't need to open `.` to get a current-directory handle.
 
-`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses
-I/O safety types rather than `RawFd`. `rustix` does not provide dynamic feature
+`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses I/O
+safety types rather than `RawFd`. `rustix` does not provide dynamic feature
 detection, so users must handle the [`NOSYS`] error themselves.
 
-`rustix`'s `termios` module is similar to the [`termios`] crate, but uses
-I/O safety types rather than `RawFd`, and the flags parameters to functions
-such as `tcsetattr` are `enum`s rather than bare integers. And, rustix calls
-its `tcgetattr` function `tcgetattr`, rather than `Termios::from_fd`.
+`rustix`'s `termios` module is similar to the [`termios`] crate, but uses I/O
+safety types rather than `RawFd`, and the flags parameters to functions such as
+`tcsetattr` are `enum`s rather than bare integers. And, rustix calls its
+`tcgetattr` function `tcgetattr`, rather than `Termios::from_fd`.
 
 ## Minimum Supported Rust Version (MSRV)
 
@@ -140,7 +140,6 @@ version of this crate.
 [`syscall`]: https://crates.io/crates/syscall
 [`sc`]: https://crates.io/crates/sc
 [`scall`]: https://crates.io/crates/scall
-[`system-interface`]: https://crates.io/crates/system-interface
 [`openat`]: https://crates.io/crates/openat
 [`openat2`]: https://crates.io/crates/openat2
 [`fs-set-times`]: https://crates.io/crates/fs-set-times
@@ -149,6 +148,9 @@ version of this crate.
 [`libc`]: https://crates.io/crates/libc
 [`windows-sys`]: https://crates.io/crates/windows-sys
 [`cap-std`]: https://crates.io/crates/cap-std
+[`memfd`]: https://crates.io/crates/memfd
+[`timerfd`]: https://crates.io/crates/timerfd
+[`io-streams`]: https://crates.io/crates/io-streams
 [`bitflags`]: https://crates.io/crates/bitflags
 [`Arg`]: https://docs.rs/rustix/latest/rustix/path/trait.Arg.html
 [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md

benches/mod.rs

@@ -1,7 +1,11 @@
-/// Benchmarks for rustix.
-///
-/// To enable these benchmarks, add `--cfg=criterion` to RUSTFLAGS and enable
-/// the "fs", "time", and "process" cargo features.
+//! Benchmarks for rustix.
+//!
+//! To enable these benchmarks, add `--cfg=criterion` to RUSTFLAGS and enable
+//! the "fs", "time", and "process" cargo features.
+//!
+//! ```sh
+//! RUSTFLAGS=--cfg=criterion cargo bench --features=fs,time,process
+//! ```
 
 #[cfg(any(
     not(criterion),
@@ -14,7 +18,7 @@
     target_os = "wasi",
 ))]
 fn main() {
-    unimplemented!()
+    unimplemented!("Add --cfg=criterion to RUSTFLAGS and enable the \"fs\", \"time\", and \"process\" cargo features.")
 }
 
 #[cfg(not(any(

examples/hello.rs

@@ -15,7 +15,7 @@ fn main() -> std::io::Result<()> {
     let stdout = rustix::io::stdout();
 
     while !bytes.is_empty() {
-        match rustix::io::write(&stdout, bytes) {
+        match rustix::io::write(stdout, bytes) {
             // `write` can write fewer bytes than requested. In that case,
             // continue writing with the remainder of the bytes.
             Ok(n) => bytes = &bytes[n..],

examples/stdio.rs

@@ -22,13 +22,13 @@ fn main() -> io::Result<()> {
     let (stdin, stdout, stderr) = (stdin(), stdout(), stderr());
 
     println!("Stdin:");
-    show(&stdin)?;
+    show(stdin)?;
 
     println!("Stdout:");
-    show(&stdout)?;
+    show(stdout)?;
 
     println!("Stderr:");
-    show(&stderr)?;
+    show(stderr)?;
 
     Ok(())
 }

src/backend/libc/fs/syscalls.rs

@@ -1422,7 +1422,7 @@ mod sys {
 
     weak_or_syscall! {
         pub(super) fn statx(
-            pirfd: BorrowedFd<'_>,
+            dirfd_: BorrowedFd<'_>,
             path: *const c::c_char,
             flags: c::c_int,
             mask: c::c_uint,

src/backend/libc/process/cpu_set.rs

@@ -1,3 +1,5 @@
+//! Rust implementation of the `CPU_*` macro API.
+
 #![allow(non_snake_case)]
 
 use super::super::c;

src/backend/libc/weak.rs

@@ -111,7 +111,7 @@ unsafe fn fetch(name: &str) -> *mut c_void {
         Ok(c_str) => c_str,
         Err(..) => return null_mut(),
     };
-    libc::dlsym(libc::RTLD_DEFAULT, name.as_ptr().cast())
+    libc::dlsym(libc::RTLD_DEFAULT, name.as_ptr())
 }
 
 #[cfg(not(any(target_os = "android", target_os = "linux")))]

src/backend/linux_raw/process/cpu_set.rs

@@ -1,3 +1,5 @@
+//! Rust implementation of the `CPU_*` macro API.
+
 #![allow(non_snake_case)]
 
 use super::types::RawCpuSet;

src/backend/linux_raw/runtime/tls.rs

@@ -1,3 +1,9 @@
+//! TLS utilities.
+//!
+//! # Safety
+//!
+//! This file contains code that reads the raw phdr array pointed to by the
+//! kernel-provided AUXV values.
 #![allow(unsafe_code)]
 
 use super::super::c;