1SD_LOGIN_MONITOR_NEW(3)      sd_login_monitor_new      SD_LOGIN_MONITOR_NEW(3)
2
3
4

NAME

6       sd_login_monitor_new, sd_login_monitor_unref, sd_login_monitor_flush,
7       sd_login_monitor_get_fd, sd_login_monitor_get_events,
8       sd_login_monitor_get_timeout, sd_login_monitor - Monitor login
9       sessions, seats, users and virtual machines/containers
10

SYNOPSIS

12       #include <systemd/sd-login.h>
13
14       int sd_login_monitor_new(const char *category, sd_login_monitor **ret);
15
16       sd_login_monitor *sd_login_monitor_unref(sd_login_monitor *m);
17
18       int sd_login_monitor_flush(sd_login_monitor *m);
19
20       int sd_login_monitor_get_fd(sd_login_monitor *m);
21
22       int sd_login_monitor_get_events(sd_login_monitor *m);
23
24       int sd_login_monitor_get_timeout(sd_login_monitor *m,
25                                        uint64_t *timeout_usec);
26

DESCRIPTION

28       sd_login_monitor_new() may be used to monitor login sessions, users,
29       seats, and virtual machines/containers. Via a monitor object a file
30       descriptor can be integrated into an application defined event loop
31       which is woken up each time a user logs in, logs out or a seat is added
32       or removed, or a session, user, seat or virtual machine/container
33       changes state otherwise. The first parameter takes a string which can
34       be "seat" (to get only notifications about seats being added, removed
35       or changed), "session" (to get only notifications about sessions being
36       created or removed or changed), "uid" (to get only notifications when a
37       user changes state in respect to logins) or "machine" (to get only
38       notifications when a virtual machine or container is started or
39       stopped). If notifications shall be generated in all these conditions,
40       NULL may be passed. Note that in the future additional categories may
41       be defined. The second parameter returns a monitor object and needs to
42       be freed with the sd_login_monitor_unref() call after use.
43
44       sd_login_monitor_unref() may be used to destroy a monitor object. Note
45       that this will invalidate any file descriptor returned by
46       sd_login_monitor_get_fd().
47
48       sd_login_monitor_flush() may be used to reset the wakeup state of the
49       monitor object. Whenever an event causes the monitor to wake up the
50       event loop via the file descriptor this function needs to be called to
51       reset the wake-up state. If this call is not invoked, the file
52       descriptor will immediately wake up the event loop again.
53
54       sd_login_monitor_get_fd() may be used to retrieve the file descriptor
55       of the monitor object that may be integrated in an application defined
56       event loop, based around poll(2) or a similar interface. The
57       application should include the returned file descriptor as wake-up
58       source for the events mask returned by sd_login_monitor_get_events().
59       It should pass a timeout value as returned by
60       sd_login_monitor_get_timeout(). Whenever a wake-up is triggered the
61       file descriptor needs to be reset via sd_login_monitor_flush(). An
62       application needs to reread the login state with a function like
63       sd_get_seats(3) or similar to determine what changed.
64
65       sd_login_monitor_get_events() will return the poll() mask to wait for.
66       This function will return a combination of POLLIN, POLLOUT and similar
67       to fill into the ".events" field of struct pollfd.
68
69       sd_login_monitor_get_timeout() will return a timeout value for usage in
70       poll(). This returns a value in microseconds since the epoch of
71       CLOCK_MONOTONIC for timing out poll() in timeout_usec. See
72       clock_gettime(2) for details about CLOCK_MONOTONIC. If there is no
73       timeout to wait for this will fill in (uint64_t) -1 instead. Note that
74       poll() takes a relative timeout in milliseconds rather than an absolute
75       timeout in microseconds. To convert the absolute 'us' timeout into
76       relative 'ms', use code like the following:
77
78           uint64_t t;
79           int msec;
80           sd_login_monitor_get_timeout(m, &t);
81           if (t == (uint64_t) -1)
82             msec = -1;
83           else {
84             struct timespec ts;
85             uint64_t n;
86             clock_getttime(CLOCK_MONOTONIC, &ts);
87             n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
88             msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
89           }
90
91       The code above does not do any error checking for brevity's sake. The
92       calculated msec integer can be passed directly as poll()'s timeout
93       parameter.
94

RETURN VALUE

96       On success, sd_login_monitor_new(), sd_login_monitor_flush() and
97       sd_login_monitor_get_timeout() return 0 or a positive integer. On
98       success, sd_login_monitor_get_fd() returns a Unix file descriptor. On
99       success, sd_login_monitor_get_events() returns a combination of POLLIN,
100       POLLOUT and suchlike. On failure, these calls return a negative
101       errno-style error code.
102
103       sd_login_monitor_unref() always returns NULL.
104

NOTES

106       The sd_login_monitor_new(), sd_login_monitor_unref(),
107       sd_login_monitor_flush(), sd_login_monitor_get_fd(),
108       sd_login_monitor_get_events() and sd_login_monitor_get_timeout()
109       interfaces are available as a shared library, which can be compiled and
110       linked to with the libsystemd pkg-config(1) file.
111

SEE ALSO

113       systemd(1), sd-login(3), sd_get_seats(3), poll(2), clock_gettime(2)
114
115
116
117systemd 219                                            SD_LOGIN_MONITOR_NEW(3)
Impressum