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