'\" t .TH "SD_SESSION_IS_ACTIVE" "3" "" "elogind 239.3" "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_seat, 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 \- Determine state of a specific session .SH "SYNOPSIS" .sp .ft B .nf #include .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_seat('u .BI "int sd_session_get_seat(const\ char\ *" "session" ", char\ **" "seat" ");" .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_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_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_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_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_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_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\&. .SH "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 NULL, where that is not accepted)\&. .RE .PP \fB\-ENOMEM\fR .RS 4 Memory allocation failed\&. .RE .SH "NOTES" .PP These APIs are implemented as a shared library, which can be compiled and linked to with the \fBlibelogind\fR\ \&\fBpkg-config\fR(1) file\&. .SH "SEE ALSO" .PP \fBelogind\fR(8), \fBsd-login\fR(3), \fBsd_pid_get_session\fR(3) .SH "NOTES" .IP " 1." 4 Desktop Entry Specification .RS 4 \%http://standards.freedesktop.org/desktop-entry-spec/latest/ .RE