Hide resv fields in io_uring. (#1370)

Users are not supposed to touch `resv` fields, so make them
`doc(hidden)` and make structs containing them `non_exhaustive`.

Also, add a `const` constructor for `io_uring_user_data`.

Author: sunfishcode

.github/workflows/main.yml

@@ -55,6 +55,7 @@ jobs:
         cargo update --package=regex --precise=1.9.0
         cargo update --package=half --precise=2.2.1
         cargo update --package=flate2 --precise=1.0.35
+        cargo update --package=textwrap --precise=0.16.1
 
     - run: >
         rustup target add
@@ -529,6 +530,7 @@ jobs:
         cargo update --package=regex --precise=1.9.0
         cargo update --package=half --precise=2.2.1
         cargo update --package=flate2 --precise=1.0.35
+        cargo update --package=textwrap --precise=0.16.1
 
     - run: |
         cargo test --verbose --features=all-apis --release --workspace -- --nocapture

CHANGES.md

@@ -57,6 +57,19 @@ constant.
 [`IORING_REGISTER_FILES_SKIP`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/constant.IORING_REGISTER_FILES_SKIP.html
 [`rustix::fs::CWD`]: https://docs.rs/rustix/1.0.0/rustix/fs/constant.CWD.html
 
+[`rustix::io_uring::io_uring_register`] now has a [`IoringRegisterFlags`]
+argument, and `rustix::io_uring::io_uring_register_with` is removed.
+
+[`rustix::io_uring::io_uring_register`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/fn.io_uring_register.html
+[`IoringRegisterFlags`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/struct.IoringRegisterFlags.html
+
+Several structs in [`rustix::io_uring`] are now marked `#[non_exhaustive]`
+because they contain padding or reserved fields. Instead of constructing
+them with field values and `..Default::default()`, construct them with
+`Default::default()` and separately assign the fields.
+
+[`rustix::io_uring`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/index.html
+
 `rustix::process::WaitidOptions` and `rustix::process::WaitidStatus` are
 renamed to
 [`rustix::process::WaitIdOptions`] and [`rustix::process::WaitIdStatus`] (note
@@ -156,12 +169,6 @@ from the number of bytes written to the buffer when
 [`rustix::net::recvfrom`]: https://docs.rs/rustix/1.0.0/rustix/net/fn.recvfrom.html
 [`rustix::net::RecvFlags::TRUNC`]: https://docs.rs/rustix/1.0.0/rustix/net/struct.RecvFlags.html#associatedconstant.TRUNC
 
-[`rustix::io_uring::io_uring_register`] now has a [`IoringRegisterFlags`]
-argument, and `rustix::io_uring::io_uring_register_with` is removed.
-
-[`rustix::io_uring::io_uring_register`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/fn.io_uring_register.html
-[`IoringRegisterFlags`]: https://docs.rs/rustix/1.0.0/rustix/io_uring/struct.IoringRegisterFlags.html
-
 [`rustix::process::Signal`] constants are now upper-cased; for example,
 `Signal::Int` is now named [`Signal::INT`]. Also, `Signal` is no longer
 directly convertible to `i32`; use [`Signal::as_raw`] instead.

src/io_uring/mod.rs

@@ -33,8 +33,8 @@ use bindgen_types::*;
 use core::cmp::Ordering;
 use core::ffi::c_void;
 use core::hash::{Hash, Hasher};
-use core::mem::{size_of, MaybeUninit};
-use core::ptr::{null_mut, write_bytes};
+use core::mem::size_of;
+use core::ptr::null_mut;
 use linux_raw_sys::net;
 
 // Export types used in io_uring APIs.
@@ -1155,6 +1155,13 @@ pub union io_uring_user_data {
 }
 
 impl io_uring_user_data {
+    /// Create a zero-initialized `Self`.
+    pub const fn zeroed() -> Self {
+        // Initialize the `u64_` field, which is the size of the full union.
+        // This can use `core::mem::zeroed` in Rust 1.75.
+        Self { u64_: 0 }
+    }
+
     /// Return the `u64` value.
     #[inline]
     pub const fn u64_(self) -> u64 {
@@ -1236,12 +1243,7 @@ impl Hash for io_uring_user_data {
 impl Default for io_uring_user_data {
     #[inline]
     fn default() -> Self {
-        let mut s = MaybeUninit::<Self>::uninit();
-        // SAFETY: All of Linux's io_uring structs may be zero-initialized.
-        unsafe {
-            write_bytes(s.as_mut_ptr(), 0, 1);
-            s.assume_init()
-        }
+        Self::zeroed()
     }
 }
 
@@ -1449,10 +1451,13 @@ pub struct io_uring_cqe {
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_restriction {
     pub opcode: IoringRestrictionOp,
     pub register_or_sqe_op_or_sqe_flags: register_or_sqe_op_or_sqe_flags_union,
+    #[doc(hidden)]
     pub resv: u8,
+    #[doc(hidden)]
     pub resv2: [u32; 3],
 }
 
@@ -1468,6 +1473,7 @@ pub union register_or_sqe_op_or_sqe_flags_union {
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_params {
     pub sq_entries: u32,
     pub cq_entries: u32,
@@ -1476,6 +1482,7 @@ pub struct io_uring_params {
     pub sq_thread_idle: u32,
     pub features: IoringFeatureFlags,
     pub wq_fd: RawFd,
+    #[doc(hidden)]
     pub resv: [u32; 3],
     pub sq_off: io_sqring_offsets,
     pub cq_off: io_cqring_offsets,
@@ -1484,6 +1491,7 @@ pub struct io_uring_params {
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_sqring_offsets {
     pub head: u32,
     pub tail: u32,
@@ -1492,13 +1500,15 @@ pub struct io_sqring_offsets {
     pub flags: u32,
     pub dropped: u32,
     pub array: u32,
+    #[doc(hidden)]
     pub resv1: u32,
     pub user_addr: io_uring_ptr,
 }
 
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_cqring_offsets {
     pub head: u32,
     pub tail: u32,
@@ -1507,46 +1517,57 @@ pub struct io_cqring_offsets {
     pub overflow: u32,
     pub cqes: u32,
     pub flags: u32,
+    #[doc(hidden)]
     pub resv1: u32,
     pub user_addr: io_uring_ptr,
 }
 
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Default)]
+#[non_exhaustive]
 pub struct io_uring_probe {
     pub last_op: IoringOp,
     pub ops_len: u8,
+    #[doc(hidden)]
     pub resv: u16,
+    #[doc(hidden)]
     pub resv2: [u32; 3],
     pub ops: IncompleteArrayField<io_uring_probe_op>,
 }
 
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_probe_op {
     pub op: IoringOp,
+    #[doc(hidden)]
     pub resv: u8,
     pub flags: IoringOpFlags,
+    #[doc(hidden)]
     pub resv2: u32,
 }
 
 #[allow(missing_docs)]
 #[repr(C, align(8))]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_files_update {
     pub offset: u32,
+    #[doc(hidden)]
     pub resv: u32,
     pub fds: io_uring_ptr,
 }
 
 #[allow(missing_docs)]
 #[repr(C, align(8))]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_rsrc_register {
     pub nr: u32,
     pub flags: IoringRsrcFlags,
+    #[doc(hidden)]
     pub resv2: u64,
     pub data: io_uring_ptr,
     pub tags: io_uring_ptr,
@@ -1555,21 +1576,26 @@ pub struct io_uring_rsrc_register {
 #[allow(missing_docs)]
 #[repr(C, align(8))]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_rsrc_update {
     pub offset: u32,
+    #[doc(hidden)]
     pub resv: u32,
     pub data: io_uring_ptr,
 }
 
 #[allow(missing_docs)]
 #[repr(C, align(8))]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_rsrc_update2 {
     pub offset: u32,
+    #[doc(hidden)]
     pub resv: u32,
     pub data: io_uring_ptr,
     pub tags: io_uring_ptr,
     pub nr: u32,
+    #[doc(hidden)]
     pub resv2: u32,
 }
 
@@ -1617,30 +1643,38 @@ pub struct open_how {
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_buf_reg {
     pub ring_addr: io_uring_ptr,
     pub ring_entries: u32,
     pub bgid: u16,
     pub flags: u16,
+    #[doc(hidden)]
     pub resv: [u64; 3_usize],
 }
 
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct io_uring_buf {
     pub addr: io_uring_ptr,
     pub len: u32,
     pub bid: u16,
+    #[doc(hidden)]
     pub resv: u16,
 }
 
 #[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
+#[non_exhaustive]
 pub struct buf_ring_tail_struct {
+    #[doc(hidden)]
     pub resv1: u64,
+    #[doc(hidden)]
     pub resv2: u32,
+    #[doc(hidden)]
     pub resv3: u16,
     pub tail: u16,
 }

tests/io_uring/register.rs

@@ -35,11 +35,9 @@ where
 }
 
 fn register_ring(fd: BorrowedFd<'_>) -> Result<BorrowedFd<'_>> {
-    let update = io_uring_rsrc_update {
-        data: io_uring_ptr::new(fd.as_raw_fd() as u64 as *mut c_void),
-        offset: u32::MAX,
-        resv: 0,
-    };
+    let mut update = io_uring_rsrc_update::default();
+    update.data = io_uring_ptr::new(fd.as_raw_fd() as usize as *mut c_void);
+    update.offset = u32::MAX;
 
     do_register(
         fd,
@@ -57,11 +55,9 @@ fn unregister_ring<FD>(fd: FD) -> Result<()>
 where
     FD: AsRawFd + AsFd,
 {
-    let update = io_uring_rsrc_update {
-        offset: fd.as_raw_fd() as u32,
-        data: io_uring_ptr::null(),
-        resv: 0,
-    };
+    let mut update = io_uring_rsrc_update::default();
+    update.offset = fd.as_raw_fd() as u32;
+    update.data = io_uring_ptr::null();
 
     do_register(
         fd,
@@ -158,13 +154,11 @@ fn io_uring_buf_ring_can_be_registered() {
 
     let br = unsafe { br_ptr.as_mut() }.expect("A valid io_uring_buf_ring struct");
 
-    let reg = io_uring_buf_reg {
-        ring_addr: br_ptr.cast::<c_void>().into(),
-        ring_entries: ENTRIES as u32,
-        bgid: BGID,
-        flags: 0,
-        resv: [0_u64; 3],
-    };
+    let mut reg = io_uring_buf_reg::default();
+    reg.ring_addr = br_ptr.cast::<c_void>().into();
+    reg.ring_entries = ENTRIES as u32;
+    reg.bgid = BGID;
+    reg.flags = 0;
 
     assert_eq!(register_buf_ring(ring_fd, &reg), Ok(()));