//! 检查和操作进程的环境。
//!
//! 该模块包含用于检查各个方面的函数，例如环境变量，进程参数，当前目录以及各种其他重要目录。
//!
//!
//! 该模块中有几个函数和结构体，它们的对应部分以 `os` 结尾。
//! 以 `os` 结尾的那些将返回 [`OsString`]，而没有以 `os` 结尾的那些将返回 [`String`]。
//!
//!

#![stable(feature = "env", since = "1.0.0")]

#[cfg(test)]
mod tests;

use crate::error::Error;
use crate::ffi::{OsStr, OsString};
use crate::fmt;
use crate::io;
use crate::path::{Path, PathBuf};
use crate::sys;
use crate::sys::os as os_imp;

/// 返回当前的工作目录为 [`PathBuf`]。
///
/// # Errors
///
/// 如果当前工作目录值无效，则返回 [`Err`]。
/// 可能的情况:
///
/// * 当前目录不存在。
/// * 没有足够的权限来访问当前目录。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// fn main() -> std::io::Result<()> {
///     let path = env::current_dir()?;
///     println!("The current directory is {}", path.display());
///     Ok(())
/// }
/// ```
#[stable(feature = "env", since = "1.0.0")]
pub fn current_dir() -> io::Result<PathBuf> {
    os_imp::getcwd()
}

/// 将当前工作目录更改为指定的路径。
///
/// 如果操作失败，则返回 [`Err`]。
///
/// # Examples
///
/// ```
/// use std::env;
/// use std::path::Path;
///
/// let root = Path::new("/");
/// assert!(env::set_current_dir(&root).is_ok());
/// println!("Successfully changed working directory to {}!", root.display());
/// ```
#[doc(alias = "chdir")]
#[stable(feature = "env", since = "1.0.0")]
pub fn set_current_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
    os_imp::chdir(path.as_ref())
}

/// 在此进程的环境变量的快照上进行迭代的迭代器。
///
/// 该结构体由 [`env::vars()`] 创建。有关更多信息，请参见其文档。
///
/// [`env::vars()`]: vars
#[stable(feature = "env", since = "1.0.0")]
pub struct Vars {
    inner: VarsOs,
}

/// 在此进程的环境变量的快照上进行迭代的迭代器。
///
/// 该结构体由 [`env::vars_os()`] 创建。有关更多信息，请参见其文档。
///
/// [`env::vars_os()`]: vars_os
#[stable(feature = "env", since = "1.0.0")]
pub struct VarsOs {
    inner: os_imp::Env,
}

/// 返回当前进程的所有环境变量的字符串 (变量，值) 对的迭代器。
///
///
/// 返回的迭代器包含此调用时进程环境变量的快照。
/// 之后对环境变量的修改将不会反映在返回的迭代器中。
///
/// # Panics
///
/// 进行迭代时，如果环境中的任何键或值不是有效的 unicode，则返回的迭代器将为 panic。
/// 如果不希望这样做，请考虑使用 [`env::vars_os()`]。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// // 我们将通过引用迭代到 env::vars () ; 返回的元素。
/////
/// for (key, value) in env::vars() {
///     println!("{}: {}", key, value);
/// }
/// ```
///
/// [`env::vars_os()`]: vars_os
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn vars() -> Vars {
    Vars { inner: vars_os() }
}

/// 对于当前进程的所有环境变量，返回 OS 字符串对 (变量，值) 对的迭代器。
///
///
/// 返回的迭代器包含此调用时进程环境变量的快照。
/// 之后对环境变量的修改将不会反映在返回的迭代器中。
///
/// 请注意，返回的迭代器不会检查环境变量是否为有效的 Unicode。
/// 如果您想在无效的 UTF-8 上使用 panic，请改用 [`vars`] 函数。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// // 我们将通过引用迭代到 env::vars_os () ; 返回的元素。
/////
/// for (key, value) in env::vars_os() {
///     println!("{:?}: {:?}", key, value);
/// }
/// ```
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn vars_os() -> VarsOs {
    VarsOs { inner: os_imp::env() }
}

#[stable(feature = "env", since = "1.0.0")]
impl Iterator for Vars {
    type Item = (String, String);
    fn next(&mut self) -> Option<(String, String)> {
        self.inner.next().map(|(a, b)| (a.into_string().unwrap(), b.into_string().unwrap()))
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

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

#[stable(feature = "env", since = "1.0.0")]
impl Iterator for VarsOs {
    type Item = (OsString, OsString);
    fn next(&mut self) -> Option<(OsString, OsString)> {
        self.inner.next()
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

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

/// 从当前进程中获取环境变量 `key`。
///
/// # Errors
///
/// 如果环境变量不存在，则会出错。
/// 如果环境变量不是有效的 Unicode，则会出错。如果不需要，请考虑使用 [`var_os`]。
///
/// # Panics
///
/// 如果 `key` 为空，包含 ASCII 等于 `'='` 或 NUL 字符 `'\0'` 或值包含 NUL 字符，则此函数可能为 panic。
///
///
/// # Examples
///
/// ```
/// use std::env;
///
/// let key = "HOME";
/// match env::var(key) {
///     Ok(val) => println!("{}: {:?}", key, val),
///     Err(e) => println!("couldn't interpret {}: {}", key, e),
/// }
/// ```
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn var<K: AsRef<OsStr>>(key: K) -> Result<String, VarError> {
    _var(key.as_ref())
}

fn _var(key: &OsStr) -> Result<String, VarError> {
    match var_os(key) {
        Some(s) => s.into_string().map_err(VarError::NotUnicode),
        None => Err(VarError::NotPresent),
    }
}

/// 从当前进程中获取环境变量 `key`，如果未设置该变量，则返回 [`None`]。
///
/// # Panics
///
/// 如果 `key` 为空，包含 ASCII 等于 `'='` 或 NUL 字符 `'\0'` 或值包含 NUL 字符，则此函数可能为 panic。
///
///
/// 请注意，该方法不会检查环境变量是否为有效的 Unicode。
/// 如果您想在无效的 UTF-8 上出错，请改用 [`var`] 函数。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// let key = "HOME";
/// match env::var_os(key) {
///     Some(val) => println!("{}: {:?}", key, val),
///     None => println!("{} is not defined in the environment.", key)
/// }
/// ```
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn var_os<K: AsRef<OsStr>>(key: K) -> Option<OsString> {
    _var_os(key.as_ref())
}

fn _var_os(key: &OsStr) -> Option<OsString> {
    os_imp::getenv(key)
        .unwrap_or_else(|e| panic!("failed to get environment variable `{:?}`: {}", key, e))
}

/// 与环境变量交互的操作的错误类型。
/// 可能是从 [`env::var()`] 返回的。
///
/// [`env::var()`]: var
#[derive(Debug, PartialEq, Eq, Clone)]
#[stable(feature = "env", since = "1.0.0")]
pub enum VarError {
    /// 当前进程的环境中不存在指定的环境变量。
    ///
    #[stable(feature = "env", since = "1.0.0")]
    NotPresent,

    /// 找到了指定的环境变量，但是它不包含有效的 unicode 数据。
    /// 找到的数据作为该成员的有效负载返回。
    ///
    #[stable(feature = "env", since = "1.0.0")]
    NotUnicode(#[stable(feature = "env", since = "1.0.0")] OsString),
}

#[stable(feature = "env", since = "1.0.0")]
impl fmt::Display for VarError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            VarError::NotPresent => write!(f, "environment variable not found"),
            VarError::NotUnicode(ref s) => {
                write!(f, "environment variable was not valid unicode: {:?}", s)
            }
        }
    }
}

#[stable(feature = "env", since = "1.0.0")]
impl Error for VarError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            VarError::NotPresent => "environment variable not found",
            VarError::NotUnicode(..) => "environment variable was not valid unicode",
        }
    }
}

/// 将当前正在运行的进程的环境变量 `k` 设置为值 `v`。
///
/// 请注意，虽然在 Rust 中对环境变量进行并发访问是安全的，但某些平台仅公开本质上不安全的非线程安全 API 来检查环境。
/// 因此，在审核对不安全的外部 FFI 函数的调用时，需要格外小心，以确保所有外部环境访问均与 Rust 中的访问正确同步。
///
///
/// 有关 Unix 上这种不安全性的讨论，请参见:
///
///  - [Austin Group Bugzilla](https://austingroupbugs.net/view.php?id=188)
///  - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
///
/// # Panics
///
/// 如果 `key` 为空，包含 ASCII 等于 `'='` 或 NUL 字符 `'\0'` 或值包含 NUL 字符，则此函数可能为 panic。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// let key = "KEY";
/// env::set_var(key, "VALUE");
/// assert_eq!(env::var(key), Ok("VALUE".to_string()));
/// ```
///
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(key: K, value: V) {
    _set_var(key.as_ref(), value.as_ref())
}

fn _set_var(key: &OsStr, value: &OsStr) {
    os_imp::setenv(key, value).unwrap_or_else(|e| {
        panic!("failed to set environment variable `{:?}` to `{:?}`: {}", key, value, e)
    })
}

/// 从当前正在运行的进程的环境中删除环境变量。
///
/// 请注意，虽然在 Rust 中对环境变量进行并发访问是安全的，但某些平台仅公开本质上不安全的非线程安全 API 来检查环境。
/// 因此，在审核对不安全的外部 FFI 函数的调用时，需要格外小心，以确保所有外部环境访问都与 Rust 中的访问正确同步。
///
///
/// 有关 Unix 上这种不安全性的讨论，请参见:
///
///  - [Austin Group Bugzilla](https://austingroupbugs.net/view.php?id=188)
///  - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
///
/// # Panics
///
/// 如果 `key` 为空，包含 ASCII 等于 `'='` 或 NUL 字符 `'\0'` 或值包含 NUL 字符，则此函数可能为 panic。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// let key = "KEY";
/// env::set_var(key, "VALUE");
/// assert_eq!(env::var(key), Ok("VALUE".to_string()));
///
/// env::remove_var(key);
/// assert!(env::var(key).is_err());
/// ```
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn remove_var<K: AsRef<OsStr>>(key: K) {
    _remove_var(key.as_ref())
}

fn _remove_var(key: &OsStr) {
    os_imp::unsetenv(key)
        .unwrap_or_else(|e| panic!("failed to remove environment variable `{:?}`: {}", key, e))
}

/// 一个迭代器，该迭代器根据特定于平台的约定将环境变量拆分为路径。
///
///
/// 迭代器元素类型为 [`PathBuf`]。
///
/// 该结构体由 [`env::split_paths()`] 创建。有关更多信息，请参见其文档。
///
/// [`env::split_paths()`]: split_paths
///
#[stable(feature = "env", since = "1.0.0")]
pub struct SplitPaths<'a> {
    inner: os_imp::SplitPaths<'a>,
}

/// 根据平台约定对 `PATH` 环境变量解析输入。
///
///
/// 返回 `unparsed` 中包含的路径上的迭代器。
/// 迭代器元素类型为 [`PathBuf`]。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// let key = "PATH";
/// match env::var_os(key) {
///     Some(paths) => {
///         for path in env::split_paths(&paths) {
///             println!("'{}'", path.display());
///         }
///     }
///     None => println!("{} is not defined in the environment.", key)
/// }
/// ```
#[stable(feature = "env", since = "1.0.0")]
pub fn split_paths<T: AsRef<OsStr> + ?Sized>(unparsed: &T) -> SplitPaths<'_> {
    SplitPaths { inner: os_imp::split_paths(unparsed.as_ref()) }
}

#[stable(feature = "env", since = "1.0.0")]
impl<'a> Iterator for SplitPaths<'a> {
    type Item = PathBuf;
    fn next(&mut self) -> Option<PathBuf> {
        self.inner.next()
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

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

/// `PATH` 变量上的操作的错误类型。
/// 可能是从 [`env::join_paths()`] 返回的。
///
/// [`env::join_paths()`]: join_paths
#[derive(Debug)]
#[stable(feature = "env", since = "1.0.0")]
pub struct JoinPathsError {
    inner: os_imp::JoinPathsError,
}

/// 为 `PATH` 环境变量适当地加入 [Path] 的集合。
///
/// # Errors
///
/// 如果输入 [Path] 之一包含用于构造 `PATH` 变量的无效字符 (Windows 上的双引号或 Unix 上的冒号)，则返回 [`Err`] (包含错误消息)。
///
///
/// # Examples
///
/// 在类似 Unix 的平台上的连接路径:
///
/// ```
/// use std::env;
/// use std::ffi::OsString;
/// use std::path::Path;
///
/// fn main() -> Result<(), env::JoinPathsError> {
/// # if cfg!(unix) {
///     let paths = [Path::new("/bin"), Path::new("/usr/bin")];
///     let path_os_string = env::join_paths(paths.iter())?;
///     assert_eq!(path_os_string, OsString::from("/bin:/usr/bin"));
/// # }
///     Ok(())
/// }
/// ```
///
/// 在类似 Unix 的平台上加入包含冒号的路径会导致错误:
///
/// ```
/// # if cfg!(unix) {
/// use std::env;
/// use std::path::Path;
///
/// let paths = [Path::new("/bin"), Path::new("/usr/bi:n")];
/// assert!(env::join_paths(paths.iter()).is_err());
/// # }
/// ```
///
/// 将 `env::join_paths()` 与 [`env::split_paths()`] 结合使用，可以将项附加到 `PATH` 环境变量中:
///
/// ```
/// use std::env;
/// use std::path::PathBuf;
///
/// fn main() -> Result<(), env::JoinPathsError> {
///     if let Some(path) = env::var_os("PATH") {
///         let mut paths = env::split_paths(&path).collect::<Vec<_>>();
///         paths.push(PathBuf::from("/home/xyz/bin"));
///         let new_path = env::join_paths(paths)?;
///         env::set_var("PATH", &new_path);
///     }
///
///     Ok(())
/// }
/// ```
///
/// [`env::split_paths()`]: split_paths
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn join_paths<I, T>(paths: I) -> Result<OsString, JoinPathsError>
where
    I: IntoIterator<Item = T>,
    T: AsRef<OsStr>,
{
    os_imp::join_paths(paths.into_iter()).map_err(|e| JoinPathsError { inner: e })
}

#[stable(feature = "env", since = "1.0.0")]
impl fmt::Display for JoinPathsError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.inner.fmt(f)
    }
}

#[stable(feature = "env", since = "1.0.0")]
impl Error for JoinPathsError {
    #[allow(deprecated, deprecated_in_future)]
    fn description(&self) -> &str {
        self.inner.description()
    }
}

/// 返回当前用户主目录的路径 (如果已知)。
///
/// # Unix
///
/// - 返回 'HOME' 环境变量的值 (如果已设置) (包括一个空字符串)。
/// - 否则，它将尝试通过使用当前用户的 UID 调用 `getpwuid_r` 函数来确定主目录。
/// 从 `getpwuid_r` 函数返回的空主目录字段被视为有效值。
/// - 如果当前用户在 /etc/passwd 文件中没有条目，则返回 `None`。
///
/// # Windows
///
/// - 返回 'HOME' 环境变量的值 (如果已设置) (包括一个空字符串)。
/// - 否则，返回 'USERPROFILE' 环境变量的值 (如果已设置) (包括一个空字符串)。
/// - 如果两者都不存在，则使用 [`GetUserProfileDirectory`][msdn] 返回路径。
///
/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya
///
/// # Examples
///
/// ```
/// use std::env;
///
/// match env::home_dir() {
///     Some(path) => println!("Your home directory, probably: {}", path.display()),
///     None => println!("Impossible to get your home dir!"),
/// }
/// ```
///
///
///
///
#[rustc_deprecated(
    since = "1.29.0",
    reason = "This function's behavior is unexpected and probably not what you want. \
              Consider using a crate from crates.io instead."
)]
#[stable(feature = "env", since = "1.0.0")]
pub fn home_dir() -> Option<PathBuf> {
    os_imp::home_dir()
}

/// 返回临时目录的路径。
///
/// 临时目录可以在用户之间共享，也可以在具有不同权限的进程之间共享; 因此，在临时目录中创建任何文件或目录都必须使用安全方法来创建唯一命名的文件。
///
/// 使用固定或可预测的名称创建文件或目录可能会导致 "insecure temporary file" 安全漏洞。
/// 考虑使用安全创建临时文件或目录的 crate。
///
/// # Unix
///
/// 返回 `TMPDIR` 环境变量的值 (如果已设置)，否则返回 `/tmp` (对于非 Android)。
/// 如果为 Android，则由于没有临时文件夹 (通常是按应用分配的)，它将返回 `/data/local/tmp`。
///
/// # Windows
///
/// 如果设置了环境变量，则按顺序返回 `TMP`，`TEMP`，`USERPROFILE` 的值，而不是空字符串。否则，`temp_dir` 返回 Windows 目录的路径。
/// 此行为与该函数在内部使用的 [`GetTempPath`][msdn] 相同。
///
/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppatha
///
/// ```no_run
/// use std::env;
///
/// fn main() {
///     let mut dir = env::temp_dir();
///     println!("Temporary directory: {}", dir.display());
/// }
/// ```
///
///
///
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn temp_dir() -> PathBuf {
    os_imp::temp_dir()
}

/// 返回当前正在运行的可执行文件的完整文件系统路径。
///
/// # 平台特定的行为
///
/// 如果可执行文件是通过符号链接调用的，则某些平台将返回符号链接的路径，而其他平台将返回符号链接目标的路径。
///
///
/// # Errors
///
/// 获取当前可执行文件的路径是特定于平台的操作，由于多种原因，该操作可能会失败。
/// 一些错误可能包括但不限于文件系统操作失败或常规 syscall 错误。
///
/// # Security
///
/// 此函数的输出不应在可能涉及安全性的任何情况下使用。例如:
///
/// ```
/// fn main() {
///     println!("{:?}", std::env::current_exe());
/// }
/// ```
///
/// 在 Linux 系统上，如果将其编译为 `foo`:
///
/// ```bash
/// $ rustc foo.rs
/// $ ./foo
/// Ok("/home/alex/foo")
/// ```
///
/// 然后您对该程序进行了硬链接:
///
/// ```bash
/// $ ln foo bar
/// ```
///
/// 运行它时，您将不会获得原始可执行文件的路径，而会获得硬链接的路径:
///
/// ```bash
/// $ ./bar
/// Ok("/home/alex/bar")
/// ```
///
/// 如果不正确使用 [lead to privilege escalation]，这种行为是已知的。
///
/// [lead to privilege escalation]: https://securityvulns.com/Wdocument183.html
///
/// # Examples
///
/// ```
/// use std::env;
///
/// match env::current_exe() {
///     Ok(exe_path) => println!("Path of this executable is: {}",
///                              exe_path.display()),
///     Err(e) => println!("failed to get current exe path: {}", e),
/// };
/// ```
///
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn current_exe() -> io::Result<PathBuf> {
    os_imp::current_exe()
}

/// 进程参数的迭代器，为每个参数产生 [`String`] 值。
///
/// 该结构体由 [`env::args()`] 创建。有关更多信息，请参见其文档。
///
/// 传统上，第一个元素是可执行文件的路径，但可以将其设置为任意文本，甚至可能不存在。
/// 这意味着出于安全目的，不应依赖此属性。
///
/// [`env::args()`]: args
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub struct Args {
    inner: ArgsOs,
}

/// 一个进程参数的迭代器，为每个参数产生 [`OsString`] 值。
///
/// 该结构体由 [`env::args_os()`] 创建。有关更多信息，请参见其文档。
///
/// 传统上，第一个元素是可执行文件的路径，但可以将其设置为任意文本，甚至可能不存在。
/// 这意味着出于安全目的，不应依赖此属性。
///
/// [`env::args_os()`]: args_os
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub struct ArgsOs {
    inner: sys::args::Args,
}

/// 返回此程序开始的参数 (通常通过命令行传递)。
///
/// 传统上，第一个元素是可执行文件的路径，但可以将其设置为任意文本，甚至可能不存在。
///
/// 这意味着出于安全目的，不应依赖此属性。
///
/// 在 Unix 系统上，shell 通常使用 glob 模式 (例如 `*` 和 `?`) 来扩展不带引号的参数。
/// 在 Windows 上，这没有完成，并且此类参数按原样传递。
///
/// 在 glibc Linux 系统上，可以通过在 `.init_array` 中放置一个函数来检索参数。
/// glibc 将 `argc`、`argv` 和 `envp` 作为非标准扩展传递给 `.init_array` 中的函数。
/// 这使得 `std::env::args` 甚至可以在 `cdylib` 或 `staticlib` 上工作，就像在 macOS 和 Windows 上一样。
///
/// # Panics
///
/// 如果进程的任何参数不是有效的 Unicode，则返回的迭代器将在迭代期间 panic。
/// 如果不希望这样做，请改用 [`args_os`] 函数。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// // 在单独的行上打印每个参数
/// for argument in env::args() {
///     println!("{}", argument);
/// }
/// ```
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn args() -> Args {
    Args { inner: args_os() }
}

/// 返回此程序开始的参数 (通常通过命令行传递)。
///
/// 传统上，第一个元素是可执行文件的路径，但可以将其设置为任意文本，甚至可能不存在。
///
/// 这意味着出于安全目的，不应依赖此属性。
///
/// 在 Unix 系统上，shell 通常使用 glob 模式 (例如 `*` 和 `?`) 来扩展不带引号的参数。
/// 在 Windows 上，这没有完成，并且此类参数按原样传递。
///
/// 在 glibc Linux 系统上，可以通过在 `.init_array` 中放置一个函数来检索参数。
/// glibc 将 `argc`、`argv` 和 `envp` 作为非标准扩展传递给 `.init_array` 中的函数。
/// 这使得 `std::env::args_os` 甚至可以在 `cdylib` 或 `staticlib` 中工作，就像在 macOS 和 Windows 上一样。
///
/// 请注意，返回的迭代器不会检查进程的参数是否为有效的 Unicode。
/// 如果您想在无效的 UTF-8 上使用 panic，请改用 [`args`] 函数。
///
/// # Examples
///
/// ```
/// use std::env;
///
/// // 在单独的行上打印每个参数
/// for argument in env::args_os() {
///     println!("{:?}", argument);
/// }
/// ```
///
///
///
///
#[stable(feature = "env", since = "1.0.0")]
pub fn args_os() -> ArgsOs {
    ArgsOs { inner: sys::args::args() }
}

#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")]
impl !Send for Args {}

#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")]
impl !Sync for Args {}

#[stable(feature = "env", since = "1.0.0")]
impl Iterator for Args {
    type Item = String;
    fn next(&mut self) -> Option<String> {
        self.inner.next().map(|s| s.into_string().unwrap())
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

#[stable(feature = "env", since = "1.0.0")]
impl ExactSizeIterator for Args {
    fn len(&self) -> usize {
        self.inner.len()
    }
    fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }
}

#[stable(feature = "env_iterators", since = "1.12.0")]
impl DoubleEndedIterator for Args {
    fn next_back(&mut self) -> Option<String> {
        self.inner.next_back().map(|s| s.into_string().unwrap())
    }
}

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

#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")]
impl !Send for ArgsOs {}

#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")]
impl !Sync for ArgsOs {}

#[stable(feature = "env", since = "1.0.0")]
impl Iterator for ArgsOs {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        self.inner.next()
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

#[stable(feature = "env", since = "1.0.0")]
impl ExactSizeIterator for ArgsOs {
    fn len(&self) -> usize {
        self.inner.len()
    }
    fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }
}

#[stable(feature = "env_iterators", since = "1.12.0")]
impl DoubleEndedIterator for ArgsOs {
    fn next_back(&mut self) -> Option<OsString> {
        self.inner.next_back()
    }
}

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

/// 与当前目标关联的常量
#[stable(feature = "env", since = "1.0.0")]
pub mod consts {
    use crate::sys::env::os;

    /// 一个字符串，描述当前正在使用的 CPU 的体系结构。
    ///
    ///
    /// 一些可能的值:
    ///
    /// - x86
    /// - x86_64
    /// - arm
    /// - aarch64
    /// - mips
    /// - mips64
    /// - powerpc
    /// - powerpc64
    /// - riscv64
    /// - s390x
    /// - sparc64
    #[stable(feature = "env", since = "1.0.0")]
    pub const ARCH: &str = env!("STD_ENV_ARCH");

    /// 操作系统的家族。示例值为 `unix`。
    ///
    /// 一些可能的值:
    ///
    /// - unix
    /// - windows
    #[stable(feature = "env", since = "1.0.0")]
    pub const FAMILY: &str = os::FAMILY;

    /// 描述正在使用的特定操作系统的字符串。
    /// 示例值为 `linux`。
    ///
    /// 一些可能的值:
    ///
    /// - linux
    /// - macos
    /// - ios
    /// - freebsd
    /// - dragonfly
    /// - netbsd
    /// - openbsd
    /// - solaris
    /// - android
    /// - windows
    #[stable(feature = "env", since = "1.0.0")]
    pub const OS: &str = os::OS;

    /// 指定用于此平台上的共享库的文件名前缀。
    /// 示例值为 `lib`。
    ///
    /// 一些可能的值:
    ///
    /// - lib
    /// - `""` (一个空字符串)
    #[stable(feature = "env", since = "1.0.0")]
    pub const DLL_PREFIX: &str = os::DLL_PREFIX;

    /// 指定此平台上共享库使用的文件名后缀。
    /// 示例值为 `.so`。
    ///
    /// 一些可能的值:
    ///
    /// - .so
    /// - .dylib
    /// - .dll
    #[stable(feature = "env", since = "1.0.0")]
    pub const DLL_SUFFIX: &str = os::DLL_SUFFIX;

    /// 指定此平台上共享库所用的文件扩展名，该扩展名位于点后。
    /// 示例值为 `so`。
    ///
    /// 一些可能的值:
    ///
    /// - so
    /// - dylib
    /// - dll
    #[stable(feature = "env", since = "1.0.0")]
    pub const DLL_EXTENSION: &str = os::DLL_EXTENSION;

    /// 指定用于此平台上的可执行二进制文件的文件名后缀。
    /// 示例值为 `.exe`。
    ///
    /// 一些可能的值:
    ///
    /// - .exe
    /// - .nexe
    /// - .pexe
    /// - `""` (一个空字符串)
    #[stable(feature = "env", since = "1.0.0")]
    pub const EXE_SUFFIX: &str = os::EXE_SUFFIX;

    /// 指定用于此平台上的可执行二进制文件的文件扩展名 (如果有)。
    /// 示例值为 `exe`。
    ///
    /// 一些可能的值:
    ///
    /// - exe
    /// - `""` (一个空字符串)
    #[stable(feature = "env", since = "1.0.0")]
    pub const EXE_EXTENSION: &str = os::EXE_EXTENSION;
}