diff options
author | bors[bot] <bors[bot]@users.noreply.github.com> | 2017-10-11 02:01:39 +0000 |
---|---|---|
committer | bors[bot] <bors[bot]@users.noreply.github.com> | 2017-10-11 02:01:39 +0000 |
commit | bd7d2b13f86a29369d9cdb21f171369b4a8d9b98 (patch) | |
tree | ba1fa8d8806e73774a21d2ad1108a16d64b82068 | |
parent | 5851bd075feeb314ddfafa56853f51b3da0a2fb2 (diff) | |
parent | 7ec567729772678899d9a53bbb25b8168d4596ca (diff) | |
download | nix-bd7d2b13f86a29369d9cdb21f171369b4a8d9b98.zip |
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.
-rw-r--r-- | src/mqueue.rs | 20 | ||||
-rw-r--r-- | src/poll.rs | 2 | ||||
-rw-r--r-- | src/pty.rs | 6 | ||||
-rw-r--r-- | src/sys/pthread.rs | 2 | ||||
-rw-r--r-- | src/sys/select.rs | 6 | ||||
-rw-r--r-- | src/sys/signal.rs | 4 | ||||
-rw-r--r-- | src/sys/socket/mod.rs | 35 | ||||
-rw-r--r-- | src/unistd.rs | 137 |
8 files changed, 132 insertions, 80 deletions
diff --git a/src/mqueue.rs b/src/mqueue.rs index af4ebe77..b4a791c9 100644 --- a/src/mqueue.rs +++ b/src/mqueue.rs @@ -63,6 +63,9 @@ impl MqAttr { } +/// Open a message queue +/// +/// See also [mq_open(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_open.html) pub fn mq_open(name: &CString, oflag: MQ_OFlag, mode: Mode, @@ -80,16 +83,25 @@ pub fn mq_open(name: &CString, Errno::result(res) } +/// Remove a message queue +/// +/// See also [mq_unlink(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_unlink.html) pub fn mq_unlink(name: &CString) -> Result<()> { let res = unsafe { libc::mq_unlink(name.as_ptr()) }; Errno::result(res).map(drop) } +/// Close a message queue +/// +/// See also [mq_close(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_close.html) pub fn mq_close(mqdes: mqd_t) -> Result<()> { let res = unsafe { libc::mq_close(mqdes) }; Errno::result(res).map(drop) } +/// Receive a message from a message queue +/// +/// See also [mq_receive(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_receive.html) pub fn mq_receive(mqdes: mqd_t, message: &mut [u8], msg_prio: &mut u32) -> Result<usize> { let len = message.len() as size_t; let res = unsafe { @@ -101,6 +113,9 @@ pub fn mq_receive(mqdes: mqd_t, message: &mut [u8], msg_prio: &mut u32) -> Resul Errno::result(res).map(|r| r as usize) } +/// Send a message to a message queue +/// +/// See also [mq_send(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_send.html) pub fn mq_send(mqdes: mqd_t, message: &[u8], msq_prio: u32) -> Result<()> { let res = unsafe { libc::mq_send(mqdes, @@ -111,6 +126,9 @@ pub fn mq_send(mqdes: mqd_t, message: &[u8], msq_prio: u32) -> Result<()> { Errno::result(res).map(drop) } +/// Get message queue attributes +/// +/// See also [mq_getattr(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_getattr.html) pub fn mq_getattr(mqd: mqd_t) -> Result<MqAttr> { let mut attr = unsafe { mem::uninitialized::<libc::mq_attr>() }; let res = unsafe { libc::mq_getattr(mqd, &mut attr) }; @@ -121,7 +139,7 @@ pub fn mq_getattr(mqd: mqd_t) -> Result<MqAttr> { /// Returns the old attributes /// It is recommend to use the `mq_set_nonblock()` and `mq_remove_nonblock()` convenience functions as they are easier to use /// -/// [Further reading](http://man7.org/linux/man-pages/man3/mq_setattr.3.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_setattr.html) pub fn mq_setattr(mqd: mqd_t, newattr: &MqAttr) -> Result<MqAttr> { let mut attr = unsafe { mem::uninitialized::<libc::mq_attr>() }; let res = unsafe { libc::mq_setattr(mqd, &newattr.mq_attr as *const libc::mq_attr, &mut attr) }; diff --git a/src/poll.rs b/src/poll.rs index 25ff170f..30a46688 100644 --- a/src/poll.rs +++ b/src/poll.rs @@ -91,7 +91,7 @@ libc_bitflags! { } /// `poll` waits for one of a set of file descriptors to become ready to perform I/O. -/// ([`poll(2)`](http://man7.org/linux/man-pages/man2/poll.2.html)) +/// ([`poll(2)`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html)) /// /// `fds` contains all [`PollFd`](struct.PollFd.html) to poll. /// The function will return as soon as any event occur for any of these `PollFd`s. @@ -61,7 +61,7 @@ impl Drop for PtyMaster { } /// Grant access to a slave pseudoterminal (see -/// [grantpt(3)](http://man7.org/linux/man-pages/man3/grantpt.3.html)) +/// [grantpt(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/grantpt.html)) /// /// `grantpt()` changes the mode and owner of the slave pseudoterminal device corresponding to the /// master pseudoterminal referred to by `fd`. This is a necessary step towards opening the slave. @@ -75,7 +75,7 @@ pub fn grantpt(fd: &PtyMaster) -> Result<()> { } /// Open a pseudoterminal device (see -/// [posix_openpt(3)](http://man7.org/linux/man-pages/man3/posix_openpt.3.html)) +/// [posix_openpt(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_openpt.html)) /// /// `posix_openpt()` returns a file descriptor to an existing unused pseuterminal master device. /// @@ -176,7 +176,7 @@ pub fn ptsname_r(fd: &PtyMaster) -> Result<String> { } /// Unlock a pseudoterminal master/slave pseudoterminal pair (see -/// [unlockpt(3)](http://man7.org/linux/man-pages/man3/unlockpt.3.html)) +/// [unlockpt(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/unlockpt.html)) /// /// `unlockpt()` unlocks the slave pseudoterminal device corresponding to the master pseudoterminal /// referred to by `fd`. This must be called before trying to open the slave side of a diff --git a/src/sys/pthread.rs b/src/sys/pthread.rs index 83b4669a..d533946b 100644 --- a/src/sys/pthread.rs +++ b/src/sys/pthread.rs @@ -3,7 +3,7 @@ use libc::{self, pthread_t}; pub type Pthread = pthread_t; /// Obtain ID of the calling thread (see -/// [pthread_self(3)](http://man7.org/linux/man-pages/man3/pthread_self.3.html) +/// [pthread_self(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_self.html) /// /// The thread ID returned by pthread_self() is not the same thing as /// the kernel thread ID returned by a call to gettid(2). diff --git a/src/sys/select.rs b/src/sys/select.rs index 07190fa1..252fa6bc 100644 --- a/src/sys/select.rs +++ b/src/sys/select.rs @@ -66,7 +66,7 @@ impl FdSet { } } -/// Monitors file descriptors for readiness (see [select(2)]). +/// Monitors file descriptors for readiness /// /// Returns the total number of ready file descriptors in all sets. The sets are changed so that all /// file descriptors that are ready for the given operation are set. @@ -84,7 +84,9 @@ impl FdSet { /// * `timeout`: Maximum time to wait for descriptors to become ready (`None` to block /// indefinitely). /// -/// [select(2)]: http://man7.org/linux/man-pages/man2/select.2.html +/// # References +/// +/// [select(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html) /// [`FdSet::highest`]: struct.FdSet.html#method.highest pub fn select<'a, N, R, W, E, T>(nfds: N, readfds: R, diff --git a/src/sys/signal.rs b/src/sys/signal.rs index c53b5f5c..b22b665c 100644 --- a/src/sys/signal.rs +++ b/src/sys/signal.rs @@ -419,8 +419,8 @@ pub unsafe fn sigaction(signal: Signal, sigaction: &SigAction) -> Result<SigActi /// /// If both `set` and `oldset` is None, this function is a no-op. /// -/// For more information, visit the [pthread_sigmask](http://man7.org/linux/man-pages/man3/pthread_sigmask.3.html), -/// or [sigprocmask](http://man7.org/linux/man-pages/man2/sigprocmask.2.html) man pages. +/// For more information, visit the [pthread_sigmask](http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_sigmask.html), +/// or [sigprocmask](http://pubs.opengroup.org/onlinepubs/9699919799/functions/sigprocmask.html) man pages. pub fn pthread_sigmask(how: SigmaskHow, set: Option<&SigSet>, oldset: Option<&mut SigSet>) -> Result<()> { diff --git a/src/sys/socket/mod.rs b/src/sys/socket/mod.rs index baddf34e..e333f005 100644 --- a/src/sys/socket/mod.rs +++ b/src/sys/socket/mod.rs @@ -165,7 +165,7 @@ libc_bitflags!{ /// file descriptor using the `SCM_RIGHTS` operation (described in /// [unix(7)](https://linux.die.net/man/7/unix)). /// This flag is useful for the same reasons as the `O_CLOEXEC` flag of - /// [open(2)](https://linux.die.net/man/2/open). + /// [open(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html). /// /// Only used in [`recvmsg`](fn.recvmsg.html) function. #[cfg(any(target_os = "linux", target_os = "android"))] @@ -548,7 +548,7 @@ pub fn recvmsg<'a, T>(fd: RawFd, iov: &[IoVec<&mut [u8]>], cmsg_buffer: Option<& /// protocols may exist, in which case a particular protocol must be /// specified in this manner. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/socket.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html) pub fn socket<T: Into<Option<SockProtocol>>>(domain: AddressFamily, ty: SockType, flags: SockFlag, protocol: T) -> Result<RawFd> { let mut ty = ty as c_int; let protocol = match protocol.into() { @@ -590,7 +590,7 @@ pub fn socket<T: Into<Option<SockProtocol>>>(domain: AddressFamily, ty: SockType /// Create a pair of connected sockets /// -/// [Further reading](http://man7.org/linux/man-pages/man2/socketpair.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/socketpair.html) pub fn socketpair<T: Into<Option<SockProtocol>>>(domain: AddressFamily, ty: SockType, protocol: T, flags: SockFlag) -> Result<(RawFd, RawFd)> { let mut ty = ty as c_int; @@ -636,7 +636,7 @@ pub fn socketpair<T: Into<Option<SockProtocol>>>(domain: AddressFamily, ty: Sock /// Listen for connections on a socket /// -/// [Further reading](http://man7.org/linux/man-pages/man2/listen.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html) pub fn listen(sockfd: RawFd, backlog: usize) -> Result<()> { let res = unsafe { libc::listen(sockfd, backlog as c_int) }; @@ -645,7 +645,7 @@ pub fn listen(sockfd: RawFd, backlog: usize) -> Result<()> { /// Bind a name to a socket /// -/// [Further reading](http://man7.org/linux/man-pages/man2/bind.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html) #[cfg(not(all(target_os="android", target_pointer_width="64")))] pub fn bind(fd: RawFd, addr: &SockAddr) -> Result<()> { let res = unsafe { @@ -673,7 +673,7 @@ pub fn bind(fd: RawFd, addr: &SockAddr) -> Result<()> { /// Accept a connection on a socket /// -/// [Further reading](http://man7.org/linux/man-pages/man2/accept.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html) pub fn accept(sockfd: RawFd) -> Result<RawFd> { let res = unsafe { libc::accept(sockfd, ptr::null_mut(), ptr::null_mut()) }; @@ -727,7 +727,7 @@ fn accept4_polyfill(sockfd: RawFd, flags: SockFlag) -> Result<RawFd> { /// Initiate a connection on a socket /// -/// [Further reading](http://man7.org/linux/man-pages/man2/connect.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html) pub fn connect(fd: RawFd, addr: &SockAddr) -> Result<()> { let res = unsafe { let (ptr, len) = addr.as_ffi_pair(); @@ -740,7 +740,7 @@ pub fn connect(fd: RawFd, addr: &SockAddr) -> Result<()> { /// Receive data from a connection-oriented socket. Returns the number of /// bytes read /// -/// [Further reading](http://man7.org/linux/man-pages/man2/recv.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/recv.html) pub fn recv(sockfd: RawFd, buf: &mut [u8], flags: MsgFlags) -> Result<usize> { unsafe { let ret = ffi::recv( @@ -756,7 +756,7 @@ pub fn recv(sockfd: RawFd, buf: &mut [u8], flags: MsgFlags) -> Result<usize> { /// Receive data from a connectionless or connection-oriented socket. Returns /// the number of bytes read and the socket address of the sender. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/recvmsg.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html) pub fn recvfrom(sockfd: RawFd, buf: &mut [u8]) -> Result<(usize, SockAddr)> { unsafe { let addr: sockaddr_storage = mem::zeroed(); @@ -775,6 +775,9 @@ pub fn recvfrom(sockfd: RawFd, buf: &mut [u8]) -> Result<(usize, SockAddr)> { } } +/// Send a message to a socket +/// +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html) pub fn sendto(fd: RawFd, buf: &[u8], addr: &SockAddr, flags: MsgFlags) -> Result<usize> { let ret = unsafe { let (ptr, len) = addr.as_ffi_pair(); @@ -786,7 +789,7 @@ pub fn sendto(fd: RawFd, buf: &[u8], addr: &SockAddr, flags: MsgFlags) -> Result /// Send data to a connection-oriented socket. Returns the number of bytes read /// -/// [Further reading](http://man7.org/linux/man-pages/man2/send.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/send.html) pub fn send(fd: RawFd, buf: &[u8], flags: MsgFlags) -> Result<usize> { let ret = unsafe { libc::send(fd, buf.as_ptr() as *const c_void, buf.len() as size_t, flags.bits()) @@ -819,7 +822,7 @@ pub struct ucred { /// The protocol level at which to get / set socket options. Used as an /// argument to `getsockopt` and `setsockopt`. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/setsockopt.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html) #[repr(i32)] pub enum SockLevel { Socket = libc::SOL_SOCKET, @@ -851,21 +854,21 @@ pub trait SetSockOpt : Copy { /// Get the current value for the requested socket option /// -/// [Further reading](http://man7.org/linux/man-pages/man2/getsockopt.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockopt.html) pub fn getsockopt<O: GetSockOpt>(fd: RawFd, opt: O) -> Result<O::Val> { opt.get(fd) } /// Sets the value for the requested socket option /// -/// [Further reading](http://man7.org/linux/man-pages/man2/setsockopt.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html) pub fn setsockopt<O: SetSockOpt>(fd: RawFd, opt: O, val: &O::Val) -> Result<()> { opt.set(fd, val) } /// Get the address of the peer connected to the socket `fd`. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/getpeername.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html) pub fn getpeername(fd: RawFd) -> Result<SockAddr> { unsafe { let addr: sockaddr_storage = mem::uninitialized(); @@ -881,7 +884,7 @@ pub fn getpeername(fd: RawFd) -> Result<SockAddr> { /// Get the current address to which the socket `fd` is bound. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/getsockname.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html) pub fn getsockname(fd: RawFd) -> Result<SockAddr> { unsafe { let addr: sockaddr_storage = mem::uninitialized(); @@ -946,7 +949,7 @@ pub enum Shutdown { /// Shut down part of a full-duplex connection. /// -/// [Further reading](http://man7.org/linux/man-pages/man2/shutdown.2.html) +/// [Further reading](http://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html) pub fn shutdown(df: RawFd, how: Shutdown) -> Result<()> { unsafe { use libc::shutdown; 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 |