From 7b9e9e572ce8aadc755c5925325440e9f8edcf4d Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 19:36:29 -0400 Subject: error: add documentation for nix::Error Signed-off-by: Paul Osborne --- src/lib.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 8dbf9fe0..ab8339ef 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -77,8 +77,16 @@ use std::fmt; use std::error; use libc::PATH_MAX; +/// Nix Result Type pub type Result = result::Result; +/// Nix Error Type +/// +/// The nix error type provides a common way of dealing with +/// various system system/libc calls that might fail. Each +/// error has a corresponding errno (usually the one from the +/// underlying OS) to which it can be mapped in addition to +/// implementing other common traits. #[derive(Clone, Copy, Debug, PartialEq)] pub enum Error { Sys(errno::Errno), @@ -86,18 +94,23 @@ pub enum Error { } impl Error { + + /// Create a nix Error from a given errno pub fn from_errno(errno: errno::Errno) -> Error { Error::Sys(errno) } + /// Get the current errno and convert it to a nix Error pub fn last() -> Error { Error::Sys(errno::Errno::last()) } + /// Create a new invalid argument error (`EINVAL`) pub fn invalid_argument() -> Error { Error::Sys(errno::EINVAL) } + /// Get the errno associated with this error pub fn errno(&self) -> errno::Errno { match *self { Error::Sys(errno) => errno, -- cgit v1.2.3 From 020baa801e541a9d7846b1e99f1dce81a31b7ac5 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 21:51:31 -0400 Subject: unistd: add better docs for fork() Signed-off-by: Paul Osborne --- src/unistd.rs | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/src/unistd.rs b/src/unistd.rs index 4549382d..257f3cd2 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -15,15 +15,20 @@ use sys::stat::Mode; #[cfg(any(target_os = "linux", target_os = "android"))] pub use self::linux::*; +/// Represents the successful result of calling `fork` +/// +/// When `fork` is called, the process continues execution in the parent process +/// and in the new child. This return type can be examined to determine whether +/// you are now executing in the parent process or in the child. #[derive(Clone, Copy)] pub enum ForkResult { - Parent { - child: pid_t - }, - Child + Parent { child: pid_t }, + Child, } impl ForkResult { + + /// Return `true` if this is the child process of the `fork()` #[inline] pub fn is_child(&self) -> bool { match *self { @@ -32,12 +37,40 @@ impl ForkResult { } } + /// Returns `true` if this is the parent process of the `fork()` #[inline] pub fn is_parent(&self) -> bool { !self.is_child() } } +/// Create a new child process duplicating the parent process ([see +/// fork(2)](http://man7.org/linux/man-pages/man2/fork.2.html)). +/// +/// After calling the fork system call (successfully) two processes will +/// be created that are identical with the exception of their pid and the +/// return value of this function. As an example: +/// +/// ```no_run +/// use nix::unistd::{fork, ForkResult}; +/// +/// match fork() { +/// Ok(ForkResult::Parent { child, .. }) => { +/// println!("Continuing execution in parent process, new child has pid: {}", child); +/// } +/// Ok(ForkResult::Child) => println!("I'm a new child process"), +/// Err(e) => println!("Fork failed"), +/// } +/// ``` +/// +/// This will print something like the following (order indeterministic). The +/// thing to note is that you end up with two processes continuing execution +/// immediately after the fork call but with different match arms. +/// +/// ```text +/// Continuing execution in parent process, new child has pid: 1234 +/// I'm a new child process +/// ``` #[inline] pub fn fork() -> Result { use self::ForkResult::*; @@ -45,7 +78,7 @@ pub fn fork() -> Result { Errno::result(res).map(|res| match res { 0 => Child, - res => Parent { child: res } + res => Parent { child: res }, }) } -- cgit v1.2.3 From 4a20c0730c2bedf7dbc8f2df8ad7a9054273ed3c Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 21:58:41 -0400 Subject: unistd: add docs for getpid/getppid Signed-off-by: Paul Osborne --- src/unistd.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/unistd.rs b/src/unistd.rs index 257f3cd2..81a342e3 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -82,14 +82,26 @@ pub fn fork() -> Result { }) } +/// Get the pid of this process (see +/// [getpid(2)](http://man7.org/linux/man-pages/man2/getpid.2.html)). +/// +/// Since you are running code, there is always a pid to return, so there +/// is no error case that needs to be handled. #[inline] pub fn getpid() -> pid_t { - unsafe { libc::getpid() } // no error handling, according to man page: "These functions are always successful." + unsafe { libc::getpid() } } + +/// Get the pid of this processes' parent (see +/// [getpid(2)](http://man7.org/linux/man-pages/man2/getpid.2.html)). +/// +/// There is always a parent pid to return, so there is no error case that needs +/// to be handled. #[inline] pub fn getppid() -> pid_t { unsafe { libc::getppid() } // no error handling, according to man page: "These functions are always successful." } + #[inline] pub fn setpgid(pid: pid_t, pgid: pid_t) -> Result<()> { let res = unsafe { libc::setpgid(pid, pgid) }; -- cgit v1.2.3 From eba38be7f5ff191954a76171da99da7baeaa1eb2 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:19:23 -0400 Subject: unistd: add documentation for setpgid Signed-off-by: Paul Osborne --- src/unistd.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/unistd.rs b/src/unistd.rs index 81a342e3..5ce002ba 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -102,6 +102,15 @@ pub fn getppid() -> pid_t { unsafe { libc::getppid() } // no error handling, according to man page: "These functions are always successful." } +/// Set a process group ID (see +/// [setpgid(2)](http://man7.org/linux/man-pages/man2/setpgid.2.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 +/// may be used to group together a set of processes in order for the OS to +/// apply some operations across the group. +/// +/// `setsid()` may be used to create a new process group. #[inline] pub fn setpgid(pid: pid_t, pgid: pid_t) -> Result<()> { let res = unsafe { libc::setpgid(pid, pgid) }; -- cgit v1.2.3 From a2e0c057bd9acd60b687ed8a2817d69be104d599 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:23:00 -0400 Subject: unistd: add setsid implementation This is a logical companion to setpgid, so adding an implementation. Signed-off-by: Paul Osborne --- src/unistd.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/unistd.rs b/src/unistd.rs index 5ce002ba..36f72c31 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -117,6 +117,13 @@ pub fn setpgid(pid: pid_t, pgid: pid_t) -> Result<()> { Errno::result(res).map(drop) } +/// Create new session and set process group id (see +/// [setsid(2)](http://man7.org/linux/man-pages/man2/setsid.2.html)). +#[inline] +pub fn setsid() -> Result { + Errno::result(unsafe { libc::setsid() }) +} + #[cfg(any(target_os = "linux", target_os = "android"))] #[inline] pub fn gettid() -> pid_t { -- cgit v1.2.3 From aea291ed2b4b0ecc34ffb817ce31f0583d6a3c70 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:27:14 -0400 Subject: unistd: add documentation for gettid Signed-off-by: Paul Osborne --- src/unistd.rs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/unistd.rs b/src/unistd.rs index 36f72c31..dce3a39a 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -124,10 +124,20 @@ pub fn setsid() -> Result { Errno::result(unsafe { libc::setsid() }) } +/// Get the caller's thread ID (see +/// [gettid(2)](http://man7.org/linux/man-pages/man2/gettid.2.html). +/// +/// This function is only available on Linux based systems. In a single +/// threaded process, the main thread will have the same ID as the process. In +/// a multithreaded process, each thread will have a unique thread id but the +/// same process ID. +/// +/// No error handling is required as a thread id should always exist for any +/// process, even if threads are not being used. #[cfg(any(target_os = "linux", target_os = "android"))] #[inline] pub fn gettid() -> pid_t { - unsafe { libc::syscall(libc::SYS_gettid) as pid_t } // no error handling, according to man page: "These functions are always successful." + unsafe { libc::syscall(libc::SYS_gettid) as pid_t } } #[inline] -- cgit v1.2.3 From 7b5068aed614286fa4f43a7c9e8a6a99119f75f7 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:40:28 -0400 Subject: unistd: document the dup, dup2, and dup3 calls Signed-off-by: Paul Osborne --- src/unistd.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/unistd.rs b/src/unistd.rs index dce3a39a..a371d075 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -140,6 +140,16 @@ pub fn gettid() -> pid_t { unsafe { libc::syscall(libc::SYS_gettid) as pid_t } } +/// Create a copy of the specified file descriptor (see +/// [dup(2)](http://man7.org/linux/man-pages/man2/dup.2.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 +/// be used interchangeably. The new and old file descriptor share the same +/// underlying resource, offset, and file status flags. The actual index used +/// for the file descriptor will be the lowest fd index that is available. +/// +/// The two file descriptors do not share file descriptor flags (e.g. `FD_CLOEXEC`). #[inline] pub fn dup(oldfd: RawFd) -> Result { let res = unsafe { libc::dup(oldfd) }; @@ -147,6 +157,12 @@ pub fn dup(oldfd: RawFd) -> Result { Errno::result(res) } +/// 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)). +/// +/// 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 +/// detail on the exact behavior of this function. #[inline] pub fn dup2(oldfd: RawFd, newfd: RawFd) -> Result { let res = unsafe { libc::dup2(oldfd, newfd) }; @@ -154,6 +170,11 @@ pub fn dup2(oldfd: RawFd, newfd: RawFd) -> Result { Errno::result(res) } +/// Create a new copy of the specified file descriptor using the specified fd +/// and flags (see [dup(2)](http://man7.org/linux/man-pages/man2/dup.2.html)). +/// +/// This function behaves similar to `dup2()` but allows for flags to be +/// specified. pub fn dup3(oldfd: RawFd, newfd: RawFd, flags: OFlag) -> Result { dup3_polyfill(oldfd, newfd, flags) } -- cgit v1.2.3 From fd1f44e26f9fcb5ac6de3082a44e140935d4c530 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:53:21 -0400 Subject: unistd: add docs for chdir Signed-off-by: Paul Osborne --- src/unistd.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/unistd.rs b/src/unistd.rs index a371d075..678209a4 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -197,6 +197,11 @@ fn dup3_polyfill(oldfd: RawFd, newfd: RawFd, flags: OFlag) -> Result { Ok(fd) } +/// Change the current working directory of the calling process (see +/// [chdir(2)](http://man7.org/linux/man-pages/man2/chdir.2.html)). +/// +/// This function may fail in a number of different scenarios. See the man +/// pages for additional details on possible failure cases. #[inline] pub fn chdir(path: &P) -> Result<()> { let res = try!(path.with_nix_path(|cstr| { -- cgit v1.2.3 From fdf8ab6d2ea107b3cbe7cba70f64a79c2c4fc4d0 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Thu, 27 Oct 2016 22:53:35 -0400 Subject: unistd: add docs for chown Signed-off-by: Paul Osborne --- src/unistd.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/unistd.rs b/src/unistd.rs index 678209a4..be1836ad 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -305,6 +305,17 @@ pub fn getcwd() -> Result { } } +/// 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)). +/// +/// 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(path: &P, owner: Option, group: Option) -> Result<()> { let res = try!(path.with_nix_path(|cstr| { -- cgit v1.2.3 From 76bd1c4c102cb7e753212a9a30dd651a184a0a15 Mon Sep 17 00:00:00 2001 From: Alan Somers Date: Sun, 23 Oct 2016 18:28:35 -0600 Subject: impl Send for KEvent --- src/sys/event.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/sys/event.rs b/src/sys/event.rs index d44963db..47d18389 100644 --- a/src/sys/event.rs +++ b/src/sys/event.rs @@ -191,6 +191,15 @@ pub fn kqueue() -> Result { Errno::result(res) } + +/* + * KEvent can't derive Send because on some operating systems, udata is defined + * as a void*. However, KEvent's public API always treats udata as a uintptr_t, + * which is safe to Send. + */ +unsafe impl Send for KEvent { +} + impl KEvent { pub fn new(ident: uintptr_t, filter: EventFilter, flags: EventFlag, fflags:FilterFlag, data: intptr_t, udata: uintptr_t) -> KEvent { -- cgit v1.2.3 From a0058f0308a1a891ea13e70d3918a49ddd53a2b4 Mon Sep 17 00:00:00 2001 From: Alan Somers Date: Sat, 29 Oct 2016 19:04:56 -0600 Subject: Update comments and CHANGELOG for PR 442 --- CHANGELOG.md | 2 ++ src/sys/event.rs | 8 +++----- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8ae74ca..c87b045e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Changed - The minimum supported version of rustc is now 1.7.0. ([#444](https://github.com/nix-rust/nix/pull/444)) +- Implement `Send` for `KEvent` + ([#442](https://github.com/nix-rust/nix/pull/442)) - Changed `KEvent` to an opaque structure that may only be modified by its constructor and the `ev_set` method. ([#415](https://github.com/nix-rust/nix/pull/415)) diff --git a/src/sys/event.rs b/src/sys/event.rs index 47d18389..68528c9e 100644 --- a/src/sys/event.rs +++ b/src/sys/event.rs @@ -192,11 +192,9 @@ pub fn kqueue() -> Result { } -/* - * KEvent can't derive Send because on some operating systems, udata is defined - * as a void*. However, KEvent's public API always treats udata as a uintptr_t, - * which is safe to Send. - */ +// KEvent can't derive Send because on some operating systems, udata is defined +// as a void*. However, KEvent's public API always treats udata as a uintptr_t, +// which is safe to Send. unsafe impl Send for KEvent { } -- cgit v1.2.3