Homedir

https://docs.rs/homedir/0.3.6/homedir/
Admin
Homedir is a Rust crate that provides a portable, cross-platform method to retrieve the home...
Tokens:4,134
Snippets:43
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Usage of my_home

Source: https://docs.rs/homedir/0.3.6/homedir/unix/fn.my_home.html

Demonstrates retrieving the home directory when the HOME environment variable is set.

```rust
use homedir::unix::my_home;

// This assumes that the HOME environment variable is set to "/home/jpetersen".
assert_eq!(
    std::path::Path::new("/home/jpetersen"),
    my_home()?.unwrap().as_path()
);
```

--------------------------------

### Retrieve a user's home directory

Source: https://docs.rs/homedir/0.3.6/homedir/unix/fn.home.html

Demonstrates how to use the home function to look up a user's home directory and handle cases where the user does not exist.

```rust
use homedir::unix::home;
use std::path::PathBuf;

// This assumes there is a user named `root` which has
// `/root` as a home directory.
assert_eq!(
    Some(PathBuf::from("/root".to_owned())),
    home("root")?
);
assert!(home("nonexistentuser")?.is_none());
```

--------------------------------

### pub fn my_home() -> Result<Option<PathBuf>, GetHomeError>

Source: https://docs.rs/homedir/0.3.6/homedir/unix/fn.my_home.html

Retrieves the home directory path for the current process user. It prioritizes the $HOME environment variable before checking /etc/passwd.

```APIDOC
## Function: my_home

### Description
Get this process’ user’s home directory path. This function will first check the $HOME environment variable. If this variable does not exist, then the /etc/passwd file is checked.

### Signature
`pub fn my_home() -> Result<Option<PathBuf>, GetHomeError>`

### Returns
- **Result<Option<PathBuf>, GetHomeError>** - Returns the path to the home directory if found, None if the user entry is missing, or a GetHomeError if an error occurs during lookup.

### Example
```rust
use homedir::unix::my_home;

// This assumes that the HOME environment variable is set to "/home/jpetersen".
assert_eq!(
    std::path::Path::new("/home/jpetersen"),
    my_home()?.unwrap().as_path()
);
```
```

--------------------------------

### pub fn home<S: AsRef<str>>(username: S) -> Result<Option<PathBuf>, GetHomeError>

Source: https://docs.rs/homedir/0.3.6/homedir/fn.home.html

Retrieves the home directory of an arbitrary user. Returns Ok(None) if the user is not found, or an Err variant if an error occurs during the lookup.

```APIDOC
## Function: home

### Description
Get the home directory of an arbitrary user. This will return the `Err` variant if an error occurs. If no user with the given username can be found, `Ok(None)` is returned instead.

### Signature
`pub fn home<S: AsRef<str>>(username: S) -> Result<Option<PathBuf>, GetHomeError>`

### Parameters
- **username** (S: AsRef<str>) - Required - The username of the user whose home directory is being requested.
```

--------------------------------

### Retrieve Home Directory from UserIdentifier

Source: https://docs.rs/homedir/0.3.6/homedir/unix/struct.UserIdentifier.html

Demonstrates how to convert a UserIdentifier derived from a UID into a home directory path on Unix systems.

```rust
use homedir::unix::UserIdentifier;
use nix::unistd::Uid;
use std::path::PathBuf;

// This only works on Unix systems, and assumes that the root user's home
// directory is located at /root.
assert_eq!(
    Some(PathBuf::from("/root".to_owned())),
    // See nix::unistd::Uid::from_raw
    UserIdentifier::from(Uid::from_raw(0)).to_home()?,
);
```

--------------------------------

### Set and Verify Errno

Source: https://docs.rs/homedir/0.3.6/homedir/unix/type.GetHomeError.html

Demonstrates setting a specific errno value and verifying it using the last() method.

```rust
use nix::errno::Errno;

Errno::EIO.set();

assert_eq!(Errno::last(), Errno::EIO);
```

--------------------------------

### Retrieve Home Directory for a User

Source: https://docs.rs/homedir/0.3.6/homedir/struct.UserIdentifier.html

Demonstrates how to obtain a UserIdentifier for a specific username and resolve its home directory path.

```rust
use homedir::UserIdentifier;

if let Some(identifier) = UserIdentifier::with_username("Administrator")? {
    println!("{:?}", identifier.to_home()?);
}
```

--------------------------------

### Add homedir dependency

Source: https://docs.rs/homedir/0.3.6/homedir/index.html

Add the crate to your project dependencies in Cargo.toml.

```toml
[dependencies]
homedir = "0.3.6"
```

--------------------------------

### my_home() -> Result<PathBuf, GetHomeError>

Source: https://docs.rs/homedir/0.3.6/homedir/unix/index.html

Retrieves the home directory path for the current process user.

```APIDOC
## my_home

### Description
Get this process’ user’s home directory path.

### Signature
`pub fn my_home() -> Result<PathBuf, GetHomeError>`
```

--------------------------------

### home(username: &str)

Source: https://docs.rs/homedir/0.3.6/homedir/index.html

Retrieves the home directory of a specified user by their username.

```APIDOC
## fn home(username: &str)

### Description
Retrieves the home directory of an arbitrary user provided their username. Returns `Ok(None)` if the user is not found, or an `Err` if an error occurs.

### Signature
`pub fn home(username: &str) -> Result<Option<PathBuf>, GetHomeError>`
```

--------------------------------

### my_home()

Source: https://docs.rs/homedir/0.3.6/homedir/fn.my_home.html

Retrieves the home directory of the process' current user.

```APIDOC
## my_home

### Description
Get the home directory of the process' current user.

### Signature
`pub fn my_home() -> Result<Option<PathBuf>, GetHomeError>`

### Returns
- **Result<Option<PathBuf>, GetHomeError>** - Returns the path to the user's home directory if found, or an error if the operation fails.
```

--------------------------------

### Retrieve home directory for a user

Source: https://docs.rs/homedir/0.3.6/homedir/fn.home.html

Returns the home directory of the specified user as a PathBuf, or None if the user is not found.

```rust
pub fn home<S: AsRef<str>>(username: S) -> Result<Option<PathBuf>, GetHomeError>
```

--------------------------------

### home(user: UserIdentifier) -> Result<PathBuf, GetHomeError>

Source: https://docs.rs/homedir/0.3.6/homedir/unix/index.html

Retrieves the home directory path for a specified user identifier.

```APIDOC
## home

### Description
Get a user’s home directory path.

### Signature
`pub fn home(user: UserIdentifier) -> Result<PathBuf, GetHomeError>`
```

--------------------------------

### Retrieve current user home directory

Source: https://docs.rs/homedir/0.3.6/homedir/fn.my_home.html

Returns the home directory of the process' current user as a PathBuf wrapped in a Result.

```rust
pub fn my_home() -> Result<Option<PathBuf>, GetHomeError>
```

--------------------------------

### UserIdentifier::to_home

Source: https://docs.rs/homedir/0.3.6/homedir/struct.UserIdentifier.html

Retrieves the home directory path for the identified user.

```APIDOC
## UserIdentifier::to_home(&self) -> Result<Option<PathBuf>, GetHomeError>

### Description
Returns the home directory path associated with the user identifier.
```

--------------------------------

### homedir::unix::home

Source: https://docs.rs/homedir/0.3.6/homedir/unix/fn.home.html

Retrieves the home directory path for a specified username. Returns Ok(Some(PathBuf)) if found, Ok(None) if the user does not exist, or Err(GetHomeError) if an error occurs.

```APIDOC
## fn home<S: AsRef<str>>(username: S) -> Result<Option<PathBuf>, GetHomeError>

### Description
Get a user’s home directory path. This function uses the `getpwnam_r(3)` library function to retrieve the home directory from the `/etc/passwd` file.

### Parameters
- **username** (S: AsRef<str>) - Required - The username to look up.

### Returns
- **Result<Option<PathBuf>, GetHomeError>** - Returns the path to the user's home directory if found, None if the user does not exist, or an error if the lookup fails.

### Example
```rust
use homedir::unix::home;
use std::path::PathBuf;

// Assumes a user named 'root' exists with home directory '/root'
assert_eq!(
    Some(PathBuf::from("/root".to_owned())),
    home("root")?
);
assert!(home("nonexistentuser")?.is_none());
```
```

--------------------------------

### Clear Errno Value

Source: https://docs.rs/homedir/0.3.6/homedir/unix/type.GetHomeError.html

Demonstrates clearing the platform-specific errno to indicate no error.

```rust
use nix::errno::Errno;

Errno::EIO.set();

Errno::clear();

let err = Errno::last();
assert_ne!(err, Errno::EIO);
assert_eq!(err, Errno::from_raw(0));
```

--------------------------------

### UserIdentifier::with_username

Source: https://docs.rs/homedir/0.3.6/homedir/struct.UserIdentifier.html

Retrieves the user identifier for a specified username.

```APIDOC
## UserIdentifier::with_username<S: AsRef<str>>(username: S) -> Result<Option<Self>, GetHomeError>

### Description
Get the user identifier of an arbitrary user by their username.

### Parameters
- **username** (S) - Required - The username to look up.
```

--------------------------------

### GetHomeError Definition

Source: https://docs.rs/homedir/0.3.6/homedir/struct.GetHomeError.html

The definition of the GetHomeError struct as provided in the crate documentation.

```rust
pub struct GetHomeError(/* private fields */);
```

--------------------------------

### UserIdentifier::my_id

Source: https://docs.rs/homedir/0.3.6/homedir/struct.UserIdentifier.html

Retrieves the user identifier for the current process user.

```APIDOC
## UserIdentifier::my_id() -> Result<Self, GetHomeError>

### Description
Get the user identifier of the process’ current user.
```

--------------------------------

### Define UserIdentifier Structure

Source: https://docs.rs/homedir/0.3.6/homedir/struct.UserIdentifier.html

The internal definition of the UserIdentifier struct.

```rust
pub struct UserIdentifier(/* private fields */);
```

--------------------------------

### GetHomeError Type Definition

Source: https://docs.rs/homedir/0.3.6/homedir/unix/type.GetHomeError.html

The primary type alias definition for error handling.

```rust
pub type GetHomeError = Errno;
```

--------------------------------

### GetHomeError Enum Variants

Source: https://docs.rs/homedir/0.3.6/homedir/unix/type.GetHomeError.html

The underlying enum structure representing various Unix error codes.

```rust
#[repr(i32)]
pub enum GetHomeError {
Show 132 variants    UnknownErrno = 0,
    EPERM = 1,
    ENOENT = 2,
    ESRCH = 3,
    EINTR = 4,
    EIO = 5,
    ENXIO = 6,
    E2BIG = 7,
    ENOEXEC = 8,
    EBADF = 9,
    ECHILD = 10,
    EAGAIN = 11,
    ENOMEM = 12,
    EACCES = 13,
    EFAULT = 14,
    ENOTBLK = 15,
    EBUSY = 16,
    EEXIST = 17,
    EXDEV = 18,
    ENODEV = 19,
    ENOTDIR = 20,
    EISDIR = 21,
    EINVAL = 22,
    ENFILE = 23,
    EMFILE = 24,
    ENOTTY = 25,
    ETXTBSY = 26,
    EFBIG = 27,
    ENOSPC = 28,
    ESPIPE = 29,
    EROFS = 30,
    EMLINK = 31,
    EPIPE = 32,
    EDOM = 33,
    ERANGE = 34,
    EDEADLK = 35,
    ENAMETOOLONG = 36,
    ENOLCK = 37,
    ENOSYS = 38,
    ENOTEMPTY = 39,
    ELOOP = 40,
    ENOMSG = 42,
    EIDRM = 43,
    ECHRNG = 44,
    EL2NSYNC = 45,
    EL3HLT = 46,
    EL3RST = 47,
    ELNRNG = 48,
    EUNATCH = 49,
    ENOCSI = 50,
    EL2HLT = 51,
    EBADE = 52,
    EBADR = 53,
    EXFULL = 54,
    ENOANO = 55,
    EBADRQC = 56,
    EBADSLT = 57,
    EBFONT = 59,
    ENOSTR = 60,
    ENODATA = 61,
    ETIME = 62,
    ENOSR = 63,
    ENONET = 64,
    ENOPKG = 65,
    EREMOTE = 66,
    ENOLINK = 67,
    EADV = 68,
    ESRMNT = 69,
    ECOMM = 70,
    EPROTO = 71,
    EMULTIHOP = 72,
    EDOTDOT = 73,
    EBADMSG = 74,
    EOVERFLOW = 75,
    ENOTUNIQ = 76,
    EBADFD = 77,
    EREMCHG = 78,
    ELIBACC = 79,
    ELIBBAD = 80,
    ELIBSCN = 81,
    ELIBMAX = 82,
    ELIBEXEC = 83,
    EILSEQ = 84,
    ERESTART = 85,
    ESTRPIPE = 86,
    EUSERS = 87,
    ENOTSOCK = 88,
    EDESTADDRREQ = 89,
    EMSGSIZE = 90,
    EPROTOTYPE = 91,
    ENOPROTOOPT = 92,
    EPROTONOSUPPORT = 93,
    ESOCKTNOSUPPORT = 94,
    EOPNOTSUPP = 95,
    EPFNOSUPPORT = 96,
    EAFNOSUPPORT = 97,
    EADDRINUSE = 98,
    EADDRNOTAVAIL = 99,
    ENETDOWN = 100,
    ENETUNREACH = 101,
    ENETRESET = 102,
    ECONNABORTED = 103,
    ECONNRESET = 104,
    ENOBUFS = 105,
    EISCONN = 106,
    ENOTCONN = 107,
    ESHUTDOWN = 108,
    ETOOMANYREFS = 109,
    ETIMEDOUT = 110,
    ECONNREFUSED = 111,
    EHOSTDOWN = 112,
    EHOSTUNREACH = 113,
    EALREADY = 114,
    EINPROGRESS = 115,
    ESTALE = 116,
    EUCLEAN = 117,
    ENOTNAM = 118,
    ENAVAIL = 119,
    EISNAM = 120,
    EREMOTEIO = 121,
    EDQUOT = 122,
    ENOMEDIUM = 123,
    EMEDIUMTYPE = 124,
    ECANCELED = 125,
    ENOKEY = 126,
    EKEYEXPIRED = 127,
    EKEYREVOKED = 128,
    EKEYREJECTED = 129,
    EOWNERDEAD = 130,
    ENOTRECOVERABLE = 131,
    ERFKILL = 132,
    EHWPOISON = 133,
}
```
Tokens:
Raw