hostname/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
//! A crate with utilities to get and set the system's host name.
//!
//! ## Examples
#![cfg_attr(
    feature = "set",
    doc = r#"
Set and get the host name:
```rust,no_run
# use std::io;
# use std::ffi::OsStr;
# fn main() -> io::Result<()> {
hostname::set("potato")?;
let new_name = hostname::get()?;
assert_eq!(new_name, OsStr::new("potato"));
# Ok(())
# }
```
"#
)]
#![cfg_attr(
    not(feature = "set"),
    doc = r#"
Get the host name:
```rust,no_run
# use std::io;
# use std::ffi::OsStr;
# fn main() -> io::Result<()> {
let name = hostname::get()?;
println!("{:?}", name);
# Ok(())
# }
```
"#
)]
#![doc(html_root_url = "https://docs.rs/hostname/0.4.0")]
#![deny(
    unused,
    unused_imports,
    unused_features,
    bare_trait_objects,
    missing_debug_implementations,
    missing_docs,
    nonstandard_style,
    dead_code,
    deprecated,
    rust_2018_idioms,
    trivial_casts,
    unused_import_braces,
    unused_results
)]
#![cfg_attr(docsrs, feature(doc_cfg))]

use cfg_if::cfg_if;

#[cfg(feature = "set")]
use std::ffi::OsStr;
use std::ffi::OsString;
use std::io;

cfg_if! {
    if #[cfg(any(unix, target_os = "redox"))] {
        mod nix;
        use crate::nix as sys;
    } else if #[cfg(target_os = "windows")] {
        mod windows;
        use crate::windows as sys;
    } else {
        compile_error!("Unsupported target OS! Create an issue: https://github.com/svartalf/hostname/issues/new");
    }
}

/// Return the system hostname.
///
/// ## Example
///
/// ```rust
/// # use std::io;
/// # fn main() -> io::Result<()> {
/// let name = hostname::get()?;
/// # Ok(())
/// # }
/// ```
///
/// ## Errors
///
/// If this function encounters any form of error, an error
/// variant will be returned; in practice it is rare to be happen.
pub fn get() -> io::Result<OsString> {
    sys::get()
}

/// Set the system hostname.
///
/// This function is available only with `set` feature enabled (**disabled** by
/// default).
#[cfg_attr(
    feature = "set",
    doc = r#"
## Example

```rust,no_run
# use std::io;
# fn main() -> io::Result<()> {
hostname::set("potato")?;
# Ok(())
# }
```
"#
)]
/// ## Errors
///
/// In order to set new hostname, caller might need
/// to have the corresponding privilege
/// (`CAP_SYS_ADMIN` capability for Linux, administrator privileges for Windows,
/// and so on).\
/// An error variant will be returned if this function
/// will encounter a permission error or any other form of error.
///
/// ## Compatibility
///
/// * Will fail with a linkage error for Android API < 23 (see [#9](https://github.com/svartalf/hostname/issues/9#issuecomment-563991112))
#[cfg(feature = "set")]
#[cfg_attr(docsrs, doc(cfg(feature = "set")))]
pub fn set<T>(hostname: T) -> io::Result<()>
where
    T: AsRef<OsStr>,
{
    sys::set(hostname.as_ref())
}