Merge #778

778: Replace most Linux man page links with Open Group man page links r=posborne a=asomers

But leave in place Linux links for non-standard functions.  Also, add
brief docs for some functions that were lacking them.

1 files changed, 83 insertions, 54 deletions

diff --git a/src/unistd.rs b/src/unistd.rs
index fad51272..14da5ffd 100644
--- a/src/unistd.rs
+++ b/src/unistd.rs
@@ -169,7 +169,7 @@ impl ForkResult {
 }
 
 /// Create a new child process duplicating the parent process ([see
-/// fork(2)](http://man7.org/linux/man-pages/man2/fork.2.html)).
+/// fork(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fork.html)).
 ///
 /// After calling the fork system call (successfully) two processes will
 /// be created that are identical with the exception of their pid and the
@@ -219,7 +219,7 @@ pub fn fork() -> Result<ForkResult> {
 }
 
 /// Get the pid of this process (see
-/// [getpid(2)](http://man7.org/linux/man-pages/man2/getpid.2.html)).
+/// [getpid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpid.html)).
 ///
 /// Since you are running code, there is always a pid to return, so there
 /// is no error case that needs to be handled.
@@ -229,7 +229,7 @@ pub fn getpid() -> Pid {
 }
 
 /// Get the pid of this processes' parent (see
-/// [getpid(2)](http://man7.org/linux/man-pages/man2/getpid.2.html)).
+/// [getpid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getppid.html)).
 ///
 /// There is always a parent pid to return, so there is no error case that needs
 /// to be handled.
@@ -239,7 +239,7 @@ pub fn getppid() -> Pid {
 }
 
 /// Set a process group ID (see
-/// [setpgid(2)](http://man7.org/linux/man-pages/man2/setpgid.2.html)).
+/// [setpgid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setpgid.html)).
 ///
 /// Set the process group id (PGID) of a particular process.  If a pid of zero
 /// is specified, then the pid of the calling process is used.  Process groups
@@ -259,7 +259,7 @@ pub fn getpgid(pid: Option<Pid>) -> Result<Pid> {
 }
 
 /// Create new session and set process group id (see
-/// [setsid(2)](http://man7.org/linux/man-pages/man2/setsid.2.html)).
+/// [setsid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsid.html)).
 #[inline]
 pub fn setsid() -> Result<Pid> {
     Errno::result(unsafe { libc::setsid() }).map(Pid)
@@ -267,7 +267,7 @@ pub fn setsid() -> Result<Pid> {
 
 
 /// Get the terminal foreground process group (see
-/// [tcgetpgrp(3)](http://man7.org/linux/man-pages/man3/tcgetpgrp.3.html)).
+/// [tcgetpgrp(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/tcgetpgrp.html)).
 ///
 /// Get the group process id (GPID) of the foreground process group on the
 /// terminal associated to file descriptor (FD).
@@ -277,7 +277,7 @@ pub fn tcgetpgrp(fd: c_int) -> Result<Pid> {
     Errno::result(res).map(Pid)
 }
 /// Set the terminal foreground process group (see
-/// [tcgetpgrp(3)](http://man7.org/linux/man-pages/man3/tcgetpgrp.3.html)).
+/// [tcgetpgrp(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/tcsetpgrp.html)).
 ///
 /// Get the group process id (PGID) to the foreground process group on the
 /// terminal associated to file descriptor (FD).
@@ -289,7 +289,7 @@ pub fn tcsetpgrp(fd: c_int, pgrp: Pid) -> Result<()> {
 
 
 /// Get the group id of the calling process (see
-///[getpgrp(3)](http://man7.org/linux/man-pages/man3/getpgrp.3p.html)).
+///[getpgrp(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpgrp.html)).
 ///
 /// Get the process group id (PGID) of the calling process.
 /// According to the man page it is always successful.
@@ -315,7 +315,7 @@ pub fn gettid() -> Pid {
 }
 
 /// Create a copy of the specified file descriptor (see
-/// [dup(2)](http://man7.org/linux/man-pages/man2/dup.2.html)).
+/// [dup(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/dup.html)).
 ///
 /// The new file descriptor will be have a new index but refer to the same
 /// resource as the old file descriptor and the old and new file descriptors may
@@ -332,7 +332,7 @@ pub fn dup(oldfd: RawFd) -> Result<RawFd> {
 }
 
 /// Create a copy of the specified file descriptor using the specified fd (see
-/// [dup(2)](http://man7.org/linux/man-pages/man2/dup.2.html)).
+/// [dup(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/dup.html)).
 ///
 /// This function behaves similar to `dup()` except that it will try to use the
 /// specified fd instead of allocating a new one.  See the man pages for more
@@ -372,7 +372,7 @@ fn dup3_polyfill(oldfd: RawFd, newfd: RawFd, flags: OFlag) -> Result<RawFd> {
 }
 
 /// Change the current working directory of the calling process (see
-/// [chdir(2)](http://man7.org/linux/man-pages/man2/chdir.2.html)).
+/// [chdir(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/chdir.html)).
 ///
 /// This function may fail in a number of different scenarios.  See the man
 /// pages for additional details on possible failure cases.
@@ -387,7 +387,7 @@ pub fn chdir<P: ?Sized + NixPath>(path: &P) -> Result<()> {
 
 /// Change the current working directory of the process to the one
 /// given as an open file descriptor (see
-/// [fchdir(2)](http://man7.org/linux/man-pages/man2/fchdir.2.html)).
+/// [fchdir(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fchdir.html)).
 ///
 /// This function may fail in a number of different scenarios.  See the man
 /// pages for additional details on possible failure cases.
@@ -398,7 +398,7 @@ pub fn fchdir(dirfd: RawFd) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
-/// Creates new directory `path` with access rights `mode`.
+/// Creates new directory `path` with access rights `mode`.  (see [mkdir(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdir.html))
 ///
 /// # Errors
 ///
@@ -408,9 +408,6 @@ pub fn fchdir(dirfd: RawFd) -> Result<()> {
 /// - the path already exists
 /// - the path name is too long (longer than `PATH_MAX`, usually 4096 on linux, 1024 on OS X)
 ///
-/// For a full list consult
-/// [man mkdir(2)](http://man7.org/linux/man-pages/man2/mkdir.2.html#ERRORS)
-///
 /// # Example
 ///
 /// ```rust
@@ -494,15 +491,11 @@ pub fn getcwd() -> Result<PathBuf> {
 
 /// Change the ownership of the file at `path` to be owned by the specified
 /// `owner` (user) and `group` (see
-/// [chown(2)](http://man7.org/linux/man-pages/man2/lchown.2.html)).
+/// [chown(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/chown.html)).
 ///
 /// The owner/group for the provided path name will not be modified if `None` is
 /// provided for that argument.  Ownership change will be attempted for the path
 /// only if `Some` owner/group is provided.
-///
-/// This call may fail under a number of different situations.  See [the man
-/// pages](http://man7.org/linux/man-pages/man2/lchown.2.html#ERRORS) for
-/// additional details.
 #[inline]
 pub fn chown<P: ?Sized + NixPath>(path: &P, owner: Option<Uid>, group: Option<Gid>) -> Result<()> {
     let res = try!(path.with_nix_path(|cstr| {
@@ -527,7 +520,7 @@ fn to_exec_array(args: &[CString]) -> Vec<*const c_char> {
 }
 
 /// Replace the current process image with a new one (see
-/// [exec(3)](http://man7.org/linux/man-pages/man3/exec.3.html)).
+/// [exec(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html)).
 ///
 /// See the `::nix::unistd::execve` system call for additional details.  `execv`
 /// performs the same action but does not allow for customization of the
@@ -545,18 +538,13 @@ pub fn execv(path: &CString, argv: &[CString]) -> Result<Void> {
 
 
 /// Replace the current process image with a new one (see
-/// [execve(2)](http://man7.org/linux/man-pages/man2/execve.2.html)).
+/// [execve(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html)).
 ///
 /// The execve system call allows for another process to be "called" which will
 /// replace the current process image.  That is, this process becomes the new
 /// command that is run. On success, this function will not return. Instead,
 /// the new program will run until it exits.
 ///
-/// If an error occurs, this function will return with an indication of the
-/// cause of failure.  See
-/// [execve(2)#errors](http://man7.org/linux/man-pages/man2/execve.2.html#ERRORS)
-/// for a list of potential problems that maight cause execv to fail.
-///
 /// `::nix::unistd::execv` and `::nix::unistd::execve` take as arguments a slice
 /// of `::std::ffi::CString`s for `args` and `env` (for `execve`). Each element
 /// in the `args` list is an argument to the new process. Each element in the
@@ -575,9 +563,9 @@ pub fn execve(path: &CString, args: &[CString], env: &[CString]) -> Result<Void>
 
 /// Replace the current process image with a new one and replicate shell `PATH`
 /// searching behavior (see
-/// [exec(3)](http://man7.org/linux/man-pages/man3/exec.3.html)).
+/// [exec(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html)).
 ///
-/// See `::nix::unistd::execve` for additoinal details.  `execvp` behaves the
+/// See `::nix::unistd::execve` for additional details.  `execvp` behaves the
 /// same as execv except that it will examine the `PATH` environment variables
 /// for file names not specified with a leading slash.  For example, `execv`
 /// would not work if "bash" was specified for the path argument, but `execvp`
@@ -603,13 +591,6 @@ pub fn execvp(filename: &CString, args: &[CString]) -> Result<Void> {
 ///
 /// This function is similar to `execve`, except that the program to be executed
 /// is referenced as a file descriptor instead of a path.
-///
-/// # Errors
-///
-/// If an error occurs, this function will return with an indication of the
-/// cause of failure.  See
-/// [fexecve(2)#errors](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fexecve.html#tag_16_111_05)
-/// for a list of error conditions.
 #[cfg(any(target_os = "android", target_os = "dragonfly", target_os = "freebsd",
           target_os = "netbsd", target_os = "openbsd", target_os = "linux"))]
 #[inline]
@@ -649,19 +630,13 @@ pub fn fexecve(fd: RawFd, args: &[CString], env: &[CString]) -> Result<Void> {
 ///   descriptors will remain identical after daemonizing.
 /// * `noclose = false`: The process' stdin, stdout, and stderr will point to
 ///   `/dev/null` after daemonizing.
-///
-/// The underlying implementation (in libc) calls both
-/// [fork(2)](http://man7.org/linux/man-pages/man2/fork.2.html) and
-/// [setsid(2)](http://man7.org/linux/man-pages/man2/setsid.2.html) and, as
-/// such, error that could be returned by either of those functions could also
-/// show up as errors here.
 pub fn daemon(nochdir: bool, noclose: bool) -> Result<()> {
     let res = unsafe { libc::daemon(nochdir as c_int, noclose as c_int) };
     Errno::result(res).map(drop)
 }
 
 /// Set the system host name (see
-/// [gethostname(2)](http://man7.org/linux/man-pages/man2/gethostname.2.html)).
+/// [sethostname(2)](http://man7.org/linux/man-pages/man2/gethostname.2.html)).
 ///
 /// Given a name, attempt to update the system host name to the given string.
 /// On some systems, the host name is limited to as few as 64 bytes.  An error
@@ -688,7 +663,7 @@ pub fn sethostname<S: AsRef<OsStr>>(name: S) -> Result<()> {
 
 /// Get the host name and store it in the provided buffer, returning a pointer
 /// the CStr in that buffer on success (see
-/// [gethostname(2)](http://man7.org/linux/man-pages/man2/gethostname.2.html)).
+/// [gethostname(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/gethostname.html)).
 ///
 /// This function call attempts to get the host name for the running system and
 /// store it in a provided buffer.  The buffer will be populated with bytes up
@@ -722,7 +697,8 @@ pub fn gethostname<'a>(buffer: &'a mut [u8]) -> Result<&'a CStr> {
 /// Be aware that many Rust types implicitly close-on-drop, including
 /// `std::fs::File`.  Explicitly closing them with this method too can result in
 /// a double-close condition, which can cause confusing `EBADF` errors in
-/// seemingly unrelated code.  Caveat programmer.
+/// seemingly unrelated code.  Caveat programmer.  See also
+/// [close(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html).
 ///
 /// # Examples
 ///
@@ -756,12 +732,18 @@ pub fn close(fd: RawFd) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Read from a raw file descriptor.
+///
+/// See also [read(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html)
 pub fn read(fd: RawFd, buf: &mut [u8]) -> Result<usize> {
     let res = unsafe { libc::read(fd, buf.as_mut_ptr() as *mut c_void, buf.len() as size_t) };
 
     Errno::result(res).map(|r| r as usize)
 }
 
+/// Write to a raw file descriptor.
+///
+/// See also [write(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html)
 pub fn write(fd: RawFd, buf: &[u8]) -> Result<usize> {
     let res = unsafe { libc::write(fd, buf.as_ptr() as *const c_void, buf.len() as size_t) };
 
@@ -799,6 +781,9 @@ pub enum Whence {
     SeekHole = libc::SEEK_HOLE
 }
 
+/// Move the read/write file offset.
+///
+/// See also [lseek(2)(http://pubs.opengroup.org/onlinepubs/9699919799/functions/lseek.html)
 pub fn lseek(fd: RawFd, offset: libc::off_t, whence: Whence) -> Result<libc::off_t> {
     let res = unsafe { libc::lseek(fd, offset, whence as i32) };
 
@@ -812,6 +797,9 @@ pub fn lseek64(fd: RawFd, offset: libc::off64_t, whence: Whence) -> Result<libc:
     Errno::result(res).map(|r| r as libc::off64_t)
 }
 
+/// Create an interprocess channel.
+///
+/// See also [pipe(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/pipe.html)
 pub fn pipe() -> Result<(RawFd, RawFd)> {
     unsafe {
         let mut fds: [c_int; 2] = mem::uninitialized();
@@ -884,6 +872,10 @@ fn pipe2_setflags(fd1: RawFd, fd2: RawFd, flags: OFlag) -> Result<()> {
     }
 }
 
+/// Truncate a file to a specified length
+///
+/// See also
+/// [ftruncate(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/ftruncate.html)
 pub fn ftruncate(fd: RawFd, len: off_t) -> Result<()> {
     Errno::result(unsafe { libc::ftruncate(fd, len) }).map(drop)
 }
@@ -905,6 +897,9 @@ pub fn isatty(fd: RawFd) -> Result<bool> {
     }
 }
 
+/// Remove a directory entry
+///
+/// See also [unlink(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/unlink.html)
 pub fn unlink<P: ?Sized + NixPath>(path: &P) -> Result<()> {
     let res = try!(path.with_nix_path(|cstr| {
         unsafe {
@@ -923,6 +918,9 @@ pub fn chroot<P: ?Sized + NixPath>(path: &P) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Synchronize changes to a file
+///
+/// See also [fsync(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html)
 #[inline]
 pub fn fsync(fd: RawFd) -> Result<()> {
     let res = unsafe { libc::fsync(fd) };
@@ -930,6 +928,10 @@ pub fn fsync(fd: RawFd) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Synchronize the data of a file
+///
+/// See also
+/// [fdatasync(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fdatasync.html)
 // `fdatasync(2) is in POSIX, but in libc it is only defined in `libc::notbsd`.
 // TODO: exclude only Apple systems after https://github.com/rust-lang/libc/pull/211
 #[cfg(any(target_os = "linux",
@@ -942,32 +944,49 @@ pub fn fdatasync(fd: RawFd) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
-// POSIX requires that getuid, geteuid, getgid, getegid are always successful,
-// so no need to check return value or errno. See:
-//   - http://pubs.opengroup.org/onlinepubs/9699919799/functions/getuid.html
-//   - http://pubs.opengroup.org/onlinepubs/9699919799/functions/geteuid.html
-//   - http://pubs.opengroup.org/onlinepubs/9699919799/functions/getgid.html
-//   - http://pubs.opengroup.org/onlinepubs/9699919799/functions/geteuid.html
+/// Get a real user ID
+///
+/// See also [getuid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getuid.html)
+// POSIX requires that getuid is always successful, so no need to check return
+// value or errno.
 #[inline]
 pub fn getuid() -> Uid {
     Uid(unsafe { libc::getuid() })
 }
 
+/// Get the effective user ID
+///
+/// See also [geteuid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/geteuid.html)
+// POSIX requires that geteuid is always successful, so no need to check return
+// value or errno.
 #[inline]
 pub fn geteuid() -> Uid {
     Uid(unsafe { libc::geteuid() })
 }
 
+/// Get the real group ID
+///
+/// See also [getgid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getgid.html)
+// POSIX requires that getgid is always successful, so no need to check return
+// value or errno.
 #[inline]
 pub fn getgid() -> Gid {
     Gid(unsafe { libc::getgid() })
 }
 
+/// Get the effective group ID
+///
+/// See also [getegid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getegid.html)
+// POSIX requires that getegid is always successful, so no need to check return
+// value or errno.
 #[inline]
 pub fn getegid() -> Gid {
     Gid(unsafe { libc::getegid() })
 }
 
+/// Set the user ID
+///
+/// See also [setuid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setuid.html)
 #[inline]
 pub fn setuid(uid: Uid) -> Result<()> {
     let res = unsafe { libc::setuid(uid.into()) };
@@ -975,6 +994,9 @@ pub fn setuid(uid: Uid) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Set the user ID
+///
+/// See also [setgid(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setgid.html)
 #[inline]
 pub fn setgid(gid: Gid) -> Result<()> {
     let res = unsafe { libc::setgid(gid.into()) };
@@ -982,6 +1004,9 @@ pub fn setgid(gid: Gid) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Suspend the thread until a signal is received
+///
+/// See also [pause(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/pause.html)
 #[inline]
 pub fn pause() -> Result<()> {
     let res = unsafe { libc::pause() };
@@ -989,9 +1014,11 @@ pub fn pause() -> Result<()> {
     Errno::result(res).map(drop)
 }
 
+/// Suspend execution for an interval of time
+///
+/// See also [sleep(2)(http://pubs.opengroup.org/onlinepubs/009695399/functions/sleep.html#tag_03_705_05)
+// Per POSIX, does not fail
 #[inline]
-// Per POSIX, does not fail:
-//   http://pubs.opengroup.org/onlinepubs/009695399/functions/sleep.html#tag_03_705_05
 pub fn sleep(seconds: libc::c_uint) -> c_uint {
     unsafe { libc::sleep(seconds) }
 }
@@ -1004,6 +1031,8 @@ pub fn sleep(seconds: libc::c_uint) -> c_uint {
 /// Err is returned either if no temporary filename could be created or the template doesn't
 /// end with XXXXXX
 ///
+/// See also [mkstemp(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mkstemp.html)
+///
 /// # Example
 ///
 /// ```rust