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. This
 109     value is the same the return value, if the latter is nonnegative.
 110     The two arrays and the last parameter may be passed as
 111     <constant>NULL</constant> in case these values need not to be
 112     determined. The arrays and the strings referenced by them need to
 113     be freed with the libc
 114     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 115     call after use. Note that instead of an empty array
 116     <constant>NULL</constant> may be returned and should be considered
 117     equivalent to an empty array.</para>
 118
 119     <para><function>sd_seat_can_multi_session()</function> may be used
 120     to determine whether a specific seat is capable of multi-session,
 121     i.e. allows multiple login sessions in parallel (with only one
 122     being active at a time).</para>
 123
 124     <para><function>sd_seat_can_tty()</function> may be used to
 125     determine whether a specific seat provides TTY functionality, i.e.
 126     is useful as a text console.</para>
 127
 128     <para><function>sd_seat_can_graphical()</function> may be used to
 129     determine whether a specific seat provides graphics functionality,
 130     i.e. is useful as a graphics display.</para>
 131
 132     <para>If the <varname>seat</varname> parameter of any of these
 133     functions is passed as <constant>NULL</constant>, the operation is
 134     executed for the seat of the session of the calling process, if
 135     there is any.</para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Return Value</title>
 140
 141     <para> On success, <function>sd_seat_get_active()</function>
 142     returns 0 or a positive integer. On success,
 143     <function>sd_seat_get_sessions()</function> returns the number of
 144     entries in the session identifier array. If the test succeeds,
 145     <function>sd_seat_can_multi_session</function>,
 146     <function>sd_seat_can_tty</function> and
 147     <function>sd_seat_can_graphical</function> return a positive
 148     integer, if it fails 0. On failure, these calls return a negative
 149     errno-style error code.</para>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Errors</title>
 154
 155     <para>Returned errors may indicate the following problems:</para>
 156
 157     <variablelist>
 158
 159       <varlistentry>
 160         <term><constant>-ENODATA</constant></term>
 161
 162         <listitem><para>The given field is not specified for the described
 163         seat.</para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><constant>-ENXIO</constant></term>
 169
 170         <listitem><para>The specified seat is unknown.</para>
 171         </listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><constant>-EINVAL</constant></term>
 176
 177         <listitem><para>An input parameter was invalid (out of range,
 178         or NULL, where that is not accepted).</para></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><constant>-ENOMEM</constant></term>
 183
 184         <listitem><para>Memory allocation failed.</para></listitem>
 185       </varlistentry>
 186     </variablelist>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Notes</title>
 191
 192     <para>The <function>sd_seat_get_active()</function>,
 193     <function>sd_seat_get_sessions()</function>,
 194     <function>sd_seat_can_multi_session()</function>,
 195     <function>sd_seat_can_tty()</function> and
 196     <function>sd_seat_can_graphical()</function> interfaces are
 197     available as a shared library, which can be compiled and linked to
 198     with the
 199     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 200     file.</para>
 201   </refsect1>
 202
 203   <refsect1>
 204     <title>See Also</title>
 205
 206     <para>
 207       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 208       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 210     </para>
 211   </refsect1>
 212
 213 </refentry>