1 //! Platform-specific types, as defined by C.
3 //! Code that interacts via FFI will almost certainly be using the
4 //! base types provided by C, which aren't nearly as nicely defined
5 //! as Rust's primitive types. This module provides types which will
6 //! match those defined by C, so that code that interacts with C will
7 //! refer to the correct types.
9 #![stable(feature = "", since = "1.30.0")]
10 #![allow(non_camel_case_types)]
13 use crate::marker::PhantomData;
15 use crate::ops::{Deref, DerefMut};
17 #[stable(feature = "core_c_str", since = "1.64.0")]
18 pub use self::c_str::{CStr, FromBytesUntilNulError, FromBytesWithNulError};
22 macro_rules! type_alias_no_nz {
24 $Docfile:tt, $Alias:ident = $Real:ty;
27 #[doc = include_str!($Docfile)]
29 #[stable(feature = "core_ffi_c", since = "1.64.0")]
30 pub type $Alias = $Real;
34 // To verify that the NonZero types in this file's macro invocations correspond
36 // perl -n < library/std/src/os/raw/mod.rs -e 'next unless m/type_alias\!/; die "$_ ?" unless m/, (c_\w+) = (\w+), NonZero_(\w+) = NonZero(\w+)/; die "$_ ?" unless $3 eq $1 and $4 eq ucfirst $2'
38 // NB this does not check that the main c_* types are right.
40 macro_rules! type_alias {
42 $Docfile:tt, $Alias:ident = $Real:ty, $NZAlias:ident = $NZReal:ty;
45 type_alias_no_nz! { $Docfile, $Alias = $Real; $( $Cfg )* }
47 #[doc = concat!("Type alias for `NonZero` version of [`", stringify!($Alias), "`]")]
48 #[unstable(feature = "raw_os_nonzero", issue = "82363")]
50 pub type $NZAlias = $NZReal;
54 type_alias! { "c_char.md", c_char = c_char_definition::c_char, NonZero_c_char = c_char_definition::NonZero_c_char;
55 // Make this type alias appear cfg-dependent so that Clippy does not suggest
56 // replacing `0 as c_char` with `0_i8`/`0_u8`. This #[cfg(all())] can be removed
57 // after the false positive in https://github.com/rust-lang/rust-clippy/issues/8093
62 type_alias! { "c_schar.md", c_schar = i8, NonZero_c_schar = NonZeroI8; }
63 type_alias! { "c_uchar.md", c_uchar = u8, NonZero_c_uchar = NonZeroU8; }
64 type_alias! { "c_short.md", c_short = i16, NonZero_c_short = NonZeroI16; }
65 type_alias! { "c_ushort.md", c_ushort = u16, NonZero_c_ushort = NonZeroU16; }
67 type_alias! { "c_int.md", c_int = c_int_definition::c_int, NonZero_c_int = c_int_definition::NonZero_c_int;
69 type_alias! { "c_uint.md", c_uint = c_int_definition::c_uint, NonZero_c_uint = c_int_definition::NonZero_c_uint;
72 type_alias! { "c_long.md", c_long = c_long_definition::c_long, NonZero_c_long = c_long_definition::NonZero_c_long;
74 type_alias! { "c_ulong.md", c_ulong = c_long_definition::c_ulong, NonZero_c_ulong = c_long_definition::NonZero_c_ulong;
77 type_alias! { "c_longlong.md", c_longlong = i64, NonZero_c_longlong = NonZeroI64; }
78 type_alias! { "c_ulonglong.md", c_ulonglong = u64, NonZero_c_ulonglong = NonZeroU64; }
80 type_alias_no_nz! { "c_float.md", c_float = f32; }
81 type_alias_no_nz! { "c_double.md", c_double = f64; }
83 /// Equivalent to C's `size_t` type, from `stddef.h` (or `cstddef` for C++).
85 /// This type is currently always [`usize`], however in the future there may be
86 /// platforms where this is not the case.
87 #[unstable(feature = "c_size_t", issue = "88345")]
88 pub type c_size_t = usize;
90 /// Equivalent to C's `ptrdiff_t` type, from `stddef.h` (or `cstddef` for C++).
92 /// This type is currently always [`isize`], however in the future there may be
93 /// platforms where this is not the case.
94 #[unstable(feature = "c_size_t", issue = "88345")]
95 pub type c_ptrdiff_t = isize;
97 /// Equivalent to C's `ssize_t` (on POSIX) or `SSIZE_T` (on Windows) type.
99 /// This type is currently always [`isize`], however in the future there may be
100 /// platforms where this is not the case.
101 #[unstable(feature = "c_size_t", issue = "88345")]
102 pub type c_ssize_t = isize;
104 mod c_char_definition {
106 // These are the targets on which c_char is unsigned.
111 target_arch = "aarch64",
113 target_arch = "hexagon",
114 target_arch = "powerpc",
115 target_arch = "powerpc64",
116 target_arch = "s390x",
117 target_arch = "riscv64",
118 target_arch = "riscv32"
121 all(target_os = "android", any(target_arch = "aarch64", target_arch = "arm")),
122 all(target_os = "l4re", target_arch = "x86_64"),
124 any(target_os = "freebsd", target_os = "openbsd"),
126 target_arch = "aarch64",
128 target_arch = "powerpc",
129 target_arch = "powerpc64",
130 target_arch = "riscv64"
134 target_os = "netbsd",
135 any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc")
138 target_os = "vxworks",
140 target_arch = "aarch64",
142 target_arch = "powerpc64",
143 target_arch = "powerpc"
146 all(target_os = "fuchsia", target_arch = "aarch64"),
147 target_os = "horizon"
149 pub type c_char = u8;
150 pub type NonZero_c_char = crate::num::NonZeroU8;
152 // On every other target, c_char is signed.
153 pub type c_char = i8;
154 pub type NonZero_c_char = crate::num::NonZeroI8;
159 mod c_int_definition {
161 if #[cfg(any(target_arch = "avr", target_arch = "msp430"))] {
162 pub type c_int = i16;
163 pub type NonZero_c_int = crate::num::NonZeroI16;
164 pub type c_uint = u16;
165 pub type NonZero_c_uint = crate::num::NonZeroU16;
167 pub type c_int = i32;
168 pub type NonZero_c_int = crate::num::NonZeroI32;
169 pub type c_uint = u32;
170 pub type NonZero_c_uint = crate::num::NonZeroU32;
175 mod c_long_definition {
177 if #[cfg(all(target_pointer_width = "64", not(windows)))] {
178 pub type c_long = i64;
179 pub type NonZero_c_long = crate::num::NonZeroI64;
180 pub type c_ulong = u64;
181 pub type NonZero_c_ulong = crate::num::NonZeroU64;
183 // The minimal size of `long` in the C standard is 32 bits
184 pub type c_long = i32;
185 pub type NonZero_c_long = crate::num::NonZeroI32;
186 pub type c_ulong = u32;
187 pub type NonZero_c_ulong = crate::num::NonZeroU32;
192 // N.B., for LLVM to recognize the void pointer type and by extension
193 // functions like malloc(), we need to have it represented as i8* in
194 // LLVM bitcode. The enum used here ensures this and prevents misuse
195 // of the "raw" type by only having private variants. We need two
196 // variants, because the compiler complains about the repr attribute
197 // otherwise and we need at least one variant as otherwise the enum
198 // would be uninhabited and at least dereferencing such pointers would
200 #[doc = include_str!("c_void.md")]
202 #[stable(feature = "core_c_void", since = "1.30.0")]
205 feature = "c_void_variant",
206 reason = "temporary implementation detail",
212 feature = "c_void_variant",
213 reason = "temporary implementation detail",
220 #[stable(feature = "std_debug", since = "1.16.0")]
221 impl fmt::Debug for c_void {
222 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
223 f.debug_struct("c_void").finish()
227 /// Basic implementation of a `va_list`.
228 // The name is WIP, using `VaListImpl` for now.
231 not(target_arch = "aarch64"),
232 not(target_arch = "powerpc"),
233 not(target_arch = "s390x"),
234 not(target_arch = "x86_64")
236 all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
237 target_family = "wasm",
238 target_arch = "asmjs",
244 feature = "c_variadic",
245 reason = "the `c_variadic` feature has not been properly tested on \
246 all supported platforms",
250 pub struct VaListImpl<'f> {
253 // Invariant over `'f`, so each `VaListImpl<'f>` object is tied to
254 // the region of the function it's defined in
255 _marker: PhantomData<&'f mut &'f c_void>,
260 not(target_arch = "aarch64"),
261 not(target_arch = "powerpc"),
262 not(target_arch = "s390x"),
263 not(target_arch = "x86_64")
265 all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
266 target_family = "wasm",
267 target_arch = "asmjs",
272 feature = "c_variadic",
273 reason = "the `c_variadic` feature has not been properly tested on \
274 all supported platforms",
277 impl<'f> fmt::Debug for VaListImpl<'f> {
278 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
279 write!(f, "va_list* {:p}", self.ptr)
283 /// AArch64 ABI implementation of a `va_list`. See the
284 /// [AArch64 Procedure Call Standard] for more details.
286 /// [AArch64 Procedure Call Standard]:
287 /// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
289 target_arch = "aarch64",
290 not(any(target_os = "macos", target_os = "ios")),
291 not(target_os = "uefi"),
297 feature = "c_variadic",
298 reason = "the `c_variadic` feature has not been properly tested on \
299 all supported platforms",
303 pub struct VaListImpl<'f> {
309 _marker: PhantomData<&'f mut &'f c_void>,
312 /// PowerPC ABI implementation of a `va_list`.
313 #[cfg(all(target_arch = "powerpc", not(target_os = "uefi"), not(windows)))]
317 feature = "c_variadic",
318 reason = "the `c_variadic` feature has not been properly tested on \
319 all supported platforms",
323 pub struct VaListImpl<'f> {
327 overflow_arg_area: *mut c_void,
328 reg_save_area: *mut c_void,
329 _marker: PhantomData<&'f mut &'f c_void>,
332 /// s390x ABI implementation of a `va_list`.
333 #[cfg(target_arch = "s390x")]
337 feature = "c_variadic",
338 reason = "the `c_variadic` feature has not been properly tested on \
339 all supported platforms",
343 pub struct VaListImpl<'f> {
346 overflow_arg_area: *mut c_void,
347 reg_save_area: *mut c_void,
348 _marker: PhantomData<&'f mut &'f c_void>,
351 /// x86_64 ABI implementation of a `va_list`.
352 #[cfg(all(target_arch = "x86_64", not(target_os = "uefi"), not(windows)))]
356 feature = "c_variadic",
357 reason = "the `c_variadic` feature has not been properly tested on \
358 all supported platforms",
362 pub struct VaListImpl<'f> {
365 overflow_arg_area: *mut c_void,
366 reg_save_area: *mut c_void,
367 _marker: PhantomData<&'f mut &'f c_void>,
370 /// A wrapper for a `va_list`
374 feature = "c_variadic",
375 reason = "the `c_variadic` feature has not been properly tested on \
376 all supported platforms",
379 pub struct VaList<'a, 'f: 'a> {
382 not(target_arch = "aarch64"),
383 not(target_arch = "powerpc"),
384 not(target_arch = "s390x"),
385 not(target_arch = "x86_64")
387 all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
388 target_family = "wasm",
389 target_arch = "asmjs",
393 inner: VaListImpl<'f>,
397 target_arch = "aarch64",
398 target_arch = "powerpc",
399 target_arch = "s390x",
400 target_arch = "x86_64"
402 any(not(target_arch = "aarch64"), not(any(target_os = "macos", target_os = "ios"))),
403 not(target_family = "wasm"),
404 not(target_arch = "asmjs"),
405 not(target_os = "uefi"),
408 inner: &'a mut VaListImpl<'f>,
410 _marker: PhantomData<&'a mut VaListImpl<'f>>,
415 not(target_arch = "aarch64"),
416 not(target_arch = "powerpc"),
417 not(target_arch = "s390x"),
418 not(target_arch = "x86_64")
420 all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
421 target_family = "wasm",
422 target_arch = "asmjs",
427 feature = "c_variadic",
428 reason = "the `c_variadic` feature has not been properly tested on \
429 all supported platforms",
432 impl<'f> VaListImpl<'f> {
433 /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
435 pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
436 VaList { inner: VaListImpl { ..*self }, _marker: PhantomData }
442 target_arch = "aarch64",
443 target_arch = "powerpc",
444 target_arch = "s390x",
445 target_arch = "x86_64"
447 any(not(target_arch = "aarch64"), not(any(target_os = "macos", target_os = "ios"))),
448 not(target_family = "wasm"),
449 not(target_arch = "asmjs"),
450 not(target_os = "uefi"),
454 feature = "c_variadic",
455 reason = "the `c_variadic` feature has not been properly tested on \
456 all supported platforms",
459 impl<'f> VaListImpl<'f> {
460 /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
462 pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
463 VaList { inner: self, _marker: PhantomData }
468 feature = "c_variadic",
469 reason = "the `c_variadic` feature has not been properly tested on \
470 all supported platforms",
473 impl<'a, 'f: 'a> Deref for VaList<'a, 'f> {
474 type Target = VaListImpl<'f>;
477 fn deref(&self) -> &VaListImpl<'f> {
483 feature = "c_variadic",
484 reason = "the `c_variadic` feature has not been properly tested on \
485 all supported platforms",
488 impl<'a, 'f: 'a> DerefMut for VaList<'a, 'f> {
490 fn deref_mut(&mut self) -> &mut VaListImpl<'f> {
495 // The VaArgSafe trait needs to be used in public interfaces, however, the trait
496 // itself must not be allowed to be used outside this module. Allowing users to
497 // implement the trait for a new type (thereby allowing the va_arg intrinsic to
498 // be used on a new type) is likely to cause undefined behavior.
500 // FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface
501 // but also ensure it cannot be used elsewhere, the trait needs to be public
502 // within a private module. Once RFC 2145 has been implemented look into
505 /// Trait which permits the allowed types to be used with [super::VaListImpl::arg].
507 feature = "c_variadic",
508 reason = "the `c_variadic` feature has not been properly tested on \
509 all supported platforms",
512 pub trait VaArgSafe {}
515 macro_rules! impl_va_arg_safe {
518 #[unstable(feature = "c_variadic",
519 reason = "the `c_variadic` feature has not been properly tested on \
520 all supported platforms",
522 impl sealed_trait::VaArgSafe for $t {}
527 impl_va_arg_safe! {i8, i16, i32, i64, usize}
528 impl_va_arg_safe! {u8, u16, u32, u64, isize}
529 impl_va_arg_safe! {f64}
532 feature = "c_variadic",
533 reason = "the `c_variadic` feature has not been properly tested on \
534 all supported platforms",
537 impl<T> sealed_trait::VaArgSafe for *mut T {}
539 feature = "c_variadic",
540 reason = "the `c_variadic` feature has not been properly tested on \
541 all supported platforms",
544 impl<T> sealed_trait::VaArgSafe for *const T {}
547 feature = "c_variadic",
548 reason = "the `c_variadic` feature has not been properly tested on \
549 all supported platforms",
552 impl<'f> VaListImpl<'f> {
553 /// Advance to the next arg.
555 pub unsafe fn arg<T: sealed_trait::VaArgSafe>(&mut self) -> T {
556 // SAFETY: the caller must uphold the safety contract for `va_arg`.
557 unsafe { va_arg(self) }
560 /// Copies the `va_list` at the current location.
561 pub unsafe fn with_copy<F, R>(&self, f: F) -> R
563 F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R,
565 let mut ap = self.clone();
566 let ret = f(ap.as_va_list());
567 // SAFETY: the caller must uphold the safety contract for `va_end`.
576 feature = "c_variadic",
577 reason = "the `c_variadic` feature has not been properly tested on \
578 all supported platforms",
581 impl<'f> Clone for VaListImpl<'f> {
583 fn clone(&self) -> Self {
584 let mut dest = crate::mem::MaybeUninit::uninit();
585 // SAFETY: we write to the `MaybeUninit`, thus it is initialized and `assume_init` is legal
587 va_copy(dest.as_mut_ptr(), self);
594 feature = "c_variadic",
595 reason = "the `c_variadic` feature has not been properly tested on \
596 all supported platforms",
599 impl<'f> Drop for VaListImpl<'f> {
601 // FIXME: this should call `va_end`, but there's no clean way to
602 // guarantee that `drop` always gets inlined into its caller,
603 // so the `va_end` would get directly called from the same function as
604 // the corresponding `va_copy`. `man va_end` states that C requires this,
605 // and LLVM basically follows the C semantics, so we need to make sure
606 // that `va_end` is always called from the same function as `va_copy`.
607 // For more details, see https://github.com/rust-lang/rust/pull/59625
608 // and https://llvm.org/docs/LangRef.html#llvm-va-end-intrinsic.
610 // This works for now, since `va_end` is a no-op on all current LLVM targets.
614 extern "rust-intrinsic" {
615 /// Destroy the arglist `ap` after initialization with `va_start` or
617 fn va_end(ap: &mut VaListImpl<'_>);
619 /// Copies the current location of arglist `src` to the arglist `dst`.
620 fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);
622 /// Loads an argument of type `T` from the `va_list` `ap` and increment the
623 /// argument `ap` points to.
624 fn va_arg<T: sealed_trait::VaArgSafe>(ap: &mut VaListImpl<'_>) -> T;