# 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`](https://docs.rs/nix/latest/nix/unistd/struct.User.html) etc:
   Part of the substantial and generally helpful `nix` library.
   `nix` makes some different decisions about data validity,
   and representation,
   and lacks `pwd-grp`s mocking facility.

 * [`sysinfo`](https://docs.rs/sysinfo/latest/sysinfo/):
   Much larger crate;
   strange API that requires manually pre-populating information.

 * [`users`](https://docs.rs/users/latest/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`](https://docs.rs/pwd/latest/pwd/):
   Not threadsafe (uses `getpwnam`, not `getpwnam_r`).
   No way to access non-UTF-8 data.
   Suboptimal error handling.

 * [`libc::getpwuid_r`](https://docs.rs/libc/latest/libc/fn.getpwuid_r.html)
   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.