PWCACHE(3)

💅 PWCACHE(3) — like, the password & group cache one ✨

okay so real talk: we're in the Library Functions Manual, section 3, and this page is literally called pwcache — it's giving "chaotic friend group of six functions that all just want to remember things so they don't have to keep asking" 🎀

---

🌸 NAME 🌸

pwcache, user_from_uid, uid_from_user, pwcache_userdb, group_from_gid, gid_from_group, pwcache_groupdb — cache password and group entries 💖

---

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yes bestie, she's built in 🫶

---

✨ SYNOPSIS ✨

#include <pwd.h>

const char *
user_from_uid(uid_t uid, int nouser);

int
uid_from_user(const char *name, uid_t *uid);

int
pwcache_userdb(int (*setpassent)(int), void (*endpwent)(void),
    struct passwd * (*getpwnam)(const char *),
    struct passwd * (*getpwuid)(uid_t));

#include <grp.h>

const char *
group_from_gid(gid_t gid, int nogroup);

int
gid_from_group(const char *name, gid_t *gid);

int
pwcache_groupdb(int (*setgroupent)(int), void (*endgrent)(void),
    struct group * (*getgrnam)(const char *),
    struct group * (*getgrgid)(gid_t));

---

👑 DESCRIPTION 👑

okay bestie, here's the whole situation. Every one of these is a little cache goblin — first call does the expensive lookup, every call after that is free because she remembered it 💅

🧚 the user-side girlies

user_from_uid() hands you back the user name that goes with the uid you passed in. The name gets cached, so calling it again with the same uid does not make another getpwuid(3) call — we're not doing that much work, periodt ✨

Now, the plot twist: if there's genuinely no user associated with that uid, she returns a pointer to a string representation of the uid — cute, fine, whatever. BUT — if the nouser argument is non-zero, you get a NULL pointer instead. Choose your fighter 🫶

uid_from_user() is the reverse icon 🦋 she returns the uid associated with name. Cached too, so multiple calls with the same name don't hit getpwnam(3) again. And the returns? If there's no uid for that name, she returns -1. Otherwise she stores the uid at the location pointed to by uid and returns 0. Slay, consistent 😌

🌈 the group-side girlies

group_from_gid() returns the group name for the gid you give her. Cached, so the same gid twice ≠ extra getgrgid(3) calls. And if there's no group for that gid? Pointer to a string representation of the gid — unless nogroup is non-zero, in which case it's NULL. Same energy as her user-side sister fr fr 🎀

gid_from_group() gives you the gid for name, cached so you're not re-calling getgrnam(3) like a menace. No gid for that name → returns -1. Found it → stores the gid at the location pointed to by gid and returns 0. Iconic behavior only 💖

🔥 the ones that swap out the whole database backend

pwcache_userdb() — this is the main character move 👑 she changes the user database access routines that user_from_uid() and uid_from_user() call when they go searching for users. Wild, I know.

Two important deets:

• the caches get flushed, and
• the existing endpwent() method is called before switching over to the new routines.

Also: getpwnam and getpwuid must be provided (non-negotiable bestie), while setpassent and endpwent may be NULL pointers. iykyk 😭

pwcache_groupdb() is the group-flavored version, obviously 💜 she changes the group database access routines that group_from_gid() and gid_from_group() call when hunting for groups. Same drill: caches flushed, existing endgrent() method called before switching to the new routines. getgrnam and getgrgid must be provided; setgroupent and endgrent may be NULL pointers. No cap 🌸

---

💀 ERRORS 💀

If insufficient memory is available, user_from_uid() and group_from_gid() may return NULL pointers, and errno is set to ENOMEM. 😭

Lowkey tragic but at least she tells you why. Notice it's only those two that get called out here — don't go assuming it applies to the others, bestie 🫶

---

🦋 SEE ALSO 🦋

• getgrgid(3)
• getgrnam(3)
• getpwnam(3)
• getpwuid(3)

go read those too, they're the whole reason this cache exists fr fr 🍓

---

⭐ HISTORY ⭐

• user_from_uid() and group_from_gid() first appeared in 4.4BSD. vintage 💅
• uid_from_user() and gid_from_group() first appeared in NetBSD 1.4.
• pwcache_userdb() and pwcache_groupdb() first appeared in NetBSD 1.6 and FreeBSD 10.0.

---

and that's the whole page, bestie — this one came from Debian, dated May 5, 2020, and honestly? she ate. mwah 💋✨