//! 特定于平台的类型，由 C 定义。
//!
//! 通过 FFI 进行交互的代码几乎肯定会使用 C 提供的原始类型，而这些原始类型的定义不如 Rust 的原始类型好。
//! 该模块提供的类型将与 C 定义的类型匹配，以便与 C 交互的代码将引用正确的类型。
//!
//!
//!

#![stable(feature = "", since = "1.30.0")]
#![allow(non_camel_case_types)]

use crate::fmt;
use crate::marker::PhantomData;
use crate::num::*;
use crate::ops::{Deref, DerefMut};

#[stable(feature = "core_c_str", since = "1.64.0")]
pub use self::c_str::{CStr, FromBytesUntilNulError, FromBytesWithNulError};

mod c_str;

macro_rules! type_alias_no_nz {
    {
      $Docfile:tt, $Alias:ident = $Real:ty;
      $( $Cfg:tt )*
    } => {
        #[doc = include_str!($Docfile)]
        $( $Cfg )*
        #[stable(feature = "core_ffi_c", since = "1.64.0")]
        pub type $Alias = $Real;
    }
}

// 验证此文件的宏调用中的 NonZero 类型是否对应
//
//  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'
//
// NB 这不会检查主要的 c_* 类型是否正确。

macro_rules! type_alias {
    {
      $Docfile:tt, $Alias:ident = $Real:ty, $NZAlias:ident = $NZReal:ty;
      $( $Cfg:tt )*
    } => {
        type_alias_no_nz! { $Docfile, $Alias = $Real; $( $Cfg )* }

        #[doc = concat!("Type alias for `NonZero` version of [`", stringify!($Alias), "`]")]
        #[unstable(feature = "raw_os_nonzero", issue = "82363")]
        $( $Cfg )*
        pub type $NZAlias = $NZReal;
    }
}

type_alias! { "c_char.md", c_char = c_char_definition::c_char, NonZero_c_char = c_char_definition::NonZero_c_char;
// 使此类型别名显示为依赖于 cfg，这样 Clippy 就不会建议用 `0 as c_char` 替换为 `0_i8`/`0_u8`。
// 这个 #[cfg(all())] 可以被删除
// after the false positive in https://github.com/rust-lang/rust-clippy/issues/8093
// 是固定的。
#[cfg(all())]
#[doc(cfg(all()))] }

type_alias! { "c_schar.md", c_schar = i8, NonZero_c_schar = NonZeroI8; }
type_alias! { "c_uchar.md", c_uchar = u8, NonZero_c_uchar = NonZeroU8; }
type_alias! { "c_short.md", c_short = i16, NonZero_c_short = NonZeroI16; }
type_alias! { "c_ushort.md", c_ushort = u16, NonZero_c_ushort = NonZeroU16; }

type_alias! { "c_int.md", c_int = c_int_definition::c_int, NonZero_c_int = c_int_definition::NonZero_c_int;
#[doc(cfg(all()))] }
type_alias! { "c_uint.md", c_uint = c_int_definition::c_uint, NonZero_c_uint = c_int_definition::NonZero_c_uint;
#[doc(cfg(all()))] }

type_alias! { "c_long.md", c_long = c_long_definition::c_long, NonZero_c_long = c_long_definition::NonZero_c_long;
#[doc(cfg(all()))] }
type_alias! { "c_ulong.md", c_ulong = c_long_definition::c_ulong, NonZero_c_ulong = c_long_definition::NonZero_c_ulong;
#[doc(cfg(all()))] }

type_alias! { "c_longlong.md", c_longlong = i64, NonZero_c_longlong = NonZeroI64; }
type_alias! { "c_ulonglong.md", c_ulonglong = u64, NonZero_c_ulonglong = NonZeroU64; }

type_alias_no_nz! { "c_float.md", c_float = f32; }
type_alias_no_nz! { "c_double.md", c_double = f64; }

/// 相当于 C 的 `size_t` 类型，来自 `stddef.h` (或 `cstddef` for C++)。
///
/// 此类型当前始终为 [`usize`]，但在 future 中可能存在并非如此的平台。
///
#[unstable(feature = "c_size_t", issue = "88345")]
pub type c_size_t = usize;

/// 相当于 C 的 `ptrdiff_t` 类型，来自 `stddef.h` (或 C++ 的 `cstddef`)。
///
/// 此类型当前始终为 [`isize`]，但在 future 中可能存在并非如此的平台。
///
#[unstable(feature = "c_size_t", issue = "88345")]
pub type c_ptrdiff_t = isize;

/// 相当于 C 的 `ssize_t` (在 POSIX 上) 或 `SSIZE_T` 类型 (在 Windows 上)。
///
/// 此类型当前始终为 [`isize`]，但在 future 中可能存在并非如此的平台。
///
#[unstable(feature = "c_size_t", issue = "88345")]
pub type c_ssize_t = isize;

mod c_char_definition {
    cfg_if! {
        // 这些是 c_char 不带符号的目标。
        if #[cfg(any(
            all(
                target_os = "linux",
                any(
                    target_arch = "aarch64",
                    target_arch = "arm",
                    target_arch = "hexagon",
                    target_arch = "powerpc",
                    target_arch = "powerpc64",
                    target_arch = "s390x",
                    target_arch = "riscv64",
                    target_arch = "riscv32"
                )
            ),
            all(target_os = "android", any(target_arch = "aarch64", target_arch = "arm")),
            all(target_os = "l4re", target_arch = "x86_64"),
            all(
                any(target_os = "freebsd", target_os = "openbsd"),
                any(
                    target_arch = "aarch64",
                    target_arch = "arm",
                    target_arch = "powerpc",
                    target_arch = "powerpc64",
                    target_arch = "riscv64"
                )
            ),
            all(
                target_os = "netbsd",
                any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc")
            ),
            all(
                target_os = "vxworks",
                any(
                    target_arch = "aarch64",
                    target_arch = "arm",
                    target_arch = "powerpc64",
                    target_arch = "powerpc"
                )
            ),
            all(
                target_os = "fuchsia",
                any(target_arch = "aarch64", target_arch = "riscv64")
            ),
            all(target_os = "nto", target_arch = "aarch64"),
            target_os = "horizon"
        ))] {
            pub type c_char = u8;
            pub type NonZero_c_char = crate::num::NonZeroU8;
        } else {
            // 在每个其他目标上，c_char 都是带符号的。
            pub type c_char = i8;
            pub type NonZero_c_char = crate::num::NonZeroI8;
        }
    }
}

mod c_int_definition {
    cfg_if! {
        if #[cfg(any(target_arch = "avr", target_arch = "msp430"))] {
            pub type c_int = i16;
            pub type NonZero_c_int = crate::num::NonZeroI16;
            pub type c_uint = u16;
            pub type NonZero_c_uint = crate::num::NonZeroU16;
        } else {
            pub type c_int = i32;
            pub type NonZero_c_int = crate::num::NonZeroI32;
            pub type c_uint = u32;
            pub type NonZero_c_uint = crate::num::NonZeroU32;
        }
    }
}

mod c_long_definition {
    cfg_if! {
        if #[cfg(all(target_pointer_width = "64", not(windows)))] {
            pub type c_long = i64;
            pub type NonZero_c_long = crate::num::NonZeroI64;
            pub type c_ulong = u64;
            pub type NonZero_c_ulong = crate::num::NonZeroU64;
        } else {
            // C 标准中 `long` 的最小尺寸是 32 位
            pub type c_long = i32;
            pub type NonZero_c_long = crate::num::NonZeroI32;
            pub type c_ulong = u32;
            pub type NonZero_c_ulong = crate::num::NonZeroU32;
        }
    }
}

// 注意，为使 LLVM 能够识别空指针类型，并通过扩展函数 (如 malloc()) 来识别它，我们需要在 LLVM 位码中将其表示为 i8 *。
// 此处使用的枚举确保了这一点，并通过仅拥有私有变体来防止滥用 "raw" 类型。
// 我们需要两个变体，因为编译器会抱怨 repr 属性，并且我们至少需要一个变体，否则枚举将无人居住，并且至少解引用此类指针将是未定义的行为。
//
//
//
//
//
#[doc = include_str!("c_void.md")]
#[cfg_attr(not(bootstrap), lang = "c_void")]
#[cfg_attr(not(doc), repr(u8))] // work around https://github.com/rust-lang/rust/issues/90435
#[stable(feature = "core_c_void", since = "1.30.0")]
pub enum c_void {
    #[unstable(
        feature = "c_void_variant",
        reason = "temporary implementation detail",
        issue = "none"
    )]
    #[doc(hidden)]
    __variant1,
    #[unstable(
        feature = "c_void_variant",
        reason = "temporary implementation detail",
        issue = "none"
    )]
    #[doc(hidden)]
    __variant2,
}

#[stable(feature = "std_debug", since = "1.16.0")]
impl fmt::Debug for c_void {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("c_void").finish()
    }
}

/// `va_list` 的基本实现。
// 名称为 WIP，现在使用 `VaListImpl`。
#[cfg(any(
    all(
        not(target_arch = "aarch64"),
        not(target_arch = "powerpc"),
        not(target_arch = "s390x"),
        not(target_arch = "x86_64")
    ),
    all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
    target_family = "wasm",
    target_arch = "asmjs",
    target_os = "uefi",
    windows,
))]
#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
#[lang = "va_list"]
pub struct VaListImpl<'f> {
    ptr: *mut c_void,

    // 在 `'f` 上不变，因此每个 `VaListImpl<'f>` 对象都绑定到它在以下位置定义的函数的区域
    //
    _marker: PhantomData<&'f mut &'f c_void>,
}

#[cfg(any(
    all(
        not(target_arch = "aarch64"),
        not(target_arch = "powerpc"),
        not(target_arch = "s390x"),
        not(target_arch = "x86_64")
    ),
    all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
    target_family = "wasm",
    target_arch = "asmjs",
    target_os = "uefi",
    windows,
))]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> fmt::Debug for VaListImpl<'f> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "va_list* {:p}", self.ptr)
    }
}

/// `va_list` 的 AArch64 ABI 实现。
/// 有关更多详细信息，请参见 [AArch64 过程调用标准][AArch64 Procedure Call Standard]。
///
/// [AArch64 Procedure Call Standard]:
/// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
#[cfg(all(
    target_arch = "aarch64",
    not(any(target_os = "macos", target_os = "ios")),
    not(target_os = "uefi"),
    not(windows),
))]
#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
#[derive(Debug)]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
#[lang = "va_list"]
pub struct VaListImpl<'f> {
    stack: *mut c_void,
    gr_top: *mut c_void,
    vr_top: *mut c_void,
    gr_offs: i32,
    vr_offs: i32,
    _marker: PhantomData<&'f mut &'f c_void>,
}

/// `va_list` 的 PowerPC ABI 实现。
#[cfg(all(target_arch = "powerpc", not(target_os = "uefi"), not(windows)))]
#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
#[derive(Debug)]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
#[lang = "va_list"]
pub struct VaListImpl<'f> {
    gpr: u8,
    fpr: u8,
    reserved: u16,
    overflow_arg_area: *mut c_void,
    reg_save_area: *mut c_void,
    _marker: PhantomData<&'f mut &'f c_void>,
}

/// `va_list` 的 s390x ABI 实现。
#[cfg(target_arch = "s390x")]
#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
#[derive(Debug)]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
#[lang = "va_list"]
pub struct VaListImpl<'f> {
    gpr: i64,
    fpr: i64,
    overflow_arg_area: *mut c_void,
    reg_save_area: *mut c_void,
    _marker: PhantomData<&'f mut &'f c_void>,
}

/// `va_list` 的 x86_64 ABI 实现。
#[cfg(all(target_arch = "x86_64", not(target_os = "uefi"), not(windows)))]
#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401
#[derive(Debug)]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
#[lang = "va_list"]
pub struct VaListImpl<'f> {
    gp_offset: i32,
    fp_offset: i32,
    overflow_arg_area: *mut c_void,
    reg_save_area: *mut c_void,
    _marker: PhantomData<&'f mut &'f c_void>,
}

/// `va_list` 的包装
#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435
#[derive(Debug)]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
pub struct VaList<'a, 'f: 'a> {
    #[cfg(any(
        all(
            not(target_arch = "aarch64"),
            not(target_arch = "powerpc"),
            not(target_arch = "s390x"),
            not(target_arch = "x86_64")
        ),
        all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
        target_family = "wasm",
        target_arch = "asmjs",
        target_os = "uefi",
        windows,
    ))]
    inner: VaListImpl<'f>,

    #[cfg(all(
        any(
            target_arch = "aarch64",
            target_arch = "powerpc",
            target_arch = "s390x",
            target_arch = "x86_64"
        ),
        any(not(target_arch = "aarch64"), not(any(target_os = "macos", target_os = "ios"))),
        not(target_family = "wasm"),
        not(target_arch = "asmjs"),
        not(target_os = "uefi"),
        not(windows),
    ))]
    inner: &'a mut VaListImpl<'f>,

    _marker: PhantomData<&'a mut VaListImpl<'f>>,
}

#[cfg(any(
    all(
        not(target_arch = "aarch64"),
        not(target_arch = "powerpc"),
        not(target_arch = "s390x"),
        not(target_arch = "x86_64")
    ),
    all(target_arch = "aarch64", any(target_os = "macos", target_os = "ios")),
    target_family = "wasm",
    target_arch = "asmjs",
    target_os = "uefi",
    windows,
))]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> VaListImpl<'f> {
    /// 将 `VaListImpl` 转换为与 C 的 `va_list` 二进制兼容的 `VaList`。
    #[inline]
    pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
        VaList { inner: VaListImpl { ..*self }, _marker: PhantomData }
    }
}

#[cfg(all(
    any(
        target_arch = "aarch64",
        target_arch = "powerpc",
        target_arch = "s390x",
        target_arch = "x86_64"
    ),
    any(not(target_arch = "aarch64"), not(any(target_os = "macos", target_os = "ios"))),
    not(target_family = "wasm"),
    not(target_arch = "asmjs"),
    not(target_os = "uefi"),
    not(windows),
))]
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> VaListImpl<'f> {
    /// 将 `VaListImpl` 转换为与 C 的 `va_list` 二进制兼容的 `VaList`。
    #[inline]
    pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
        VaList { inner: self, _marker: PhantomData }
    }
}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'a, 'f: 'a> Deref for VaList<'a, 'f> {
    type Target = VaListImpl<'f>;

    #[inline]
    fn deref(&self) -> &VaListImpl<'f> {
        &self.inner
    }
}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'a, 'f: 'a> DerefMut for VaList<'a, 'f> {
    #[inline]
    fn deref_mut(&mut self) -> &mut VaListImpl<'f> {
        &mut self.inner
    }
}

// 必须在公共接口中使用 VaArgSafe trait，但是，不允许在该模块之外使用 trait 本身。
// 允许用户为新类型实现 trait (从而允许在新类型上使用 va_arg 内部函数) 可能会导致未定义的行为。
//
// FIXME(dlrobertson): 为了在公共接口中使用 VaArgSafe trait 并确保它不能在其他地方使用，trait 需要在私有模块中公开。
// RFC 2145 实现后，可以考虑对此进行改进。
//
//
//
//
mod sealed_trait {
    /// 一个允许将允许的类型与 [super::VaListImpl::arg] 一起使用的 trait。
    #[unstable(
        feature = "c_variadic",
        reason = "the `c_variadic` feature has not been properly tested on \
                  all supported platforms",
        issue = "44930"
    )]
    pub trait VaArgSafe {}
}

macro_rules! impl_va_arg_safe {
    ($($t:ty),+) => {
        $(
            #[unstable(feature = "c_variadic",
                       reason = "the `c_variadic` feature has not been properly tested on \
                                 all supported platforms",
                       issue = "44930")]
            impl sealed_trait::VaArgSafe for $t {}
        )+
    }
}

impl_va_arg_safe! {i8, i16, i32, i64, usize}
impl_va_arg_safe! {u8, u16, u32, u64, isize}
impl_va_arg_safe! {f64}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<T> sealed_trait::VaArgSafe for *mut T {}
#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<T> sealed_trait::VaArgSafe for *const T {}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> VaListImpl<'f> {
    /// 前进到下一个 arg。
    #[inline]
    pub unsafe fn arg<T: sealed_trait::VaArgSafe>(&mut self) -> T {
        // SAFETY: 调用者必须遵守 `va_arg` 的安全保证。
        unsafe { va_arg(self) }
    }

    /// 在当前位置复制 `va_list`。
    pub unsafe fn with_copy<F, R>(&self, f: F) -> R
    where
        F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R,
    {
        let mut ap = self.clone();
        let ret = f(ap.as_va_list());
        // SAFETY: 调用者必须遵守 `va_end` 的安全保证。
        unsafe {
            va_end(&mut ap);
        }
        ret
    }
}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> Clone for VaListImpl<'f> {
    #[inline]
    fn clone(&self) -> Self {
        let mut dest = crate::mem::MaybeUninit::uninit();
        // SAFETY: 我们写入 `MaybeUninit`，因此它被初始化并且 `assume_init` 是合法的
        unsafe {
            va_copy(dest.as_mut_ptr(), self);
            dest.assume_init()
        }
    }
}

#[unstable(
    feature = "c_variadic",
    reason = "the `c_variadic` feature has not been properly tested on \
              all supported platforms",
    issue = "44930"
)]
impl<'f> Drop for VaListImpl<'f> {
    fn drop(&mut self) {
        // FIXME: 这应该调用 `va_end`，但是没有干净的方法来保证 `drop` 总是内联到其调用程序中，因此 `va_end` 将直接从与相应 `va_copy` 相同的函数中调用。
        //
        // `man va_end` 声明 C 需要这个，而 LLVM 基本上遵循 C 语义，所以我们需要确保 `va_end` 总是从与 `va_copy` 相同的函数中调用。
        // 欲知更多详情，see https://github.com/rust-lang/rust/pull/59625andhttps://llvm.org/docs/LangRef.html#llvm-va-end-intrinsic。
        //
        // 由于 `va_end` 是当前所有 LLVM 目标上的无操作项，因此，该操作现在有效。
        //
        //
        //
        //
    }
}

extern "rust-intrinsic" {
    /// 用 `va_start` 或 `va_copy` 初始化后，销毁参数列表 `ap`。
    ///
    #[rustc_nounwind]
    fn va_end(ap: &mut VaListImpl<'_>);

    /// 将 arglist `src` 的当前位置复制到 arglist `dst`。
    #[rustc_nounwind]
    fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);

    /// 从 `va_list` `ap` 加载 `T` 类型的参数，并将 `ap` 指向的参数递增。
    ///
    #[rustc_nounwind]
    fn va_arg<T: sealed_trait::VaArgSafe>(ap: &mut VaListImpl<'_>) -> T;
}