man/sd_session_is_active.3

   1 '\" t
   2 .TH "SD_SESSION_IS_ACTIVE" "3" "" "systemd 208" "sd_session_is_active"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 sd_session_is_active, sd_session_get_state, sd_session_get_uid, sd_session_get_seat, sd_session_get_service, sd_session_get_type, sd_session_get_class, sd_session_get_display, sd_session_get_tty, sd_session_get_vt \- Determine state of a specific session
  24 .SH "SYNOPSIS"
  25 .sp
  26 .ft B
  27 .nf
  28 #include <systemd/sd\-login\&.h>
  29 .fi
  30 .ft
  31 .HP \w'int\ sd_session_is_active('u
  32 .BI "int sd_session_is_active(const\ char*\ " "session" ");"
  33 .HP \w'int\ sd_session_get_state('u
  34 .BI "int sd_session_get_state(const\ char*\ " "session" ", char**\ " "state" ");"
  35 .HP \w'int\ sd_session_get_uid('u
  36 .BI "int sd_session_get_uid(const\ char*\ " "session" ", uid_t*\ " "uid" ");"
  37 .HP \w'int\ sd_session_get_seat('u
  38 .BI "int sd_session_get_seat(const\ char*\ " "session" ", char**\ " "seat" ");"
  39 .HP \w'int\ sd_session_get_service('u
  40 .BI "int sd_session_get_service(const\ char*\ " "session" ", char**\ " "service" ");"
  41 .HP \w'int\ sd_session_get_type('u
  42 .BI "int sd_session_get_type(const\ char*\ " "session" ", char**\ " "type" ");"
  43 .HP \w'int\ sd_session_get_class('u
  44 .BI "int sd_session_get_class(const\ char*\ " "session" ", char**\ " "class" ");"
  45 .HP \w'int\ sd_session_get_display('u
  46 .BI "int sd_session_get_display(const\ char*\ " "session" ", char**\ " "display" ");"
  47 .HP \w'int\ sd_session_get_tty('u
  48 .BI "int sd_session_get_tty(const\ char*\ " "session" ", char**\ " "tty" ");"
  49 .HP \w'int\ sd_session_get_vt('u
  50 .BI "int sd_session_get_vt(const\ char*\ " "session" ", unsigned\ int*\ " "vt" ");"
  51 .SH "DESCRIPTION"
  52 .PP
  53 \fBsd_session_is_active()\fR
  54 may be used to determine whether the session identified by the specified session identifier is currently active (i\&.e\&. currently in the foreground and available for user input) or not\&.
  55 .PP
  56 \fBsd_session_get_state()\fR
  57 may be used to determine the state of the session identified by the specified session identifier\&. The following states are currently known:
  58 "online"
  59 (session logged in, but session not active, i\&.e\&. not in the foreground),
  60 "active"
  61 (session logged in and active, i\&.e\&. in the foreground),
  62 "closing"
  63 (session nominally logged out, but some processes belonging to it are still around)\&. In the future additional states might be defined, client code should be written to be robust in regards to additional state strings being returned\&. This function is a more generic version of
  64 \fBsd_session_is_active()\fR\&. The returned string needs to be freed with the libc
  65 \fBfree\fR(3)
  66 call after use\&.
  67 .PP
  68 \fBsd_session_get_uid()\fR
  69 may be used to determine the user identifier of the Unix user the session identified by the specified session identifier belongs to\&.
  70 .PP
  71 \fBsd_session_get_seat()\fR
  72 may be used to determine the seat identifier of the seat the session identified by the specified session identifier belongs to\&. Note that not all sessions are attached to a seat, this call will fail for them\&. The returned string needs to be freed with the libc
  73 \fBfree\fR(3)
  74 call after use\&.
  75 .PP
  76 \fBsd_session_get_service()\fR
  77 may be used to determine the name of the service (as passed during PAM session setup) that registered the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
  78 \fBfree\fR(3)
  79 call after use\&.
  80 .PP
  81 \fBsd_session_get_type()\fR
  82 may be used to determine the type of the session identified by the specified session identifier\&. The returned string is one of
  83 "x11",
  84 "tty"
  85 or
  86 "unspecified"
  87 and needs to be freed with the libc
  88 \fBfree\fR(3)
  89 call after use\&.
  90 .PP
  91 \fBsd_session_get_class()\fR
  92 may be used to determine the class of the session identified by the specified session identifier\&. The returned string is one of
  93 "user",
  94 "greeter",
  95 "lock\-screen", or
  96 "background"
  97 and needs to be freed with the libc
  98 \fBfree\fR(3)
  99 call after use\&.
 100 .PP
 101 \fBsd_session_get_display()\fR
 102 may be used to determine the X11 display of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
 103 \fBfree\fR(3)
 104 call after use\&.
 105 .PP
 106 \fBsd_session_get_tty()\fR
 107 may be used to determine the TTY device of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
 108 \fBfree\fR(3)
 109 call after use\&.
 110 .PP
 111 \fBsd_session_get_vt()\fR
 112 may be used to determine the VT number of the session identified by the specified session identifier\&. This function will return an error if the seat does not support VTs\&.
 113 .PP
 114 If the
 115 \fIsession\fR
 116 parameter of any of these functions is passed as
 117 \fBNULL\fR, the operation is executed for the session the calling process is a member of, if there is any\&.
 118 .SH "RETURN VALUE"
 119 .PP
 120 If the test succeeds,
 121 \fBsd_session_is_active()\fR
 122 returns a positive integer, if it fails 0\&. On success
 123 \fBsd_session_get_state()\fR,
 124 \fBsd_session_get_uid()\fR,
 125 \fBsd_session_get_seat()\fR,
 126 \fBsd_session_get_service()\fR,
 127 \fBsd_session_get_type()\fR,
 128 \fBsd_session_get_class()\fR,
 129 \fBsd_session_get_display()\fR
 130 and
 131 \fBsd_session_get_tty()\fR
 132 return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
 133 .SH "NOTES"
 134 .PP
 135 The
 136 \fBsd_session_is_active()\fR,
 137 \fBsd_session_get_state()\fR,
 138 \fBsd_session_get_uid()\fR,
 139 \fBsd_session_get_seat()\fR,
 140 \fBsd_session_get_service()\fR,
 141 \fBsd_session_get_type()\fR,
 142 \fBsd_session_get_class()\fR,
 143 \fBsd_session_get_display()\fR
 144 and
 145 \fBsd_session_get_tty()\fR
 146 interfaces are available as shared library, which can be compiled and linked to with the
 147 \fBlibsystemd\-login\fR\ \&\fBpkg-config\fR(1)
 148 file\&.
 149 .SH "SEE ALSO"
 150 .PP
 151 \fBsystemd\fR(1),
 152 \fBsd-login\fR(3),
 153 \fBsd_pid_get_session\fR(3)