1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-10-31 07:51:08 +03:00
systemd-stable/man/sd_login_monitor_new.xml
Zbigniew Jędrzejewski-Szmek 56ba3c78ae build-sys: create Makefile-man.am automatically
man rules were repeating the same information in too many places,
which was error prone. Those rules can be easily generated from .xml
files. For efficiency and because python is not a required dependency,
Makefile-man.am is only regenerated when requested with

  make update-man-list

If no metadata in man/*.xml changed, this file should not change. So
only when a new man page or a new alias is added, this file should
show up in 'git diff'. The change should then be committed.

If the support for building from git without python was dropped, we
could drop Makefile-man.am from version control. This would also
increase the partial build time (since more stuff would be rebuild
whenever sources in man/*.xml would be modified), so it would probably
wouldn't be worth it.
2013-02-06 23:16:16 -05:00

174 lines
8.1 KiB
XML

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>
<refentryinfo>
<title>sd_login_monitor_new</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_login_monitor_new</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_login_monitor_new</refname>
<refname>sd_login_monitor_unref</refname>
<refname>sd_login_monitor_flush</refname>
<refname>sd_login_monitor_get_fd</refname>
<refname>sd_login_monitor</refname>
<refpurpose>Monitor login sessions, seats and users</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_login_monitor_new</function></funcdef>
<paramdef>const char* <parameter>category</parameter></paramdef>
<paramdef>sd_login_monitor** <parameter>ret</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_login_monitor* <function>sd_login_monitor_unref</function></funcdef>
<paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_login_monitor_flush</function></funcdef>
<paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>
<paramdef>sd_login_monitor* <parameter>m</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_login_monitor_new()</function> may
be used to monitor login sessions, users and seats. Via
a monitor object a file descriptor can be integrated
into an application defined event loop which is woken
up each time a user logs in, logs out or a seat is
added or removed, or a session, user, or seat changes
state otherwise. The first parameter takes a string
which can be <literal>seat</literal> (to get
only notifications about seats being added, removed or
changed), <literal>session</literal> (to get only
notifications about sessions being created or removed
or changed) or <literal>uid</literal> (to get only
notifications when a user changes state in respect to
logins). If notifications shall be generated in all
these conditions, NULL may be passed. Note that in the
future additional categories may be defined. The
second parameter returns a monitor object and needs to
be freed with the
<function>sd_login_monitor_unref()</function> call
after use.</para>
<para><function>sd_login_monitor_unref()</function>
may be used to destroy a monitor object. Note that
this will invalidate any file descriptor returned by
<function>sd_login_monitor_get_fd()</function>.</para>
<para><function>sd_login_monitor_flush()</function>
may be used to reset the wakeup state of the monitor
object. Whenever an event causes the monitor to wake
up the event loop via the file descriptor this
function needs to be called to reset the wake-up
state. If this call is not invoked the file descriptor
will immediately wake up the event loop again.</para>
<para><function>sd_login_monitor_get_fd()</function>
may be used to retrieve the file descriptor of the
monitor object that may be integrated in an
application defined event loop, based around
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
or a similar interface. The application should include
the returned file descriptor as wake up source for
POLLIN events. Whenever a wake-up is triggered the
file descriptor needs to be reset via
<function>sd_login_monitor_flush()</function>. An
application needs to reread the login state with a
function like
<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or similar to determine what changed.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success
<function>sd_login_monitor_new()</function> and
<function>sd_login_monitor_flush()</function> return 0
or a positive integer. On success
<function>sd_login_monitor_get_fd()</function> returns
a Unix file descriptor. On failure, these calls return
a negative errno-style error code.</para>
<para><function>sd_login_monitor_unref()</function>
always returns NULL.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The <function>sd_login_monitor_new()</function>,
<function>sd_login_monitor_unref()</function>, <function>sd_login_monitor_flush()</function> and
<function>sd_login_monitor_get_fd()</function> interfaces
are available as shared library, which can be compiled
and linked to with the
<literal>libsystemd-login</literal>
<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>