X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_login_monitor_new.xml;h=909a3d9bfda5b220949ad56807f2128a17c2ffa2;hp=de484329a9900c794489d891804c3d08787452f9;hb=b408e2a8be6b87fd1796c45a767d00bbb00d7148;hpb=595aae376fae21f885ec9af2cac1aaf3ff3e9bee diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index de484329a..909a3d9bf 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -8,20 +8,20 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> - + sd_login_monitor_new @@ -47,7 +47,10 @@ sd_login_monitor_unref sd_login_monitor_flush sd_login_monitor_get_fd - Monitor login sessions, seats and users + sd_login_monitor_get_events + sd_login_monitor_get_timeout + sd_login_monitor + Monitor login sessions, seats, users and virtual machines/containers @@ -75,6 +78,17 @@ sd_login_monitor* m + + int sd_login_monitor_get_events + sd_login_monitor* m + + + + int sd_login_monitor_get_timeout + sd_login_monitor* m + uint64_t* timeout_usec + + @@ -82,23 +96,26 @@ Description sd_login_monitor_new() may - be used to monitor login session, users and seats. 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, or seat changes - state otherwise. The first parameter takes a string - which can be either seat (to get + 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 seat (to get only notifications about seats being added, removed or changed), session (to get only notifications about sessions being created or removed - or changed) or uid (to get only + or changed), uid (to get only notifications when a user changes state in respect to - logins). If notifications shall be generated in all - these conditions, NULL may be passed. Note that in - future additional categories may be defined. The - second parameter returns a monitor object and needs to - be freed with the + logins) or machine (to get only + notifications when a virtual machine or container is + started or stopped). If notifications shall be + generated in all these conditions, NULL 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 sd_login_monitor_unref() call after use. @@ -112,7 +129,7 @@ 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 + state. If this call is not invoked, the file descriptor will immediately wake up the event loop again. sd_login_monitor_get_fd() @@ -121,41 +138,95 @@ application defined event loop, based around poll2 or a similar interface. The application should include - the returned file descriptor as wake up source for - POLLIN events. Whenever a wake-up is triggered the - file descriptor needs to be reset via + the returned file descriptor as wake-up source for the + events mask returned by + sd_login_monitor_get_events(). It + should pass a timeout value as returned by + sd_login_monitor_get_timeout(). Whenever + a wake-up is triggered the file descriptor needs to be + reset via sd_login_monitor_flush(). An application needs to reread the login state with a function like sd_get_seats3 or similar to determine what changed. + + sd_login_monitor_get_events() + will return the poll() mask to + wait for. This function will return a combination of + POLLIN, POLLOUT + and similar to fill into the + .events field of struct + pollfd. + + sd_login_monitor_get_timeout() + will return a timeout value for usage in + poll(). This returns a value in + microseconds since the epoch of CLOCK_MONOTONIC + for timing out poll() in + timeout_usec. See + clock_gettime2 + for details about + CLOCK_MONOTONIC. If there is no + timeout to wait for this will fill in + (uint64_t) -1 instead. Note that + poll() takes a relative timeout + in milliseconds rather than an absolute timeout in + microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following: + + uint64_t t; +int msec; +sd_login_monitor_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +} + + The code above does not do any error checking + for brevity's sake. The calculated msec + integer can be passed directly as + poll()'s timeout + parameter. Return Value On success - sd_login_monitor_new() and - sd_login_monitor_flush() return 0 - or a positive integer. On success + sd_login_monitor_new(), + sd_login_monitor_flush() and + sd_login_monitor_get_timeout() + return 0 or a positive integer. On success sd_login_monitor_get_fd() returns - a Unix file descriptor. On failure, these calls return - a negative errno-style error code. + a Unix file descriptor. On success + sd_login_monitor_get_events() + returns a combination of POLLIN, + POLLOUT and suchlike. On failure, + these calls return a negative errno-style error + code. sd_login_monitor_unref() - always returns NULL. + always returns NULL. Notes The sd_login_monitor_new(), - sd_login_monitor_unref(), sd_login_monitor_flush() and - sd_login_monitor_get_fd() interfaces - are available as shared library, which can be compiled - and linked to with the - libsystemd-login - pkg-config1 + sd_login_monitor_unref(), + sd_login_monitor_flush(), + sd_login_monitor_get_fd(), + sd_login_monitor_get_events() and + sd_login_monitor_get_timeout() + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-login pkg-config1 file. @@ -164,8 +235,10 @@ systemd1, - sd-login7, - sd_get_seats3 + sd-login3, + sd_get_seats3, + poll2, + clock_gettime2