SD_SEAT_GET_ACTIVE(3)

💖 SD_SEAT_GET_ACTIVE 💖

okay so bestie, this is a page from the sd_seat_get_active corner of the systemd manual (section 3, library calls, you know the vibe) and it's literally all about finding out what's going on with a specific seat. no cap, it's more useful than it sounds.

---

✨ NAME ✨

sd_seat_get_active, sd_seat_get_sessions, sd_seat_can_tty, sd_seat_can_graphical — figure out the state of one specific seat 🪑

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-login.h>

int sd_seat_get_active(const char *seat, char **session, uid_t *uid);

int sd_seat_get_sessions(const char *seat, char ***ret_sessions,
                         uid_t **ret_uids, unsigned int *ret_n_uids);

int sd_seat_can_tty(const char *seat);

int sd_seat_can_graphical(const char *seat);

---

🦋 DESCRIPTION 🦋

💅 sd_seat_get_active()

so this one tells you which session is currently active on a seat — if there even is one, which, mood. it hands you back the session identifier and the user identifier of the Unix user that session belongs to. you can pass NULL for either the session or the user identifier parameter if you only wanna query one of them, no pressure. the returned string? you gotta free it with the libc free(3) call after use. don't forget, bestie, that's a leak waiting to happen 😭

🎀 sd_seat_get_sessions()

this one gives you all the sessions on the specified seat. it returns two arrays: one is NULL-terminated and holds the session identifiers, and the other holds the user identifiers of the Unix users those sessions belong to. there's an extra parameter you can use to get the number of entries in that latter array — and fun fact, that value is the same as the return value, as long as the return value is nonnegative. you can pass any of the output parameters as NULL if you don't need those values. the arrays and the strings they point at all need freeing with the libc free(3) call after use. ⚠️ and heads up: instead of an empty array, NULL may be returned, and you should consider that equivalent to an empty array. slay, but also, be careful.

🌈 sd_seat_can_tty()

does this specific seat provide TTY functionality, i.e. is it useful as a text console? that's the whole question. yes or no, iconically.

⭐ sd_seat_can_graphical()

does this specific seat provide graphics functionality, i.e. is it useful as a graphics display? same energy, different vibes.

🫶 and here's the group-chat PSA: if you pass the seat parameter of any of these functions as NULL, the operation gets executed for the seat of the session of the calling process — if there is any. so like, it just does the thing for your own seat. convenient.

---

👑 RETURN VALUE 👑

on success, sd_seat_get_active() returns 0 or a positive integer. periodt.

on success, sd_seat_get_sessions() returns the number of entries in the session identifier array. iconic.

if the test succeeds, sd_seat_can_tty() and sd_seat_can_graphical() return a positive integer — and if it fails, 0. that's it, that's the whole answer.

on failure, these calls return a negative errno-style error code. 😭

💀 Errors

the returned errors may indicate the following problems, and yes you should actually read them:

• -ENODATA — the given field is not specified for the described seat. it's just not there, bestie.
• -ENXIO — the specified seat is unknown. who is she? never heard of her.
• -EINVAL — an input parameter was invalid (out of range, or NULL where that is not accepted). read the docs before you @ me.
• -ENOMEM — memory allocation failed. rip.

---

🧚 NOTES 🧚

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. standard stuff, but now you know ✨

🙈 lowkey important: the code described here uses getenv(3), which is declared to be not multi-thread-safe. that means code calling the functions described here must not call setenv(3) from a parallel thread. the recommendation is to only do calls to setenv() from an early phase of the program, when no other threads have been started yet. do not skip this part, i'm begging 🫶

---

🌸 HISTORY 🌸

sd_seat_can_tty() and sd_seat_can_graphical() were added in version 186. they're the OGs of this page, honestly.

---

🌟 SEE ALSO 🌟

systemd(1), sd-login(3), sd_session_get_seat(3)

---

and that's the whole page, bestie!! go forth and query some seats 💜✨ this little love letter came to you courtesy of systemd 261.3 — mwah, see you in the next manpage 🎀🦋