<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!ENTITY % entities SYSTEM "custom-entities.ent" >

%entities;

]>

<refentry id="sd_uid_get_state" conditional='HAVE_PAM'>

<refentryinfo>

<title>sd_uid_get_state</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_uid_get_state</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_uid_get_state</refname>

<refname>sd_uid_is_on_seat</refname>

<refname>sd_uid_get_sessions</refname>

<refname>sd_uid_get_seats</refname>

<refname>sd_uid_get_display</refname>

<refpurpose>Determine login state of a specific Unix user ID</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_uid_get_state</function></funcdef>

<paramdef>uid_t <parameter>uid</parameter></paramdef>

<paramdef>char **<parameter>state</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_uid_is_on_seat</function></funcdef>

<paramdef>uid_t <parameter>uid</parameter></paramdef>

<paramdef>int <parameter>require_active</parameter></paramdef>

<paramdef>const char *<parameter>seat</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_uid_get_sessions</function></funcdef>

<paramdef>uid_t <parameter>uid</parameter></paramdef>

<paramdef>int <parameter>require_active</parameter></paramdef>

<paramdef>char ***<parameter>sessions</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_uid_get_seats</function></funcdef>

<paramdef>uid_t <parameter>uid</parameter></paramdef>

<paramdef>int <parameter>require_active</parameter></paramdef>

<paramdef>char ***<parameter>seats</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_uid_get_display</function></funcdef>

<paramdef>uid_t <parameter>uid</parameter></paramdef>

<paramdef>char **<parameter>session</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_uid_get_state()</function> may be used to

determine the login state of a specific Unix user identifier. The

following states are currently known: <literal>offline</literal>

(user not logged in at all), <literal>lingering</literal> (user

not logged in, but some user services running),

<literal>online</literal> (user logged in, but not active, i.e.

has no session in the foreground), <literal>active</literal> (user

logged in, and has at least one active session, i.e. one session

in the foreground), <literal>closing</literal> (user not logged

in, and not lingering, but some processes 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. The returned string needs to be freed with the

libc

<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use.</para>

<para><function>sd_uid_is_on_seat()</function> may be used to

determine whether a specific user is logged in or active on a

specific seat. Accepts a Unix user identifier and a seat

identifier string as parameters. The

<parameter>require_active</parameter> parameter is a boolean

value. If non-zero (true), this function will test if the user is

active (i.e. has a session that is in the foreground and accepting

user input) on the specified seat, otherwise (false) only if the

user is logged in (and possibly inactive) on the specified

seat.</para>

<para><function>sd_uid_get_sessions()</function> may be used to

determine the current sessions of the specified user. Accepts a

Unix user identifier as parameter. The

<parameter>require_active</parameter> parameter controls whether

the returned list shall consist of only those sessions where the

user is currently active (&gt; 0), where the user is currently

online but possibly inactive (= 0), or logged in at all but

possibly closing the session (&lt; 0). The call returns a

<constant>NULL</constant> terminated string array of session

identifiers in <parameter>sessions</parameter> which needs to be

freed by the caller with the libc

<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use, including all the strings referenced. If the

string array parameter is passed as <constant>NULL</constant>, the

array will not be filled in, but the return code still indicates

the number of current sessions. Note that instead of an empty

array <constant>NULL</constant> may be returned and should be

considered equivalent to an empty array.</para>

<para>Similarly, <function>sd_uid_get_seats()</function> may be

used to determine the list of seats on which the user currently

has sessions. Similar semantics apply, however note that the user

may have multiple sessions on the same seat as well as sessions

with no attached seat and hence the number of entries in the

returned array may differ from the one returned by

<function>sd_uid_get_sessions()</function>.</para>

<para><function>sd_uid_get_display()</function> returns the name

of the "primary" session of a user. If the user has graphical

sessions, it will be the oldest graphical session. Otherwise, it

will be the oldest open session.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On success, <function>sd_uid_get_state()</function> returns

0 or a positive integer. If the test succeeds,

<function>sd_uid_is_on_seat()</function> returns a positive

integer; if it fails, 0.

<function>sd_uid_get_sessions()</function> and

<function>sd_uid_get_seats()</function> return the number of

entries in the returned arrays.

<function>sd_uid_get_display()</function> returns a non-negative

code on success. On failure, these calls return a negative

errno-style error code.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>Functions described here are available as a shared library,

and can be compiled and linked to using the

<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

entry.</para>

</refsect1>

<refsect1>

<title>History</title>

<para><function>sd_uid_get_state()</function>,

<function>sd_uid_is_on_seat()</function>,

<function>sd_uid_get_sessions()</function>, and

<function>sd_uid_get_seats()</function> functions were added in

systemd-31.</para>

<para><function>sd_uid_get_display()</function> was added in

systemd-213.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>