Disable use-libc-auxv by default, and document cargo features (#1389)

* Disable use-libc-auxv by default, and document cargo features

Disable use-libc-auxv by default, as we can now use `PR_GET_AUXV` on
most systems today, and fall back to "/proc/self/auxv".

And add documentation for the main user-facing Cargo features to
README.md.

Fixes #1387.

* Bump linux-raw-sys to 0.9.1 to pick up `EM_CURRENT` for powerpc.

* Bump linux-raw-sys to 0.9.2 to pick up `EM_CURRENT` for s390x.

Author: sunfishcode

Cargo.toml

@@ -30,7 +30,7 @@ compiler_builtins = { version = '0.1.49', optional = true }
 # libc backend can be selected via adding `--cfg=rustix_use_libc` to
 # `RUSTFLAGS` or enabling the `use-libc` cargo feature.
 [target.'cfg(all(not(rustix_use_libc), not(miri), target_os = "linux", any(target_endian = "little", any(target_arch = "s390x", target_arch = "powerpc")), any(target_arch = "arm", all(target_arch = "aarch64", target_pointer_width = "64"), target_arch = "riscv64", all(rustix_use_experimental_asm, target_arch = "powerpc"), all(rustix_use_experimental_asm, target_arch = "powerpc64"), all(rustix_use_experimental_asm, target_arch = "s390x"), all(rustix_use_experimental_asm, target_arch = "mips"), all(rustix_use_experimental_asm, target_arch = "mips32r6"), all(rustix_use_experimental_asm, target_arch = "mips64"), all(rustix_use_experimental_asm, target_arch = "mips64r6"), target_arch = "x86", all(target_arch = "x86_64", target_pointer_width = "64"))))'.dependencies]
-linux-raw-sys = { version = "0.9.0", default-features = false, features = ["general", "errno", "ioctl", "no_std", "elf"] }
+linux-raw-sys = { version = "0.9.2", default-features = false, features = ["general", "errno", "ioctl", "no_std", "elf"] }
 libc_errno = { package = "errno", version = "0.3.10", default-features = false, optional = true }
 libc = { version = "0.2.168", default-features = false, optional = true }
 
@@ -47,7 +47,7 @@ libc = { version = "0.2.168", default-features = false }
 # Some syscalls do not have libc wrappers, such as in `io_uring`. For these,
 # the libc backend uses the linux-raw-sys ABI and `libc::syscall`.
 [target.'cfg(all(any(target_os = "android", target_os = "linux"), any(rustix_use_libc, miri, not(all(target_os = "linux", any(target_endian = "little", any(target_arch = "s390x", target_arch = "powerpc")), any(target_arch = "arm", all(target_arch = "aarch64", target_pointer_width = "64"), target_arch = "riscv64", all(rustix_use_experimental_asm, target_arch = "powerpc"), all(rustix_use_experimental_asm, target_arch = "powerpc64"), all(rustix_use_experimental_asm, target_arch = "s390x"), all(rustix_use_experimental_asm, target_arch = "mips"), all(rustix_use_experimental_asm, target_arch = "mips32r6"), all(rustix_use_experimental_asm, target_arch = "mips64"), all(rustix_use_experimental_asm, target_arch = "mips64r6"), target_arch = "x86", all(target_arch = "x86_64", target_pointer_width = "64")))))))'.dependencies]
-linux-raw-sys = { version = "0.9.0", default-features = false, features = ["general", "ioctl", "no_std"] }
+linux-raw-sys = { version = "0.9.2", default-features = false, features = ["general", "ioctl", "no_std"] }
 
 # For the libc backend on Windows, use the Winsock API in windows-sys.
 [target.'cfg(windows)'.dependencies.windows-sys]
@@ -106,12 +106,8 @@ targets = [
 
 [features]
 
-# By default, use `std` and use libc for aux values.
-#
-# It turns out to be bizarrely awkward to obtain the aux values reliably and
-# efficiently on Linux from anywhere other than libc. We can do it, but most
-# users are better served by just using libc for this.
-default = ["std", "use-libc-auxv"]
+# By default, use `std`.
+default = ["std"]
 
 # This enables use of std. Disabling this enables `#![no_std]`, and requires
 # Rust 1.77 or newer.
@@ -200,8 +196,8 @@ all-apis = [
     "time",
 ]
 
-# When using the linux_raw backend, should we use libc for reading the aux
-# vectors, instead of reading them ourselves from /proc/self/auxv?
+# When using the linux_raw backend, should we use `getauxval` for reading aux
+# vectors, instead of `PR_GET_AUXV` or "/proc/self/auxv"?
 use-libc-auxv = []
 
 # Enable "use-explicitly-provided-auxv" mode, with a public

README.md

@@ -53,8 +53,8 @@ building.
 ## Cargo features
 
 The modules [`rustix::io`], [`rustix::fd`], [`rustix::ffi`], and
-[`rustix::ioctl`] are enabled by default. The rest of the API is conditional
-with cargo feature flags:
+[`rustix::ioctl`] are enabled by default. The rest of the API modules are
+conditional with cargo feature flags.
 
 | Name       | Description                                                    |
 | ---------- | -------------------------------------------------------------- |
@@ -77,6 +77,16 @@ with cargo feature flags:
 | `time`     | [`rustix::time`]—Time-related operations.                      |
 |            |                                                                |
 | `use-libc` | Enable the libc backend.                                       |
+|            |                                                                |
+| `linux_4_11`    | Enable optimizations that assume Linux ≥ 4.11             |
+| `linux_5_1`     | Enable optimizations that assume Linux ≥ 5.1              |
+| `linux_5_11`    | Enable optimizations that assume Linux ≥ 5.11             |
+| `linux_latest`  | Enable optimizations that assume the latest Linux release |
+|                 |                                                           |
+| `use-libc-auxv` | Use `getauxval` instead of `PR_GET_AUXV` or "/proc/self/auxv". |
+|                 |                                                           |
+| `std`      | On by default; disable to activate `#![no_std]`.               |
+| `alloc`    | On by default; enables features that depend on [`alloc`].      |
 
 [`rustix::event`]: https://docs.rs/rustix/*/rustix/event/index.html
 [`rustix::fs`]: https://docs.rs/rustix/*/rustix/fs/index.html
@@ -194,3 +204,4 @@ always reflect “very old” Linux versions.
 [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html
 [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html
 [`NOSYS`]: https://docs.rs/rustix/*/rustix/io/struct.Errno.html#associatedconstant.NOSYS
+[`alloc`]: https://doc.rust-lang.org/alloc/alloc/index.html

src/backend/libc/event/syscalls.rs

@@ -379,7 +379,7 @@ pub(crate) fn port_get(port: BorrowedFd<'_>, timeout: Option<&Timespec>) -> io::
 
     let mut event = MaybeUninit::<c::port_event>::uninit();
 
-    // In Rust >= 1.65, the `as _` can be `.cast_mut()`.
+    // In Rust ≥ 1.65, the `as _` can be `.cast_mut()`.
     unsafe {
         ret(c::port_get(
             borrowed_fd(port),
@@ -426,7 +426,7 @@ pub(crate) unsafe fn port_getn(
         return Ok(0);
     }
 
-    // In Rust >= 1.65, the `as _` can be `.cast_mut()`.
+    // In Rust ≥ 1.65, the `as _` can be `.cast_mut()`.
     ret(c::port_getn(
         borrowed_fd(port),
         events.0.cast(),
@@ -538,7 +538,7 @@ pub(crate) unsafe fn epoll_wait(
     events: (*mut crate::event::epoll::Event, usize),
     timeout: Option<&Timespec>,
 ) -> io::Result<usize> {
-    // If we're on Linux >= 5.11 and a libc that has an `epoll_pwait2`
+    // If we're on Linux ≥ 5.11 and a libc that has an `epoll_pwait2`
     // function, and it's y2038-safe, use it.
     #[cfg(all(
         linux_kernel,
@@ -569,7 +569,7 @@ pub(crate) unsafe fn epoll_wait(
         }
     }
 
-    // If we're on Linux >= 5.11, use `epoll_pwait2` via `libc::syscall`.
+    // If we're on Linux ≥ 5.11, use `epoll_pwait2` via `libc::syscall`.
     #[cfg(all(linux_kernel, feature = "linux_5_11"))]
     {
         syscall! {

src/backend/linux_raw/param/auxv.rs

@@ -204,11 +204,13 @@ static RANDOM: AtomicPtr<[u8; 16]> = AtomicPtr::new(null_mut());
 
 const PR_GET_AUXV: c::c_int = 0x4155_5856;
 
-/// Use Linux ≥ 6.4's `PR_GET_AUXV` to read the aux records, into a provided
+/// Use Linux ≥ 6.4's [`PR_GET_AUXV`] to read the aux records, into a provided
 /// statically-sized buffer. Return:
 ///  - `Ok(…)` if the buffer is big enough.
 ///  - `Err(Ok(len))` if we need a buffer of length `len`.
 ///  - `Err(Err(err))` if we failed with `err`.
+///
+///  [`PR_GET_AUXV`]: https://www.man7.org/linux/man-pages/man2/PR_GET_AUXV.2const.html
 #[cold]
 fn pr_get_auxv_static(buffer: &mut [u8; 512]) -> Result<&mut [u8], crate::io::Result<usize>> {
     let len = unsafe {
@@ -228,11 +230,13 @@ fn pr_get_auxv_static(buffer: &mut [u8; 512]) -> Result<&mut [u8], crate::io::Re
     Err(Ok(len))
 }
 
-/// Use Linux ≥ 6.4's `PR_GET_AUXV` to read the aux records, using a provided
-/// statically-sized buffer if possible, or a dynamically allocated buffer
-/// otherwise. Return:
+/// Use Linux ≥ 6.4's [`PR_GET_AUXV`] to read the aux records, using a
+/// provided statically-sized buffer if possible, or a dynamically allocated
+/// buffer otherwise. Return:
 ///  - Ok(…) on success.
 ///  - Err(err) on failure.
+///
+///  [`PR_GET_AUXV`]: https://www.man7.org/linux/man-pages/man2/PR_GET_AUXV.2const.html
 #[cfg(feature = "alloc")]
 #[cold]
 fn pr_get_auxv_dynamic(buffer: &mut [u8; 512]) -> crate::io::Result<Cow<'_, [u8]>> {
@@ -278,6 +282,7 @@ fn maybe_init_auxv() {
 /// /proc/self/auxv for kernels that don't support `PR_GET_AUXV`.
 #[cold]
 fn init_auxv_impl() -> Result<(), ()> {
+    // 512 AUX elements ought to be enough for anybody…
     let mut buffer = [0_u8; 512];
 
     // If we don't have "alloc", just try to read into our statically-sized

src/thread/futex.rs

@@ -556,7 +556,7 @@ impl Default for Wait {
 /// `futex_waitv(waiters.as_ptr(), waiters.len(), flags, timeout, clockd)`—
 /// Wait on an array of futexes, wake on any.
 ///
-/// This requires Linux >= 5.16.
+/// This requires Linux ≥ 5.16.
 ///
 /// # References
 ///  - [Linux]