homedir Rust Crate

Quick Links

Description
Motivation
Licensing
Contribution
The Development of Version 0.3.0

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, home and 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. As well, there are some issues on Windows regarding the COM library. These are discussed in the crate's documentation and the section regarding version 0.3.0.

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 that 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 email me, [email protected]. Thanks!

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.

The Development of Version `0.3.0`

After I finished version 0.2.1 last year (2023), I took a break the development of this crate. At the time, I remained dissatisfied with my crate’s implementation on Windows, due to the use of the wmi and serde crates as dependencies. There is nothing wrong with these crates, I simply wanted my crate to leave as small of a footprint as possible.

Around Christmas time last year, I had a look at finally removing these dependencies. However, after investigating the problem for a short period, I observed a sad fact about the steps I would need to perform. Previously, I used the windows-sys crate, which contains raw C-like hooks to the Win32 API. However, to perform the operations the wmi crate did, I needed to use the windows crate, which contained more abstracted C++-like hooks. This is because the one specific interface I needed to use, IWbemLocator, does not exist within the C Win32 API. I know this to be the case because I searched for WbemLocator within the windows-rs repository, and the only results I found were within the windows crate. At the time, facing the prospects of needing to re-write the entire Windows portion of my library to use a new API, I turned in the towel.

A few days ago (July 2024), I was browsing crates on crates.io when I decided to check in on my crate. There, I was stunned to learn that there were over one hundred thousand downloads! At that point, I felt like I had a duty to re-write the Windows portion of my library to fix the flaw I perceived existed there. So, I re-wrote my entire implementation, and then did a deep dive into MSN documentation to re-implement the features that were originally in wmi. I also referenced the source code of wmi.

During this research, I discovered the pleasant existence of the CoInitializeEx function, which wonderfully caused segmentation faults in some pure Rust code, see this GitHub issue . The research I did online was inconclusive regarding whether the CoUninitialize function should be called after CoInitializeEx, so I asked in the linked issue, and received a response from one of the repository’s maintainer in record time (many thanks to them).

After I finished my implementation, I decided to go through the Rust API guidelines, which inspired me to perform a complete redesign of the platform-agnostic part of my crate. Previously, I simply pub used the platform-specific implementations in the crate root. However, I didn’t like some of the consequences of this approach, such as the way that the documentation of the crate would be presented. So, I re-wrote everything using the Newtype design pattern. I also renamed most of the functions within the API, as the original names were redundant. For example, get_home was renamed to home.