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