man/sd_seat_get_active.xml

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