chiark / gitweb /
tree-wide: add SD_ID128_MAKE_STR, remove LOG_MESSAGE_ID
[elogind.git] / 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 elogind.
7
8   Copyright 2010 Lennart Poettering
9
10   elogind 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   elogind 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 elogind; 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>elogind</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;elogind/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_graphical()</function> interfaces are
196     available as a shared library, which can be compiled and linked to
197     with the
198     <constant>libelogind</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>elogind</refentrytitle><manvolnum>8</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>