From c270fd25b7ef0d73bc1fbdc5bb9e5dd7aa078cc0 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Fri, 28 Oct 2016 16:47:35 -0400 Subject: unistd: add docs for exec* functions Signed-off-by: Paul Osborne --- src/unistd.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'src/unistd.rs') diff --git a/src/unistd.rs b/src/unistd.rs index 771a50fb..e37482a5 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -344,6 +344,12 @@ fn to_exec_array(args: &[CString]) -> Vec<*const c_char> { args_p } +/// Replace the current process image with a new one (see +/// [exec(3)](http://man7.org/linux/man-pages/man3/exec.3.html)). +/// +/// See the `::nix::unistd::execve` system call for additional details. `execv` +/// performs the same action but does not allow for customization of the +/// environment for the new process. #[inline] pub fn execv(path: &CString, argv: &[CString]) -> Result { let args_p = to_exec_array(argv); @@ -355,6 +361,24 @@ pub fn execv(path: &CString, argv: &[CString]) -> Result { Err(Error::Sys(Errno::last())) } + +/// Replace the current process image with a new one (see +/// [execve(2)](http://man7.org/linux/man-pages/man2/execve.2.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. +/// +/// Both `::nix::unistd::execv` and `::nix::unistd::execve` take as arguments a +/// slice of `::std::ffi::CString`s for `args` and `env`. Each element in +/// the `args` list is an argument to the new process. Each element in the +/// `env` list should be a string in the form "key=value". #[inline] pub fn execve(path: &CString, args: &[CString], env: &[CString]) -> Result { let args_p = to_exec_array(args); @@ -367,6 +391,15 @@ pub fn execve(path: &CString, args: &[CString], env: &[CString]) -> Result Err(Error::Sys(Errno::last())) } +/// 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)). +/// +/// See `::nix::unistd::execve` for additoinal details. `execvp` behaves the +/// sme 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 I specified "bash" for the path argument, but `execvp` +/// would assuming that I had a bash executable on my `PATH`. #[inline] pub fn execvp(filename: &CString, args: &[CString]) -> Result { let args_p = to_exec_array(args); -- cgit v1.2.3 From 4b6b7b4b4626ad72d47c5021c3d7c94e600e62ee Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Sat, 29 Oct 2016 00:06:12 -0400 Subject: unistd: add documentation for the daemon function Signed-off-by: Paul Osborne --- src/unistd.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'src/unistd.rs') diff --git a/src/unistd.rs b/src/unistd.rs index e37482a5..bcc09150 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -411,6 +411,40 @@ pub fn execvp(filename: &CString, args: &[CString]) -> Result { Err(Error::Sys(Errno::last())) } +/// Daemonize this process by detaching from the controlling terminal (see +/// [daemon(3)](http://man7.org/linux/man-pages/man3/daemon.3.html)). +/// +/// When a process is launched it is typically associated with a parent and it, +/// in turn, by its controlling terminal/process. In order for a process to run +/// in the "background" it must daemonize itself by detaching itself. Under +/// posix, this is done by doing the following: +/// +/// 1. Parent process (this one) forks +/// 2. Parent process exits +/// 3. Child process continues to run. +/// +/// There are a couple options here whose names and meaning can be a bit +/// confusing, so we'll describe the behavior for each state. +/// +/// For `nochdir`: +/// +/// * `nochdir = true`: The current working directory after daemonizing will +/// be the current working directory. +/// * `nochdir = false`: The current working directory after daemonizing will +/// be the root direcory, `/`. +/// +/// For `noclose`: +/// +/// * `noclose = true`: The process' current stdin, stdout, and stderr file +/// 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) -- cgit v1.2.3 From 2f220fce96184e8624b5534153f3182b61bb05c5 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Sat, 29 Oct 2016 17:00:47 -0500 Subject: unistd: add module-level doc comment that makes sense The previous one was entirely too generic. Signed-off-by: Paul Osborne --- src/unistd.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/unistd.rs') diff --git a/src/unistd.rs b/src/unistd.rs index bcc09150..8966ea12 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -1,5 +1,5 @@ -//! Standard symbolic constants and types -//! +//! Safe wrappers around functions found in libc "unistd.h" header + use {Errno, Error, Result, NixPath}; use fcntl::{fcntl, OFlag, O_CLOEXEC, FD_CLOEXEC}; use fcntl::FcntlArg::F_SETFD; -- cgit v1.2.3 From 173f2acec8d0276b6f4c9ebc5f0cfceeafbec741 Mon Sep 17 00:00:00 2001 From: Paul Osborne Date: Tue, 1 Nov 2016 23:13:02 -0500 Subject: unistd: doc updates based on review comments These make the language consistent in the 3rd person, fix a few minor mistakes, and remove some superflous prose. Signed-off-by: Paul Osborne --- src/unistd.rs | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) (limited to 'src/unistd.rs') diff --git a/src/unistd.rs b/src/unistd.rs index 8966ea12..31b55f83 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -375,9 +375,9 @@ pub fn execv(path: &CString, argv: &[CString]) -> Result { /// [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. /// -/// Both `::nix::unistd::execv` and `::nix::unistd::execve` take as arguments a -/// slice of `::std::ffi::CString`s for `args` and `env`. Each element in -/// the `args` list is an argument to the new process. Each element in the +/// `::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 /// `env` list should be a string in the form "key=value". #[inline] pub fn execve(path: &CString, args: &[CString], env: &[CString]) -> Result { @@ -396,10 +396,10 @@ pub fn execve(path: &CString, args: &[CString], env: &[CString]) -> Result /// [exec(3)](http://man7.org/linux/man-pages/man3/exec.3.html)). /// /// See `::nix::unistd::execve` for additoinal details. `execvp` behaves the -/// sme as execv except that it will examine the `PATH` environment variables +/// 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 I specified "bash" for the path argument, but `execvp` -/// would assuming that I had a bash executable on my `PATH`. +/// would not work if "bash" was specified for the path argument, but `execvp` +/// would assuming that a bash executable was on the system `PATH`. #[inline] pub fn execvp(filename: &CString, args: &[CString]) -> Result { let args_p = to_exec_array(args); @@ -423,17 +423,14 @@ pub fn execvp(filename: &CString, args: &[CString]) -> Result { /// 2. Parent process exits /// 3. Child process continues to run. /// -/// There are a couple options here whose names and meaning can be a bit -/// confusing, so we'll describe the behavior for each state. -/// -/// For `nochdir`: +/// `nochdir`: /// /// * `nochdir = true`: The current working directory after daemonizing will /// be the current working directory. /// * `nochdir = false`: The current working directory after daemonizing will /// be the root direcory, `/`. /// -/// For `noclose`: +/// `noclose`: /// /// * `noclose = true`: The process' current stdin, stdout, and stderr file /// descriptors will remain identical after daemonizing. -- cgit v1.2.3