1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_seat_get_active" conditional='HAVE_PAM'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_seat_get_active
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_seat_get_active
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_seat_get_active
</refname>
21 <refname>sd_seat_get_sessions
</refname>
22 <refname>sd_seat_can_tty
</refname>
23 <refname>sd_seat_can_graphical
</refname>
24 <refpurpose>Determine state of a specific seat
</refpurpose>
29 <funcsynopsisinfo>#include
<systemd/sd-login.h
></funcsynopsisinfo>
32 <funcdef>int
<function>sd_seat_get_active
</function></funcdef>
33 <paramdef>const char *
<parameter>seat
</parameter></paramdef>
34 <paramdef>char **
<parameter>session
</parameter></paramdef>
35 <paramdef>uid_t *
<parameter>uid
</parameter></paramdef>
39 <funcdef>int
<function>sd_seat_get_sessions
</function></funcdef>
40 <paramdef>const char *
<parameter>seat
</parameter></paramdef>
41 <paramdef>char ***
<parameter>sessions
</parameter></paramdef>
42 <paramdef>uid_t **
<parameter>uid
</parameter></paramdef>
43 <paramdef>unsigned int *
<parameter>n_uids
</parameter></paramdef>
47 <funcdef>int
<function>sd_seat_can_tty
</function></funcdef>
48 <paramdef>const char *
<parameter>seat
</parameter></paramdef>
52 <funcdef>int
<function>sd_seat_can_graphical
</function></funcdef>
53 <paramdef>const char *
<parameter>seat
</parameter></paramdef>
59 <title>Description
</title>
61 <para><function>sd_seat_get_active()
</function> may be used to
62 determine which session is currently active on a seat, if there is
63 any. Returns the session identifier and the user identifier of the
64 Unix user the session is belonging to. Either the session or the
65 user identifier parameter can be passed
<constant>NULL
</constant>,
66 in case only one of the parameters shall be queried. The returned
67 string needs to be freed with the libc
68 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
69 call after use.
</para>
71 <para><function>sd_seat_get_sessions()
</function> may be used to
72 determine all sessions on the specified seat. Returns two arrays,
73 one (
<constant>NULL
</constant> terminated) with the session
74 identifiers of the sessions and one with the user identifiers of
75 the Unix users the sessions belong to. An additional parameter may
76 be used to return the number of entries in the latter array. This
77 value is the same the return value, if the latter is nonnegative.
78 The two arrays and the last parameter may be passed as
79 <constant>NULL
</constant> in case these values need not to be
80 determined. The arrays and the strings referenced by them need to
81 be freed with the libc
82 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
83 call after use. Note that instead of an empty array
84 <constant>NULL
</constant> may be returned and should be considered
85 equivalent to an empty array.
</para>
87 <para><function>sd_seat_can_tty()
</function> may be used to
88 determine whether a specific seat provides TTY functionality, i.e.
89 is useful as a text console.
</para>
91 <para><function>sd_seat_can_graphical()
</function> may be used to
92 determine whether a specific seat provides graphics functionality,
93 i.e. is useful as a graphics display.
</para>
95 <para>If the
<varname>seat
</varname> parameter of any of these
96 functions is passed as
<constant>NULL
</constant>, the operation is
97 executed for the seat of the session of the calling process, if
102 <title>Return Value
</title>
104 <para> On success,
<function>sd_seat_get_active()
</function> returns
0 or a positive integer. On success,
105 <function>sd_seat_get_sessions()
</function> returns the number of entries in the session identifier
106 array. If the test succeeds,
107 <function>sd_seat_can_tty
</function> and
<function>sd_seat_can_graphical
</function> return a positive
108 integer, if it fails
0. On failure, these calls return a negative errno-style error code.
</para>
111 <title>Errors
</title>
113 <para>Returned errors may indicate the following problems:
</para>
118 <term><constant>-ENODATA
</constant></term>
120 <listitem><para>The given field is not specified for the described seat.
</para>
125 <term><constant>-ENXIO
</constant></term>
127 <listitem><para>The specified seat is unknown.
</para>
132 <term><constant>-EINVAL
</constant></term>
134 <listitem><para>An input parameter was invalid (out of range, or
<constant>NULL
</constant>, where
135 that is not accepted).
</para></listitem>
139 <term><constant>-ENOMEM
</constant></term>
141 <listitem><para>Memory allocation failed.
</para></listitem>
147 <xi:include href=
"libsystemd-pkgconfig.xml" />
150 <title>History
</title>
152 <para>In the past,
<function>sd_seat_can_multi_session()
</function> was used to check whether the seat
153 supports multiple sessions. All seats support that now, so that function has been deprecated and always
158 <title>See Also
</title>
161 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
162 <citerefentry><refentrytitle>sd-login
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
163 <citerefentry><refentrytitle>sd_session_get_seat
</refentrytitle><manvolnum>3</manvolnum></citerefentry>