path: root/upstream/opensuse-tumbleweed/man3/sd_session_is_active.3

'\" t
.TH "SD_SESSION_IS_ACTIVE" "3" "" "systemd 254" "sd_session_is_active"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_session_is_active, sd_session_is_remote, sd_session_get_state, sd_session_get_uid, sd_session_get_username, sd_session_get_seat, sd_session_get_start_time, sd_session_get_service, sd_session_get_type, sd_session_get_class, sd_session_get_desktop, sd_session_get_display, sd_session_get_tty, sd_session_get_vt, sd_session_get_remote_host, sd_session_get_remote_user, sd_session_get_leader \- Determine state of a specific session
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-login\&.h>
.fi
.ft
.HP \w'int\ sd_session_is_active('u
.BI "int sd_session_is_active(const\ char\ *" "session" ");"
.HP \w'int\ sd_session_is_remote('u
.BI "int sd_session_is_remote(const\ char\ *" "session" ");"
.HP \w'int\ sd_session_get_state('u
.BI "int sd_session_get_state(const\ char\ *" "session" ", char\ **" "state" ");"
.HP \w'int\ sd_session_get_uid('u
.BI "int sd_session_get_uid(const\ char\ *" "session" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_session_get_username('u
.BI "int sd_session_get_username(const\ char\ *" "session" ", char\ **" "username" ");"
.HP \w'int\ sd_session_get_seat('u
.BI "int sd_session_get_seat(const\ char\ *" "session" ", char\ **" "seat" ");"
.HP \w'int\ sd_session_get_start_time('u
.BI "int sd_session_get_start_time(const\ char\ *" "session" ", uint64_t\ *" "usec" ");"
.HP \w'int\ sd_session_get_service('u
.BI "int sd_session_get_service(const\ char\ *" "session" ", char\ **" "service" ");"
.HP \w'int\ sd_session_get_type('u
.BI "int sd_session_get_type(const\ char\ *" "session" ", char\ **" "type" ");"
.HP \w'int\ sd_session_get_class('u
.BI "int sd_session_get_class(const\ char\ *" "session" ", char\ **" "class" ");"
.HP \w'int\ sd_session_get_desktop('u
.BI "int sd_session_get_desktop(const\ char\ *" "session" ", char\ **" "desktop" ");"
.HP \w'int\ sd_session_get_display('u
.BI "int sd_session_get_display(const\ char\ *" "session" ", char\ **" "display" ");"
.HP \w'int\ sd_session_get_leader('u
.BI "int sd_session_get_leader(const\ char\ *" "session" ", pid_t\ *" "leader" ");"
.HP \w'int\ sd_session_get_remote_host('u
.BI "int sd_session_get_remote_host(const\ char\ *" "session" ", char\ **" "remote_host" ");"
.HP \w'int\ sd_session_get_remote_user('u
.BI "int sd_session_get_remote_user(const\ char\ *" "session" ", char\ **" "remote_user" ");"
.HP \w'int\ sd_session_get_tty('u
.BI "int sd_session_get_tty(const\ char\ *" "session" ", char\ **" "tty" ");"
.HP \w'int\ sd_session_get_vt('u
.BI "int sd_session_get_vt(const\ char\ *" "session" ", unsigned\ int\ *" "vt" ");"
.SH "DESCRIPTION"
.PP
\fBsd_session_is_active()\fR
may be used to determine whether the session identified by the specified session identifier is currently active (i\&.e\&. currently in the foreground and available for user input) or not\&.
.PP
\fBsd_session_is_remote()\fR
may be used to determine whether the session identified by the specified session identifier is a remote session (i\&.e\&. its remote host is known) or not\&.
.PP
\fBsd_session_get_state()\fR
may be used to determine the state of the session identified by the specified session identifier\&. The following states are currently known:
"online"
(session logged in, but session not active, i\&.e\&. not in the foreground),
"active"
(session logged in and active, i\&.e\&. in the foreground),
"closing"
(session nominally logged out, but some processes belonging to it are still around)\&. In the future additional states might be defined, client code should be written to be robust in regards to additional state strings being returned\&. This function is a more generic version of
\fBsd_session_is_active()\fR\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_uid()\fR
may be used to determine the user identifier of the Unix user the session identified by the specified session identifier belongs to\&.
.PP
\fBsd_session_get_username()\fR
may be used to determine the name of the Unix user the session identified by the specified session identifier belongs to\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_seat()\fR
may be used to determine the seat identifier of the seat the session identified by the specified session identifier belongs to\&. Note that not all sessions are attached to a seat, this call will fail (returning
\fB\-ENODATA\fR) for them\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_start_time()\fR
may be used to determine the start time of the session identified by the specified session identifier belongs to\&. The
\fIusec\fR
is in microseconds since the epoch (\fBCLOCK_REALTIME\fR)\&.
.PP
\fBsd_session_get_service()\fR
may be used to determine the name of the service (as passed during PAM session setup) that registered the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_type()\fR
may be used to determine the type of the session identified by the specified session identifier\&. The returned string is one of
"x11",
"wayland",
"tty",
"mir"
or
"unspecified"
and needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_class()\fR
may be used to determine the class of the session identified by the specified session identifier\&. The returned string is one of
"user",
"greeter",
"lock\-screen", or
"background"
and needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_desktop()\fR
may be used to determine the brand of the desktop running on the session identified by the specified session identifier\&. This field can be set freely by desktop environments and does not follow any special formatting\&. However, desktops are strongly recommended to use the same identifiers and capitalization as for
\fI$XDG_CURRENT_DESKTOP\fR, as defined by the
\m[blue]\fBDesktop Entry Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_display()\fR
may be used to determine the X11 display of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_leader()\fR
may be used to determine the PID of the leader of the session identified by the specified session identifier\&.
.PP
\fBsd_session_get_remote_host()\fR
may be used to determine the remote hostname of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_remote_user()\fR
may be used to determine the remote username of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&. Note that this value is rarely known to the system, and even then should not be relied on\&.
.PP
\fBsd_session_get_tty()\fR
may be used to determine the TTY device of the session identified by the specified session identifier\&. The returned string needs to be freed with the libc
\fBfree\fR(3)
call after use\&.
.PP
\fBsd_session_get_vt()\fR
may be used to determine the VT number of the session identified by the specified session identifier\&. This function will return an error if the seat does not support VTs\&.
.PP
If the
\fIsession\fR
parameter of any of these functions is passed as
\fBNULL\fR, the operation is executed for the session the calling process is a member of, if there is any\&.
.SH "RETURN VALUE"
.PP
If the test succeeds,
\fBsd_session_is_active()\fR
and
\fBsd_session_is_remote()\fR
return a positive integer; if it fails, 0\&. On success,
\fBsd_session_get_state()\fR,
\fBsd_session_get_uid()\fR,
\fBsd_session_get_username()\fR,
\fBsd_session_get_seat()\fR,
\fBsd_session_get_service()\fR,
\fBsd_session_get_type()\fR,
\fBsd_session_get_class()\fR,
\fBsd_session_get_display()\fR,
\fBsd_session_get_leader()\fR,
\fBsd_session_get_remote_user()\fR,
\fBsd_session_get_remote_host()\fR
and
\fBsd_session_get_tty()\fR
return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-ENXIO\fR
.RS 4
The specified session does not exist\&.
.RE
.PP
\fB\-ENODATA\fR
.RS 4
The given field is not specified for the described session\&.
.RE
.PP
\fB\-EINVAL\fR
.RS 4
An input parameter was invalid (out of range, or
\fBNULL\fR, where that is not accepted)\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-login\fR(3),
\fBsd_pid_get_session\fR(3)
.SH "NOTES"
.IP " 1." 4
Desktop Entry Specification
.RS 4
\%https://standards.freedesktop.org/desktop-entry-spec/latest/
.RE