1SD_LOGIN_MONITOR_NEW(3) sd_login_monitor_new SD_LOGIN_MONITOR_NEW(3)
2
3
4
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
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
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
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
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
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)