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 ); | 
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
                poll(2)
                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_seats(3)
                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_gettime(2)
                for details about
                CLOCK_MONOTONIC. If there's 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.
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.
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 shared library, which can
                be compiled and linked to with the
                libsystemd-login
                pkg-config(1)
                file.