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=7319c061c975cbbc1f17fcc06b4054902d19faa7;hp=de484329a9900c794489d891804c3d08787452f9;hb=1839f931d9b61cecefe20717d371cc430aa1b61e;hpb=595aae376fae21f885ec9af2cac1aaf3ff3e9bee diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index de484329a..7319c061c 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -1,6 +1,6 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - - sd_login_monitor_new - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - sd_login_monitor_new - 3 - - - - sd_login_monitor_new - sd_login_monitor_unref - sd_login_monitor_flush - sd_login_monitor_get_fd - Monitor login sessions, seats and users - - - - - #include <systemd/sd-login.h> - - - int sd_login_monitor_new - const char* category - sd_login_monitor** ret - - - - sd_login_monitor* sd_login_monitor_unref - sd_login_monitor* m - - - - int sd_login_monitor_flush - sd_login_monitor* m - - - - int sd_login_monitor_get_fd - sd_login_monitor* m - - - - - - - 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 - 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 - 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 - sd_login_monitor_unref() call - after use. - - sd_login_monitor_unref() - may be used to destroy a monitor object. Note that - this will invalidate any file descriptor returned by - sd_login_monitor_get_fd(). - - sd_login_monitor_flush() - 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. - - sd_login_monitor_get_fd() - may be used to retrieve the file descriptor of the - monitor object that may be integrated in an - 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 - 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. - - - - Return Value - - On success - sd_login_monitor_new() and - sd_login_monitor_flush() 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. - - sd_login_monitor_unref() - 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 - file. - - - - See Also - - - systemd1, - sd-login7, - sd_get_seats3 - - + + + + sd_login_monitor_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_login_monitor_new + 3 + + + + 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 + + + + + #include <systemd/sd-login.h> + + + int sd_login_monitor_new + const char *category + sd_login_monitor **ret + + + + sd_login_monitor *sd_login_monitor_unref + sd_login_monitor *m + + + + int sd_login_monitor_flush + sd_login_monitor *m + + + + int sd_login_monitor_get_fd + 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 + + + + + + + Description + + sd_login_monitor_new() 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 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), uid (to get only notifications + when a user changes state in respect to 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. + + sd_login_monitor_unref() may be used to + destroy a monitor object. Note that this will invalidate any file + descriptor returned by + sd_login_monitor_get_fd(). + + sd_login_monitor_flush() 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. + + sd_login_monitor_get_fd() may be used + to retrieve the file descriptor of the monitor object that may be + integrated in an application defined event loop, based around + poll2 + or a similar interface. The application should include 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(), + 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 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. + + + + Notes + + The sd_login_monitor_new(), + 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 a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_get_seats3, + poll2, + clock_gettime2 + +