chiark / gitweb /
man: typo fixes
[elogind.git] / man / sd_login_monitor_new.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_login_monitor_new" conditional='HAVE_PAM'>
25
26   <refentryinfo>
27     <title>sd_login_monitor_new</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_login_monitor_new</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>sd_login_monitor_new</refname>
47     <refname>sd_login_monitor_unref</refname>
48     <refname>sd_login_monitor_flush</refname>
49     <refname>sd_login_monitor_get_fd</refname>
50     <refname>sd_login_monitor_get_events</refname>
51     <refname>sd_login_monitor_get_timeout</refname>
52     <refname>sd_login_monitor</refname>
53     <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>
54   </refnamediv>
55
56   <refsynopsisdiv>
57     <funcsynopsis>
58       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
59
60       <funcprototype>
61         <funcdef>int <function>sd_login_monitor_new</function></funcdef>
62         <paramdef>const char *<parameter>category</parameter></paramdef>
63         <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>
64       </funcprototype>
65
66       <funcprototype>
67         <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>
68         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
69       </funcprototype>
70
71       <funcprototype>
72         <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
73         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
74       </funcprototype>
75
76       <funcprototype>
77         <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
78         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
79       </funcprototype>
80
81       <funcprototype>
82         <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
83         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
84       </funcprototype>
85
86       <funcprototype>
87         <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>
88         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
89         <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
90       </funcprototype>
91
92     </funcsynopsis>
93   </refsynopsisdiv>
94
95   <refsect1>
96     <title>Description</title>
97
98     <para><function>sd_login_monitor_new()</function> may be used to
99     monitor login sessions, users, seats, and virtual
100     machines/containers. Via a monitor object a file descriptor can be
101     integrated into an application defined event loop which is woken
102     up each time a user logs in, logs out or a seat is added or
103     removed, or a session, user, seat or virtual machine/container
104     changes state otherwise. The first parameter takes a string which
105     can be <literal>seat</literal> (to get only notifications about
106     seats being added, removed or changed), <literal>session</literal>
107     (to get only notifications about sessions being created or removed
108     or changed), <literal>uid</literal> (to get only notifications
109     when a user changes state in respect to logins) or
110     <literal>machine</literal> (to get only notifications when a
111     virtual machine or container is started or stopped). If
112     notifications shall be generated in all these conditions,
113     <constant>NULL</constant> may be passed. Note that in the future
114     additional categories may be defined. The second parameter returns
115     a monitor object and needs to be freed with the
116     <function>sd_login_monitor_unref()</function> call after
117     use.</para>
118
119     <para><function>sd_login_monitor_unref()</function> may be used to
120     destroy a monitor object. Note that this will invalidate any file
121     descriptor returned by
122     <function>sd_login_monitor_get_fd()</function>.</para>
123
124     <para><function>sd_login_monitor_flush()</function> may be used to
125     reset the wakeup state of the monitor object. Whenever an event
126     causes the monitor to wake up the event loop via the file
127     descriptor this function needs to be called to reset the wake-up
128     state. If this call is not invoked, the file descriptor will
129     immediately wake up the event loop again.</para>
130
131     <para><function>sd_login_monitor_get_fd()</function> may be used
132     to retrieve the file descriptor of the monitor object that may be
133     integrated in an application defined event loop, based around
134     <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
135     or a similar interface. The application should include the
136     returned file descriptor as wake-up source for the events mask
137     returned by <function>sd_login_monitor_get_events()</function>. It
138     should pass a timeout value as returned by
139     <function>sd_login_monitor_get_timeout()</function>. Whenever a
140     wake-up is triggered the file descriptor needs to be reset via
141     <function>sd_login_monitor_flush()</function>. An application
142     needs to reread the login state with a function like
143     <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
144     or similar to determine what changed.</para>
145
146     <para><function>sd_login_monitor_get_events()</function> will
147     return the <function>poll()</function> mask to wait for. This
148     function will return a combination of <constant>POLLIN</constant>,
149     <constant>POLLOUT</constant> and similar to fill into the
150     <literal>.events</literal> field of <varname>struct
151     pollfd</varname>.</para>
152
153     <para><function>sd_login_monitor_get_timeout()</function> will
154     return a timeout value for usage in <function>poll()</function>.
155     This returns a value in microseconds since the epoch of
156     <constant>CLOCK_MONOTONIC</constant> for timing out
157     <function>poll()</function> in <varname>timeout_usec</varname>.
158     See
159     <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
160     for details about <constant>CLOCK_MONOTONIC</constant>. If there
161     is no timeout to wait for this will fill in <constant>(uint64_t)
162     -1</constant> instead. Note that <function>poll()</function> takes
163     a relative timeout in milliseconds rather than an absolute timeout
164     in microseconds. To convert the absolute 'us' timeout into
165     relative 'ms', use code like the following:</para>
166
167     <programlisting>uint64_t t;
168 int msec;
169 sd_login_monitor_get_timeout(m, &amp;t);
170 if (t == (uint64_t) -1)
171   msec = -1;
172 else {
173   struct timespec ts;
174   uint64_t n;
175   clock_getttime(CLOCK_MONOTONIC, &amp;ts);
176   n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
177   msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
178 }</programlisting>
179
180     <para>The code above does not do any error checking for brevity's
181     sake. The calculated <varname>msec</varname> integer can be passed
182     directly as <function>poll()</function>'s timeout
183     parameter.</para>
184   </refsect1>
185
186   <refsect1>
187     <title>Return Value</title>
188
189     <para>On success,
190     <function>sd_login_monitor_new()</function>,
191     <function>sd_login_monitor_flush()</function> and
192     <function>sd_login_monitor_get_timeout()</function>
193     return 0 or a positive integer. On success,
194     <function>sd_login_monitor_get_fd()</function> returns
195     a Unix file descriptor. On success,
196     <function>sd_login_monitor_get_events()</function>
197     returns a combination of <constant>POLLIN</constant>,
198     <constant>POLLOUT</constant> and suchlike. On failure,
199     these calls return a negative errno-style error
200     code.</para>
201
202     <para><function>sd_login_monitor_unref()</function>
203     always returns <constant>NULL</constant>.</para>
204   </refsect1>
205
206   <refsect1>
207     <title>Notes</title>
208
209     <para>The <function>sd_login_monitor_new()</function>,
210     <function>sd_login_monitor_unref()</function>,
211     <function>sd_login_monitor_flush()</function>,
212     <function>sd_login_monitor_get_fd()</function>,
213     <function>sd_login_monitor_get_events()</function> and
214     <function>sd_login_monitor_get_timeout()</function>
215     interfaces are available as a shared library, which can be
216     compiled and linked to with the
217     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
218     file.</para>
219   </refsect1>
220
221   <refsect1>
222     <title>See Also</title>
223
224     <para>
225       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
226       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
227       <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
228       <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
229       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
230     </para>
231   </refsect1>
232
233 </refentry>