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                 <refpurpose>Determine state of a specific seat</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <funcsynopsis>
  54                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  55
  56                         <funcprototype>
  57                                 <funcdef>int <function>sd_seat_get_active</function></funcdef>
  58                                 <paramdef>const char* <parameter>seat</parameter></paramdef>
  59                                 <paramdef>char** <parameter>session</parameter></paramdef>
  60                                 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
  61                         </funcprototype>
  62
  63                         <funcprototype>
  64                                 <funcdef>int <function>sd_seat_get_sessions</function></funcdef>
  65                                 <paramdef>const char* <parameter>seat</parameter></paramdef>
  66                                 <paramdef>char*** <parameter>sessions</parameter></paramdef>
  67                                 <paramdef>uid_t** <parameter>uid</parameter></paramdef>
  68                                 <paramdef>unsigned int* <parameter>n_uids</parameter></paramdef>
  69                         </funcprototype>
  70
  71                         <funcprototype>
  72                                 <funcdef>int <function>sd_seat_can_multi_session</function></funcdef>
  73                                 <paramdef>const char* <parameter>seat</parameter></paramdef>
  74                         </funcprototype>
  75
  76                         <funcprototype>
  77                                 <funcdef>int <function>sd_seat_can_tty</function></funcdef>
  78                                 <paramdef>const char* <parameter>seat</parameter></paramdef>
  79                         </funcprototype>
  80
  81                         <funcprototype>
  82                                 <funcdef>int <function>sd_seat_can_graphical</function></funcdef>
  83                                 <paramdef>const char* <parameter>seat</parameter></paramdef>
  84                         </funcprototype>
  85                 </funcsynopsis>
  86         </refsynopsisdiv>
  87
  88         <refsect1>
  89                 <title>Description</title>
  90
  91                 <para><function>sd_seat_get_active()</function> may be
  92                 used to determine which session is currently active on
  93                 a seat, if there is any. Returns the session
  94                 identifier and the user identifier of the Unix user
  95                 the session is belonging to. Either the session or the
  96                 user identifier parameter can be passed
  97                 <constant>NULL</constant>, in case only one of the
  98                 parameters shall be queried. The returned string needs
  99                 to be freed with the libc
 100                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 101                 call after use.</para>
 102
 103                 <para><function>sd_seat_get_sessions()</function> may
 104                 be used to determine all sessions on the specified
 105                 seat. Returns two arrays, one (<constant>NULL</constant> terminated) with
 106                 the session identifiers of the sessions and one with
 107                 the user identifiers of the Unix users the sessions
 108                 belong to. An additional parameter may be used to
 109                 return the number of entries in the latter array. The
 110                 two arrays and the latter 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
 113                 them need to be freed with the libc
 114                 <citerefentry><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>
 120                 may be used to determine whether a specific seat is
 121                 capable of multi-session, i.e. allows multiple login
 122                 sessions in parallel (with only one being active at a
 123                 time).</para>
 124
 125                 <para><function>sd_seat_can_tty()</function> may be
 126                 used to determine whether a specific seat provides TTY
 127                 functionality, i.e. is useful as a text console.</para>
 128
 129                 <para><function>sd_seat_can_graphical()</function> may
 130                 be used to determine whether a specific seat provides
 131                 graphics functionality, i.e. is useful as a graphics
 132                 display.</para>
 133
 134                 <para>If the <varname>seat</varname> parameter of any
 135                 of these functions is passed as
 136                 <constant>NULL</constant>, the operation is executed
 137                 for the seat of the session of the calling process, if
 138                 there is any.</para>
 139         </refsect1>
 140
 141         <refsect1>
 142                 <title>Return Value</title>
 143
 144                 <para> On success
 145                 <function>sd_seat_get_active()</function>
 146                 returns 0 or a positive integer. On success
 147                 <function>sd_seat_get_sessions()</function> returns
 148                 the number of entries in the session identifier
 149                 array. If the test succeeds,
 150                 <function>sd_seat_can_multi_session</function>,
 151                 <function>sd_seat_can_tty</function> and
 152                 <function>sd_seat_can_graphical</function> return a
 153                 positive integer, if it fails 0. On failure, these
 154                 calls return a negative errno-style error code.</para>
 155         </refsect1>
 156
 157         <refsect1>
 158                 <title>Notes</title>
 159
 160                 <para>The <function>sd_seat_get_active()</function>,
 161                 <function>sd_seat_get_sessions()</function>,
 162                 <function>sd_seat_can_multi_session()</function>,
 163                 <function>sd_seat_can_tty()</function> and
 164                 <function>sd_seat_can_grapical()</function> interfaces
 165                 are available as shared library, which can be compiled
 166                 and linked to with the
 167                 <constant>libsystemd-login</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 168                 file.</para>
 169         </refsect1>
 170
 171         <refsect1>
 172                 <title>See Also</title>
 173
 174                 <para>
 175                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 176                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177                         <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 178                 </para>
 179         </refsect1>
 180
 181 </refentry>