Merge #1693

1693: Document aliases for functions like getuid() r=asomers a=rtzoeller

Add the autocfg crate as a build dependency, and introduce `has_doc_alias` as a conditional compilation symbol.

Closes #1673.

Co-authored-by: Ryan Zoeller <rtzoeller@rtzoeller.com>

Cargo.toml

@@ -35,6 +35,9 @@ pin-utils = { version = "0.1.0", optional = true }
 [target.'cfg(not(target_os = "redox"))'.dependencies]
 memoffset = { version = "0.6.3", optional = true }
 
+[build-dependencies]
+autocfg = "1.1.0"
+
 [features]
 default = [
   "acct", "aio", "dir", "env", "event", "feature", "fs",

build.rs

@@ -0,0 +1,7 @@
+fn main() {
+    let cfg = autocfg::new();
+
+    if cfg.probe_rustc_version(1, 52) {
+        autocfg::emit("has_doc_alias");
+    }
+}

src/dir.rs

@@ -53,6 +53,7 @@ impl Dir {
     }
 
     /// Converts from a file descriptor, closing it on success or failure.
+    #[cfg_attr(has_doc_alias, doc(alias("fdopendir")))]
     pub fn from_fd(fd: RawFd) -> Result<Self> {
         let d = ptr::NonNull::new(unsafe { libc::fdopendir(fd) }).ok_or_else(|| {
             let e = Error::last();

src/sys/signal.rs

@@ -472,6 +472,7 @@ pub struct SigSet {
 
 impl SigSet {
     /// Initialize to include all signals.
+    #[cfg_attr(has_doc_alias, doc(alias("sigfillset")))]
     pub fn all() -> SigSet {
         let mut sigset = mem::MaybeUninit::uninit();
         let _ = unsafe { libc::sigfillset(sigset.as_mut_ptr()) };
@@ -480,6 +481,7 @@ impl SigSet {
     }
 
     /// Initialize to include nothing.
+    #[cfg_attr(has_doc_alias, doc(alias("sigemptyset")))]
     pub fn empty() -> SigSet {
         let mut sigset = mem::MaybeUninit::uninit();
         let _ = unsafe { libc::sigemptyset(sigset.as_mut_ptr()) };
@@ -488,21 +490,25 @@ impl SigSet {
     }
 
     /// Add the specified signal to the set.
+    #[cfg_attr(has_doc_alias, doc(alias("sigaddset")))]
     pub fn add(&mut self, signal: Signal) {
         unsafe { libc::sigaddset(&mut self.sigset as *mut libc::sigset_t, signal as libc::c_int) };
     }
 
     /// Remove all signals from this set.
+    #[cfg_attr(has_doc_alias, doc(alias("sigemptyset")))]
     pub fn clear(&mut self) {
         unsafe { libc::sigemptyset(&mut self.sigset as *mut libc::sigset_t) };
     }
 
     /// Remove the specified signal from this set.
+    #[cfg_attr(has_doc_alias, doc(alias("sigdelset")))]
     pub fn remove(&mut self, signal: Signal) {
         unsafe { libc::sigdelset(&mut self.sigset as *mut libc::sigset_t, signal as libc::c_int) };
     }
 
     /// Return whether this set includes the specified signal.
+    #[cfg_attr(has_doc_alias, doc(alias("sigismember")))]
     pub fn contains(&self, signal: Signal) -> bool {
         let res = unsafe { libc::sigismember(&self.sigset as *const libc::sigset_t, signal as libc::c_int) };
 

src/sys/timer.rs

@@ -70,6 +70,7 @@ pub struct Timer(libc::timer_t);
 impl Timer {
     /// Creates a new timer based on the clock defined by `clockid`. The details
     /// of the signal and its handler are defined by the passed `sigevent`.
+    #[cfg_attr(has_doc_alias, doc(alias("timer_create")))]
     pub fn new(clockid: ClockId, mut sigevent: SigEvent) -> Result<Self> {
         let mut timer_id: mem::MaybeUninit<libc::timer_t> = mem::MaybeUninit::uninit();
         Errno::result(unsafe {
@@ -122,6 +123,7 @@ impl Timer {
     ///
     /// Note: Setting a one shot alarm with a 0s TimeSpec disable the alarm
     /// altogether.
+    #[cfg_attr(has_doc_alias, doc(alias("timer_settime")))]
     pub fn set(&mut self, expiration: Expiration, flags: TimerSetTimeFlags) -> Result<()> {
         let timerspec: TimerSpec = expiration.into();
         Errno::result(unsafe {
@@ -136,6 +138,7 @@ impl Timer {
     }
 
     /// Get the parameters for the alarm currently set, if any.
+    #[cfg_attr(has_doc_alias, doc(alias("timer_gettime")))]
     pub fn get(&self) -> Result<Option<Expiration>> {
         let mut timerspec = TimerSpec::none();
         Errno::result(unsafe { libc::timer_gettime(self.0, timerspec.as_mut()) }).map(|_| {
@@ -158,6 +161,7 @@ impl Timer {
     /// 'overrun'. This function returns how many times that has happened to
     /// this timer, up to `libc::DELAYTIMER_MAX`. If more than the maximum
     /// number of overruns have happened the return is capped to the maximum.
+    #[cfg_attr(has_doc_alias, doc(alias("timer_getoverrun")))]
     pub fn overruns(&self) -> i32 {
         unsafe { libc::timer_getoverrun(self.0) }
     }

src/sys/timerfd.rs

@@ -92,6 +92,7 @@ impl TimerFd {
     /// Creates a new timer based on the clock defined by `clockid`. The
     /// underlying fd can be assigned specific flags with `flags` (CLOEXEC,
     /// NONBLOCK). The underlying fd will be closed on drop.
+    #[cfg_attr(has_doc_alias, doc(alias("timerfd_create")))]
     pub fn new(clockid: ClockId, flags: TimerFlags) -> Result<Self> {
         Errno::result(unsafe { libc::timerfd_create(clockid as i32, flags.bits()) })
             .map(|fd| Self { fd })
@@ -133,6 +134,7 @@ impl TimerFd {
     ///
     /// Note: Setting a one shot alarm with a 0s TimeSpec disables the alarm
     /// altogether.
+    #[cfg_attr(has_doc_alias, doc(alias("timerfd_settime")))]
     pub fn set(&self, expiration: Expiration, flags: TimerSetTimeFlags) -> Result<()> {
         let timerspec: TimerSpec = expiration.into();
         Errno::result(unsafe {
@@ -147,6 +149,7 @@ impl TimerFd {
     }
 
     /// Get the parameters for the alarm currently set, if any.
+    #[cfg_attr(has_doc_alias, doc(alias("timerfd_gettime")))]
     pub fn get(&self) -> Result<Option<Expiration>> {
         let mut timerspec = TimerSpec::none();
         Errno::result(unsafe { libc::timerfd_gettime(self.fd, timerspec.as_mut()) }).map(|_| {
@@ -163,6 +166,7 @@ impl TimerFd {
     }
 
     /// Remove the alarm if any is set.
+    #[cfg_attr(has_doc_alias, doc(alias("timerfd_settime")))]
     pub fn unset(&self) -> Result<()> {
         Errno::result(unsafe {
             libc::timerfd_settime(

src/unistd.rs

@@ -67,11 +67,13 @@ impl Uid {
     }
 
     /// Returns Uid of calling process. This is practically a more Rusty alias for `getuid`.
+    #[cfg_attr(has_doc_alias, doc(alias("getuid")))]
     pub fn current() -> Self {
         getuid()
     }
 
     /// Returns effective Uid of calling process. This is practically a more Rusty alias for `geteuid`.
+    #[cfg_attr(has_doc_alias, doc(alias("geteuid")))]
     pub fn effective() -> Self {
         geteuid()
     }
@@ -122,11 +124,13 @@ impl Gid {
     }
 
     /// Returns Gid of calling process. This is practically a more Rusty alias for `getgid`.
+    #[cfg_attr(has_doc_alias, doc(alias("getgid")))]
     pub fn current() -> Self {
         getgid()
     }
 
     /// Returns effective Gid of calling process. This is practically a more Rusty alias for `getegid`.
+    #[cfg_attr(has_doc_alias, doc(alias("getegid")))]
     pub fn effective() -> Self {
         getegid()
     }
@@ -172,11 +176,13 @@ impl Pid {
     }
 
     /// Returns PID of calling process
+    #[cfg_attr(has_doc_alias, doc(alias("getpid")))]
     pub fn this() -> Self {
         getpid()
     }
 
     /// Returns PID of parent of calling process
+    #[cfg_attr(has_doc_alias, doc(alias("getppid")))]
     pub fn parent() -> Self {
         getppid()
     }