diff options
Diffstat (limited to 'man/sd_login_monitor_new.xml')
| -rw-r--r-- | man/sd_login_monitor_new.xml | 129 |
1 files changed, 101 insertions, 28 deletions
diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 35cb6b368b..26af0ea247 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_login_monitor_new"> +<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'> <refentryinfo> <title>sd_login_monitor_new</title> @@ -47,8 +47,10 @@ <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 and users</refpurpose> + <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> </refnamediv> <refsynopsisdiv> @@ -76,6 +78,17 @@ <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> @@ -83,23 +96,26 @@ <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 + 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) or <literal>uid</literal> (to get only + or changed), <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 + 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, 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> @@ -122,26 +138,78 @@ 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 + 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 + <literal>POLLIN</literal>, <literal>POLLOUT</literal> + and similar to fill into the + <literal>.events</literal> field of <literal>struct + pollfd</literal>.</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 CLOCK_MONOTONIC for + timing out <function>poll()</function> in + <literal>timeout_usec</literal>. See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about + <literal>CLOCK_MONOTONIC</literal>. If there's no + timeout to wait for this will fill in + <literal>(uint64_t) -1</literal> 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; +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; +}</programlisting> + + <para>The code above does not do any error checking + for brevity's sake. The calculated <literal>msec</literal> + 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> and - <function>sd_login_monitor_flush()</function> return 0 - or a positive integer. 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 failure, these calls return - a negative errno-style error code.</para> + a Unix file descriptor. On success + <function>sd_login_monitor_get_events()</function> + returns a combination of <literal>POLLIN</literal>, + <literal>POLLOUT</literal> and suchlike. On failure, + these calls return a negative errno-style error + code.</para> <para><function>sd_login_monitor_unref()</function> always returns NULL.</para> @@ -151,10 +219,13 @@ <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 + <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 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> @@ -166,7 +237,9 @@ <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>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> |