1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
-->
<refentry id="sd_seat_get_active" conditional='HAVE_PAM'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_seat_get_active</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_seat_get_active</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_seat_get_active</refname>
<refname>sd_seat_get_sessions</refname>
<refname>sd_seat_can_multi_session</refname>
<refname>sd_seat_can_tty</refname>
<refname>sd_seat_can_graphical</refname>
<refpurpose>Determine state of a specific seat</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_seat_get_active</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
<paramdef>char **<parameter>session</parameter></paramdef>
<paramdef>uid_t *<parameter>uid</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_get_sessions</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
<paramdef>char ***<parameter>sessions</parameter></paramdef>
<paramdef>uid_t **<parameter>uid</parameter></paramdef>
<paramdef>unsigned int *<parameter>n_uids</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_can_multi_session</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_can_tty</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_seat_can_graphical</function></funcdef>
<paramdef>const char *<parameter>seat</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_seat_get_active()</function> may be used to
determine which session is currently active on a seat, if there is
any. Returns the session identifier and the user identifier of the
Unix user the session is belonging to. Either the session or the
user identifier parameter can be passed <constant>NULL</constant>,
in case only one of the parameters shall be queried. The returned
string needs to be freed with the libc
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use.</para>
<para><function>sd_seat_get_sessions()</function> may be used to
determine all sessions on the specified seat. Returns two arrays,
one (<constant>NULL</constant> terminated) with the session
identifiers of the sessions and one with the user identifiers of
the Unix users the sessions belong to. An additional parameter may
be used to return the number of entries in the latter array. This
value is the same the return value, if the latter is nonnegative.
The two arrays and the last parameter may be passed as
<constant>NULL</constant> in case these values need not to be
determined. The arrays and the strings referenced by them need to
be freed with the libc
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use. Note that instead of an empty array
<constant>NULL</constant> may be returned and should be considered
equivalent to an empty array.</para>
<para><function>sd_seat_can_multi_session()</function> may be used
to determine whether a specific seat is capable of multi-session,
i.e. allows multiple login sessions in parallel (with only one
being active at a time).</para>
<para><function>sd_seat_can_tty()</function> may be used to
determine whether a specific seat provides TTY functionality, i.e.
is useful as a text console.</para>
<para><function>sd_seat_can_graphical()</function> may be used to
determine whether a specific seat provides graphics functionality,
i.e. is useful as a graphics display.</para>
<para>If the <varname>seat</varname> parameter of any of these
functions is passed as <constant>NULL</constant>, the operation is
executed for the seat of the session of the calling process, if
there is any.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para> On success, <function>sd_seat_get_active()</function>
returns 0 or a positive integer. On success,
<function>sd_seat_get_sessions()</function> returns the number of
entries in the session identifier array. If the test succeeds,
<function>sd_seat_can_multi_session</function>,
<function>sd_seat_can_tty</function> and
<function>sd_seat_can_graphical</function> return a positive
integer, if it fails 0. On failure, these calls return a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ENODATA</constant></term>
<listitem><para>The given field is not specified for the described
seat.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENXIO</constant></term>
<listitem><para>The specified seat is unknown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An input parameter was invalid (out of range,
or NULL, where that is not accepted).</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
|
