man/sd_seat_get_active.xml

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