1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id="sd_seat_get_active" conditional='HAVE_PAM'>
30 <title>sd_seat_get_active</title>
31 <productname>systemd</productname>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
44 <refentrytitle>sd_seat_get_active</refentrytitle>
45 <manvolnum>3</manvolnum>
49 <refname>sd_seat_get_active</refname>
50 <refname>sd_seat_get_sessions</refname>
51 <refname>sd_seat_can_multi_session</refname>
52 <refname>sd_seat_can_tty</refname>
53 <refname>sd_seat_can_graphical</refname>
54 <refpurpose>Determine state of a specific seat</refpurpose>
59 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
62 <funcdef>int <function>sd_seat_get_active</function></funcdef>
63 <paramdef>const char *<parameter>seat</parameter></paramdef>
64 <paramdef>char **<parameter>session</parameter></paramdef>
65 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
69 <funcdef>int <function>sd_seat_get_sessions</function></funcdef>
70 <paramdef>const char *<parameter>seat</parameter></paramdef>
71 <paramdef>char ***<parameter>sessions</parameter></paramdef>
72 <paramdef>uid_t **<parameter>uid</parameter></paramdef>
73 <paramdef>unsigned int *<parameter>n_uids</parameter></paramdef>
77 <funcdef>int <function>sd_seat_can_multi_session</function></funcdef>
78 <paramdef>const char *<parameter>seat</parameter></paramdef>
82 <funcdef>int <function>sd_seat_can_tty</function></funcdef>
83 <paramdef>const char *<parameter>seat</parameter></paramdef>
87 <funcdef>int <function>sd_seat_can_graphical</function></funcdef>
88 <paramdef>const char *<parameter>seat</parameter></paramdef>
94 <title>Description</title>
96 <para><function>sd_seat_get_active()</function> may be used to
97 determine which session is currently active on a seat, if there is
98 any. Returns the session identifier and the user identifier of the
99 Unix user the session is belonging to. Either the session or the
100 user identifier parameter can be passed <constant>NULL</constant>,
101 in case only one of the parameters shall be queried. The returned
102 string needs to be freed with the libc
103 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
104 call after use.</para>
106 <para><function>sd_seat_get_sessions()</function> may be used to
107 determine all sessions on the specified seat. Returns two arrays,
108 one (<constant>NULL</constant> terminated) with the session
109 identifiers of the sessions and one with the user identifiers of
110 the Unix users the sessions belong to. An additional parameter may
111 be used to return the number of entries in the latter array. The
112 two arrays and the latter parameter may be passed as
113 <constant>NULL</constant> in case these values need not to be
114 determined. The arrays and the strings referenced by them need to
115 be freed with the libc
116 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
117 call after use. Note that instead of an empty array
118 <constant>NULL</constant> may be returned and should be considered
119 equivalent to an empty array.</para>
121 <para><function>sd_seat_can_multi_session()</function> may be used
122 to determine whether a specific seat is capable of multi-session,
123 i.e. allows multiple login sessions in parallel (with only one
124 being active at a time).</para>
126 <para><function>sd_seat_can_tty()</function> may be used to
127 determine whether a specific seat provides TTY functionality, i.e.
128 is useful as a text console.</para>
130 <para><function>sd_seat_can_graphical()</function> may be used to
131 determine whether a specific seat provides graphics functionality,
132 i.e. is useful as a graphics display.</para>
134 <para>If the <varname>seat</varname> parameter of any of these
135 functions is passed as <constant>NULL</constant>, the operation is
136 executed for the seat of the session of the calling process, if
141 <title>Return Value</title>
143 <para> On success, <function>sd_seat_get_active()</function>
144 returns 0 or a positive integer. On success,
145 <function>sd_seat_get_sessions()</function> returns the number of
146 entries in the session identifier array. If the test succeeds,
147 <function>sd_seat_can_multi_session</function>,
148 <function>sd_seat_can_tty</function> and
149 <function>sd_seat_can_graphical</function> return a positive
150 integer, if it fails 0. On failure, these calls return a negative
151 errno-style error code.</para>
157 <para>The <function>sd_seat_get_active()</function>,
158 <function>sd_seat_get_sessions()</function>,
159 <function>sd_seat_can_multi_session()</function>,
160 <function>sd_seat_can_tty()</function> and
161 <function>sd_seat_can_grapical()</function> interfaces are
162 available as a shared library, which can be compiled and linked to
164 <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
169 <title>See Also</title>
172 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>