]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
f47781d8 | 2 | .TH "SD_LOGIN_MONITOR_NEW" "3" "" "systemd 218" "sd_login_monitor_new" |
14228c0d MB |
3 | .\" ----------------------------------------------------------------- |
4 | .\" * Define some portability stuff | |
5 | .\" ----------------------------------------------------------------- | |
6 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7 | .\" http://bugs.debian.org/507673 | |
8 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
9 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
10 | .ie \n(.g .ds Aq \(aq | |
11 | .el .ds Aq ' | |
12 | .\" ----------------------------------------------------------------- | |
13 | .\" * set default formatting | |
14 | .\" ----------------------------------------------------------------- | |
15 | .\" disable hyphenation | |
16 | .nh | |
17 | .\" disable justification (adjust text to left margin only) | |
18 | .ad l | |
19 | .\" ----------------------------------------------------------------- | |
20 | .\" * MAIN CONTENT STARTS HERE * | |
21 | .\" ----------------------------------------------------------------- | |
22 | .SH "NAME" | |
23 | sd_login_monitor_new, sd_login_monitor_unref, sd_login_monitor_flush, sd_login_monitor_get_fd, sd_login_monitor_get_events, sd_login_monitor_get_timeout, sd_login_monitor \- Monitor login sessions, seats, users and virtual machines/containers | |
24 | .SH "SYNOPSIS" | |
25 | .sp | |
26 | .ft B | |
27 | .nf | |
28 | #include <systemd/sd\-login\&.h> | |
29 | .fi | |
30 | .ft | |
31 | .HP \w'int\ sd_login_monitor_new('u | |
60f067b4 JS |
32 | .BI "int sd_login_monitor_new(const\ char\ *" "category" ", sd_login_monitor\ **" "ret" ");" |
33 | .HP \w'sd_login_monitor\ *sd_login_monitor_unref('u | |
34 | .BI "sd_login_monitor *sd_login_monitor_unref(sd_login_monitor\ *" "m" ");" | |
14228c0d | 35 | .HP \w'int\ sd_login_monitor_flush('u |
60f067b4 | 36 | .BI "int sd_login_monitor_flush(sd_login_monitor\ *" "m" ");" |
14228c0d | 37 | .HP \w'int\ sd_login_monitor_get_fd('u |
60f067b4 | 38 | .BI "int sd_login_monitor_get_fd(sd_login_monitor\ *" "m" ");" |
14228c0d | 39 | .HP \w'int\ sd_login_monitor_get_events('u |
60f067b4 | 40 | .BI "int sd_login_monitor_get_events(sd_login_monitor\ *" "m" ");" |
14228c0d | 41 | .HP \w'int\ sd_login_monitor_get_timeout('u |
60f067b4 | 42 | .BI "int sd_login_monitor_get_timeout(sd_login_monitor\ *" "m" ", uint64_t\ *" "timeout_usec" ");" |
14228c0d MB |
43 | .SH "DESCRIPTION" |
44 | .PP | |
45 | \fBsd_login_monitor_new()\fR | |
46 | 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 | |
47 | "seat" | |
48 | (to get only notifications about seats being added, removed or changed), | |
49 | "session" | |
50 | (to get only notifications about sessions being created or removed or changed), | |
51 | "uid" | |
52 | (to get only notifications when a user changes state in respect to logins) or | |
53 | "machine" | |
54 | (to get only notifications when a virtual machine or container is started or stopped)\&. If notifications shall be generated in all these conditions, | |
55 | \fBNULL\fR | |
56 | 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 | |
57 | \fBsd_login_monitor_unref()\fR | |
58 | call after use\&. | |
59 | .PP | |
60 | \fBsd_login_monitor_unref()\fR | |
61 | may be used to destroy a monitor object\&. Note that this will invalidate any file descriptor returned by | |
62 | \fBsd_login_monitor_get_fd()\fR\&. | |
63 | .PP | |
64 | \fBsd_login_monitor_flush()\fR | |
65 | 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\&. | |
66 | .PP | |
67 | \fBsd_login_monitor_get_fd()\fR | |
68 | may be used to retrieve the file descriptor of the monitor object that may be integrated in an application defined event loop, based around | |
69 | \fBpoll\fR(2) | |
70 | or a similar interface\&. The application should include the returned file descriptor as wake\-up source for the events mask returned by | |
71 | \fBsd_login_monitor_get_events()\fR\&. It should pass a timeout value as returned by | |
72 | \fBsd_login_monitor_get_timeout()\fR\&. Whenever a wake\-up is triggered the file descriptor needs to be reset via | |
73 | \fBsd_login_monitor_flush()\fR\&. An application needs to reread the login state with a function like | |
74 | \fBsd_get_seats\fR(3) | |
75 | or similar to determine what changed\&. | |
76 | .PP | |
77 | \fBsd_login_monitor_get_events()\fR | |
78 | will return the | |
79 | \fBpoll()\fR | |
80 | mask to wait for\&. This function will return a combination of | |
81 | \fBPOLLIN\fR, | |
82 | \fBPOLLOUT\fR | |
83 | and similar to fill into the | |
84 | "\&.events" | |
85 | field of | |
86 | \fIstruct pollfd\fR\&. | |
87 | .PP | |
88 | \fBsd_login_monitor_get_timeout()\fR | |
89 | will return a timeout value for usage in | |
90 | \fBpoll()\fR\&. This returns a value in microseconds since the epoch of | |
91 | \fBCLOCK_MONOTONIC\fR | |
92 | for timing out | |
93 | \fBpoll()\fR | |
94 | in | |
95 | \fItimeout_usec\fR\&. See | |
96 | \fBclock_gettime\fR(2) | |
97 | for details about | |
98 | \fBCLOCK_MONOTONIC\fR\&. If there is no timeout to wait for this will fill in | |
99 | \fB(uint64_t) \-1\fR | |
100 | instead\&. Note that | |
101 | \fBpoll()\fR | |
102 | takes a relative timeout in milliseconds rather than an absolute timeout in microseconds\&. To convert the absolute \*(Aqus\*(Aq timeout into relative \*(Aqms\*(Aq, use code like the following: | |
103 | .sp | |
104 | .if n \{\ | |
105 | .RS 4 | |
106 | .\} | |
107 | .nf | |
108 | uint64_t t; | |
109 | int msec; | |
110 | sd_login_monitor_get_timeout(m, &t); | |
111 | if (t == (uint64_t) \-1) | |
112 | msec = \-1; | |
113 | else { | |
114 | struct timespec ts; | |
115 | uint64_t n; | |
116 | clock_getttime(CLOCK_MONOTONIC, &ts); | |
117 | n = (uint64_t) ts\&.tv_sec * 1000000 + ts\&.tv_nsec / 1000; | |
118 | msec = t > n ? (int) ((t \- n + 999) / 1000) : 0; | |
119 | } | |
120 | .fi | |
121 | .if n \{\ | |
122 | .RE | |
123 | .\} | |
124 | .PP | |
125 | The code above does not do any error checking for brevity\*(Aqs sake\&. The calculated | |
126 | \fImsec\fR | |
127 | integer can be passed directly as | |
128 | \fBpoll()\fR\*(Aqs timeout parameter\&. | |
129 | .SH "RETURN VALUE" | |
130 | .PP | |
60f067b4 | 131 | On success, |
14228c0d MB |
132 | \fBsd_login_monitor_new()\fR, |
133 | \fBsd_login_monitor_flush()\fR | |
134 | and | |
135 | \fBsd_login_monitor_get_timeout()\fR | |
60f067b4 | 136 | return 0 or a positive integer\&. On success, |
14228c0d | 137 | \fBsd_login_monitor_get_fd()\fR |
60f067b4 | 138 | returns a Unix file descriptor\&. On success, |
14228c0d MB |
139 | \fBsd_login_monitor_get_events()\fR |
140 | returns a combination of | |
141 | \fBPOLLIN\fR, | |
142 | \fBPOLLOUT\fR | |
143 | and suchlike\&. On failure, these calls return a negative errno\-style error code\&. | |
144 | .PP | |
145 | \fBsd_login_monitor_unref()\fR | |
146 | always returns | |
147 | \fBNULL\fR\&. | |
148 | .SH "NOTES" | |
149 | .PP | |
150 | The | |
151 | \fBsd_login_monitor_new()\fR, | |
152 | \fBsd_login_monitor_unref()\fR, | |
153 | \fBsd_login_monitor_flush()\fR, | |
154 | \fBsd_login_monitor_get_fd()\fR, | |
155 | \fBsd_login_monitor_get_events()\fR | |
156 | and | |
157 | \fBsd_login_monitor_get_timeout()\fR | |
60f067b4 JS |
158 | interfaces are available as a shared library, which can be compiled and linked to with the |
159 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
14228c0d MB |
160 | file\&. |
161 | .SH "SEE ALSO" | |
162 | .PP | |
163 | \fBsystemd\fR(1), | |
164 | \fBsd-login\fR(3), | |
165 | \fBsd_get_seats\fR(3), | |
166 | \fBpoll\fR(2), | |
167 | \fBclock_gettime\fR(2) |