src/systemd/sd-login.h

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