std/sys/process/unix/common/
cstring_array.rs

1use crate::ffi::{CStr, CString, c_char};
2use crate::ops::Index;
3use crate::{fmt, mem, ptr};
4
5/// Helper type to manage ownership of the strings within a C-style array.
6///
7/// This type manages an array of C-string pointers terminated by a null
8/// pointer. The pointer to the array (as returned by `as_ptr`) can be used as
9/// a value of `argv` or `environ`.
10pub struct CStringArray {
11    ptrs: Vec<*const c_char>,
12}
13
14impl CStringArray {
15    /// Creates a new `CStringArray` with enough capacity to hold `capacity`
16    /// strings.
17    pub fn with_capacity(capacity: usize) -> Self {
18        let mut result = CStringArray { ptrs: Vec::with_capacity(capacity + 1) };
19        result.ptrs.push(ptr::null());
20        result
21    }
22
23    /// Replace the string at position `index`.
24    pub fn write(&mut self, index: usize, item: CString) {
25        let argc = self.ptrs.len() - 1;
26        let ptr = &mut self.ptrs[..argc][index];
27        let old = mem::replace(ptr, item.into_raw());
28        // SAFETY:
29        // `CStringArray` owns all of its strings, and they were all transformed
30        // into pointers using `CString::into_raw`. Also, this is not the null
31        // pointer since the indexing above would have failed.
32        drop(unsafe { CString::from_raw(old.cast_mut()) });
33    }
34
35    /// Push an additional string to the array.
36    pub fn push(&mut self, item: CString) {
37        let argc = self.ptrs.len() - 1;
38        // Amend the array by another null pointer first, to ensure that the
39        // array is null-terminated even when the `push` panics, in which case
40        // the array will be left undisturbed (see #155748).
41        self.ptrs.push(ptr::null());
42        // Now, replace the previous null pointer.
43        self.ptrs[argc] = item.into_raw();
44    }
45
46    /// Returns a pointer to the C-string array managed by this type.
47    pub fn as_ptr(&self) -> *const *const c_char {
48        self.ptrs.as_ptr()
49    }
50
51    /// Returns an iterator over all `CStr`s contained in this array.
52    pub fn iter(&self) -> CStringIter<'_> {
53        CStringIter { iter: self.ptrs[..self.ptrs.len() - 1].iter() }
54    }
55}
56
57impl Index<usize> for CStringArray {
58    type Output = CStr;
59    fn index(&self, index: usize) -> &CStr {
60        let ptr = self.ptrs[..self.ptrs.len() - 1][index];
61        // SAFETY:
62        // `CStringArray` owns all of its strings. Also, this is not the null
63        // pointer since the indexing above would have failed.
64        unsafe { CStr::from_ptr(ptr) }
65    }
66}
67
68impl fmt::Debug for CStringArray {
69    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70        f.debug_list().entries(self.iter()).finish()
71    }
72}
73
74// SAFETY: `CStringArray` is basically just a `Vec<CString>`
75unsafe impl Send for CStringArray {}
76// SAFETY: `CStringArray` is basically just a `Vec<CString>`
77unsafe impl Sync for CStringArray {}
78
79impl Drop for CStringArray {
80    fn drop(&mut self) {
81        // SAFETY:
82        // `CStringArray` owns all of its strings, and they were all transformed
83        // into pointers using `CString::into_raw`.
84        self.ptrs[..self.ptrs.len() - 1]
85            .iter()
86            .for_each(|&p| drop(unsafe { CString::from_raw(p.cast_mut()) }))
87    }
88}
89
90/// An iterator over all `CStr`s contained in a `CStringArray`.
91#[derive(Clone)]
92pub struct CStringIter<'a> {
93    iter: crate::slice::Iter<'a, *const c_char>,
94}
95
96impl<'a> Iterator for CStringIter<'a> {
97    type Item = &'a CStr;
98    fn next(&mut self) -> Option<&'a CStr> {
99        // SAFETY:
100        // `CStringArray` owns all of its strings. Also, this is not the null
101        // pointer since the last element is excluded when creating `iter`.
102        self.iter.next().map(|&p| unsafe { CStr::from_ptr(p) })
103    }
104
105    fn size_hint(&self) -> (usize, Option<usize>) {
106        self.iter.size_hint()
107    }
108}
109
110impl<'a> ExactSizeIterator for CStringIter<'a> {
111    fn len(&self) -> usize {
112        self.iter.len()
113    }
114    fn is_empty(&self) -> bool {
115        self.iter.is_empty()
116    }
117}
std/sys/process/unix/common/cstring_array.rs

std/sys/process/unix/common/
cstring_array.rs
