1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_uid_get_state" conditional='HAVE_PAM' 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_uid_get_state</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_uid_get_state</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_uid_get_state</refname> 21 <refname>sd_uid_is_on_seat</refname> 22 <refname>sd_uid_get_sessions</refname> 23 <refname>sd_uid_get_seats</refname> 24 <refname>sd_uid_get_display</refname> 25 <refpurpose>Determine login state of a specific Unix user ID</refpurpose> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <funcsynopsis> 30 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> 31 32 <funcprototype> 33 <funcdef>int <function>sd_uid_get_state</function></funcdef> 34 <paramdef>uid_t <parameter>uid</parameter></paramdef> 35 <paramdef>char **<parameter>state</parameter></paramdef> 36 </funcprototype> 37 38 <funcprototype> 39 <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> 40 <paramdef>uid_t <parameter>uid</parameter></paramdef> 41 <paramdef>int <parameter>require_active</parameter></paramdef> 42 <paramdef>const char *<parameter>seat</parameter></paramdef> 43 </funcprototype> 44 45 <funcprototype> 46 <funcdef>int <function>sd_uid_get_sessions</function></funcdef> 47 <paramdef>uid_t <parameter>uid</parameter></paramdef> 48 <paramdef>int <parameter>require_active</parameter></paramdef> 49 <paramdef>char ***<parameter>sessions</parameter></paramdef> 50 </funcprototype> 51 52 <funcprototype> 53 <funcdef>int <function>sd_uid_get_seats</function></funcdef> 54 <paramdef>uid_t <parameter>uid</parameter></paramdef> 55 <paramdef>int <parameter>require_active</parameter></paramdef> 56 <paramdef>char ***<parameter>seats</parameter></paramdef> 57 </funcprototype> 58 59 <funcprototype> 60 <funcdef>int <function>sd_uid_get_display</function></funcdef> 61 <paramdef>uid_t <parameter>uid</parameter></paramdef> 62 <paramdef>char **<parameter>session</parameter></paramdef> 63 </funcprototype> 64 </funcsynopsis> 65 </refsynopsisdiv> 66 67 <refsect1> 68 <title>Description</title> 69 70 <para><function>sd_uid_get_state()</function> may be used to 71 determine the login state of a specific Unix user identifier. The 72 following states are currently known: <literal>offline</literal> 73 (user not logged in at all), <literal>lingering</literal> (user 74 not logged in, but some user services running), 75 <literal>online</literal> (user logged in, but not active, i.e. 76 has no session in the foreground), <literal>active</literal> (user 77 logged in, and has at least one active session, i.e. one session 78 in the foreground), <literal>closing</literal> (user not logged 79 in, and not lingering, but some processes are still around). In 80 the future additional states might be defined, client code should 81 be written to be robust in regards to additional state strings 82 being returned. The returned string needs to be freed with the 83 libc 84 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> 85 call after use.</para> 86 87 <para><function>sd_uid_is_on_seat()</function> may be used to 88 determine whether a specific user is logged in or active on a 89 specific seat. Accepts a Unix user identifier and a seat 90 identifier string as parameters. The 91 <parameter>require_active</parameter> parameter is a boolean 92 value. If non-zero (true), this function will test if the user is 93 active (i.e. has a session that is in the foreground and accepting 94 user input) on the specified seat, otherwise (false) only if the 95 user is logged in (and possibly inactive) on the specified 96 seat.</para> 97 98 <para><function>sd_uid_get_sessions()</function> may be used to 99 determine the current sessions of the specified user. Accepts a 100 Unix user identifier as parameter. The 101 <parameter>require_active</parameter> parameter controls whether 102 the returned list shall consist of only those sessions where the 103 user is currently active (> 0), where the user is currently 104 online but possibly inactive (= 0), or logged in but 105 possibly closing the session (< 0). The call returns a 106 <constant>NULL</constant> terminated string array of session 107 identifiers in <parameter>sessions</parameter> which needs to be 108 freed by the caller with the libc 109 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> 110 call after use, including all the strings referenced. If the 111 string array parameter is passed as <constant>NULL</constant>, the 112 array will not be filled in, but the return code still indicates 113 the number of current sessions. Note that instead of an empty 114 array <constant>NULL</constant> may be returned and should be 115 considered equivalent to an empty array.</para> 116 117 <para>Similarly, <function>sd_uid_get_seats()</function> may be 118 used to determine the list of seats on which the user currently 119 has sessions. Similar semantics apply, however note that the user 120 may have multiple sessions on the same seat as well as sessions 121 with no attached seat and hence the number of entries in the 122 returned array may differ from the one returned by 123 <function>sd_uid_get_sessions()</function>.</para> 124 125 <para><function>sd_uid_get_display()</function> returns the name 126 of the "primary" session of a user. If the user has graphical 127 sessions, it will be the oldest graphical session. Otherwise, it 128 will be the oldest open session.</para> 129 </refsect1> 130 131 <refsect1> 132 <title>Return Value</title> 133 134 <para>On success, <function>sd_uid_get_state()</function> returns 0 or a positive integer. If the test 135 succeeds, <function>sd_uid_is_on_seat()</function> returns a positive integer; if it fails, 0. 136 <function>sd_uid_get_sessions()</function> and <function>sd_uid_get_seats()</function> return the number 137 of entries in the returned arrays. <function>sd_uid_get_display()</function> returns a non-negative code 138 on success. On failure, these calls return a negative errno-style error code.</para> 139 140 <refsect2> 141 <title>Errors</title> 142 143 <para>Returned errors may indicate the following problems:</para> 144 145 <variablelist> 146 147 <varlistentry> 148 <term><constant>-ENODATA</constant></term> 149 150 <listitem><para>The given field is not specified for the described user.</para> 151 </listitem> 152 </varlistentry> 153 154 <varlistentry> 155 <term><constant>-ENXIO</constant></term> 156 157 <listitem><para>The specified seat is unknown.</para> 158 </listitem> 159 </varlistentry> 160 161 <varlistentry> 162 <term><constant>-EINVAL</constant></term> 163 164 <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, 165 where that is not accepted). This is also returned if the passed user ID is 166 <constant>0xFFFF</constant> or <constant>0xFFFFFFFF</constant>, which are undefined on Linux. 167 </para></listitem> 168 </varlistentry> 169 170 <varlistentry> 171 <term><constant>-ENOMEM</constant></term> 172 173 <listitem><para>Memory allocation failed.</para></listitem> 174 </varlistentry> 175 </variablelist> 176 </refsect2> 177 </refsect1> 178 179 <xi:include href="libsystemd-pkgconfig.xml" /> 180 181 <refsect1> 182 <title>See Also</title> 183 184 <para> 185 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 186 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 187 <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> 188 </para> 189 </refsect1> 190 191</refentry> 192