OPENPAM_SUBST(3)

💅 OPENPAM_SUBST(3) — the openpam_subst manual, but make it make sense ✨

okay so bestie, welcome to the openpam_subst(3) page from the Library Functions Manual 🎀 — it's a real one, and it's honestly kind of iconic once you get what it does.

---

🌸 NAME 🌸

openpam_subst — substitute PAM item values in a string 💖

---

🦋 SYNOPSIS 🦋

like, here's the vibe, exactly as written:

#include <sys/types.h>
#include <security/pam_appl.h>
#include <security/openpam.h>

int
openpam_subst(const pam_handle_t *pamh, char *buf, size_t *bufsize,
    const char *template);

---

✨ DESCRIPTION ✨

So openpam_subst() takes a string and expands it — like, it goes through and swaps out every occurrence of certain substitution codes for the matching PAM item value. slay. 💅

The template argument points at the initial string you're starting with. The result lands in the buffer pointed to by the buf argument, and the bufsize argument tells it how big that buffer is. Then — plot twist — the actual size of the resulting string, including the terminating NUL character, gets stored in the location that bufsize points to. so it's an in-and-out situation, iykyk. 🫶

🚨 if buf is NULL, or the buffer is too small to hold the expanded string, then bufsize gets updated to reflect how much space you'd actually need for the whole entire string, and openpam_subst() returns PAM_TRY_AGAIN.

And if openpam_subst() fails for any other reason? The bufsize argument stays untouched — but heads up, part of the buffer may still have been overwritten. so don't assume your buffer is pristine. 😭

Substitution codes are introduced by a percent character %, and each one corresponds to a PAM item:

• %H — replaced by the current value of the PAM_RHOST item 🖥️
• %h — replaced by the current value of the PAM_HOST item 🏠
• %s — replaced by the current value of the PAM_SERVICE item ⚙️
• %t — replaced by the current value of the PAM_TTY item ⌨️
• %U — replaced by the current value of the PAM_RUSER item 👤
• %u — replaced by the current value of the PAM_USER item 🫧

---

🔥 RETURN VALUES 🔥

openpam_subst() returns one of these, no cap:

• [PAM_SUCCESS] — success, we ate 🎉
• [PAM_BAD_ITEM] — unrecognized or restricted item 🙈
• [PAM_TRY_AGAIN] — try again 🔁

---

💜 SEE ALSO 💜

pam(3), pam_get_authtok(3), pam_get_item(3), pam_get_user(3), pam_strerror(3) — go read those too, bestie, they're all connected 🧚

---

⭐ STANDARDS ⭐

The openpam_subst() function is an OpenPAM extension. so like, it's special, not standard-issue 🌈

---

👑 AUTHORS 👑

The openpam_subst() function and this manual page were developed by Dag-Erling Smørgrav <des@des.no>. king behavior, honestly 🫡

---

and that's the whole page!! 💖 sign-off time: this one's from Debian, dated June 27, 2023, and it's OPENPAM_SUBST(3) — periodt. 🎀✨