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