whoami/
fallible.rs

1//! Fallible versions of the whoami APIs.
2//!
3//! Some of the functions in the root module will return "Unknown" or
4//! "localhost" on error.  This might not be desirable in some situations.  The
5//! functions in this module all return a [`Result`].
6
7use std::ffi::OsString;
8
9use crate::{
10    conversions,
11    os::{Os, Target},
12    Result,
13};
14
15/// Get the user's account name; usually just the username, but may include an
16/// account server hostname.
17///
18/// If you don't want the account server hostname, use [`username()`].
19///
20/// Example: `username@example.com`
21#[inline(always)]
22pub fn account() -> Result<String> {
23    account_os().and_then(conversions::string_from_os)
24}
25
26/// Get the user's account name; usually just the username, but may include an
27/// account server hostname.
28///
29/// If you don't want the account server hostname, use [`username()`].
30///
31/// Example: `username@example.com`
32#[inline(always)]
33pub fn account_os() -> Result<OsString> {
34    Target::account(Os)
35}
36
37/// Get the user's username.
38///
39/// On unix-systems this differs from [`realname()`] most notably in that spaces
40/// are not allowed in the username.
41#[inline(always)]
42pub fn username() -> Result<String> {
43    username_os().and_then(conversions::string_from_os)
44}
45
46/// Get the user's username.
47///
48/// On unix-systems this differs from [`realname_os()`] most notably in that
49/// spaces are not allowed in the username.
50#[inline(always)]
51pub fn username_os() -> Result<OsString> {
52    Target::username(Os)
53}
54
55/// Get the user's real (full) name.
56#[inline(always)]
57pub fn realname() -> Result<String> {
58    realname_os().and_then(conversions::string_from_os)
59}
60
61/// Get the user's real (full) name.
62#[inline(always)]
63pub fn realname_os() -> Result<OsString> {
64    Target::realname(Os)
65}
66
67/// Get the name of the operating system distribution and (possibly) version.
68///
69/// Example: "Windows 10" or "Fedora 26 (Workstation Edition)"
70#[inline(always)]
71pub fn distro() -> Result<String> {
72    Target::distro(Os)
73}
74
75/// Get the device name (also known as "Pretty Name").
76///
77/// Often used to identify device for bluetooth pairing.
78#[inline(always)]
79pub fn devicename() -> Result<String> {
80    devicename_os().and_then(conversions::string_from_os)
81}
82
83/// Get the device name (also known as "Pretty Name").
84///
85/// Often used to identify device for bluetooth pairing.
86#[inline(always)]
87pub fn devicename_os() -> Result<OsString> {
88    Target::devicename(Os)
89}
90
91/// Get the host device's hostname.
92///
93/// Limited to a-z, A-Z, 0-9, and dashes.  This limit also applies to
94/// [`devicename()`] when targeting Windows.  Usually hostnames are
95/// case-insensitive, but it's not a hard requirement.
96#[inline(always)]
97pub fn hostname() -> Result<String> {
98    Target::hostname(Os)
99}