sg_get_user_stats(3)

🌸 sg_get_user_stats(3) — the libstatgrab manual, bestie edition 🌸

okay so this is the page for sg_get_user_stats from the libstatgrab manual set (yep, section 3, the library-functions one 💅). it's all about finding out who's logged in rn. let's get into it 🫶

---

✨ NAME ✨

sg_get_user_stats, sg_get_user_stats_r, sg_free_user_stats — grab the current logged in users 👑

✨ SYNOPSIS ✨

#include <statgrab.h>

sg_user_stats *sg_get_user_stats (size_t *entries);

sg_user_stats *sg_get_user_stats_r (size_t *entries);

sg_error sg_free_user_stats (sg_user_stats *data);

like, literally just include the header and you're in 🎀

✨ DESCRIPTION ✨

so the user statistics module hands you back some info about the people logged on. each logon is treated separately — so if someone's logged in twice, that's two entries, no merging, no cap 💅

both of the getter functions, sg_get_user_stats() and sg_get_user_stats_r(), return a vector of sg_user_stats with entries elements. that's the whole vibe ✨

🦋 API Shortcut 🦋

the original lays this out as a table, but tables are not the move in a terminal, so here it is as a list — same facts, cuter packaging:

• sg_get_user_stats → returns sg_user_stats * → data owner is libstatgrab (thread local)
• sg_get_user_stats_r → returns sg_user_stats * → data owner is caller

and the important bit, bestie, do not skip this one: the sg_user_stats vector you get back from sg_get_user_stats_r() must be freed using sg_free_user_stats() when you don't need it anymore. the caller is responsible for doing it. no one else is gonna clean that up for you 😭

✨ RETURN VALUES ✨

the structure returned is of type sg_user_stats:

typedef struct {
        char *login_name;
        char *record_id;
        size_t record_id_size;
        char *device;
        char *hostname;
        pid_t pid;
        time_t login_time;
        time_t systime;
} sg_user_stats;

and here's what each field is giving 🧚

• login_name — the username which was used to log in 👤
• record_id — record identifier of host database containing login information (and heads up: not necessarily 0-terminated — do not assume it is, fr fr)
• record_id_size — size of the record identifier 📏
• device — device name (eg. "pts/0") of the tty assigned to the login session
• hostname — the (remote) hostname from where the user is logged on, eg. "infoterm7.some.kind.of.domain.local", "localhost", "10.42.17.4" or ":0.0" (in case it's a local logon via new xterm) 🌈
• pid — process identifier of the process which made the entry to the logged on users database
• login_time — timestamp (time in seconds since epoch) when the user logged on ⏰
• systime — the timestamp when the above stats where collected in seconds since epoch ⭐

✨ SEE ALSO ✨

• statgrab(3)

✨ WEBSITE ✨

⟨https://libstatgrab.org/⟩ — go snoop, it's iconic 🌐

---

ngl this one's short and sweet — but do not sleep on that sg_free_user_stats() call, that's the whole plot twist 💀

libstatgrab · 2019-03-08 — that's the source, the version and the date, all bundled up in this little sign-off. mwah, bye bestie 💖🎀✨