src/systemd/sd-login.h

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