97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml version='1.0'?> <!--*-nxml-*-->

97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

97a9a944b5887e91042b019776c41d5dd74557aferikabele "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

a945f35eff8b6a88009ce73de6d4c862ce58de3cslive

3f08db06526d6901aa08c110b5bc7dde6bc39905nd

5a58787efeb02a1c3f06569d019ad81fd2efa06end<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'>

a63f0ab647ad2ab72efc9bea7a66e24e9ebc5cc2nd

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <refentryinfo>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <title>sd_login_monitor_new</title>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <productname>systemd</productname>

e1e8390280254f7f0580d701e583f670643d4f3fnilgun

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <authorgroup>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <author>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <contrib>Developer</contrib>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <firstname>Lennart</firstname>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <surname>Poettering</surname>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <email>lennart@poettering.net</email>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </author>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </authorgroup>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </refentryinfo>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd <refmeta>

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refentrytitle>sd_login_monitor_new</refentrytitle>

ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd <manvolnum>3</manvolnum>

b21197dc8e6b8c764fdcc24d4bae8b0eebb6bc4end </refmeta>

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refnamediv>

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refname>sd_login_monitor_new</refname>

97a9a944b5887e91042b019776c41d5dd74557aferikabele <refname>sd_login_monitor_unref</refname>

f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_login_monitor_flush</refname>

ffb01336be79c64046b636e59fa8ddca8ec029edsf <refname>sd_login_monitor_get_fd</refname>

f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_login_monitor_get_events</refname>

f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_login_monitor_get_timeout</refname>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <refname>sd_login_monitor</refname>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </refnamediv>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

deeee6bb6fd94c0ba5f3730b58abd9d299c89ccdnd <refsynopsisdiv>

4db28ee269aa06f7c6232e11cd01f58c3349af23noodl <funcsynopsis>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd

4a31db3c3a0202003c1b9f87affa7cc143e120e5sf <funcprototype>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcdef>int <function>sd_login_monitor_new</function></funcdef>

ffb01336be79c64046b636e59fa8ddca8ec029edsf <paramdef>const char *<parameter>category</parameter></paramdef>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd </funcprototype>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd

2bc7f1cf720973a67f8ff7a8d523e40569ae5b6cnd <funcprototype>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd </funcprototype>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcprototype>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcdef>int <function>sd_login_monitor_flush</function></funcdef>

87ffb6e33f3cbef3b9bb406cc2d27039fa336eaatrawick <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>

4db28ee269aa06f7c6232e11cd01f58c3349af23noodl </funcprototype>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

5a58787efeb02a1c3f06569d019ad81fd2efa06end <funcprototype>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </funcprototype>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

654d8eb036bedc99e90e11910ee02d3421417697rbowen <funcprototype>

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <funcdef>int <function>sd_login_monitor_get_events</function></funcdef>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>

5a58787efeb02a1c3f06569d019ad81fd2efa06end </funcprototype>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <funcprototype>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick </funcprototype>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

654d8eb036bedc99e90e11910ee02d3421417697rbowen </funcsynopsis>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </refsynopsisdiv>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refsect1>

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <title>Description</title>

97a9a944b5887e91042b019776c41d5dd74557aferikabele

654d8eb036bedc99e90e11910ee02d3421417697rbowen <para><function>sd_login_monitor_new()</function> may be used to

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive monitor login sessions, users, seats, and virtual

97a9a944b5887e91042b019776c41d5dd74557aferikabele machines/containers. Via a monitor object a file descriptor can be

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive integrated into an application defined event loop which is woken

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive up each time a user logs in, logs out or a seat is added or

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive removed, or a session, user, seat or virtual machine/container

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive changes state otherwise. The first parameter takes a string which

ffb01336be79c64046b636e59fa8ddca8ec029edsf can be <literal>seat</literal> (to get only notifications about

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick seats being added, removed or changed), <literal>session</literal>

ffb01336be79c64046b636e59fa8ddca8ec029edsf (to get only notifications about sessions being created or removed

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick or changed), <literal>uid</literal> (to get only notifications

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick when a user changes state in respect to logins) or

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <literal>machine</literal> (to get only notifications when a

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick virtual machine or container is started or stopped). If

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick notifications shall be generated in all these conditions,

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <constant>NULL</constant> may be passed. Note that in the future

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick additional categories may be defined. The second parameter returns

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf a monitor object and needs to be freed with the

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <function>sd_login_monitor_unref()</function> call after

ffb01336be79c64046b636e59fa8ddca8ec029edsf use.</para>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <para><function>sd_login_monitor_unref()</function> may be used to

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick destroy a monitor object. Note that this will invalidate any file

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick descriptor returned by

77c77cf89621f21c8e2bbad63058b5eaa5f88d4ajim <function>sd_login_monitor_get_fd()</function>.</para>

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <para><function>sd_login_monitor_flush()</function> may be used to

ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd reset the wakeup state of the monitor object. Whenever an event

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick causes the monitor to wake up the event loop via the file

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf descriptor this function needs to be called to reset the wake-up

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf state. If this call is not invoked, the file descriptor will

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf immediately wake up the event loop again.</para>

ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <para><function>sd_login_monitor_get_fd()</function> may be used

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick to retrieve the file descriptor of the monitor object that may be

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick integrated in an application defined event loop, based around

4a31db3c3a0202003c1b9f87affa7cc143e120e5sf <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>

4a31db3c3a0202003c1b9f87affa7cc143e120e5sf or a similar interface. The application should include the

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick returned file descriptor as wake-up source for the events mask

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick returned by <function>sd_login_monitor_get_events()</function>. It

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick should pass a timeout value as returned by

ffb01336be79c64046b636e59fa8ddca8ec029edsf <function>sd_login_monitor_get_timeout()</function>. Whenever a

8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick wake-up is triggered the file descriptor needs to be reset via

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <function>sd_login_monitor_flush()</function>. An application

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive needs to reread the login state with a function like

97a9a944b5887e91042b019776c41d5dd74557aferikabele <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>

92510838f2eb125726e15c5eb4f7a23c7a0396e4slive or similar to determine what changed.</para>

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic <para><function>sd_login_monitor_get_events()</function> will

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic return the <function>poll()</function> mask to wait for. This

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic function will return a combination of <constant>POLLIN</constant>,

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic <constant>POLLOUT</constant> and similar to fill into the

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic <literal>.events</literal> field of <varname>struct

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic pollfd</varname>.</para>

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic

f0fa55ff14fa0bf8fd72d989f6625de6dc3260c8igalic <para><function>sd_login_monitor_get_timeout()</function> will

06ba4a61654b3763ad65f52283832ebf058fdf1cslive return a timeout value for usage in <function>poll()</function>.

e8d485701957d5c6de870111c112e168a894d49and This returns a value in microseconds since the epoch of

e8d485701957d5c6de870111c112e168a894d49and <constant>CLOCK_MONOTONIC</constant> for timing out

654d8eb036bedc99e90e11910ee02d3421417697rbowen <function>poll()</function> in <varname>timeout_usec</varname>.

654d8eb036bedc99e90e11910ee02d3421417697rbowen See

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive for details about <constant>CLOCK_MONOTONIC</constant>. If there

9bcfc3697a91b5215893a7d0206865b13fc72148nd is no timeout to wait for this will fill in <constant>(uint64_t)

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive -1</constant> instead. Note that <function>poll()</function> takes

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive a relative timeout in milliseconds rather than an absolute timeout

06ba4a61654b3763ad65f52283832ebf058fdf1cslive in microseconds. To convert the absolute 'µs' timeout into

4a31db3c3a0202003c1b9f87affa7cc143e120e5sf relative 'ms', use code like the following:</para>

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive

9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <programlisting>uint64_t t;

709e3a21ba73b8433462959cd56c773454b34441trawickint msec;

709e3a21ba73b8433462959cd56c773454b34441trawicksd_login_monitor_get_timeout(m, &amp;t);

709e3a21ba73b8433462959cd56c773454b34441trawickif (t == (uint64_t) -1)

709e3a21ba73b8433462959cd56c773454b34441trawick msec = -1;

709e3a21ba73b8433462959cd56c773454b34441trawickelse {

709e3a21ba73b8433462959cd56c773454b34441trawick struct timespec ts;

709e3a21ba73b8433462959cd56c773454b34441trawick uint64_t n;

5a58787efeb02a1c3f06569d019ad81fd2efa06end clock_getttime(CLOCK_MONOTONIC, &amp;ts);

5a58787efeb02a1c3f06569d019ad81fd2efa06end n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd msec = t > n ? (int) ((t - n + 999) / 1000) : 0;

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd}</programlisting>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd

e1e8390280254f7f0580d701e583f670643d4f3fnilgun <para>The code above does not do any error checking for brevity's

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung sake. The calculated <varname>msec</varname> integer can be passed

727872d18412fc021f03969b8641810d8896820bhumbedooh directly as <function>poll()</function>'s timeout

0d0ba3a410038e179b695446bb149cce6264e0abnd parameter.</para>

727872d18412fc021f03969b8641810d8896820bhumbedooh </refsect1>

727872d18412fc021f03969b8641810d8896820bhumbedooh

0d0ba3a410038e179b695446bb149cce6264e0abnd <refsect1>

727872d18412fc021f03969b8641810d8896820bhumbedooh <title>Return Value</title>

888cb40bdeec5abf452bd85d6bf63b26d5913d4chumbedooh

727872d18412fc021f03969b8641810d8896820bhumbedooh <para>On success,

0d0ba3a410038e179b695446bb149cce6264e0abnd <function>sd_login_monitor_new()</function>,

0d0ba3a410038e179b695446bb149cce6264e0abnd <function>sd_login_monitor_flush()</function> and

0d0ba3a410038e179b695446bb149cce6264e0abnd <function>sd_login_monitor_get_timeout()</function>

727872d18412fc021f03969b8641810d8896820bhumbedooh return 0 or a positive integer. On success,

0d0ba3a410038e179b695446bb149cce6264e0abnd <function>sd_login_monitor_get_fd()</function> returns

0d0ba3a410038e179b695446bb149cce6264e0abnd a Unix file descriptor. On success,

0d0ba3a410038e179b695446bb149cce6264e0abnd <function>sd_login_monitor_get_events()</function>

727872d18412fc021f03969b8641810d8896820bhumbedooh returns a combination of <constant>POLLIN</constant>,

0d0ba3a410038e179b695446bb149cce6264e0abnd <constant>POLLOUT</constant> and suchlike. On failure,

0d0ba3a410038e179b695446bb149cce6264e0abnd these calls return a negative errno-style error

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh code.</para>

5effc8b39fae5cd169d17f342bfc265705840014rbowen

d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen <para><function>sd_login_monitor_unref()</function>

0d0ba3a410038e179b695446bb149cce6264e0abnd always returns <constant>NULL</constant>.</para>

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd </refsect1>

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <refsect1>

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

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