man/sd_uid_get_display.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_uid_get_state</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</span><hr><div class="refentry"><a name="sd_uid_get_state"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_uid_get_state, sd_uid_is_on_seat, sd_uid_get_sessions, sd_uid_get_seats, sd_uid_get_display — Determine login state of a specific Unix user ID</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-login.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_uid_get_state</b>(</code></td><td>uid_t <var class="pdparam">uid</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">state</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_uid_is_on_seat</b>(</code></td><td>uid_t <var class="pdparam">uid</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">require_active</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">seat</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_uid_get_sessions</b>(</code></td><td>uid_t <var class="pdparam">uid</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">require_active</var>, </td></tr><tr><td> </td><td>char ***<var class="pdparam">sessions</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_uid_get_seats</b>(</code></td><td>uid_t <var class="pdparam">uid</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">require_active</var>, </td></tr><tr><td> </td><td>char ***<var class="pdparam">seats</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_uid_get_display</b>(</code></td><td>uid_t <var class="pdparam">uid</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm140277216078640"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_uid_get_state()</code> may be used to
  23     determine the login state of a specific Unix user identifier. The
  24     following states are currently known: "<code class="literal">offline</code>"
  25     (user not logged in at all), "<code class="literal">lingering</code>" (user
  26     not logged in, but some user services running),
  27     "<code class="literal">online</code>" (user logged in, but not active, i.e.
  28     has no session in the foreground), "<code class="literal">active</code>" (user
  29     logged in, and has at least one active session, i.e. one session
  30     in the foreground), "<code class="literal">closing</code>" (user not logged
  31     in, and not lingering, but some processes are still around). In
  32     the future additional states might be defined, client code should
  33     be written to be robust in regards to additional state strings
  34     being returned. The returned string needs to be freed with the
  35     libc
  36     <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  37     call after use.</p><p><code class="function">sd_uid_is_on_seat()</code> may be used to
  38     determine whether a specific user is logged in or active on a
  39     specific seat. Accepts a Unix user identifier and a seat
  40     identifier string as parameters. The
  41     <em class="parameter"><code>require_active</code></em> parameter is a boolean
  42     value. If non-zero (true), this function will test if the user is
  43     active (i.e. has a session that is in the foreground and accepting
  44     user input) on the specified seat, otherwise (false) only if the
  45     user is logged in (and possibly inactive) on the specified
  46     seat.</p><p><code class="function">sd_uid_get_sessions()</code> may be used to
  47     determine the current sessions of the specified user. Accepts a
  48     Unix user identifier as parameter. The
  49     <em class="parameter"><code>require_active</code></em> parameter controls whether
  50     the returned list shall consist of only those sessions where the
  51     user is currently active (&gt; 0), where the user is currently
  52     online but possibly inactive (= 0), or logged in at all but
  53     possibly closing the session (&lt; 0). The call returns a
  54     <code class="constant">NULL</code> terminated string array of session
  55     identifiers in <em class="parameter"><code>sessions</code></em> which needs to be
  56     freed by the caller with the libc
  57     <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  58     call after use, including all the strings referenced. If the
  59     string array parameter is passed as <code class="constant">NULL</code>, the
  60     array will not be filled in, but the return code still indicates
  61     the number of current sessions. Note that instead of an empty
  62     array <code class="constant">NULL</code> may be returned and should be
  63     considered equivalent to an empty array.</p><p>Similarly, <code class="function">sd_uid_get_seats()</code> may be
  64     used to determine the list of seats on which the user currently
  65     has sessions. Similar semantics apply, however note that the user
  66     may have multiple sessions on the same seat as well as sessions
  67     with no attached seat and hence the number of entries in the
  68     returned array may differ from the one returned by
  69     <code class="function">sd_uid_get_sessions()</code>.</p><p><code class="function">sd_uid_get_display()</code> returns the name
  70     of the "primary" session of a user. If the user has graphical
  71     sessions, it will be the oldest graphical session. Otherwise, it
  72     will be the oldest open session.</p></div><div class="refsect1"><a name="idm140277216053408"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success, <code class="function">sd_uid_get_state()</code> returns
  73     0 or a positive integer. If the test succeeds,
  74     <code class="function">sd_uid_is_on_seat()</code> returns a positive
  75     integer; if it fails, 0.
  76     <code class="function">sd_uid_get_sessions()</code> and
  77     <code class="function">sd_uid_get_seats()</code> return the number of
  78     entries in the returned arrays.
  79     <code class="function">sd_uid_get_display()</code> returns a non-negative
  80     code on success. On failure, these calls return a negative
  81     errno-style error code.</p></div><div class="refsect1"><a name="idm140277216048592"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>Functions described here are available as a shared library,
  82     and can be compiled and linked to using the
  83     <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  84     entry.</p></div><div class="refsect1"><a name="idm140277216045680"></a><h2 id="History">History<a class="headerlink" title="Permalink to this headline" href="#History">¶</a></h2><p><code class="function">sd_uid_get_state()</code>,
  85     <code class="function">sd_uid_is_on_seat()</code>,
  86     <code class="function">sd_uid_get_sessions()</code>, and
  87     <code class="function">sd_uid_get_seats()</code> functions were added in
  88     systemd-31.</p><p><code class="function">sd_uid_get_display()</code> was added in
  89     systemd-213.</p></div><div class="refsect1"><a name="idm140277216040784"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  90       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  91       <a href="sd-login.html"><span class="citerefentry"><span class="refentrytitle">sd-login</span>(3)</span></a>,
  92       <a href="sd_pid_get_owner_uid.html"><span class="citerefentry"><span class="refentrytitle">sd_pid_get_owner_uid</span>(3)</span></a>
  93     </p></div></div></body></html>