Crate pwd_grp

Crate pwd_grp 

Source
Expand description

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

Modules§

error
Error handling and error types
mock
Mock provider of passwd/group data

Structs§

Group
Information about a group in the password database
Passwd
Information about a user in the password database
PwdGrp
Provider of passwd and group information, from system databases

Traits§

PwdGrpProvider
Provider of passwd and group information.
PwdGrpString
Strings that can we can work with

Functions§

getegid
Get the current process’s effective gid
geteuid
Get the current process’s effective uid
getgid
Get the current process’s (real) gid
getgrgid
Look up a group entry by gid
getgrnam
Look up a group entry by name
getgroups
Get the current process’s supplementary group list
getpwnam
Look up a passwd entry by name
getpwuid
Look up a passwd entry by uid
getresgid
Get the current process’s real, effective and saved set-gid
getresuid
Get the current process’s real, effective and saved set-uid
getuid
Get the current process’s (real) uid