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