hostname/
lib.rs

Help
1//! A crate with utilities to get and set the system's host name.
2//!
3//! ## Examples
4#![cfg_attr(
5    feature = "set",
6    doc = r#"
7Set and get the host name:
8```rust,no_run
9# use std::io;
10# use std::ffi::OsStr;
11# fn main() -> io::Result<()> {
12hostname::set("potato")?;
13let new_name = hostname::get()?;
14assert_eq!(new_name, OsStr::new("potato"));
15# Ok(())
16# }
17```
18"#
19)]
20#![cfg_attr(
21    not(feature = "set"),
22    doc = r#"
23Get the host name:
24```rust,no_run
25# use std::io;
26# use std::ffi::OsStr;
27# fn main() -> io::Result<()> {
28let name = hostname::get()?;
29println!("{:?}", name);
30# Ok(())
31# }
32```
33"#
34)]
35#![doc(html_root_url = "https://docs.rs/hostname/0.4.1")]
36#![deny(
37    unused,
38    unused_imports,
39    unused_features,
40    bare_trait_objects,
41    missing_debug_implementations,
42    missing_docs,
43    nonstandard_style,
44    dead_code,
45    deprecated,
46    rust_2018_idioms,
47    trivial_casts,
48    unused_import_braces,
49    unused_results
50)]
51#![cfg_attr(docsrs, feature(doc_cfg))]
52
53use cfg_if::cfg_if;
54
55#[cfg(feature = "set")]
56use std::ffi::OsStr;
57use std::ffi::OsString;
58use std::io;
59
60cfg_if! {
61    if #[cfg(any(unix, target_os = "redox"))] {
62        mod nix;
63        use crate::nix as sys;
64    } else if #[cfg(target_os = "windows")] {
65        mod windows;
66        use crate::windows as sys;
67    } else {
68        compile_error!("Unsupported target OS! Create an issue: https://github.com/svartalf/hostname/issues/new");
69    }
70}
71
72/// Return the system hostname.
73///
74/// ## Example
75///
76/// ```rust
77/// # use std::io;
78/// # fn main() -> io::Result<()> {
79/// let name = hostname::get()?;
80/// # Ok(())
81/// # }
82/// ```
83///
84/// ## Errors
85///
86/// If this function encounters any form of error, an error
87/// variant will be returned; in practice it is rare to be happen.
88pub fn get() -> io::Result<OsString> {
89    sys::get()
90}
91
92/// Set the system hostname.
93///
94/// This function is available only with `set` feature enabled (**disabled** by
95/// default).
96#[cfg_attr(
97    feature = "set",
98    doc = r#"
99## Example
100
101```rust,no_run
102# use std::io;
103# fn main() -> io::Result<()> {
104hostname::set("potato")?;
105# Ok(())
106# }
107```
108"#
109)]
110/// ## Errors
111///
112/// In order to set new hostname, caller might need
113/// to have the corresponding privilege
114/// (`CAP_SYS_ADMIN` capability for Linux, administrator privileges for Windows,
115/// and so on).\
116/// An error variant will be returned if this function
117/// will encounter a permission error or any other form of error.
118///
119/// ## Compatibility
120///
121/// * Will fail with a linkage error for Android API < 23 (see [#9](https://github.com/svartalf/hostname/issues/9#issuecomment-563991112))
122#[cfg(feature = "set")]
123#[cfg_attr(docsrs, doc(cfg(feature = "set")))]
124pub fn set<T>(hostname: T) -> io::Result<()>
125where
126    T: AsRef<OsStr>,
127{
128    sys::set(hostname.as_ref())
129}
hostname/lib.rs

hostname/
lib.rs
