Safe interface to Unix <pwd.h> and <grp.h>

This crate presents a simple, safe, flexible wrapper around the standard Unix functions used to read information about users and groups.

Example

let pwent = pwd_grp::getpwnam("root").unwrap().unwrap();
assert_eq!(pwent.uid, 0);

Thread safety

This library is thread-safe. It uses getpwuid_r and friends.

There is no interface for iterating over entries, unfortunately. This is because getpwent_r and getgrent_r are almost completely useless: they still involve a global cursor into the database!

Unicode and character set handling

The free functions in this library insist that the password and group entries contain only valid UTF-8. When this is not the case, they return an error.

For faithful handling of the bytes found in the passwd and group databases, on systems where those aren't always valid UTF-8, use the methods on PwdGrp (via PwdGrpProvider).

Cargo features

The following cargo features are available:

• full: Metafeature. Enable all reasonable, non-experimental, features.
• serde: implements Serialize and Deserialize for Passwd and Group
• minimal-1: Minimal feature set. Must be enabled.

The test-with-lmock feature is internal. It only has any effect with cfg(test), i.e. during testing of this crate. It requires Nightly Rust and is used for testing with miri.

MSRV and MSRV policy

The Minimum Supported Rust Version for rust-pwd-grp is 1.56.

We expect to increase it cautiously. (However, MSRV increase would be a minor version bump.)

Alternatives to this library

You might also be considering:

• nix::unistd::User etc: Part of the substantial and generally helpful nix library. nix makes some different decisions about data validity, and representation, and lacks pwd-grps mocking facility.

• sysinfo: Much larger crate; strange API that requires manually pre-populating information.

• users: Doesn't give access to all passwd fields. No convenient UTF-8 API. (At the time of writing) unmaintained. However, it does have a built-in caching mechanism.

• pwd: Not threadsafe (uses getpwnam, not getpwnam_r). No way to access non-UTF-8 data. Suboptimal error handling.

• libc::getpwuid_r etc: These low-level unsafe functions require you to manage buffers and allocation, and convert types to and from Rust structures. This can be tricky to do correctly and efficiently.