src/systemd/sd-login.h

   1 /* SPDX-License-Identifier: LGPL-2.1+ */
   2 #ifndef foosdloginhfoo
   3 #define foosdloginhfoo
   4
   5 /***
   6   Copyright 2011 Lennart Poettering
   7
   8   systemd is free software; you can redistribute it and/or modify it
   9   under the terms of the GNU Lesser General Public License as published by
  10   the Free Software Foundation; either version 2.1 of the License, or
  11   (at your option) any later version.
  12
  13   systemd is distributed in the hope that it will be useful, but
  14   WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16   Lesser General Public License for more details.
  17
  18   You should have received a copy of the GNU Lesser General Public License
  19   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  20 ***/
  21
  22 #include <inttypes.h>
  23 #include <sys/types.h>
  24
  25 #include "_sd-common.h"
  26
  27 /*
  28  * A few points:
  29  *
  30  * Instead of returning an empty string array or empty uid array, we
  31  * may return NULL.
  32  *
  33  * Free the data the library returns with libc free(). String arrays
  34  * are NULL terminated, and you need to free the array itself, in
  35  * addition to the strings contained.
  36  *
  37  * We return error codes as negative errno, kernel-style. On success, we
  38  * return 0 or positive.
  39  *
  40  * These functions access data in /proc, /sys/fs/cgroup, and /run. All
  41  * of these are virtual file systems; therefore, accesses are
  42  * relatively cheap.
  43  *
  44  * See sd-login(3) for more information.
  45  */
  46
  47 _SD_BEGIN_DECLARATIONS;
  48
  49 /* Get session from PID. Note that 'shared' processes of a user are
  50  * not attached to a session, but only attached to a user. This will
  51  * return an error for system processes and 'shared' processes of a
  52  * user. */
  53 int sd_pid_get_session(pid_t pid, char **session);
  54
  55 /* Get UID of the owner of the session of the PID (or in case the
  56  * process is a 'shared' user process, the UID of that user is
  57  * returned). This will not return the UID of the process, but rather
  58  * the UID of the owner of the cgroup that the process is in. This will
  59  * return an error for system processes. */
  60 int sd_pid_get_owner_uid(pid_t pid, uid_t *uid);
  61
  62 /* Get systemd non-slice unit (i.e. service) name from PID, for system
  63  * services. This will return an error for non-service processes. */
  64 int sd_pid_get_unit(pid_t pid, char **unit);
  65
  66 /* Get systemd non-slice unit (i.e. service) name from PID, for user
  67  * services. This will return an error for non-user-service
  68  * processes. */
  69 int sd_pid_get_user_unit(pid_t pid, char **unit);
  70
  71 /* Get slice name from PID. */
  72 int sd_pid_get_slice(pid_t pid, char **slice);
  73
  74 /* Get user slice name from PID. */
  75 int sd_pid_get_user_slice(pid_t pid, char **slice);
  76
  77 /* Get machine name from PID, for processes assigned to a VM or
  78  * container. This will return an error for non-machine processes. */
  79 int sd_pid_get_machine_name(pid_t pid, char **machine);
  80
  81 /* Get the control group from a PID, relative to the root of the
  82  * hierarchy. */
  83 int sd_pid_get_cgroup(pid_t pid, char **cgroup);
  84
  85 /* Similar to sd_pid_get_session(), but retrieves data about the peer
  86  * of a connected AF_UNIX socket */
  87 int sd_peer_get_session(int fd, char **session);
  88
  89 /* Similar to sd_pid_get_owner_uid(), but retrieves data about the peer of
  90  * a connected AF_UNIX socket */
  91 int sd_peer_get_owner_uid(int fd, uid_t *uid);
  92
  93 /* Similar to sd_pid_get_unit(), but retrieves data about the peer of
  94  * a connected AF_UNIX socket */
  95 int sd_peer_get_unit(int fd, char **unit);
  96
  97 /* Similar to sd_pid_get_user_unit(), but retrieves data about the peer of
  98  * a connected AF_UNIX socket */
  99 int sd_peer_get_user_unit(int fd, char **unit);
 100
 101 /* Similar to sd_pid_get_slice(), but retrieves data about the peer of
 102  * a connected AF_UNIX socket */
 103 int sd_peer_get_slice(int fd, char **slice);
 104
 105 /* Similar to sd_pid_get_user_slice(), but retrieves data about the peer of
 106  * a connected AF_UNIX socket */
 107 int sd_peer_get_user_slice(int fd, char **slice);
 108
 109 /* Similar to sd_pid_get_machine_name(), but retrieves data about the
 110  * peer of a connected AF_UNIX socket */
 111 int sd_peer_get_machine_name(int fd, char **machine);
 112
 113 /* Similar to sd_pid_get_cgroup(), but retrieves data about the peer
 114  * of a connected AF_UNIX socket. */
 115 int sd_peer_get_cgroup(pid_t pid, char **cgroup);
 116
 117 /* Get state from UID. Possible states: offline, lingering, online, active, closing */
 118 int sd_uid_get_state(uid_t uid, char **state);
 119
 120 /* Return primary session of user, if there is any */
 121 int sd_uid_get_display(uid_t uid, char **session);
 122
 123 /* Return 1 if UID has session on seat. If require_active is true, this will
 124  * look for active sessions only. */
 125 int sd_uid_is_on_seat(uid_t uid, int require_active, const char *seat);
 126
 127 /* Return sessions of user. If require_active is true, this will look for
 128  * active sessions only. Returns the number of sessions.
 129  * If sessions is NULL, this will just return the number of sessions. */
 130 int sd_uid_get_sessions(uid_t uid, int require_active, char ***sessions);
 131
 132 /* Return seats of user is on. If require_active is true, this will look for
 133  * active seats only. Returns the number of seats.
 134  * If seats is NULL, this will just return the number of seats. */
 135 int sd_uid_get_seats(uid_t uid, int require_active, char ***seats);
 136
 137 /* Return 1 if the session is active. */
 138 int sd_session_is_active(const char *session);
 139
 140 /* Return 1 if the session is remote. */
 141 int sd_session_is_remote(const char *session);
 142
 143 /* Get state from session. Possible states: online, active, closing.
 144  * This function is a more generic version of sd_session_is_active(). */
 145 int sd_session_get_state(const char *session, char **state);
 146
 147 /* Determine user ID of session */
 148 int sd_session_get_uid(const char *session, uid_t *uid);
 149
 150 /* Determine seat of session */
 151 int sd_session_get_seat(const char *session, char **seat);
 152
 153 /* Determine the (PAM) service name this session was registered by. */
 154 int sd_session_get_service(const char *session, char **service);
 155
 156 /* Determine the type of this session, i.e. one of "tty", "x11", "wayland", "mir" or "unspecified". */
 157 int sd_session_get_type(const char *session, char **type);
 158
 159 /* Determine the class of this session, i.e. one of "user", "greeter" or "lock-screen". */
 160 int sd_session_get_class(const char *session, char **clazz);
 161
 162 /* Determine the desktop brand of this session, i.e. something like "GNOME", "KDE" or "systemd-console". */
 163 int sd_session_get_desktop(const char *session, char **desktop);
 164
 165 /* Determine the X11 display of this session. */
 166 int sd_session_get_display(const char *session, char **display);
 167
 168 /* Determine the remote host of this session. */
 169 int sd_session_get_remote_host(const char *session, char **remote_host);
 170
 171 /* Determine the remote user of this session (if provided by PAM). */
 172 int sd_session_get_remote_user(const char *session, char **remote_user);
 173
 174 /* Determine the TTY of this session. */
 175 int sd_session_get_tty(const char *session, char **display);
 176
 177 /* Determine the VT number of this session. */
 178 int sd_session_get_vt(const char *session, unsigned *vtnr);
 179
 180 /* Return active session and user of seat */
 181 int sd_seat_get_active(const char *seat, char **session, uid_t *uid);
 182
 183 /* Return sessions and users on seat. Returns number of sessions.
 184  * If sessions is NULL, this returns only the number of sessions. */
 185 int sd_seat_get_sessions(const char *seat, char ***sessions, uid_t **uid, unsigned *n_uids);
 186
 187 /* Return whether the seat is multi-session capable */
 188 int sd_seat_can_multi_session(const char *seat);
 189
 190 /* Return whether the seat is TTY capable, i.e. suitable for showing console UIs */
 191 int sd_seat_can_tty(const char *seat);
 192
 193 /* Return whether the seat is graphics capable, i.e. suitable for showing graphical UIs */
 194 int sd_seat_can_graphical(const char *seat);
 195
 196 /* Return the class of machine */
 197 int sd_machine_get_class(const char *machine, char **clazz);
 198
 199 /* Return the list if host-side network interface indices of a machine */
 200 int sd_machine_get_ifindices(const char *machine, int **ifindices);
 201
 202 /* Get all seats, store in *seats. Returns the number of seats. If
 203  * seats is NULL, this only returns the number of seats. */
 204 int sd_get_seats(char ***seats);
 205
 206 /* Get all sessions, store in *sessions. Returns the number of
 207  * sessions. If sessions is NULL, this only returns the number of sessions. */
 208 int sd_get_sessions(char ***sessions);
 209
 210 /* Get all logged in users, store in *users. Returns the number of
 211  * users. If users is NULL, this only returns the number of users. */
 212 int sd_get_uids(uid_t **users);
 213
 214 /* Get all running virtual machines/containers */
 215 int sd_get_machine_names(char ***machines);
 216
 217 /* Monitor object */
 218 typedef struct sd_login_monitor sd_login_monitor;
 219
 220 /* Create a new monitor. Category must be NULL, "seat", "session",
 221  * "uid", or "machine" to get monitor events for the specific category
 222  * (or all). */
 223 int sd_login_monitor_new(const char *category, sd_login_monitor** ret);
 224
 225 /* Destroys the passed monitor. Returns NULL. */
 226 sd_login_monitor* sd_login_monitor_unref(sd_login_monitor *m);
 227
 228 /* Flushes the monitor */
 229 int sd_login_monitor_flush(sd_login_monitor *m);
 230
 231 /* Get FD from monitor */
 232 int sd_login_monitor_get_fd(sd_login_monitor *m);
 233
 234 /* Get poll() mask to monitor */
 235 int sd_login_monitor_get_events(sd_login_monitor *m);
 236
 237 /* Get timeout for poll(), as usec value relative to CLOCK_MONOTONIC's epoch */
 238 int sd_login_monitor_get_timeout(sd_login_monitor *m, uint64_t *timeout_usec);
 239
 240 _SD_DEFINE_POINTER_CLEANUP_FUNC(sd_login_monitor, sd_login_monitor_unref);
 241
 242 _SD_END_DECLARATIONS;
 243
 244 #endif