summaryrefslogtreecommitdiffstats
path: root/man/sd_login_monitor_new.xml
blob: b6b0bc408d243bde6f83b9ffa91d0fb19312e6ab (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/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) {
    errno = -r;
    fprintf(stderr, "Failed to allocate login monitor object: %m\n");
  }
  …
}</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>History</title>
    <para><function>sd_login_monitor_get_events()</function> and
    <function>sd_login_monitor_get_timeout()</function> were added in version 201.</para>
    <para><function>sd_login_monitor_unrefp()</function> was added in version 229.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>