sd_seat_get_active.xml revision b040723ea412209e0edf54647fa5aa4287411507
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny This file is part of systemd.
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny Copyright 2010 Lennart Poettering
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny systemd is free software; you can redistribute it and/or modify it
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny under the terms of the GNU Lesser General Public License as published by
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny the Free Software Foundation; either version 2.1 of the License, or
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny (at your option) any later version.
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny systemd is distributed in the hope that it will be useful, but
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny WITHOUT ANY WARRANTY; without even the implied warranty of
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny Lesser General Public License for more details.
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny You should have received a copy of the GNU Lesser General Public License
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny along with systemd; If not, see <http://www.gnu.org/licenses/>.
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny<refentry id="sd_seat_get_active" conditional='HAVE_PAM'>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <refentryinfo>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <authorgroup>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek </authorgroup>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek </refentryinfo>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <refentrytitle>sd_seat_get_active</refentrytitle>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <refnamediv>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <refpurpose>Determine state of a specific seat</refpurpose>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek </refnamediv>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <refsynopsisdiv>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <funcsynopsis>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcprototype>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <funcdef>int <function>sd_seat_get_active</function></funcdef>
bdbf4f169e4d5d00b0616df19f7a55debb407f78Pavel Březina <paramdef>const char* <parameter>seat</parameter></paramdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <paramdef>char** <parameter>session</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <paramdef>uid_t* <parameter>uid</parameter></paramdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek </funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcdef>int <function>sd_seat_get_sessions</function></funcdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <paramdef>const char* <parameter>seat</parameter></paramdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <paramdef>char*** <parameter>sessions</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <paramdef>uid_t** <parameter>uid</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <paramdef>unsigned int* <parameter>n_uids</parameter></paramdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek </funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcdef>int <function>sd_seat_can_multi_session</function></funcdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <paramdef>const char* <parameter>seat</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny </funcprototype>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <funcprototype>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <funcdef>int <function>sd_seat_can_tty</function></funcdef>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <paramdef>const char* <parameter>seat</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny </funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <funcdef>int <function>sd_seat_can_graphical</function></funcdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <paramdef>const char* <parameter>seat</parameter></paramdef>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny </funcprototype>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny </funcsynopsis>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny </refsynopsisdiv>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <para><function>sd_seat_get_active()</function> may be
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny used to determine which session is currently active on
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny a seat, if there is any. Returns the session
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny identifier and the user identifier of the Unix user
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny the session is belonging to. Either the session or the
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny user identifier parameter can be passed
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <constant>NULL</constant>, in case only one of the
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny parameters shall be queried. The returned string needs
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny to be freed with the libc
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny call after use.</para>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <para><function>sd_seat_get_sessions()</function> may
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny be used to determine all sessions on the specified
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny seat. Returns two arrays, one (<constant>NULL</constant> terminated) with
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny the session identifiers of the sessions and one with
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny the user identifiers of the Unix users the sessions
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny belong to. An additional parameter may be used to
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny return the number of entries in the latter array. The
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny two arrays and the latter parameter may be passed as
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <constant>NULL</constant> in case these values need not to be
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny determined. The arrays and the strings referenced by
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny them need to be freed with the libc
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny call after use. Note that instead of an empty array
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <constant>NULL</constant> may be returned and should be considered
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny equivalent to an empty array.</para>
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny <para><function>sd_seat_can_multi_session()</function>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek may be used to determine whether a specific seat is
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek capable of multi-session, i.e. allows multiple login
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek sessions in parallel (with only one being active at a
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek time).</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <para><function>sd_seat_can_tty()</function> may be
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek used to determine whether a specific seat provides TTY
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek functionality, i.e. is useful as a text console.</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <para><function>sd_seat_can_graphical()</function> may
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek be used to determine whether a specific seat provides
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek graphics functionality, i.e. is useful as a graphics
99bac83188601c2b07e0b141aac7dc7d882b464aSumit Bose display.</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <para>If the <varname>seat</varname> parameter of any
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek of these functions is passed as
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <constant>NULL</constant>, the operation is executed
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek for the seat of the session of the calling process, if
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek there is any.</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <para> On success,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek returns 0 or a positive integer. On success,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <function>sd_seat_get_sessions()</function> returns
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek the number of entries in the session identifier
c0f9698cd951b7223f251ff2511c4b22a6e4ba60Jan Zeleny array. If the test succeeds,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <function>sd_seat_can_graphical</function> return a
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek positive integer, if it fails 0. On failure, these
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek calls return a negative errno-style error code.</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <para>The <function>sd_seat_get_active()</function>,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <function>sd_seat_can_multi_session()</function>,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <function>sd_seat_can_grapical()</function> interfaces
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek are available as a shared library, which can be compiled
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek and linked to with the
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <constant>libsystemd-login</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek file.</para>
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
8ba8222afca3026fd67af08e224b1d9e848aceaaJakub Hrozek <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>