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