hostname

hostname is a minimal Rust crate that wraps the platform-specific system calls for reading and setting a machine’s host name behind a single cross-platform API: hostname::get() and, behind an opt-in set feature, hostname::set(). On POSIX-compliant systems (Linux, macOS, Android, the BSDs, Solaris, Redox) it binds directly to libc’s gethostname/sethostname, while on Windows it uses the Win32 networking APIs via generated bindings — all exposed to callers as plain OsString/&OsStr values with standard io::Result error handling, so application code never needs #[cfg(...)] branches for the platform it’s running on.

The crate is intentionally tiny: two implementation modules (nix.rs for POSIX, windows/ for Win32) selected at compile time via cfg_if, with only libc (Unix) or windows-link (Windows) as platform-conditional dependencies and no dependencies at all on the shared code path. Its 179M+ total crates.io downloads make it one of the standard building blocks other Rust libraries and CLI tools reach for whenever they need the local machine’s hostname without hand-rolling FFI bindings per platform.

What You Get

• hostname::get() — returns the system hostname as an OsString, working identically across POSIX systems and Windows
• hostname::set() — an opt-in function (behind the set Cargo feature) for changing the system hostname, gated separately since it typically requires elevated privileges
• Platform dispatch handled entirely at compile time via cfg_if, so consumers link only the implementation relevant to their target (libc on Unix, windows-link bindings on Windows)
• Standard std::io::Result error handling matching the rest of the Rust standard library’s I/O conventions, rather than a bespoke error type
• A deliberately minimal dependency footprint — no dependencies at all on the default feature path beyond the platform-conditional libc/windows-link crates

Common Use Cases

• CLI tools and system utilities that need to display or log the machine’s hostname without writing per-platform FFI code
• Distributed systems and services that use the local hostname as a node identifier or for service-discovery registration
• Diagnostic and telemetry tooling that tags logs/metrics with the originating host’s name
• Configuration management or provisioning scripts written in Rust that need to set a machine’s hostname during setup

Under The Hood

Architecture — The crate is a thin FFI wrapper split into exactly two backend modules selected at compile time: src/nix.rs calls libc’s gethostname/sethostname directly for POSIX-compliant targets (detected via cfg(any(unix, target_os = "redox"))), and src/windows/ (mod.rs plus generated bindings.rs) calls the equivalent Win32 networking APIs; src/lib.rs re-exports whichever backend matches the compile target via the cfg_if macro, so the public API surface (get/set) is identical regardless of platform. Tech Stack — Rust 2021 edition, MSRV 1.74, with libc as the sole Unix-side dependency and windows-link for Windows bindings (generated with windows-bindgen as a dev-dependency); the crate has effectively zero cross-platform dependencies, keeping compile times and supply-chain surface minimal. Code Quality — lib.rs opens with an aggressive #![deny(...)] lint list (missing docs, dead code, deprecated APIs, non-standard style, unused results, and more), and the crate is tested with similar-asserts plus version-sync to keep README/Cargo.toml version references in sync automatically; the implementation is small enough (four source files total) that the lint strictness substitutes effectively for a large test suite. API Design — The entire public API is two functions (get, set) with the set variant deliberately feature-gated off by default since changing a hostname is a privileged, rarely-needed operation — this keeps the common read-only case (the vast majority of consumers) free of unnecessary capability exposure while still making the write path available to those who opt in.