1 #![stable(feature = "", since = "1.30.0")]
3 #![allow(non_camel_case_types)]
5 //! Utilities related to FFI bindings.
8 use crate::marker::PhantomData;
9 use crate::ops::{Deref, DerefMut};
11 /// Equivalent to C's `void` type when used as a [pointer].
13 /// In essence, `*const c_void` is equivalent to C's `const void*`
14 /// and `*mut c_void` is equivalent to C's `void*`. That said, this is
15 /// *not* the same as C's `void` return type, which is Rust's `()` type.
17 /// To model pointers to opaque types in FFI, until `extern type` is
18 /// stabilized, it is recommended to use a newtype wrapper around an empty
19 /// byte array. See the [Nomicon] for details.
21 /// [pointer]: ../../std/primitive.pointer.html
22 /// [Nomicon]: https://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs
23 // N.B., for LLVM to recognize the void pointer type and by extension
24 // functions like malloc(), we need to have it represented as i8* in
25 // LLVM bitcode. The enum used here ensures this and prevents misuse
26 // of the "raw" type by only having private variants. We need two
27 // variants, because the compiler complains about the repr attribute
28 // otherwise and we need at least one variant as otherwise the enum
29 // would be uninhabited and at least dereferencing such pointers would
32 #[stable(feature = "raw_os", since = "1.1.0")]
34 #[unstable(feature = "c_void_variant", reason = "temporary implementation detail",
36 #[doc(hidden)] __variant1,
37 #[unstable(feature = "c_void_variant", reason = "temporary implementation detail",
39 #[doc(hidden)] __variant2,
42 #[stable(feature = "std_debug", since = "1.16.0")]
43 impl fmt::Debug for c_void {
44 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
49 /// Basic implementation of a `va_list`.
50 // The name is WIP, using `VaListImpl` for now.
51 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
52 not(target_arch = "x86_64"), not(target_arch = "asmjs")),
53 all(target_arch = "aarch64", target_os = "ios"),
56 #[unstable(feature = "c_variadic",
57 reason = "the `c_variadic` feature has not been properly tested on \
58 all supported platforms",
61 pub struct VaListImpl<'f> {
64 // Invariant over `'f`, so each `VaListImpl<'f>` object is tied to
65 // the region of the function it's defined in
66 _marker: PhantomData<&'f mut &'f c_void>,
69 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
70 not(target_arch = "x86_64"), not(target_arch = "asmjs")),
71 all(target_arch = "aarch64", target_os = "ios"),
73 #[unstable(feature = "c_variadic",
74 reason = "the `c_variadic` feature has not been properly tested on \
75 all supported platforms",
77 impl<'f> fmt::Debug for VaListImpl<'f> {
78 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
79 write!(f, "va_list* {:p}", self.ptr)
83 /// AArch64 ABI implementation of a `va_list`. See the
84 /// [AArch64 Procedure Call Standard] for more details.
86 /// [AArch64 Procedure Call Standard]:
87 /// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
88 #[cfg(all(target_arch = "aarch64", not(target_os = "ios"), not(windows)))]
91 #[unstable(feature = "c_variadic",
92 reason = "the `c_variadic` feature has not been properly tested on \
93 all supported platforms",
96 pub struct VaListImpl<'f> {
102 _marker: PhantomData<&'f mut &'f c_void>,
105 /// PowerPC ABI implementation of a `va_list`.
106 #[cfg(all(target_arch = "powerpc", not(windows)))]
109 #[unstable(feature = "c_variadic",
110 reason = "the `c_variadic` feature has not been properly tested on \
111 all supported platforms",
114 pub struct VaListImpl<'f> {
118 overflow_arg_area: *mut c_void,
119 reg_save_area: *mut c_void,
120 _marker: PhantomData<&'f mut &'f c_void>,
123 /// x86_64 ABI implementation of a `va_list`.
124 #[cfg(all(target_arch = "x86_64", not(windows)))]
127 #[unstable(feature = "c_variadic",
128 reason = "the `c_variadic` feature has not been properly tested on \
129 all supported platforms",
132 pub struct VaListImpl<'f> {
135 overflow_arg_area: *mut c_void,
136 reg_save_area: *mut c_void,
137 _marker: PhantomData<&'f mut &'f c_void>,
140 /// asm.js ABI implementation of a `va_list`.
141 // asm.js uses the PNaCl ABI, which specifies that a `va_list` is
142 // an array of 4 32-bit integers, according to the old PNaCl docs at
143 // https://web.archive.org/web/20130518054430/https://www.chromium.org/nativeclient/pnacl/bitcode-abi#TOC-Derived-Types
144 // and clang does the same in `CreatePNaClABIBuiltinVaListDecl` from `lib/AST/ASTContext.cpp`
145 #[cfg(all(target_arch = "asmjs", not(windows)))]
147 #[unstable(feature = "c_variadic",
148 reason = "the `c_variadic` feature has not been properly tested on \
149 all supported platforms",
152 pub struct VaListImpl<'f> {
153 inner: [crate::mem::MaybeUninit<i32>; 4],
154 _marker: PhantomData<&'f mut &'f c_void>,
157 #[cfg(all(target_arch = "asmjs", not(windows)))]
158 #[unstable(feature = "c_variadic",
159 reason = "the `c_variadic` feature has not been properly tested on \
160 all supported platforms",
162 impl<'f> fmt::Debug for VaListImpl<'f> {
163 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
165 write!(f, "va_list* [{:#x}, {:#x}, {:#x}, {:#x}]",
166 self.inner[0].read(), self.inner[1].read(),
167 self.inner[2].read(), self.inner[3].read())
172 /// A wrapper for a `va_list`
175 #[unstable(feature = "c_variadic",
176 reason = "the `c_variadic` feature has not been properly tested on \
177 all supported platforms",
179 pub struct VaList<'a, 'f: 'a> {
180 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
181 not(target_arch = "x86_64"), not(target_arch = "asmjs")),
182 all(target_arch = "aarch64", target_os = "ios"),
184 inner: VaListImpl<'f>,
186 #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc",
187 target_arch = "x86_64", target_arch = "asmjs"),
188 any(not(target_arch = "aarch64"), not(target_os = "ios")),
190 inner: &'a mut VaListImpl<'f>,
192 _marker: PhantomData<&'a mut VaListImpl<'f>>,
195 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
196 not(target_arch = "x86_64"), not(target_arch = "asmjs")),
197 all(target_arch = "aarch64", target_os = "ios"),
199 #[unstable(feature = "c_variadic",
200 reason = "the `c_variadic` feature has not been properly tested on \
201 all supported platforms",
203 impl<'f> VaListImpl<'f> {
204 /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
206 pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
208 inner: VaListImpl { ..*self },
209 _marker: PhantomData,
214 #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc",
215 target_arch = "x86_64", target_arch = "asmjs"),
216 any(not(target_arch = "aarch64"), not(target_os = "ios")),
218 #[unstable(feature = "c_variadic",
219 reason = "the `c_variadic` feature has not been properly tested on \
220 all supported platforms",
222 impl<'f> VaListImpl<'f> {
223 /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
225 pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
228 _marker: PhantomData,
233 #[unstable(feature = "c_variadic",
234 reason = "the `c_variadic` feature has not been properly tested on \
235 all supported platforms",
237 impl<'a, 'f: 'a> Deref for VaList<'a, 'f> {
238 type Target = VaListImpl<'f>;
241 fn deref(&self) -> &VaListImpl<'f> {
246 #[unstable(feature = "c_variadic",
247 reason = "the `c_variadic` feature has not been properly tested on \
248 all supported platforms",
250 impl<'a, 'f: 'a> DerefMut for VaList<'a, 'f> {
252 fn deref_mut(&mut self) -> &mut VaListImpl<'f> {
257 // The VaArgSafe trait needs to be used in public interfaces, however, the trait
258 // itself must not be allowed to be used outside this module. Allowing users to
259 // implement the trait for a new type (thereby allowing the va_arg intrinsic to
260 // be used on a new type) is likely to cause undefined behavior.
262 // FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface
263 // but also ensure it cannot be used elsewhere, the trait needs to be public
264 // within a private module. Once RFC 2145 has been implemented look into
267 /// Trait which whitelists the allowed types to be used with [VaList::arg]
269 /// [VaList::va_arg]: struct.VaList.html#method.arg
270 #[unstable(feature = "c_variadic",
271 reason = "the `c_variadic` feature has not been properly tested on \
272 all supported platforms",
274 pub trait VaArgSafe {}
277 macro_rules! impl_va_arg_safe {
280 #[unstable(feature = "c_variadic",
281 reason = "the `c_variadic` feature has not been properly tested on \
282 all supported platforms",
284 impl sealed_trait::VaArgSafe for $t {}
289 impl_va_arg_safe!{i8, i16, i32, i64, usize}
290 impl_va_arg_safe!{u8, u16, u32, u64, isize}
291 impl_va_arg_safe!{f64}
293 #[unstable(feature = "c_variadic",
294 reason = "the `c_variadic` feature has not been properly tested on \
295 all supported platforms",
297 impl<T> sealed_trait::VaArgSafe for *mut T {}
298 #[unstable(feature = "c_variadic",
299 reason = "the `c_variadic` feature has not been properly tested on \
300 all supported platforms",
302 impl<T> sealed_trait::VaArgSafe for *const T {}
304 #[unstable(feature = "c_variadic",
305 reason = "the `c_variadic` feature has not been properly tested on \
306 all supported platforms",
308 impl<'f> VaListImpl<'f> {
309 /// Advance to the next arg.
311 pub unsafe fn arg<T: sealed_trait::VaArgSafe>(&mut self) -> T {
315 /// Copies the `va_list` at the current location.
316 pub unsafe fn with_copy<F, R>(&self, f: F) -> R
317 where F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R {
318 let mut ap = self.clone();
319 let ret = f(ap.as_va_list());
325 #[unstable(feature = "c_variadic",
326 reason = "the `c_variadic` feature has not been properly tested on \
327 all supported platforms",
329 impl<'f> Clone for VaListImpl<'f> {
331 fn clone(&self) -> Self {
332 let mut dest = crate::mem::MaybeUninit::uninit();
334 va_copy(dest.as_mut_ptr(), self);
340 #[unstable(feature = "c_variadic",
341 reason = "the `c_variadic` feature has not been properly tested on \
342 all supported platforms",
344 impl<'f> Drop for VaListImpl<'f> {
346 // FIXME: this should call `va_end`, but there's no clean way to
347 // guarantee that `drop` always gets inlined into its caller,
348 // so the `va_end` would get directly called from the same function as
349 // the corresponding `va_copy`. `man va_end` states that C requires this,
350 // and LLVM basically follows the C semantics, so we need to make sure
351 // that `va_end` is always called from the same function as `va_copy`.
352 // For more details, see https://github.com/rust-lang/rust/pull/59625
353 // and https://llvm.org/docs/LangRef.html#llvm-va-end-intrinsic.
355 // This works for now, since `va_end` is a no-op on all current LLVM targets.
359 extern "rust-intrinsic" {
360 /// Destroy the arglist `ap` after initialization with `va_start` or
362 fn va_end(ap: &mut VaListImpl<'_>);
364 /// Copies the current location of arglist `src` to the arglist `dst`.
365 fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);
367 /// Loads an argument of type `T` from the `va_list` `ap` and increment the
368 /// argument `ap` points to.
369 fn va_arg<T: sealed_trait::VaArgSafe>(ap: &mut VaListImpl<'_>) -> T;