0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering This file is part of systemd.
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering Copyright 2010 Lennart Poettering
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering (at your option) any later version.
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering systemd is distributed in the hope that it will be useful, but
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
0b3b020a178cf3b957fed627de13c895773995ecLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
56ba3c78ae35065064c4289a0c8e22a81256af20Zbigniew Jędrzejewski-Szmek<refentry id="sd_seat_get_active" conditional='HAVE_PAM'>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>sd_seat_get_active</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_seat_get_active</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_seat_get_active</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_seat_get_sessions</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_seat_can_multi_session</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_seat_can_tty</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_seat_can_graphical</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Determine state of a specific seat</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_seat_get_active</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>seat</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>char **<parameter>session</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uid_t *<parameter>uid</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_seat_get_sessions</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>seat</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>char ***<parameter>sessions</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uid_t **<parameter>uid</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>unsigned int *<parameter>n_uids</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_seat_can_multi_session</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>seat</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_seat_can_tty</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>seat</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_seat_can_graphical</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>seat</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_seat_get_active()</function> may be used to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek determine which session is currently active on a seat, if there is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek any. Returns the session identifier and the user identifier of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Unix user the session is belonging to. Either the session or the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek user identifier parameter can be passed <constant>NULL</constant>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in case only one of the parameters shall be queried. The returned
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek string needs to be freed with the libc
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek call after use.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_seat_get_sessions()</function> may be used to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek determine all sessions on the specified seat. Returns two arrays,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek one (<constant>NULL</constant> terminated) with the session
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek identifiers of the sessions and one with the user identifiers of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the Unix users the sessions belong to. An additional parameter may
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be used to return the number of entries in the latter array. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek two arrays and the latter parameter may be passed as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>NULL</constant> in case these values need not to be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek determined. The arrays and the strings referenced by them need to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be freed with the libc
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek call after use. Note that instead of an empty array
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>NULL</constant> may be returned and should be considered
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek equivalent to an empty array.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_seat_can_multi_session()</function> may be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to determine whether a specific seat is capable of multi-session,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek i.e. allows multiple login sessions in parallel (with only one
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek being active at a time).</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_seat_can_tty()</function> may be used to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek determine whether a specific seat provides TTY functionality, i.e.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is useful as a text console.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_seat_can_graphical()</function> may be used to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek determine whether a specific seat provides graphics functionality,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek i.e. is useful as a graphics display.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the <varname>seat</varname> parameter of any of these
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek functions is passed as <constant>NULL</constant>, the operation is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek executed for the seat of the session of the calling process, if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek there is any.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para> On success, <function>sd_seat_get_active()</function>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek returns 0 or a positive integer. On success,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_get_sessions()</function> returns the number of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek entries in the session identifier array. If the test succeeds,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_can_multi_session</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_can_tty</function> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_can_graphical</function> return a positive
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek integer, if it fails 0. On failure, these calls return a negative
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek errno-style error code.</para>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <para>Returned errors may indicate the following problems:</para>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <variablelist>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <term><constant>-ENODATA</constant></term>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <listitem><para>The given field is not specified for the described
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering </varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <listitem><para>The specified seat is unknown.</para>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering </varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <term><constant>-EINVAL</constant></term>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <listitem><para>An input parameter was invalid (out of range,
7ca4155737730ece73ae4b4ac80571005cb99b69Jan Engelhardt or NULL, where that is not accepted).</para></listitem>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering </varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <term><constant>-ENOMEM</constant></term>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering <listitem><para>Memory allocation failed.</para></listitem>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering </varlistentry>
707b66c66381c899d7ef640e158ffdd5bcff4debLennart Poettering </variablelist>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The <function>sd_seat_get_active()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_get_sessions()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_can_multi_session()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_seat_can_tty()</function> and
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk <function>sd_seat_can_graphical()</function> interfaces are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available as a shared library, which can be compiled and linked to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>