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">
  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* <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 be passed NULL, in
  97                 case only one of the parameters shall be queried. The
  98                 returned string needs to be freed with the libc
  99                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 100                 call after use.</para>
 101
 102                 <para><function>sd_seat_get_sessions()</function> may
 103                 be used to determine all sessions on the specified
 104                 seat. Returns two arrays, one (NULL terminated) with
 105                 the session identifiers of the sessions and one with
 106                 the user identifiers of the Unix users the sessions
 107                 belong to. An additional parameter may be used to
 108                 return the number of entries in the latter array. The
 109                 two arrays and the latter parameter may be passed as
 110                 NULL in case these values need not to be
 111                 determined. The arrays and the strings referenced by
 112                 them need to be freed with the libc
 113                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114                 call after use. Note that instead of an empty array
 115                 NULL may be returned and should be considered
 116                 equivalent to an empty array.</para>
 117
 118                 <para><function>sd_seat_can_multi_session()</function>
 119                 may be used to determine whether a specific seat is
 120                 capable of multi-session, i.e. allows multiple login
 121                 sessions in parallel (with only one being active at a
 122                 time).</para>
 123
 124                 <para><function>sd_seat_can_tty()</function> may be
 125                 used to determine whether a specific seat provides TTY
 126                 functionality, i.e. is useful as a text console.</para>
 127
 128                 <para><function>sd_seat_can_graphical()</function> may
 129                 be used to determine whether a specific seat provides
 130                 graphics functionality, i.e. is useful as a graphics
 131                 display.</para>
 132
 133                 <para>If the <literal>seat</literal> parameter of any
 134                 of these functions is passed as NULL the operation is
 135                 executed for the seat of the session of the calling
 136                 process, if there is any.</para>
 137         </refsect1>
 138
 139         <refsect1>
 140                 <title>Return Value</title>
 141
 142                 <para> On success
 143                 <function>sd_seat_get_active()</function> return
 144                 return 0 or a positive integer. On success
 145                 <function>sd_seat_get_sessions()</function> returns
 146                 the number of entries in the session identifier
 147                 array. If the test succeeds
 148                 <function>sd_seat_can_multi_session</function>,
 149                 <function>sd_seat_can_tty</function> and
 150                 <function>sd_seat_can_graphical</function> return a
 151                 positive integer, if it fails 0. On failure, these
 152                 calls return a negative errno-style error code.</para>
 153         </refsect1>
 154
 155         <refsect1>
 156                 <title>Notes</title>
 157
 158                 <para>The <function>sd_seat_get_active()</function>,
 159                 <function>sd_seat_get_sessions()</function>,
 160                 <function>sd_seat_can_multi_session()</function>,
 161                 <function>sd_seat_can_tty()</function> and
 162                 <function>sd_seat_can_grapical()</function> interfaces
 163                 are available as shared library, which can be compiled
 164                 and linked to with the
 165                 <literal>libsystemd-login</literal>
 166                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 167                 file.</para>
 168         </refsect1>
 169
 170         <refsect1>
 171                 <title>See Also</title>
 172
 173                 <para>
 174                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 175                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176                         <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 177                 </para>
 178         </refsect1>
 179
 180 </refentry>