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
: implementsSerialize
andDeserialize
forPasswd
andGroup
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.)
Alternatives to this library
You might also be considering:
-
nix::unistd::User
etc: Part of the substantial and generally helpfulnix
library.nix
makes some different decisions about data validity, and representation, and lackspwd-grp
s 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 (usesgetpwnam
, notgetpwnam_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 handling and error types
- Mock provider of passwd/group data
Structs
- Information about a group in the password database
- Information about a user in the password database
- Provider of passwd and group information, from system databases
Traits
- Provider of passwd and group information.
- Strings that can we can work with
Functions
- Get the current process’s effective gid
- Get the current process’s effective uid
- Get the current process’s (real) gid
- Look up a group entry by gid
- Look up a group entry by name
- Get the current process’s supplementary group list
- Look up a passwd entry by name
- Look up a passwd entry by uid
- Get the current process’s real, effective and saved set-gid
- Get the current process’s real, effective and saved set-uid
- Get the current process’s (real) uid