1 #![stable(feature = "", since = "1.30.0")]
3 #![allow(non_camel_case_types)]
5 //! Utilities related to FFI bindings.
9 /// Equivalent to C's `void` type when used as a [pointer].
11 /// In essence, `*const c_void` is equivalent to C's `const void*`
12 /// and `*mut c_void` is equivalent to C's `void*`. That said, this is
13 /// *not* the same as C's `void` return type, which is Rust's `()` type.
15 /// To model pointers to opaque types in FFI, until `extern type` is
16 /// stabilized, it is recommended to use a newtype wrapper around an empty
17 /// byte array. See the [Nomicon] for details.
19 /// [pointer]: ../../std/primitive.pointer.html
20 /// [Nomicon]: https://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs
21 // N.B., for LLVM to recognize the void pointer type and by extension
22 // functions like malloc(), we need to have it represented as i8* in
23 // LLVM bitcode. The enum used here ensures this and prevents misuse
24 // of the "raw" type by only having private variants. We need two
25 // variants, because the compiler complains about the repr attribute
26 // otherwise and we need at least one variant as otherwise the enum
27 // would be uninhabited and at least dereferencing such pointers would
30 #[stable(feature = "raw_os", since = "1.1.0")]
32 #[unstable(feature = "c_void_variant", reason = "temporary implementation detail",
34 #[doc(hidden)] __variant1,
35 #[unstable(feature = "c_void_variant", reason = "temporary implementation detail",
37 #[doc(hidden)] __variant2,
40 #[stable(feature = "std_debug", since = "1.16.0")]
41 impl fmt
::Debug
for c_void
{
42 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
47 /// Basic implementation of a `va_list`.
48 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
49 not(target_arch
= "x86_64")),
50 all(target_arch
= "aarch4", target_os
= "ios"),
52 #[unstable(feature = "c_variadic",
53 reason
= "the `c_variadic` feature has not been properly tested on \
54 all supported platforms",
60 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
61 not(target_arch
= "x86_64")),
63 impl fmt
::Debug
for VaListImpl
{
64 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
65 write
!(f
, "va_list* {:p}", self)
69 /// AArch64 ABI implementation of a `va_list`. See the
70 /// [Aarch64 Procedure Call Standard] for more details.
72 /// [AArch64 Procedure Call Standard]:
73 /// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
74 #[cfg(all(target_arch = "aarch64", not(windows)))]
77 #[unstable(feature = "c_variadic",
78 reason
= "the `c_variadic` feature has not been properly tested on \
79 all supported platforms",
89 /// PowerPC ABI implementation of a `va_list`.
90 #[cfg(all(target_arch = "powerpc", not(windows)))]
93 #[unstable(feature = "c_variadic",
94 reason
= "the `c_variadic` feature has not been properly tested on \
95 all supported platforms",
101 overflow_arg_area
: *mut (),
102 reg_save_area
: *mut (),
105 /// x86_64 ABI implementation of a `va_list`.
106 #[cfg(all(target_arch = "x86_64", not(windows)))]
109 #[unstable(feature = "c_variadic",
110 reason
= "the `c_variadic` feature has not been properly tested on \
111 all supported platforms",
116 overflow_arg_area
: *mut (),
117 reg_save_area
: *mut (),
120 /// A wrapper for a `va_list`
123 #[unstable(feature = "c_variadic",
124 reason
= "the `c_variadic` feature has not been properly tested on \
125 all supported platforms",
128 pub struct VaList
<'a
>(&'a
mut VaListImpl
);
130 // The VaArgSafe trait needs to be used in public interfaces, however, the trait
131 // itself must not be allowed to be used outside this module. Allowing users to
132 // implement the trait for a new type (thereby allowing the va_arg intrinsic to
133 // be used on a new type) is likely to cause undefined behavior.
135 // FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface
136 // but also ensure it cannot be used elsewhere, the trait needs to be public
137 // within a private module. Once RFC 2145 has been implemented look into
140 /// Trait which whitelists the allowed types to be used with [VaList::arg]
142 /// [VaList::va_arg]: struct.VaList.html#method.arg
143 #[unstable(feature = "c_variadic",
144 reason
= "the `c_variadic` feature has not been properly tested on \
145 all supported platforms",
147 pub trait VaArgSafe {}
150 macro_rules
! impl_va_arg_safe
{
153 #[unstable(feature = "c_variadic",
154 reason
= "the `c_variadic` feature has not been properly tested on \
155 all supported platforms",
157 impl sealed_trait
::VaArgSafe
for $t {}
162 impl_va_arg_safe
!{i8, i16, i32, i64, usize}
163 impl_va_arg_safe
!{u8, u16, u32, u64, isize}
164 impl_va_arg_safe
!{f64}
166 #[unstable(feature = "c_variadic",
167 reason
= "the `c_variadic` feature has not been properly tested on \
168 all supported platforms",
170 impl<T
> sealed_trait
::VaArgSafe
for *mut T {}
171 #[unstable(feature = "c_variadic",
172 reason
= "the `c_variadic` feature has not been properly tested on \
173 all supported platforms",
175 impl<T
> sealed_trait
::VaArgSafe
for *const T {}
177 impl<'a
> VaList
<'a
> {
178 /// Advance to the next arg.
179 #[unstable(feature = "c_variadic",
180 reason
= "the `c_variadic` feature has not been properly tested on \
181 all supported platforms",
183 pub unsafe fn arg
<T
: sealed_trait
::VaArgSafe
>(&mut self) -> T
{
187 /// Copies the `va_list` at the current location.
188 #[unstable(feature = "c_variadic",
189 reason
= "the `c_variadic` feature has not been properly tested on \
190 all supported platforms",
192 pub unsafe fn copy
<F
, R
>(&self, f
: F
) -> R
193 where F
: for<'copy
> FnOnce(VaList
<'copy
>) -> R
{
194 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
195 not(target_arch
= "x86_64")),
196 all(target_arch
= "aarch4", target_os
= "ios"),
198 let mut ap
= va_copy(self);
199 #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
201 let mut ap_inner
= va_copy(self);
202 #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
204 let mut ap
= VaList(&mut ap_inner
);
205 let ret
= f(VaList(ap
.0));
211 extern "rust-intrinsic" {
212 /// Destroy the arglist `ap` after initialization with `va_start` or
214 fn va_end(ap
: &mut VaList
);
216 /// Copies the current location of arglist `src` to the arglist `dst`.
217 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
218 not(target_arch
= "x86_64")),
220 fn va_copy
<'a
>(src
: &VaList
<'a
>) -> VaList
<'a
>;
221 #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
223 fn va_copy(src
: &VaList
) -> VaListImpl
;
225 /// Loads an argument of type `T` from the `va_list` `ap` and increment the
226 /// argument `ap` points to.
227 fn va_arg
<T
: sealed_trait
::VaArgSafe
>(ap
: &mut VaList
) -> T
;