]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
e3bff60a | 2 | .TH "SD_SESSION_IS_ACTIVE" "3" "" "systemd 220" "sd_session_is_active" |
14228c0d MB |
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" | |
5eef597e | 23 | sd_session_is_active, sd_session_is_remote, 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_desktop, sd_session_get_display, sd_session_get_tty, sd_session_get_vt, sd_session_get_remote_host, sd_session_get_remote_user \- Determine state of a specific session |
14228c0d MB |
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 | |
60f067b4 JS |
32 | .BI "int sd_session_is_active(const\ char\ *" "session" ");" |
33 | .HP \w'int\ sd_session_is_remote('u | |
34 | .BI "int sd_session_is_remote(const\ char\ *" "session" ");" | |
14228c0d | 35 | .HP \w'int\ sd_session_get_state('u |
60f067b4 | 36 | .BI "int sd_session_get_state(const\ char\ *" "session" ", char\ **" "state" ");" |
14228c0d | 37 | .HP \w'int\ sd_session_get_uid('u |
60f067b4 | 38 | .BI "int sd_session_get_uid(const\ char\ *" "session" ", uid_t\ *" "uid" ");" |
14228c0d | 39 | .HP \w'int\ sd_session_get_seat('u |
60f067b4 | 40 | .BI "int sd_session_get_seat(const\ char\ *" "session" ", char\ **" "seat" ");" |
14228c0d | 41 | .HP \w'int\ sd_session_get_service('u |
60f067b4 | 42 | .BI "int sd_session_get_service(const\ char\ *" "session" ", char\ **" "service" ");" |
14228c0d | 43 | .HP \w'int\ sd_session_get_type('u |
60f067b4 | 44 | .BI "int sd_session_get_type(const\ char\ *" "session" ", char\ **" "type" ");" |
14228c0d | 45 | .HP \w'int\ sd_session_get_class('u |
60f067b4 | 46 | .BI "int sd_session_get_class(const\ char\ *" "session" ", char\ **" "class" ");" |
5eef597e MP |
47 | .HP \w'int\ sd_session_get_desktop('u |
48 | .BI "int sd_session_get_desktop(const\ char\ *" "session" ", char\ **" "desktop" ");" | |
14228c0d | 49 | .HP \w'int\ sd_session_get_display('u |
60f067b4 JS |
50 | .BI "int sd_session_get_display(const\ char\ *" "session" ", char\ **" "display" ");" |
51 | .HP \w'int\ sd_session_get_remote_host('u | |
52 | .BI "int sd_session_get_remote_host(const\ char\ *" "session" ", char\ **" "remote_host" ");" | |
53 | .HP \w'int\ sd_session_get_remote_user('u | |
54 | .BI "int sd_session_get_remote_user(const\ char\ *" "session" ", char\ **" "remote_user" ");" | |
14228c0d | 55 | .HP \w'int\ sd_session_get_tty('u |
60f067b4 | 56 | .BI "int sd_session_get_tty(const\ char\ *" "session" ", char\ **" "tty" ");" |
14228c0d | 57 | .HP \w'int\ sd_session_get_vt('u |
60f067b4 | 58 | .BI "int sd_session_get_vt(const\ char\ *" "session" ", unsigned\ int\ *" "vt" ");" |
14228c0d MB |
59 | .SH "DESCRIPTION" |
60 | .PP | |
61 | \fBsd_session_is_active()\fR | |
62 | 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\&. | |
63 | .PP | |
60f067b4 JS |
64 | \fBsd_session_is_remote()\fR |
65 | may be used to determine whether the session identified by the specified session identifier is a remote session (i\&.e\&. its remote host is known) or not\&. | |
66 | .PP | |
14228c0d MB |
67 | \fBsd_session_get_state()\fR |
68 | may be used to determine the state of the session identified by the specified session identifier\&. The following states are currently known: | |
69 | "online" | |
70 | (session logged in, but session not active, i\&.e\&. not in the foreground), | |
71 | "active" | |
72 | (session logged in and active, i\&.e\&. in the foreground), | |
73 | "closing" | |
74 | (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 | |
75 | \fBsd_session_is_active()\fR\&. The returned string needs to be freed with the libc | |
76 | \fBfree\fR(3) | |
77 | call after use\&. | |
78 | .PP | |
79 | \fBsd_session_get_uid()\fR | |
80 | may be used to determine the user identifier of the Unix user the session identified by the specified session identifier belongs to\&. | |
81 | .PP | |
82 | \fBsd_session_get_seat()\fR | |
83 | 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 | |
84 | \fBfree\fR(3) | |
85 | call after use\&. | |
86 | .PP | |
87 | \fBsd_session_get_service()\fR | |
88 | 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 | |
89 | \fBfree\fR(3) | |
90 | call after use\&. | |
91 | .PP | |
92 | \fBsd_session_get_type()\fR | |
93 | may be used to determine the type of the session identified by the specified session identifier\&. The returned string is one of | |
94 | "x11", | |
60f067b4 JS |
95 | "wayland", |
96 | "tty", | |
97 | "mir" | |
14228c0d MB |
98 | or |
99 | "unspecified" | |
100 | and needs to be freed with the libc | |
101 | \fBfree\fR(3) | |
102 | call after use\&. | |
103 | .PP | |
104 | \fBsd_session_get_class()\fR | |
105 | may be used to determine the class of the session identified by the specified session identifier\&. The returned string is one of | |
106 | "user", | |
107 | "greeter", | |
108 | "lock\-screen", or | |
109 | "background" | |
110 | and needs to be freed with the libc | |
111 | \fBfree\fR(3) | |
112 | call after use\&. | |
113 | .PP | |
5eef597e MP |
114 | \fBsd_session_get_desktop()\fR |
115 | may be used to determine the brand of the desktop running on the session identified by the specified session identifier\&. This field can be set freely by desktop environments and does not follow any special formatting\&. However, desktops are strongly recommended to use the same identifiers and capitalization as for | |
116 | \fI$XDG_CURRENT_DESKTOP\fR, as defined by the | |
117 | \m[blue]\fBDesktop Entry Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. The returned string needs to be freed with the libc | |
118 | \fBfree\fR(3) | |
119 | call after use\&. | |
120 | .PP | |
14228c0d MB |
121 | \fBsd_session_get_display()\fR |
122 | 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 | |
123 | \fBfree\fR(3) | |
124 | call after use\&. | |
125 | .PP | |
60f067b4 JS |
126 | \fBsd_session_get_remote_host()\fR |
127 | may be used to determine the remote hostname of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc | |
128 | \fBfree\fR(3) | |
129 | call after use\&. | |
130 | .PP | |
131 | \fBsd_session_get_remote_user()\fR | |
132 | may be used to determine the remote username of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc | |
133 | \fBfree\fR(3) | |
134 | call after use\&. Note that this value is rarely known to the system, and even then should not be relied on\&. | |
135 | .PP | |
14228c0d MB |
136 | \fBsd_session_get_tty()\fR |
137 | 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 | |
138 | \fBfree\fR(3) | |
139 | call after use\&. | |
140 | .PP | |
141 | \fBsd_session_get_vt()\fR | |
142 | 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\&. | |
143 | .PP | |
144 | If the | |
145 | \fIsession\fR | |
146 | parameter of any of these functions is passed as | |
147 | \fBNULL\fR, the operation is executed for the session the calling process is a member of, if there is any\&. | |
148 | .SH "RETURN VALUE" | |
149 | .PP | |
150 | If the test succeeds, | |
151 | \fBsd_session_is_active()\fR | |
60f067b4 JS |
152 | and |
153 | \fBsd_session_is_remote()\fR | |
154 | return a positive integer; if it fails, 0\&. On success, | |
14228c0d MB |
155 | \fBsd_session_get_state()\fR, |
156 | \fBsd_session_get_uid()\fR, | |
157 | \fBsd_session_get_seat()\fR, | |
158 | \fBsd_session_get_service()\fR, | |
159 | \fBsd_session_get_type()\fR, | |
160 | \fBsd_session_get_class()\fR, | |
60f067b4 JS |
161 | \fBsd_session_get_display()\fR, |
162 | \fBsd_session_get_remote_user()\fR, | |
163 | \fBsd_session_get_remote_host()\fR | |
14228c0d MB |
164 | and |
165 | \fBsd_session_get_tty()\fR | |
166 | return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&. | |
167 | .SH "NOTES" | |
168 | .PP | |
169 | The | |
170 | \fBsd_session_is_active()\fR, | |
171 | \fBsd_session_get_state()\fR, | |
172 | \fBsd_session_get_uid()\fR, | |
173 | \fBsd_session_get_seat()\fR, | |
174 | \fBsd_session_get_service()\fR, | |
175 | \fBsd_session_get_type()\fR, | |
176 | \fBsd_session_get_class()\fR, | |
60f067b4 JS |
177 | \fBsd_session_get_display()\fR, |
178 | \fBsd_session_get_remote_host()\fR, | |
179 | \fBsd_session_get_remote_user()\fR | |
14228c0d MB |
180 | and |
181 | \fBsd_session_get_tty()\fR | |
60f067b4 JS |
182 | interfaces are available as a shared library, which can be compiled and linked to with the |
183 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
14228c0d MB |
184 | file\&. |
185 | .SH "SEE ALSO" | |
186 | .PP | |
187 | \fBsystemd\fR(1), | |
188 | \fBsd-login\fR(3), | |
189 | \fBsd_pid_get_session\fR(3) | |
5eef597e MP |
190 | .SH "NOTES" |
191 | .IP " 1." 4 | |
192 | Desktop Entry Specification | |
193 | .RS 4 | |
194 | \%http://standards.freedesktop.org/desktop-entry-spec/latest/ | |
195 | .RE |