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

hostname/
lib.rs
