Skip to content

Commit

Permalink
More miscellaneous cleanups (#554)
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
sunfishcode authored Mar 3, 2023
1 parent f1d44da commit 352cc4e
Show file tree
Hide file tree
Showing 31 changed files with 72 additions and 56 deletions.
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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)

Expand All @@ -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
Expand All @@ -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
Expand Down
14 changes: 9 additions & 5 deletions benches/mod.rs
Original file line number Diff line number Diff line change
@@ -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),
Expand All @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion examples/hello.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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..],
Expand Down
6 changes: 3 additions & 3 deletions examples/stdio.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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(())
}
Expand Down
2 changes: 1 addition & 1 deletion src/backend/libc/fs/syscalls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions src/backend/libc/process/cpu_set.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Rust implementation of the `CPU_*` macro API.
#![allow(non_snake_case)]

use super::super::c;
Expand Down
2 changes: 1 addition & 1 deletion src/backend/libc/weak.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")))]
Expand Down
2 changes: 2 additions & 0 deletions src/backend/linux_raw/process/cpu_set.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Rust implementation of the `CPU_*` macro API.
#![allow(non_snake_case)]

use super::types::RawCpuSet;
Expand Down
6 changes: 6 additions & 0 deletions src/backend/linux_raw/runtime/tls.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/weak.rs
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,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")))]
Expand Down
6 changes: 6 additions & 0 deletions src/io/pipe.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
//! `pipe` and related APIs.
//!
//! # Safety
//!
//! `vmsplice` is an unsafe function.
#![allow(unsafe_code)]

use crate::fd::OwnedFd;
Expand Down
2 changes: 0 additions & 2 deletions src/net/addr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@
//! This defines `SocketAddr`, `SocketAddrV4`, and `SocketAddrV6` in a
//! platform-independent way. It is not the native representation.
#![allow(unsafe_code)]

use crate::net::ip::{IpAddr, Ipv4Addr, Ipv6Addr};
use core::cmp::Ordering;
use core::hash;
Expand Down
9 changes: 9 additions & 0 deletions src/thread/prctl.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
//! Linux `prctl` wrappers.
//!
//! Rustix wraps variadic/dynamic-dispatch functions like `prctl` in
//! type-safe wrappers.
//!
//! # Safety
//!
//! The inner `prctl` calls are dynamically typed and must be called
//! correctly.
#![allow(unsafe_code)]

use core::convert::TryFrom;
Expand Down
2 changes: 0 additions & 2 deletions src/thread/setns.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![allow(unsafe_code)]

use bitflags::bitflags;
use linux_raw_sys::general::{
CLONE_FILES, CLONE_FS, CLONE_NEWCGROUP, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID,
Expand Down
1 change: 1 addition & 0 deletions tests/fs/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ mod mknodat;
mod openat;
#[cfg(any(target_os = "android", target_os = "linux"))]
mod openat2;
#[cfg(not(target_os = "redox"))]
mod readdir;
mod renameat;
#[cfg(not(any(solarish, target_os = "haiku", target_os = "redox", target_os = "wasi")))]
Expand Down
6 changes: 3 additions & 3 deletions tests/fs/openat2.rs
Original file line number Diff line number Diff line change
Expand Up @@ -86,23 +86,23 @@ fn test_openat2() {
.unwrap();
let _ = openat2_more(
&dir,
&format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
OFlags::RDONLY | OFlags::CLOEXEC,
Mode::empty(),
ResolveFlags::empty(),
)
.unwrap();
let _ = openat2_more(
&dir,
&format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
OFlags::RDONLY | OFlags::CLOEXEC,
Mode::empty(),
ResolveFlags::NO_SYMLINKS,
)
.unwrap_err();
let _ = openat2_more(
&dir,
&format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
format!("/proc/self/fd/{}", test.as_fd().as_raw_fd()),
OFlags::RDONLY | OFlags::CLOEXEC,
Mode::empty(),
ResolveFlags::NO_MAGICLINKS,
Expand Down
2 changes: 0 additions & 2 deletions tests/fs/readdir.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(not(target_os = "redox"))]

use std::collections::HashMap;
use std::fs::File;
#[cfg(any(target_os = "android", target_os = "linux"))]
Expand Down
4 changes: 2 additions & 2 deletions tests/fs/y2038.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ fn test_y2038_with_utimensat() {
use std::convert::TryInto;

let tmp = tempfile::tempdir().unwrap();
let dir = openat(&cwd(), tmp.path(), OFlags::RDONLY, Mode::empty()).unwrap();
let dir = openat(cwd(), tmp.path(), OFlags::RDONLY, Mode::empty()).unwrap();

let m_sec = 1_u64 << 32;
let m_nsec = 17_u32;
Expand Down Expand Up @@ -112,7 +112,7 @@ fn test_y2038_with_futimens() {
use std::convert::TryInto;

let tmp = tempfile::tempdir().unwrap();
let dir = openat(&cwd(), tmp.path(), OFlags::RDONLY, Mode::empty()).unwrap();
let dir = openat(cwd(), tmp.path(), OFlags::RDONLY, Mode::empty()).unwrap();

let m_sec = 1_u64 << 32;
let m_nsec = 17_u32;
Expand Down
2 changes: 0 additions & 2 deletions tests/io/dup2_to_replace_stdio.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(not(target_os = "wasi"))]

use std::env;
use std::process::Command;

Expand Down
2 changes: 0 additions & 2 deletions tests/io/epoll.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(any(target_os = "android", target_os = "linux"))]

use rustix::io::{epoll, ioctl_fionbio, read, write};
use rustix::net::{
accept, bind_v4, connect_v4, getsockname, listen, socket, AddressFamily, Ipv4Addr, Protocol,
Expand Down
3 changes: 1 addition & 2 deletions tests/io/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,8 @@
#[cfg(not(target_os = "wasi"))]
mod dup2_to_replace_stdio;
#[cfg(not(feature = "rustc-dep-of-std"))] // TODO
#[cfg(not(windows))]
#[cfg(feature = "net")]
#[cfg(not(target_os = "wasi"))]
#[cfg(any(target_os = "android", target_os = "linux"))]
mod epoll;
mod error;
#[cfg(not(windows))]
Expand Down
2 changes: 1 addition & 1 deletion tests/io/poll.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ use rustix::fd::{AsFd, AsRawFd, FromRawFd, IntoRawFd, OwnedFd};
use rustix::io::{poll, retry_on_intr};
use rustix::io::{PollFd, PollFlags};

#[cfg(not(windows))]
#[cfg(not(any(windows, target_os = "wasi")))]
#[test]
fn test_poll() {
use rustix::io::{pipe, read, write};
Expand Down
5 changes: 2 additions & 3 deletions tests/mm/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,9 @@
#![cfg_attr(target_os = "wasi", feature(wasi_ext))]
#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]

#[cfg(not(windows))]
#[cfg(not(target_os = "wasi"))]
#[cfg(not(any(windows, target_os = "wasi")))]
mod mlock;
#[cfg(not(windows))]
#[cfg(not(any(windows, target_os = "wasi")))]
mod mmap;
#[cfg(not(windows))]
mod prot;
2 changes: 0 additions & 2 deletions tests/mm/mmap.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(not(target_os = "wasi"))]

#[cfg(feature = "fs")]
#[cfg(not(target_os = "redox"))]
#[test]
Expand Down
1 change: 1 addition & 0 deletions tests/process/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,5 @@ mod uname;
#[cfg(not(target_os = "wasi"))] // WASI doesn't have waitpid.
mod wait;
#[cfg(not(any(target_os = "redox", target_os = "wasi")))]
#[cfg(feature = "fs")]
mod working_directory;
2 changes: 1 addition & 1 deletion tests/process/weak.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")))]
Expand Down
2 changes: 0 additions & 2 deletions tests/process/working_directory.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(feature = "fs")]

#[cfg(not(any(target_os = "fuchsia", target_os = "macos")))]
use rustix::fs::{Mode, OFlags};
use tempfile::{tempdir, TempDir};
Expand Down
12 changes: 6 additions & 6 deletions tests/termios/isatty.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,21 @@ fn stdout_stderr_terminals() {
}

// Compare `isatty` against `libc::isatty`.
assert_eq!(isatty(&std::io::stdout()), unsafe {
assert_eq!(isatty(std::io::stdout()), unsafe {
libc::isatty(std::io::stdout().as_raw_fd()) != 0
});
assert_eq!(isatty(&std::io::stderr()), unsafe {
assert_eq!(isatty(std::io::stderr()), unsafe {
libc::isatty(std::io::stderr().as_raw_fd()) != 0
});

// Compare `isatty` against `tcgetwinsize`.
assert_eq!(
isatty(&std::io::stdout()),
tcgetwinsize(&std::io::stdout()).is_ok()
isatty(std::io::stdout()),
tcgetwinsize(std::io::stdout()).is_ok()
);
assert_eq!(
isatty(&std::io::stderr()),
tcgetwinsize(&std::io::stderr()).is_ok()
isatty(std::io::stderr()),
tcgetwinsize(std::io::stderr()).is_ok()
);
}

Expand Down
2 changes: 0 additions & 2 deletions tests/time/dynamic_clocks.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![cfg(not(any(target_os = "redox", target_os = "wasi")))]

use rustix::fd::AsFd;
use rustix::time::{clock_gettime_dynamic, ClockId, DynamicClockId};

Expand Down
1 change: 1 addition & 0 deletions tests/time/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
#![cfg_attr(target_os = "wasi", feature(wasi_ext))]
#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]

#[cfg(not(any(target_os = "redox", target_os = "wasi")))]
mod dynamic_clocks;
#[cfg(not(any(target_os = "redox", target_os = "wasi")))]
mod monotonic;
Expand Down

0 comments on commit 352cc4e

Please sign in to comment.