summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/mqueue.rs20
-rw-r--r--src/poll.rs2
-rw-r--r--src/pty.rs6
-rw-r--r--src/sys/pthread.rs2
-rw-r--r--src/sys/select.rs6
-rw-r--r--src/sys/signal.rs4
-rw-r--r--src/sys/socket/mod.rs35
-rw-r--r--src/unistd.rs137
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.
diff --git a/src/pty.rs b/src/pty.rs
index e6b33aa2..98443d61 100644
--- a/src/pty.rs
+++ b/src/pty.rs
@@ -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
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-04 06:56:55 +0000