man: move more examples to stand-alone files and use 2-space indentation consistenty

[thirdparty/systemd.git] / man / sd_login_monitor_new.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">

<!--
  SPDX-License-Identifier: LGPL-2.1+
-->

<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_login_monitor_new</title>
    <productname>systemd</productname>
  </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_unrefp</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 &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>void <function>sd_login_monitor_unrefp</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_unrefp()</function> is similar to
    <function>sd_login_monitor_unref()</function> but takes a pointer
    to a pointer to an <type>sd_login_monitor</type> object. This call
    is useful in conjunction with GCC's and LLVM's <ulink
    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
    Variable Attribute</ulink>. Note that this function is defined as
    inline function. Use a declaration like the following, in order to
    allocate a login monitor object that is freed automatically as the
    code block is left:</para>

    <programlisting>{
  __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
  int r;
  …
  r = sd_login_monitor_default(&amp;m);
  if (r &lt; 0)
    fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
  …
}</programlisting>

    <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_unref()</function> and
    <function>sd_login_monitor_unrefp()</function> execute no
    operation if the passed in monitor object is
    <constant>NULL</constant>.</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 'µs' timeout into
    relative 'ms', use code like the following:</para>

    <programlisting>uint64_t t;
int msec;
sd_login_monitor_get_timeout(m, &amp;t);
if (t == (uint64_t) -1)
  msec = -1;
else {
  struct timespec ts;
  uint64_t n;
  clock_gettime(CLOCK_MONOTONIC, &amp;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>Errors</title>

    <para>Returned errors may indicate the following problems:</para>

    <variablelist>

      <varlistentry>
        <term><constant>-EINVAL</constant></term>

        <listitem><para>An input parameter was invalid (out of range,
        or NULL, where that is not accepted). The specified category to
        watch is not known.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>-ENOMEM</constant></term>

        <listitem><para>Memory allocation failed.</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <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>