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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>
27 <title>sd_login_monitor_new</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_login_monitor_new</refentrytitle>
42 <manvolnum>3</manvolnum>
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</refname>
52 <refpurpose>Monitor login sessions, seats and users</refpurpose>
57 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
60 <funcdef>int <function>sd_login_monitor_new</function></funcdef>
61 <paramdef>const char* <parameter>category</parameter></paramdef>
62 <paramdef>sd_login_monitor** <parameter>ret</parameter></paramdef>
66 <funcdef>sd_login_monitor* <function>sd_login_monitor_unref</function></funcdef>
67 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
71 <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
72 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
76 <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
77 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
81 <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>
82 <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
89 <title>Description</title>
91 <para><function>sd_login_monitor_new()</function> may
92 be used to monitor login sessions, users and seats. Via
93 a monitor object a file descriptor can be integrated
94 into an application defined event loop which is woken
95 up each time a user logs in, logs out or a seat is
96 added or removed, or a session, user, or seat changes
97 state otherwise. The first parameter takes a string
98 which can be <literal>seat</literal> (to get
99 only notifications about seats being added, removed or
100 changed), <literal>session</literal> (to get only
101 notifications about sessions being created or removed
102 or changed) or <literal>uid</literal> (to get only
103 notifications when a user changes state in respect to
104 logins). If notifications shall be generated in all
105 these conditions, NULL may be passed. Note that in the
106 future additional categories may be defined. The
107 second parameter returns a monitor object and needs to
109 <function>sd_login_monitor_unref()</function> call
112 <para><function>sd_login_monitor_unref()</function>
113 may be used to destroy a monitor object. Note that
114 this will invalidate any file descriptor returned by
115 <function>sd_login_monitor_get_fd()</function>.</para>
117 <para><function>sd_login_monitor_flush()</function>
118 may be used to reset the wakeup state of the monitor
119 object. Whenever an event causes the monitor to wake
120 up the event loop via the file descriptor this
121 function needs to be called to reset the wake-up
122 state. If this call is not invoked the file descriptor
123 will immediately wake up the event loop again.</para>
125 <para><function>sd_login_monitor_get_fd()</function>
126 may be used to retrieve the file descriptor of the
127 monitor object that may be integrated in an
128 application defined event loop, based around
129 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
130 or a similar interface. The application should include
131 the returned file descriptor as wake-up source for the
132 events mask returned by
133 <function>sd_login_monitor_get_events()</function>. Whenever
134 a wake-up is triggered the file descriptor needs to be
136 <function>sd_login_monitor_flush()</function>. An
137 application needs to reread the login state with a
139 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
140 or similar to determine what changed.</para>
142 <para><function>sd_login_monitor_get_events()</function>
143 will return the <function>poll()</function> mask to
144 wait for. This function will return a combination of
145 <literal>POLLIN</literal>, <literal>POLLOUT</literal>
146 and similar to fill into the
147 <literal>.events</literal> field of <literal>struct
148 pollfd</literal>.</para>
152 <title>Return Value</title>
155 <function>sd_login_monitor_new()</function> and
156 <function>sd_login_monitor_flush()</function> return 0
157 or a positive integer. On success
158 <function>sd_login_monitor_get_fd()</function> returns
159 a Unix file descriptor. On success
160 <function>sd_login_monitor_get_events()</function>
161 returns a combination of <literal>POLLIN</literal>,
162 <literal>POLLOUT</literal> and suchlike. On failure,
163 these calls return a negative errno-style error
166 <para><function>sd_login_monitor_unref()</function>
167 always returns NULL.</para>
173 <para>The <function>sd_login_monitor_new()</function>,
174 <function>sd_login_monitor_unref()</function>,
175 <function>sd_login_monitor_flush()</function>,
176 <function>sd_login_monitor_get_fd()</function> and
177 <function>sd_login_monitor_get_events()</function>
178 interfaces are available as shared library, which can
179 be compiled and linked to with the
180 <literal>libsystemd-login</literal>
181 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
186 <title>See Also</title>
189 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
190 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
191 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
192 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>