Remove the port_ and Inotify prefixes. (#1284)

* Remove the `port_` and `Inotify` prefixes.

`port_*` and `Inotify*` are in public modules named `port` and `inotify`
so remove their prefixes to make them less redundant.

* Name the `Examples` section in docs consistently.

* Add a simple usage example for the port API.

* Fix test output for inotify.

* Add doc aliases for the port API.

* Fix io_uring naming inconsistency.

Author: sunfishcode

src/backend/linux_raw/conv.rs

@@ -164,12 +164,9 @@ pub(super) unsafe fn raw_fd<'a, Num: ArgNumber>(fd: RawFd) -> ArgReg<'a, Num> {
     #[cfg(feature = "fs")]
     debug_assert!(fd == crate::fs::CWD.as_raw_fd() || fd == crate::fs::ABS.as_raw_fd() || fd >= 0);
 
-    // Don't pass the `IO_URING_REGISTER_FILES_SKIP` sentry value this way.
+    // Don't pass the `IORING_REGISTER_FILES_SKIP` sentry value this way.
     #[cfg(feature = "io_uring")]
-    debug_assert_ne!(
-        fd,
-        crate::io_uring::IO_URING_REGISTER_FILES_SKIP.as_raw_fd()
-    );
+    debug_assert_ne!(fd, crate::io_uring::IORING_REGISTER_FILES_SKIP.as_raw_fd());
 
     // Linux doesn't look at the high bits beyond the `c_int`, so use
     // zero-extension rather than sign-extension because it's a smaller

src/event/port.rs

@@ -1,17 +1,45 @@
 //! Solaris/illumos event ports.
+//!
+//! # Examples
+//!
+//! ```
+//! # fn test() -> std::io::Result<()> {
+//! use rustix::event::port;
+//! use rustix::stdio::stdout;
+//! use std::io;
+//!
+//! let some_fd = stdout();
+//! let some_userdata = 7 as *mut _;
+//!
+//! // Create a port.
+//! let port = port::create()?;
+//!
+//! // Associate `some_fd` with the port.
+//! unsafe {
+//!     port::associate_fd(&port, some_fd, port::PollFlags::IN, some_userdata)?;
+//! }
+//!
+//! // Get a single event.
+//! let event = port::get(&port, None)?;
+//!
+//! assert_eq!(event.userdata(), some_userdata);
+//! # Ok(())
+//! # }
+//! ```
 
 use crate::backend::c;
 use crate::backend::event::syscalls;
 use crate::fd::{AsFd, AsRawFd, OwnedFd};
 use crate::ffi;
 use crate::io;
 
-use super::PollFlags;
-
 use core::time::Duration;
 
+pub use super::PollFlags;
+
 /// The structure representing a port event.
 #[repr(transparent)]
+#[doc(alias = "port_event")]
 pub struct Event(pub(crate) c::port_event);
 
 impl Event {
@@ -39,7 +67,8 @@ impl Event {
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_create/
 /// [illumos]: https://illumos.org/man/3C/port_create
-pub fn port_create() -> io::Result<OwnedFd> {
+#[doc(alias = "port_create")]
+pub fn create() -> io::Result<OwnedFd> {
     syscalls::port_create()
 }
 
@@ -50,15 +79,16 @@ pub fn port_create() -> io::Result<OwnedFd> {
 ///
 /// Any `object`s passed into the `port` must be valid for the lifetime of the
 /// `port`. Logically, `port` keeps a borrowed reference to the `object` until
-/// it is removed via `port_dissociate_fd`.
+/// it is removed via [`dissociate_fd`].
 ///
 /// # References
 ///  - [OpenSolaris]
 ///  - [illumos]
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_associate/
 /// [illumos]: https://illumos.org/man/3C/port_associate
-pub unsafe fn port_associate_fd<Fd: AsFd, RawFd: AsRawFd>(
+#[doc(alias = "port_associate")]
+pub unsafe fn associate_fd<Fd: AsFd, RawFd: AsRawFd>(
     port: Fd,
     object: RawFd,
     events: PollFlags,
@@ -79,18 +109,16 @@ pub unsafe fn port_associate_fd<Fd: AsFd, RawFd: AsRawFd>(
 /// # Safety
 ///
 /// The file descriptor passed into this function must have been previously
-/// associated with the port via [`port_associate_fd`].
+/// associated with the port via [`associate_fd`].
 ///
 /// # References
 ///  - [OpenSolaris]
 ///  - [illumos]
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_dissociate
 /// [illumos]: https://illumos.org/man/3C/port_dissociate
-pub unsafe fn port_dissociate_fd<Fd: AsFd, RawFd: AsRawFd>(
-    port: Fd,
-    object: RawFd,
-) -> io::Result<()> {
+#[doc(alias = "port_dissociate")]
+pub unsafe fn dissociate_fd<Fd: AsFd, RawFd: AsRawFd>(port: Fd, object: RawFd) -> io::Result<()> {
     syscalls::port_dissociate(port.as_fd(), c::PORT_SOURCE_FD, object.as_raw_fd() as _)
 }
 
@@ -102,7 +130,8 @@ pub unsafe fn port_dissociate_fd<Fd: AsFd, RawFd: AsRawFd>(
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_get/
 /// [illumos]: https://illumos.org/man/3C/port_get
-pub fn port_get<Fd: AsFd>(port: Fd, timeout: Option<Duration>) -> io::Result<Event> {
+#[doc(alias = "port_get")]
+pub fn get<Fd: AsFd>(port: Fd, timeout: Option<Duration>) -> io::Result<Event> {
     let mut timeout = timeout.map(|timeout| c::timespec {
         tv_sec: timeout.as_secs().try_into().unwrap(),
         tv_nsec: timeout.subsec_nanos() as _,
@@ -119,7 +148,7 @@ pub fn port_get<Fd: AsFd>(port: Fd, timeout: Option<Duration>) -> io::Result<Eve
 /// this does nothing and returns immediately.
 ///
 /// To query the number of events without retrieving any, use
-/// [`port_getn_query`].
+/// [`getn_query`].
 ///
 /// # References
 ///  - [OpenSolaris]
@@ -128,7 +157,8 @@ pub fn port_get<Fd: AsFd>(port: Fd, timeout: Option<Duration>) -> io::Result<Eve
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_getn/
 /// [illumos]: https://illumos.org/man/3C/port_getn
 #[cfg(feature = "alloc")]
-pub fn port_getn<Fd: AsFd>(
+#[doc(alias = "port_getn")]
+pub fn getn<Fd: AsFd>(
     port: Fd,
     events: &mut Vec<Event>,
     min_events: usize,
@@ -152,15 +182,16 @@ pub fn port_getn<Fd: AsFd>(
 /// `port_getn(port, NULL, 0, NULL)`—Queries the number of events
 /// available from a port.
 ///
-/// To retrieve the events, use [`port_getn`].
+/// To retrieve the events, use [`getn`].
 ///
 /// # References
 ///  - [OpenSolaris]
 ///  - [illumos]
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_getn/
 /// [illumos]: https://illumos.org/man/3C/port_getn
-pub fn port_getn_query<Fd: AsFd>(port: Fd) -> io::Result<u32> {
+#[doc(alias = "port_getn")]
+pub fn getn_query<Fd: AsFd>(port: Fd) -> io::Result<u32> {
     syscalls::port_getn_query(port.as_fd())
 }
 
@@ -172,6 +203,7 @@ pub fn port_getn_query<Fd: AsFd>(port: Fd) -> io::Result<u32> {
 ///
 /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_send/
 /// [illumos]: https://illumos.org/man/3C/port_send
-pub fn port_send<Fd: AsFd>(port: Fd, events: i32, userdata: *mut ffi::c_void) -> io::Result<()> {
+#[doc(alias = "port_send")]
+pub fn send<Fd: AsFd>(port: Fd, events: i32, userdata: *mut ffi::c_void) -> io::Result<()> {
     syscalls::port_send(port.as_fd(), events, userdata.cast())
 }

src/fs/inotify.rs

@@ -123,14 +123,14 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
 
 /// An inotify event.
 #[derive(Debug)]
-pub struct InotifyEvent<'a> {
+pub struct Event<'a> {
     wd: i32,
     events: ReadFlags,
     cookie: u32,
     file_name: Option<&'a CStr>,
 }
 
-impl<'a> InotifyEvent<'a> {
+impl<'a> Event<'a> {
     /// Returns the watch for which this event occurs.
     #[inline]
     pub fn wd(&self) -> i32 {
@@ -172,7 +172,7 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
     ///    error occurs.
     #[allow(unsafe_code)]
     #[allow(clippy::should_implement_trait)]
-    pub fn next(&mut self) -> io::Result<InotifyEvent<'_>> {
+    pub fn next(&mut self) -> io::Result<Event<'_>> {
         if self.is_buffer_empty() {
             match read_uninit(self.fd.as_fd(), self.buf).map(|(init, _)| init.len()) {
                 Ok(0) => return Err(Errno::INVAL),
@@ -195,7 +195,7 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
 
         self.offset += size_of::<inotify_event>() + usize::try_from(event.len).unwrap();
 
-        Ok(InotifyEvent {
+        Ok(Event {
             wd: event.wd,
             events: ReadFlags::from_bits_retain(event.mask),
             cookie: event.cookie,

src/io_uring/mod.rs

@@ -912,11 +912,10 @@ pub const IORING_OFF_CQ_RING: u64 = sys::IORING_OFF_CQ_RING as _;
 pub const IORING_OFF_SQES: u64 = sys::IORING_OFF_SQES as _;
 
 /// `IORING_REGISTER_FILES_SKIP`
-#[doc(alias = "IORING_REGISTER_FILES_SKIP")]
 // SAFETY: `IORING_REGISTER_FILES_SKIP` is a reserved value that is never
 // dynamically allocated, so it'll remain valid for the duration of
 // `'static`.
-pub const IO_URING_REGISTER_FILES_SKIP: BorrowedFd<'static> =
+pub const IORING_REGISTER_FILES_SKIP: BorrowedFd<'static> =
     unsafe { BorrowedFd::<'static>::borrow_raw(sys::IORING_REGISTER_FILES_SKIP as RawFd) };
 
 /// `IORING_NOTIF_USAGE_ZC_COPIED` (since Linux 6.2)

src/shm.rs

@@ -1,6 +1,6 @@
 //! POSIX shared memory
 //!
-//! # Example
+//! # Examples
 //!
 //! ```
 //! use rustix::fs::{ftruncate, Mode};

tests/fs/inotify.rs

@@ -41,7 +41,7 @@ fn test_inotify_iter() {
     }
 
     let expected = format!(
-        r#"InotifyEvent {{
+        r#"Event {{
     wd: 1,
     events: ReadFlags(
         CREATE,
@@ -51,7 +51,7 @@ fn test_inotify_iter() {
         "foo",
     ),
 }}
-InotifyEvent {{
+Event {{
     wd: 1,
     events: ReadFlags(
         OPEN,
@@ -61,7 +61,7 @@ InotifyEvent {{
         "foo",
     ),
 }}
-InotifyEvent {{
+Event {{
     wd: 1,
     events: ReadFlags(
         CLOSE_WRITE,
@@ -71,7 +71,7 @@ InotifyEvent {{
         "foo",
     ),
 }}
-InotifyEvent {{
+Event {{
     wd: 1,
     events: ReadFlags(
         MOVED_FROM,
@@ -81,7 +81,7 @@ InotifyEvent {{
         "foo",
     ),
 }}
-InotifyEvent {{
+Event {{
     wd: 1,
     events: ReadFlags(
         MOVED_TO,
@@ -91,7 +91,7 @@ InotifyEvent {{
         "bar",
     ),
 }}
-InotifyEvent {{
+Event {{
     wd: 1,
     events: ReadFlags(
         DELETE,