chiark / gitweb /
man: typo fixes
[elogind.git] / man / sd_uid_get_state.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_uid_get_state" conditional='HAVE_PAM'>
25
26   <refentryinfo>
27     <title>sd_uid_get_state</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_uid_get_state</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>sd_uid_get_state</refname>
47     <refname>sd_uid_is_on_seat</refname>
48     <refname>sd_uid_get_sessions</refname>
49     <refname>sd_uid_get_seats</refname>
50     <refname>sd_uid_get_display</refname>
51     <refpurpose>Determine login state of a specific Unix user ID</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_uid_get_state</function></funcdef>
60         <paramdef>uid_t <parameter>uid</parameter></paramdef>
61         <paramdef>char **<parameter>state</parameter></paramdef>
62       </funcprototype>
63
64       <funcprototype>
65         <funcdef>int <function>sd_uid_is_on_seat</function></funcdef>
66         <paramdef>uid_t <parameter>uid</parameter></paramdef>
67         <paramdef>int <parameter>require_active</parameter></paramdef>
68         <paramdef>const char *<parameter>seat</parameter></paramdef>
69       </funcprototype>
70
71       <funcprototype>
72         <funcdef>int <function>sd_uid_get_sessions</function></funcdef>
73         <paramdef>uid_t <parameter>uid</parameter></paramdef>
74         <paramdef>int <parameter>require_active</parameter></paramdef>
75         <paramdef>char ***<parameter>sessions</parameter></paramdef>
76       </funcprototype>
77
78       <funcprototype>
79         <funcdef>int <function>sd_uid_get_seats</function></funcdef>
80         <paramdef>uid_t <parameter>uid</parameter></paramdef>
81         <paramdef>int <parameter>require_active</parameter></paramdef>
82         <paramdef>char ***<parameter>seats</parameter></paramdef>
83       </funcprototype>
84
85       <funcprototype>
86         <funcdef>int <function>sd_uid_get_display</function></funcdef>
87         <paramdef>uid_t <parameter>uid</parameter></paramdef>
88         <paramdef>char **<parameter>session</parameter></paramdef>
89       </funcprototype>
90     </funcsynopsis>
91   </refsynopsisdiv>
92
93   <refsect1>
94     <title>Description</title>
95
96     <para><function>sd_uid_get_state()</function> may be used to
97     determine the login state of a specific Unix user identifier. The
98     following states are currently known: <literal>offline</literal>
99     (user not logged in at all), <literal>lingering</literal> (user
100     not logged in, but some user services running),
101     <literal>online</literal> (user logged in, but not active, i.e.
102     has no session in the foreground), <literal>active</literal> (user
103     logged in, and has at least one active session, i.e. one session
104     in the foreground), <literal>closing</literal> (user not logged
105     in, and not lingering, but some processes are still around). In
106     the future additional states might be defined, client code should
107     be written to be robust in regards to additional state strings
108     being returned. The returned string needs to be freed with the
109     libc
110     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
111     call after use.</para>
112
113     <para><function>sd_uid_is_on_seat()</function> may be used to
114     determine whether a specific user is logged in or active on a
115     specific seat. Accepts a Unix user identifier and a seat
116     identifier string as parameters. The
117     <parameter>require_active</parameter> parameter is a boolean
118     value. If non-zero (true), this function will test if the user is
119     active (i.e. has a session that is in the foreground and accepting
120     user input) on the specified seat, otherwise (false) only if the
121     user is logged in (and possibly inactive) on the specified
122     seat.</para>
123
124     <para><function>sd_uid_get_sessions()</function> may be used to
125     determine the current sessions of the specified user. Accepts a
126     Unix user identifier as parameter. The
127     <parameter>require_active</parameter> parameter controls whether
128     the returned list shall consist of only those sessions where the
129     user is currently active (&gt; 0), where the user is currently
130     online but possibly inactive (= 0), or logged in at all but
131     possibly closing the session (&lt; 0). The call returns a
132     <constant>NULL</constant> terminated string array of session
133     identifiers in <parameter>sessions</parameter> which needs to be
134     freed by the caller with the libc
135     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
136     call after use, including all the strings referenced. If the
137     string array parameter is passed as <constant>NULL</constant>, the
138     array will not be filled in, but the return code still indicates
139     the number of current sessions. Note that instead of an empty
140     array <constant>NULL</constant> may be returned and should be
141     considered equivalent to an empty array.</para>
142
143     <para>Similarly, <function>sd_uid_get_seats()</function> may be
144     used to determine the list of seats on which the user currently
145     has sessions. Similar semantics apply, however note that the user
146     may have multiple sessions on the same seat as well as sessions
147     with no attached seat and hence the number of entries in the
148     returned array may differ from the one returned by
149     <function>sd_uid_get_sessions()</function>.</para>
150
151     <para><function>sd_uid_get_display()</function> returns the name
152     of the "primary" session of a user. If the user has graphical
153     sessions, it will be the oldest graphical session. Otherwise, it
154     will be the oldest open session.</para>
155   </refsect1>
156
157   <refsect1>
158     <title>Return Value</title>
159
160     <para>On success, <function>sd_uid_get_state()</function> returns
161     0 or a positive integer. If the test succeeds,
162     <function>sd_uid_is_on_seat()</function> returns a positive
163     integer; if it fails, 0.
164     <function>sd_uid_get_sessions()</function> and
165     <function>sd_uid_get_seats()</function> return the number of
166     entries in the returned arrays.
167     <function>sd_uid_get_display()</function> returns a non-negative
168     code on success. On failure, these calls return a negative
169     errno-style error code.</para>
170   </refsect1>
171
172   <refsect1>
173     <title>Notes</title>
174
175     <para>Functions described here are available as a shared library,
176     and can be compiled and linked to using the
177     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
178     entry.</para>
179   </refsect1>
180
181   <refsect1>
182     <title>History</title>
183
184     <para><function>sd_uid_get_state()</function>,
185     <function>sd_uid_is_on_seat()</function>,
186     <function>sd_uid_get_sessions()</function>, and
187     <function>sd_uid_get_seats()</function> functions were added in
188     systemd-31.</para>
189
190     <para><function>sd_uid_get_display()</function> was added in
191     systemd-213.</para>
192   </refsect1>
193
194   <refsect1>
195     <title>See Also</title>
196
197     <para>
198       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
199       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200       <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
201     </para>
202   </refsect1>
203
204 </refentry>