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.

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.

Stability

The API is not stabilised yet but we do intend to make a 1.0 version some time in 2023. Please report API defects as you find them!

MSRV and MSRV policy

The Minimum Supported Rust Version for derive-adhoc is 1.54.

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

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]).

Alternatives to this library

You might also be considering:

• 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.