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