platform_info/
lib.rs

1// This file is part of the uutils coreutils package.
2//
3// (c) Alex Lyon <arcterus@mail.com>
4//
5// For the full copyright and license information, please view the LICENSE file
6// that was distributed with this source code.
7
8// spell-checker:ignore (abbrev/names) MSVC POSIX (names) rivy (rust) rustdoc RUSTDOCFLAGS
9
10// Documentation
11// See <https://docs.rs/platform-info> or <https://docs.rs/crate/platform-info>.
12// Use `cargo doc --no-deps --open --target=i686-pc-windows-msvc` to view WinOS documentation for this crate.
13// Use `cargo doc --no-deps --open --target=i686-unknown-linux-gnu` to view POSIX documentation for this crate.
14// * note: `cargo rustdoc` is equivalent to `cargo doc --no-deps` and is what `docs.rs` uses to generate documentation.
15// * ref: <https://users.rust-lang.org/t/docs-rs-does-not-show-my-documentation/70414/4> @@ <https://archive.is/W0N8W>
16
17// Enable documentation warnings for missing documentation (for public items) and broken intra-doc links.
18// * note: CI documentation linting has all warnings escalated to errors (using `RUSTDOCFLAGS="--deny warnings" cargo doc`)
19#![warn(missing_docs)]
20#![warn(rustdoc::broken_intra_doc_links)]
21#![doc = include_str!("../README.md")]
22// spell-checker:ignore (API) nodename osname sysname
23// spell-checker:ignore (uutils) coreutils uutils
24#![warn(unsafe_op_in_unsafe_fn)] // require explicit unsafe blocks inside unsafe fns
25#![warn(unused_results)] // enable warnings for unused results
26
27use std::ffi::OsStr;
28
29mod lib_impl;
30
31//===
32
33// PlatformInfo
34// Handles initial retrieval and holds cached information for the current platform.
35pub use lib_impl::PlatformInfo;
36#[cfg(unix)]
37pub use lib_impl::UTSName;
38#[cfg(windows)]
39pub use lib_impl::{WinApiSystemInfo, WinOsVersionInfo};
40
41// PlatformInfoError
42/// The common error type for [`PlatformInfoAPI`].
43pub use lib_impl::BoxedThreadSafeStdError as PlatformInfoError;
44
45// PlatformInfoAPI
46/// Defines the full API for [`PlatformInfo`].
47// * includes `UNameAPI`
48pub trait PlatformInfoAPI: UNameAPI {
49    /// Creates a new instance of [`PlatformInfo`].
50    /// <br> On some platforms, it is possible for this function to fail.
51    fn new() -> Result<Self, PlatformInfoError>
52    where
53        Self: Sized;
54}
55
56// UNameAPI
57/// Defines a trait API providing `uname` (aka "Unix name") style platform information.
58// ref: <https://www.gnu.org/software/libc/manual/html_node/Platform-Type.html> @@ <https://archive.is/YjjWJ>
59pub trait UNameAPI {
60    /// The name of this implementation of the operating system.
61    fn sysname(&self) -> &OsStr;
62
63    /// The node name (network node hostname) of this machine.
64    fn nodename(&self) -> &OsStr;
65
66    /// The current release level of the operating system.
67    fn release(&self) -> &OsStr;
68
69    /// The current version level of the current release.
70    fn version(&self) -> &OsStr;
71
72    /// The name of the current system's hardware.
73    fn machine(&self) -> &OsStr;
74
75    /// The processor type (architecture) of the current system.
76    ///
77    /// Maps machine architecture strings to GNU coreutils-compatible processor types.
78    /// For example, "arm64" may map to "arm", "x86_64" to "x86_64", etc.
79    /// This provides more semantically meaningful processor information than the
80    /// raw machine string in some contexts.
81    fn processor(&self) -> &OsStr;
82
83    /// The name of the current OS.
84    fn osname(&self) -> &OsStr;
85}
platform_info/lib.rs

platform_info/
lib.rs
