homedir Rust Crate

Quick Links

Description
Motivation
Usage
Changelog
Examples
1. Get the process’ user’s home directory.
2. Get an arbitrary user’s home directory.
Licensing
Contribution

Description

This crate exists to provide a portable method to getting any user's home directory. The API is rather simple: there are two main functions, get_home and get_my_home. The former can get the home directory of any user provided you have their username. The latter can get the home directory of the user executing this process.

This crate aims to work on both Windows and Unix systems. However, Unix systems do not have a unified API. This crate may not work on Unix systems which do not have the getpwnam_r(3), getpwuid_r(3), and getuid(2) functions.

Motivation

As I was working on another project, which will eventually also be added to this website, I got nerdsniped by the fact that there didn’t seem to be any easy way to get an arbitrary user’s home directory on Windows.

This was quite surprising for me, so I decided to investigate further. I eventually found a method to get a user's home directory on Windows, but I decided to test it out just to make sure. Then, seeing as I already had a prototype written, I thought I might as well write a crate around the code so others don't have to go through the same search as I have.

This is the first crate I've published, so I want to make sure that I get everything right. If you (the person reading this) notice any mistakes I've made in this page or others belonging to this crate, it would be extremely appreciated if you could send me an email, [email protected]. Thanks!

Usage

This crate is on crates.io and can be used by executing cargo add homedir or adding the following to the dependencies in your Cargo.toml file.

[dependencies]
homedir = "0.2.1"

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.2.1 - 2023-08-27

Fixed

Documentation tests that would not compile have been fixed.

0.2.0 - 2023-08-27

Added

get_id, get_home_from_id, and get_my_id functions.
A UserIdentifier type alias.

Changed

The get_my_home implementation on Unix systems now checks the $HOME environment variable first before checking the /etc/passwd directory.

Removed

The check_env feature flag.

0.1.0 - 2023-08-12

The first release of this crate.

Examples

Get the process’ user’s home directory.

use homedir::get_my_home;

// This assumes that the process' user has "/home/jpetersen" as home directory.
assert_eq!(
    std::path::Path::new("/home/jpetersen"),
    get_my_home().unwrap().unwrap().as_path()
);

Get an arbitrary user’s home directory.

use homedir::get_home;

// This assumes there is a user named "Administrator" which has
// "C:\Users\Administrator" as a home directory.
assert_eq!(
    std::path::Path::new("C:\\Users\\Administrator"),
    get_home("Administrator").unwrap().unwrap().as_path()
);
assert!(get_home("NonExistentUser").unwrap().is_none());

Licensing

Licensed under either of

Apache License, Version 2.0
(http://www.apache.org/licenses/LICENSE-2.0)
MIT License
(http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitely state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Feel free to put a copyright header in your name in any files you contribute to.