diff options
Diffstat (limited to 'man/sd_login_monitor_new.xml')
| -rw-r--r-- | man/sd_login_monitor_new.xml | 414 |
1 files changed, 201 insertions, 213 deletions
diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index ba6623826f..a7b47a3207 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,223 +23,211 @@ <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_get_events</refname> - <refname>sd_login_monitor_get_timeout</refname> - <refname>sd_login_monitor</refname> - <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></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> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_login_monitor_new()</function> may - be used to monitor login sessions, users, seats, and - virtual machines/containers. 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, seat or virtual machine/container - 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), <literal>uid</literal> (to get only - notifications when a user changes state in respect to - logins) or <literal>machine</literal> (to get only - notifications when a virtual machine or container is - started or stopped). If notifications shall be - generated in all these conditions, <constant>NULL</constant> 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 the - events mask returned by - <function>sd_login_monitor_get_events()</function>. It - should pass a timeout value as returned by - <function>sd_login_monitor_get_timeout()</function>. 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> - - <para><function>sd_login_monitor_get_events()</function> - will return the <function>poll()</function> mask to - wait for. This function will return a combination of - <constant>POLLIN</constant>, <constant>POLLOUT</constant> - and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_login_monitor_get_timeout()</function> - will return a timeout value for usage in - <function>poll()</function>. This returns a value in - microseconds since the epoch of <constant>CLOCK_MONOTONIC</constant> - for timing out <function>poll()</function> in - <varname>timeout_usec</varname>. See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about - <constant>CLOCK_MONOTONIC</constant>. If there is no - timeout to wait for this will fill in - <constant>(uint64_t) -1</constant> instead. Note that - <function>poll()</function> takes a relative timeout - in milliseconds rather than an absolute timeout in - microseconds. To convert the absolute 'us' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; + <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_get_events</refname> + <refname>sd_login_monitor_get_timeout</refname> + <refname>sd_login_monitor</refname> + <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></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> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_login_monitor_new()</function> may be used to + monitor login sessions, users, seats, and virtual + machines/containers. 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, seat or virtual machine/container + 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), <literal>uid</literal> (to get only notifications + when a user changes state in respect to logins) or + <literal>machine</literal> (to get only notifications when a + virtual machine or container is started or stopped). If + notifications shall be generated in all these conditions, + <constant>NULL</constant> 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 the events mask + returned by <function>sd_login_monitor_get_events()</function>. It + should pass a timeout value as returned by + <function>sd_login_monitor_get_timeout()</function>. 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> + + <para><function>sd_login_monitor_get_events()</function> will + return the <function>poll()</function> mask to wait for. This + function will return a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and similar to fill into the + <literal>.events</literal> field of <varname>struct + pollfd</varname>.</para> + + <para><function>sd_login_monitor_get_timeout()</function> will + return a timeout value for usage in <function>poll()</function>. + This returns a value in microseconds since the epoch of + <constant>CLOCK_MONOTONIC</constant> for timing out + <function>poll()</function> in <varname>timeout_usec</varname>. + See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about <constant>CLOCK_MONOTONIC</constant>. If there + is no timeout to wait for this will fill in <constant>(uint64_t) + -1</constant> instead. Note that <function>poll()</function> takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following:</para> + + <programlisting>uint64_t t; int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; }</programlisting> - <para>The code above does not do any error checking - for brevity's sake. The calculated <varname>msec</varname> - integer can be passed directly as - <function>poll()</function>'s timeout - parameter.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_flush()</function> and - <function>sd_login_monitor_get_timeout()</function> - return 0 or a positive integer. On success, - <function>sd_login_monitor_get_fd()</function> returns - a Unix file descriptor. On success, - <function>sd_login_monitor_get_events()</function> - returns a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike. On failure, - these calls return a negative errno-style error - code.</para> - - <para><function>sd_login_monitor_unref()</function> - always returns <constant>NULL</constant>.</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>, - <function>sd_login_monitor_get_fd()</function>, - <function>sd_login_monitor_get_events()</function> and - <function>sd_login_monitor_get_timeout()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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>, - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + <para>The code above does not do any error checking for brevity's + sake. The calculated <varname>msec</varname> integer can be passed + directly as <function>poll()</function>'s timeout + parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_flush()</function> and + <function>sd_login_monitor_get_timeout()</function> + return 0 or a positive integer. On success, + <function>sd_login_monitor_get_fd()</function> returns + a Unix file descriptor. On success, + <function>sd_login_monitor_get_events()</function> + returns a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and suchlike. On failure, + these calls return a negative errno-style error + code.</para> + + <para><function>sd_login_monitor_unref()</function> + always returns <constant>NULL</constant>.</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>, + <function>sd_login_monitor_get_fd()</function>, + <function>sd_login_monitor_get_events()</function> and + <function>sd_login_monitor_get_timeout()</function> + interfaces are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><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>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> |