diff options
Diffstat (limited to 'src/unistd.rs')
| -rw-r--r-- | src/unistd.rs | 137 |
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 |