Null terminated slices for exec

src/lib.rs

@@ -70,7 +70,7 @@ pub mod unistd;
 
 use libc::c_char;
 use std::{ptr, result};
-use std::ffi::{CStr, OsStr};
+use std::ffi::{CStr, CString, OsStr};
 use std::path::{Path, PathBuf};
 use std::os::unix::ffi::OsStrExt;
 use std::fmt;
@@ -193,6 +193,17 @@ impl NixPath for CStr {
     }
 }
 
+impl NixPath for CString {
+    fn len(&self) -> usize {
+        self.to_bytes().len()
+    }
+
+    fn with_nix_path<T, F>(&self, f: F) -> Result<T>
+            where F: FnOnce(&CStr) -> T {
+        self.as_c_str().with_nix_path(f)
+    }
+}
+
 impl NixPath for [u8] {
     fn len(&self) -> usize {
         self.len()
@@ -254,3 +265,334 @@ impl<'a, NP: ?Sized + NixPath>  NixPath for Option<&'a NP> {
         }
     }
 }
+
+/*
+ *
+ * ===== Null terminated slices for exec =====
+ *
+ */
+
+use std::ops::{Deref, DerefMut};
+use std::mem::transmute;
+use std::{iter, io};
+
+/// An error returned from the [`TerminatedSlice::from_slice`] family of
+/// functions when the provided data is not terminated by `None`.
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct NotTerminatedError {
+    // private initializers only
+    _inner: (),
+}
+
+impl NotTerminatedError {
+    fn not_terminated() -> Self {
+        NotTerminatedError {
+            _inner: (),
+        }
+    }
+}
+
+impl error::Error for NotTerminatedError {
+    fn description(&self) -> &str { "data not terminated by None" }
+}
+
+impl fmt::Display for NotTerminatedError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", error::Error::description(self))
+    }
+}
+
+impl From<NotTerminatedError> for io::Error {
+    fn from(e: NotTerminatedError) -> io::Error {
+        io::Error::new(io::ErrorKind::InvalidInput,
+                       error::Error::description(&e))
+    }
+}
+
+/// An error returned from [`TerminatedVec::from_vec`] when the provided data is
+/// not terminated by `None`.
+#[derive(Clone, PartialEq, Eq)]
+pub struct NotTerminatedVecError<T> {
+    inner: Vec<Option<T>>,
+}
+
+impl<T> NotTerminatedVecError<T> {
+    fn not_terminated(vec: Vec<Option<T>>) -> Self {
+        NotTerminatedVecError {
+            inner: vec,
+        }
+    }
+
+    pub fn into_vec(self) -> Vec<Option<T>> {
+        self.inner
+    }
+}
+
+impl<T> fmt::Debug for NotTerminatedVecError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("NotTerminatedVecError").finish()
+    }
+}
+
+impl<T> error::Error for NotTerminatedVecError<T> {
+    fn description(&self) -> &str { "data not terminated by None" }
+}
+
+impl<T> fmt::Display for NotTerminatedVecError<T> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", error::Error::description(self))
+    }
+}
+
+impl<T> From<NotTerminatedVecError<T>> for io::Error {
+    fn from(e: NotTerminatedVecError<T>) -> io::Error {
+        io::Error::new(io::ErrorKind::InvalidInput,
+                       error::Error::description(&e))
+    }
+}
+
+/// A conversion trait that may borrow or allocate memory depending on the input.
+/// Used to convert between terminated slices and `Vec`s.
+pub trait IntoRef<'a, T: ?Sized> {
+    type Target: 'a + AsRef<T> + Deref<Target=T>;
+
+    fn into_ref(self) -> Self::Target;
+}
+
+/// A slice of references terminated by `None`. Used by API calls that accept
+/// null-terminated arrays such as the `exec` family of functions.
+pub struct TerminatedSlice<T> {
+    inner: [Option<T>],
+}
+
+impl<T> TerminatedSlice<T> {
+    /// Instantiate a `TerminatedSlice` from a slice ending in `None`. Fails if
+    /// the provided slice is not properly terminated.
+    pub fn from_slice(slice: &[Option<T>]) -> result::Result<&Self, NotTerminatedError> {
+        if slice.last().map(Option::is_none).unwrap_or(false) {
+            Ok(unsafe { Self::from_slice_unchecked(slice) })
+        } else {
+            Err(NotTerminatedError::not_terminated())
+        }
+    }
+
+    /// Instantiate a `TerminatedSlice` from a mutable slice ending in `None`.
+    /// Fails if the provided slice is not properly terminated.
+    pub fn from_slice_mut(slice: &mut [Option<T>]) -> result::Result<&mut Self, NotTerminatedError> {
+        if slice.last().map(Option::is_none).unwrap_or(false) {
+            Ok(unsafe { Self::from_slice_mut_unchecked(slice) })
+        } else {
+            Err(NotTerminatedError::not_terminated())
+        }
+    }
+
+    /// Instantiate a `TerminatedSlice` from a slice ending in `None`.
+    ///
+    /// ## Unsafety
+    ///
+    /// This assumes that the slice is properly terminated, and can cause
+    /// undefined behaviour if that invariant is not upheld.
+    pub unsafe fn from_slice_unchecked(slice: &[Option<T>]) -> &Self {
+        transmute(slice)
+    }
+
+    /// Instantiate a `TerminatedSlice` from a mutable slice ending in `None`.
+    ///
+    /// ## Unsafety
+    ///
+    /// This assumes that the slice is properly terminated, and can cause
+    /// undefined behaviour if that invariant is not upheld.
+    pub unsafe fn from_slice_mut_unchecked(slice: &mut [Option<T>]) -> &mut Self {
+        transmute(slice)
+    }
+}
+
+impl<'a, U: Sized> TerminatedSlice<&'a U> {
+    pub fn as_ptr(&self) -> *const *const U {
+        self.inner.as_ptr() as *const _
+    }
+}
+
+impl<T> Deref for TerminatedSlice<T> {
+    type Target = [Option<T>];
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner[..self.inner.len() - 1]
+    }
+}
+
+impl<T> DerefMut for TerminatedSlice<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        let len = self.inner.len();
+        &mut self.inner[..len - 1]
+    }
+}
+
+impl<T> AsRef<TerminatedSlice<T>> for TerminatedSlice<T> {
+    fn as_ref(&self) -> &Self {
+        self
+    }
+}
+
+/// Coercion into an argument that can be passed to `exec`.
+impl<'a, T: 'a> IntoRef<'a, TerminatedSlice<&'a T>> for &'a TerminatedSlice<&'a T> {
+    type Target = &'a TerminatedSlice<&'a T>;
+
+    fn into_ref(self) -> Self::Target {
+        self
+    }
+}
+
+/// A `Vec` of references terminated by `None`. Used by API calls that accept
+/// null-terminated arrays such as the `exec` family of functions. Owned variant
+/// of [`TerminatedSlice`].
+pub struct TerminatedVec<T> {
+    inner: Vec<Option<T>>,
+}
+
+impl<T> TerminatedVec<T> {
+    /// Instantiates a `TerminatedVec` from a `None` terminated `Vec`. Fails if
+    /// the provided `Vec` is not properly terminated.
+    pub fn from_vec(vec: Vec<Option<T>>) -> result::Result<Self, NotTerminatedVecError<T>> {
+        if vec.last().map(Option::is_none).unwrap_or(false) {
+            Ok(unsafe { Self::from_vec_unchecked(vec) })
+        } else {
+            Err(NotTerminatedVecError::not_terminated(vec))
+        }
+    }
+
+    /// Instantiates a `TerminatedVec` from a `None` terminated `Vec`.
+    ///
+    /// ## Unsafety
+    ///
+    /// This assumes that the `Vec` is properly terminated, and can cause
+    /// undefined behaviour if that invariant is not upheld.
+    pub unsafe fn from_vec_unchecked(vec: Vec<Option<T>>) -> Self {
+        TerminatedVec {
+            inner: vec,
+        }
+    }
+
+    /// Consume `self` to return the inner wrapped `Vec`.
+    pub fn into_inner(self) -> Vec<Option<T>> {
+        self.inner
+    }
+
+    /// Converts an iterator into a `None` terminated `Vec`.
+    pub fn terminate<I: IntoIterator<Item=T>>(iter: I) -> Self {
+        let terminated = iter.into_iter()
+            .map(Some).chain(iter::once(None)).collect();
+
+        unsafe {
+            Self::from_vec_unchecked(terminated)
+        }
+    }
+}
+
+impl<'a> TerminatedVec<&'a c_char> {
+    /// Converts an iterator of `AsRef<CStr>` into a `TerminatedVec` to
+    /// be used by the `exec` functions. This allows for preallocation of the
+    /// array when memory allocation could otherwise cause problems (such as
+    /// when combined with `fork`).
+    ///
+    /// ```
+    /// use std::iter;
+    /// use std::ffi::CString;
+    /// use nix::{TerminatedVec, unistd};
+    /// use nix::sys::wait;
+    /// use nix::libc::_exit;
+    ///
+    /// # #[cfg(target_os = "android")]
+    /// # fn exe_path() -> CString {
+    /// # CString::new("/system/bin/sh").unwrap()
+    /// # }
+    /// # #[cfg(not(target_os = "android"))]
+    /// # fn exe_path() -> CString {
+    /// let exe = CString::new("/bin/sh").unwrap();
+    /// #    exe
+    /// # }
+    /// # let exe = exe_path();
+    /// let args = [
+    ///     exe.clone(),
+    ///     CString::new("-c").unwrap(),
+    ///     CString::new("echo hi").unwrap(),
+    /// ];
+    /// let args_p = TerminatedVec::terminate_cstr(&args);
+    /// let env = TerminatedVec::terminate(iter::empty());
+    ///
+    /// match unistd::fork().unwrap() {
+    ///     unistd::ForkResult::Child => {
+    ///         match unistd::execve(exe.as_c_str(), &args_p, &env) {
+    ///             Err(..) => {
+    ///                 // Panicking or returning will drop locals and
+    ///                 // deallocate memory, so let's avoid that here.
+    ///                 unsafe { _exit(1); }
+    ///             },
+    ///             Ok(..) => unreachable!(),
+    ///         }
+    ///     },
+    ///     unistd::ForkResult::Parent { child } => {
+    ///         let status = wait::waitpid(child, None).unwrap();
+    ///         assert_eq!(status, wait::WaitStatus::Exited(child, 0));
+    ///     },
+    /// }
+    /// ```
+    pub fn terminate_cstr<T: AsRef<CStr> + 'a, I: IntoIterator<Item=T>>(iter: I) -> Self {
+        fn cstr_char<'a, S: AsRef<CStr> + 'a>(s: S) -> &'a c_char {
+            unsafe {
+                &*s.as_ref().as_ptr()
+            }
+        }
+
+        Self::terminate(iter.into_iter().map(cstr_char))
+    }
+}
+
+impl<T> Deref for TerminatedVec<T> {
+    type Target = TerminatedSlice<T>;
+
+    fn deref(&self) -> &Self::Target {
+        unsafe {
+            TerminatedSlice::from_slice_unchecked(&self.inner)
+        }
+    }
+}
+
+impl<T> DerefMut for TerminatedVec<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        unsafe {
+            TerminatedSlice::from_slice_mut_unchecked(&mut self.inner)
+        }
+    }
+}
+
+impl<T> AsRef<TerminatedSlice<T>> for TerminatedVec<T> {
+    fn as_ref(&self) -> &TerminatedSlice<T> {
+        self
+    }
+}
+
+impl<'a, T: 'a> IntoRef<'a, TerminatedSlice<T>> for TerminatedVec<T> {
+    type Target = TerminatedVec<T>;
+
+    fn into_ref(self) -> Self::Target {
+        self
+    }
+}
+
+impl<'a, T> IntoRef<'a, TerminatedSlice<T>> for &'a TerminatedVec<T> {
+    type Target = &'a TerminatedSlice<T>;
+
+    fn into_ref(self) -> Self::Target {
+        self
+    }
+}
+
+/// Coercion of `CStr` iterators into an argument that can be passed to `exec`.
+impl<'a, T: AsRef<CStr> + 'a, I: IntoIterator<Item=T>> IntoRef<'a, TerminatedSlice<&'a c_char>> for I {
+    type Target = TerminatedVec<&'a c_char>;
+
+    fn into_ref(self) -> Self::Target {
+        TerminatedVec::terminate_cstr(self)
+    }
+}