man/sd_login_monitor_new.xml - systemd - Git at Google

 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

 <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_new(NULL, &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>

     <refsect2>
       <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 <constant>NULL</constant>, 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>
     </refsect2>
   </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>
	<?xml version='1.0'?> <!---nxml--->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

	<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 <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>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_new(NULL, &m);
	if (r < 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, &t);
	if (t == (uint64_t) -1)
	msec = -1;
	else {
	struct timespec ts;
	uint64_t n;
	clock_gettime(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>

	<refsect2>
	<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 <constant>NULL</constant>, 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>
	</refsect2>
	</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>