chiark / gitweb /
headers: fix git URLs for source files
[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 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 General Public License as published by
12   the Free Software Foundation; either version 2 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   General Public License for more details.
19
20   You should have received a copy of the GNU 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>session</parameter></paramdef>
74                         </funcprototype>
75                 </funcsynopsis>
76         </refsynopsisdiv>
77
78         <refsect1>
79                 <title>Description</title>
80
81                 <para><function>sd_seat_get_active()</function> may be
82                 used to determine which session is currently active on
83                 a seat, if there is any. Returns the session
84                 identifier and the user identifier of the Unix user
85                 the session is belonging to. Either the session or the
86                 user identifier parameter can be be passed NULL, in
87                 case only one of the parameters shall be queried. The
88                 returned string needs to be freed with the libc
89                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
90                 call after use.</para>
91
92                 <para><function>sd_seat_get_sessions()</function> may
93                 be used to determine all sessions on the specified
94                 seat. Returns two arrays, one (NULL terminated) with
95                 the session identifiers of the sessions and one with
96                 the user identifiers of the Unix users the sessions
97                 belong to. An additional parameter may be used to
98                 return the number of entries in the latter array. The
99                 two arrays and the latter parameter may be passed as
100                 NULL in case these values need not to be
101                 determined. The arrays and the strings referenced by
102                 them need to be freed with the libc
103                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
104                 call after use. Note that instead of an empty array
105                 NULL may be returned and should be considered
106                 equivalent to an empty array.</para>
107
108                 <para><function>sd_seat_can_multi_session()</function>
109                 may be used to determine whether a specific seat is
110                 capable of multi-session, i.e. allows multiple login
111                 sessions in parallel (whith only one being active at a
112                 time).</para>
113         </refsect1>
114
115         <refsect1>
116                 <title>Return Value</title>
117
118                 <para> On success
119                 <function>sd_seat_get_active()</function> return
120                 return 0 or a positive integer. On success
121                 <function>sd_seat_get_sessions()</function> returns
122                 the number of entries in the session identifier
123                 array. If the test succeeds
124                 <function>sd_seat_can_multi_session</function> returns
125                 a positive integer, if it fails 0. On failure, these
126                 calls return a negative errno-style error code.</para>
127         </refsect1>
128
129         <refsect1>
130                 <title>Notes</title>
131
132                 <para>The <function>sd_seat_get_active()</function>,
133                 <function>sd_seat_get_sessions()</function>, and
134                 <function>sd_seat_can_multi_session()</function> interfaces
135                 are available as shared library, which can be compiled
136                 and linked to with the
137                 <literal>libsystemd-login</literal>
138                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
139                 file.</para>
140         </refsect1>
141
142         <refsect1>
143                 <title>See Also</title>
144
145                 <para>
146                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
148                         <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
149                 </para>
150         </refsect1>
151
152 </refentry>