core/ffi/
va_list.rs

Help
1//! C's "variable arguments"
2//!
3//! Better known as "varargs".
4
5use crate::ffi::c_void;
6#[allow(unused_imports)]
7use crate::fmt;
8use crate::marker::PhantomData;
9use crate::ops::{Deref, DerefMut};
10
11/// Basic implementation of a `va_list`.
12// The name is WIP, using `VaListImpl` for now.
13#[cfg(any(
14    all(
15        not(target_arch = "aarch64"),
16        not(target_arch = "powerpc"),
17        not(target_arch = "s390x"),
18        not(target_arch = "xtensa"),
19        not(target_arch = "x86_64")
20    ),
21    all(target_arch = "aarch64", target_vendor = "apple"),
22    target_family = "wasm",
23    target_os = "uefi",
24    windows,
25))]
26#[repr(transparent)]
27#[lang = "va_list"]
28pub struct VaListImpl<'f> {
29    ptr: *mut c_void,
30
31    // Invariant over `'f`, so each `VaListImpl<'f>` object is tied to
32    // the region of the function it's defined in
33    _marker: PhantomData<&'f mut &'f c_void>,
34}
35
36#[cfg(any(
37    all(
38        not(target_arch = "aarch64"),
39        not(target_arch = "powerpc"),
40        not(target_arch = "s390x"),
41        not(target_arch = "xtensa"),
42        not(target_arch = "x86_64")
43    ),
44    all(target_arch = "aarch64", target_vendor = "apple"),
45    target_family = "wasm",
46    target_os = "uefi",
47    windows,
48))]
49impl<'f> fmt::Debug for VaListImpl<'f> {
50    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51        write!(f, "va_list* {:p}", self.ptr)
52    }
53}
54
55/// AArch64 ABI implementation of a `va_list`. See the
56/// [AArch64 Procedure Call Standard] for more details.
57///
58/// [AArch64 Procedure Call Standard]:
59/// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
60#[cfg(all(
61    target_arch = "aarch64",
62    not(target_vendor = "apple"),
63    not(target_os = "uefi"),
64    not(windows),
65))]
66#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
67#[derive(Debug)]
68#[lang = "va_list"]
69pub struct VaListImpl<'f> {
70    stack: *mut c_void,
71    gr_top: *mut c_void,
72    vr_top: *mut c_void,
73    gr_offs: i32,
74    vr_offs: i32,
75    _marker: PhantomData<&'f mut &'f c_void>,
76}
77
78/// PowerPC ABI implementation of a `va_list`.
79#[cfg(all(target_arch = "powerpc", not(target_os = "uefi"), not(windows)))]
80#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
81#[derive(Debug)]
82#[lang = "va_list"]
83pub struct VaListImpl<'f> {
84    gpr: u8,
85    fpr: u8,
86    reserved: u16,
87    overflow_arg_area: *mut c_void,
88    reg_save_area: *mut c_void,
89    _marker: PhantomData<&'f mut &'f c_void>,
90}
91
92/// s390x ABI implementation of a `va_list`.
93#[cfg(target_arch = "s390x")]
94#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
95#[derive(Debug)]
96#[lang = "va_list"]
97pub struct VaListImpl<'f> {
98    gpr: i64,
99    fpr: i64,
100    overflow_arg_area: *mut c_void,
101    reg_save_area: *mut c_void,
102    _marker: PhantomData<&'f mut &'f c_void>,
103}
104
105/// x86_64 ABI implementation of a `va_list`.
106#[cfg(all(target_arch = "x86_64", not(target_os = "uefi"), not(windows)))]
107#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
108#[derive(Debug)]
109#[lang = "va_list"]
110pub struct VaListImpl<'f> {
111    gp_offset: i32,
112    fp_offset: i32,
113    overflow_arg_area: *mut c_void,
114    reg_save_area: *mut c_void,
115    _marker: PhantomData<&'f mut &'f c_void>,
116}
117
118/// Xtensa ABI implementation of a `va_list`.
119#[cfg(target_arch = "xtensa")]
120#[repr(C)]
121#[derive(Debug)]
122#[lang = "va_list"]
123pub struct VaListImpl<'f> {
124    stk: *mut i32,
125    reg: *mut i32,
126    ndx: i32,
127    _marker: PhantomData<&'f mut &'f c_void>,
128}
129
130/// A wrapper for a `va_list`
131#[repr(transparent)]
132#[derive(Debug)]
133pub struct VaList<'a, 'f: 'a> {
134    #[cfg(any(
135        all(
136            not(target_arch = "aarch64"),
137            not(target_arch = "powerpc"),
138            not(target_arch = "s390x"),
139            not(target_arch = "x86_64")
140        ),
141        target_arch = "xtensa",
142        all(target_arch = "aarch64", target_vendor = "apple"),
143        target_family = "wasm",
144        target_os = "uefi",
145        windows,
146    ))]
147    inner: VaListImpl<'f>,
148
149    #[cfg(all(
150        any(
151            target_arch = "aarch64",
152            target_arch = "powerpc",
153            target_arch = "s390x",
154            target_arch = "x86_64"
155        ),
156        not(target_arch = "xtensa"),
157        any(not(target_arch = "aarch64"), not(target_vendor = "apple")),
158        not(target_family = "wasm"),
159        not(target_os = "uefi"),
160        not(windows),
161    ))]
162    inner: &'a mut VaListImpl<'f>,
163
164    _marker: PhantomData<&'a mut VaListImpl<'f>>,
165}
166
167#[cfg(any(
168    all(
169        not(target_arch = "aarch64"),
170        not(target_arch = "powerpc"),
171        not(target_arch = "s390x"),
172        not(target_arch = "x86_64")
173    ),
174    target_arch = "xtensa",
175    all(target_arch = "aarch64", target_vendor = "apple"),
176    target_family = "wasm",
177    target_os = "uefi",
178    windows,
179))]
180impl<'f> VaListImpl<'f> {
181    /// Converts a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
182    #[inline]
183    pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
184        VaList { inner: VaListImpl { ..*self }, _marker: PhantomData }
185    }
186}
187
188#[cfg(all(
189    any(
190        target_arch = "aarch64",
191        target_arch = "powerpc",
192        target_arch = "s390x",
193        target_arch = "xtensa",
194        target_arch = "x86_64"
195    ),
196    not(target_arch = "xtensa"),
197    any(not(target_arch = "aarch64"), not(target_vendor = "apple")),
198    not(target_family = "wasm"),
199    not(target_os = "uefi"),
200    not(windows),
201))]
202impl<'f> VaListImpl<'f> {
203    /// Converts a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
204    #[inline]
205    pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
206        VaList { inner: self, _marker: PhantomData }
207    }
208}
209
210impl<'a, 'f: 'a> Deref for VaList<'a, 'f> {
211    type Target = VaListImpl<'f>;
212
213    #[inline]
214    fn deref(&self) -> &VaListImpl<'f> {
215        &self.inner
216    }
217}
218
219impl<'a, 'f: 'a> DerefMut for VaList<'a, 'f> {
220    #[inline]
221    fn deref_mut(&mut self) -> &mut VaListImpl<'f> {
222        &mut self.inner
223    }
224}
225
226// The VaArgSafe trait needs to be used in public interfaces, however, the trait
227// itself must not be allowed to be used outside this module. Allowing users to
228// implement the trait for a new type (thereby allowing the va_arg intrinsic to
229// be used on a new type) is likely to cause undefined behavior.
230//
231// FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface
232// but also ensure it cannot be used elsewhere, the trait needs to be public
233// within a private module. Once RFC 2145 has been implemented look into
234// improving this.
235mod sealed_trait {
236    /// Trait which permits the allowed types to be used with [super::VaListImpl::arg].
237    pub unsafe trait VaArgSafe {}
238}
239
240macro_rules! impl_va_arg_safe {
241    ($($t:ty),+) => {
242        $(
243            unsafe impl sealed_trait::VaArgSafe for $t {}
244        )+
245    }
246}
247
248impl_va_arg_safe! {i8, i16, i32, i64, usize}
249impl_va_arg_safe! {u8, u16, u32, u64, isize}
250impl_va_arg_safe! {f64}
251
252unsafe impl<T> sealed_trait::VaArgSafe for *mut T {}
253unsafe impl<T> sealed_trait::VaArgSafe for *const T {}
254
255impl<'f> VaListImpl<'f> {
256    /// Advance to the next arg.
257    #[inline]
258    pub unsafe fn arg<T: sealed_trait::VaArgSafe>(&mut self) -> T {
259        // SAFETY: the caller must uphold the safety contract for `va_arg`.
260        unsafe { va_arg(self) }
261    }
262
263    /// Copies the `va_list` at the current location.
264    pub unsafe fn with_copy<F, R>(&self, f: F) -> R
265    where
266        F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R,
267    {
268        let mut ap = self.clone();
269        let ret = f(ap.as_va_list());
270        // SAFETY: the caller must uphold the safety contract for `va_end`.
271        unsafe {
272            va_end(&mut ap);
273        }
274        ret
275    }
276}
277
278impl<'f> Clone for VaListImpl<'f> {
279    #[inline]
280    fn clone(&self) -> Self {
281        let mut dest = crate::mem::MaybeUninit::uninit();
282        // SAFETY: we write to the `MaybeUninit`, thus it is initialized and `assume_init` is legal
283        unsafe {
284            va_copy(dest.as_mut_ptr(), self);
285            dest.assume_init()
286        }
287    }
288}
289
290impl<'f> Drop for VaListImpl<'f> {
291    fn drop(&mut self) {
292        // FIXME: this should call `va_end`, but there's no clean way to
293        // guarantee that `drop` always gets inlined into its caller,
294        // so the `va_end` would get directly called from the same function as
295        // the corresponding `va_copy`. `man va_end` states that C requires this,
296        // and LLVM basically follows the C semantics, so we need to make sure
297        // that `va_end` is always called from the same function as `va_copy`.
298        // For more details, see https://github.com/rust-lang/rust/pull/59625
299        // and https://llvm.org/docs/LangRef.html#llvm-va-end-intrinsic.
300        //
301        // This works for now, since `va_end` is a no-op on all current LLVM targets.
302    }
303}
304
305/// Destroy the arglist `ap` after initialization with `va_start` or
306/// `va_copy`.
307#[rustc_intrinsic]
308#[rustc_intrinsic_must_be_overridden]
309#[rustc_nounwind]
310unsafe fn va_end(_ap: &mut VaListImpl<'_>) {
311    unreachable!()
312}
313
314/// Copies the current location of arglist `src` to the arglist `dst`.
315#[rustc_intrinsic]
316#[rustc_intrinsic_must_be_overridden]
317#[rustc_nounwind]
318unsafe fn va_copy<'f>(_dest: *mut VaListImpl<'f>, _src: &VaListImpl<'f>) {
319    unreachable!()
320}
321
322/// Loads an argument of type `T` from the `va_list` `ap` and increment the
323/// argument `ap` points to.
324#[rustc_intrinsic]
325#[rustc_intrinsic_must_be_overridden]
326#[rustc_nounwind]
327unsafe fn va_arg<T: sealed_trait::VaArgSafe>(_ap: &mut VaListImpl<'_>) -> T {
328    unreachable!()
329}
core/ffi/va_list.rs

core/ffi/
va_list.rs
