chiark / gitweb /
run: add a new "-t" mode for invoking a binary on an allocated TTY
[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
99                 be used to monitor login sessions, users, seats, and
100                 virtual machines/containers. Via a monitor object a
101                 file descriptor can be integrated into an application
102                 defined event loop which is woken up each time a user
103                 logs in, logs out or a seat is added or removed, or a
104                 session, user, seat or virtual machine/container
105                 changes state otherwise. The first parameter takes a
106                 string which can be <literal>seat</literal> (to get
107                 only notifications about seats being added, removed or
108                 changed), <literal>session</literal> (to get only
109                 notifications about sessions being created or removed
110                 or changed), <literal>uid</literal> (to get only
111                 notifications when a user changes state in respect to
112                 logins) or <literal>machine</literal> (to get only
113                 notifications when a virtual machine or container is
114                 started or stopped). If notifications shall be
115                 generated in all these conditions, <constant>NULL</constant> may be
116                 passed. Note that in the future additional categories
117                 may be defined. The second parameter returns a monitor
118                 object and needs to be freed with the
119                 <function>sd_login_monitor_unref()</function> call
120                 after use.</para>
121
122                 <para><function>sd_login_monitor_unref()</function>
123                 may be used to destroy a monitor object. Note that
124                 this will invalidate any file descriptor returned by
125                 <function>sd_login_monitor_get_fd()</function>.</para>
126
127                 <para><function>sd_login_monitor_flush()</function>
128                 may be used to reset the wakeup state of the monitor
129                 object. Whenever an event causes the monitor to wake
130                 up the event loop via the file descriptor this
131                 function needs to be called to reset the wake-up
132                 state. If this call is not invoked, the file descriptor
133                 will immediately wake up the event loop again.</para>
134
135                 <para><function>sd_login_monitor_get_fd()</function>
136                 may be used to retrieve the file descriptor of the
137                 monitor object that may be integrated in an
138                 application defined event loop, based around
139                 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
140                 or a similar interface. The application should include
141                 the returned file descriptor as wake-up source for the
142                 events mask returned by
143                 <function>sd_login_monitor_get_events()</function>. It
144                 should pass a timeout value as returned by
145                 <function>sd_login_monitor_get_timeout()</function>. Whenever
146                 a wake-up is triggered the file descriptor needs to be
147                 reset via
148                 <function>sd_login_monitor_flush()</function>. An
149                 application needs to reread the login state with a
150                 function like
151                 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
152                 or similar to determine what changed.</para>
153
154                 <para><function>sd_login_monitor_get_events()</function>
155                 will return the <function>poll()</function> mask to
156                 wait for. This function will return a combination of
157                 <constant>POLLIN</constant>, <constant>POLLOUT</constant>
158                 and similar to fill into the
159                 <literal>.events</literal> field of <varname>struct
160                 pollfd</varname>.</para>
161
162                 <para><function>sd_login_monitor_get_timeout()</function>
163                 will return a timeout value for usage in
164                 <function>poll()</function>. This returns a value in
165                 microseconds since the epoch of <constant>CLOCK_MONOTONIC</constant>
166                 for timing out <function>poll()</function> in
167                 <varname>timeout_usec</varname>. See
168                 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
169                 for details about
170                 <constant>CLOCK_MONOTONIC</constant>. If there is no
171                 timeout to wait for this will fill in
172                 <constant>(uint64_t) -1</constant> instead. Note that
173                 <function>poll()</function> takes a relative timeout
174                 in milliseconds rather than an absolute timeout in
175                 microseconds. To convert the absolute 'us' timeout into
176                 relative 'ms', use code like the following:</para>
177
178                 <programlisting>uint64_t t;
179 int msec;
180 sd_login_monitor_get_timeout(m, &amp;t);
181 if (t == (uint64_t) -1)
182         msec = -1;
183 else {
184         struct timespec ts;
185         uint64_t n;
186         clock_getttime(CLOCK_MONOTONIC, &amp;ts);
187         n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
188         msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
189 }</programlisting>
190
191                 <para>The code above does not do any error checking
192                 for brevity's sake. The calculated <varname>msec</varname>
193                 integer can be passed directly as
194                 <function>poll()</function>'s timeout
195                 parameter.</para>
196         </refsect1>
197
198         <refsect1>
199                 <title>Return Value</title>
200
201                 <para>On success,
202                 <function>sd_login_monitor_new()</function>,
203                 <function>sd_login_monitor_flush()</function> and
204                 <function>sd_login_monitor_get_timeout()</function>
205                 return 0 or a positive integer. On success,
206                 <function>sd_login_monitor_get_fd()</function> returns
207                 a Unix file descriptor. On success,
208                 <function>sd_login_monitor_get_events()</function>
209                 returns a combination of <constant>POLLIN</constant>,
210                 <constant>POLLOUT</constant> and suchlike. On failure,
211                 these calls return a negative errno-style error
212                 code.</para>
213
214                 <para><function>sd_login_monitor_unref()</function>
215                 always returns <constant>NULL</constant>.</para>
216         </refsect1>
217
218         <refsect1>
219                 <title>Notes</title>
220
221                 <para>The <function>sd_login_monitor_new()</function>,
222                 <function>sd_login_monitor_unref()</function>,
223                 <function>sd_login_monitor_flush()</function>,
224                 <function>sd_login_monitor_get_fd()</function>,
225                 <function>sd_login_monitor_get_events()</function> and
226                 <function>sd_login_monitor_get_timeout()</function>
227                 interfaces are available as a shared library, which can
228                 be compiled and linked to with the
229                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
230                 file.</para>
231         </refsect1>
232
233         <refsect1>
234                 <title>See Also</title>
235
236                 <para>
237                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
238                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
239                         <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
240                         <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
241                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
242                 </para>
243         </refsect1>
244
245 </refentry>