sd_session_is_active.html 16.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_session_is_active</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_session_is_active"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>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_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</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_session_is_active</b>(</code></td><td>const char *<var class="pdparam">session</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_session_is_remote</b>(</code></td><td>const char *<var class="pdparam">session</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_session_get_state</b>(</code></td><td>const char *<var class="pdparam">session</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_session_get_uid</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>uid_t *<var class="pdparam">uid</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_session_get_seat</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>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_session_get_service</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">service</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_session_get_type</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">type</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_session_get_class</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">class</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_session_get_display</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">display</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_session_get_remote_host</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">remote_host</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_session_get_remote_user</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">remote_user</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_session_get_tty</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">tty</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_session_get_vt</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>unsigned int *<var class="pdparam">vt</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214172690320"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_session_is_active()</code> may
23 24 25
                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
26 27 28 29
                user input) or not.</p><p><code class="function">sd_session_is_remote()</code> 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.</p><p><code class="function">sd_session_get_state()</code> may
30 31 32
                be used to determine the state of the session
                identified by the specified session identifier. The
                following states are currently known:
Michael Biebl's avatar
Michael Biebl committed
33
                "<code class="literal">online</code>" (session logged in, but
34
                session not active, i.e. not in the foreground),
Michael Biebl's avatar
Michael Biebl committed
35
                "<code class="literal">active</code>" (session logged in and
36
                active, i.e. in the foreground),
Michael Biebl's avatar
Michael Biebl committed
37
                "<code class="literal">closing</code>" (session nominally logged
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
                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
                <code class="function">sd_session_is_active()</code>. The returned
                string needs to be freed with the libc
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_uid()</code> may be
                used to determine the user identifier of the Unix user the session
                identified by the specified session identifier belongs
                to.</p><p><code class="function">sd_session_get_seat()</code> 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 for them. The
                returned string needs to be freed with the libc
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_service()</code>
                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
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_type()</code> may
                be used to determine the type of the session
                identified by the specified session identifier. The
Michael Biebl's avatar
Michael Biebl committed
66
                returned string is one of "<code class="literal">x11</code>",
67 68 69
                "<code class="literal">wayland</code>", "<code class="literal">tty</code>",
                "<code class="literal">mir</code>" or "<code class="literal">unspecified</code>" and
                needs to be freed with the libc
70 71 72 73
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_class()</code> may
                be used to determine the class of the session
                identified by the specified session identifier. The
Michael Biebl's avatar
Michael Biebl committed
74 75 76 77
                returned string is one of "<code class="literal">user</code>",
                "<code class="literal">greeter</code>",
                "<code class="literal">lock-screen</code>", or
                "<code class="literal">background</code>" and needs to be freed
78 79 80 81 82 83 84 85
                with the libc
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_display()</code>
                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
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
86 87 88 89 90 91 92 93 94 95 96 97 98 99
                call after use.</p><p><code class="function">sd_session_get_remote_host()</code>
                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
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use.</p><p><code class="function">sd_session_get_remote_user()</code>
                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
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
                call after use. Note that this value is rarely known
                to the system, and even then should not be relied on.</p><p><code class="function">sd_session_get_tty()</code>
100 101 102 103 104
                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
                <a href="free.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
Michael Biebl's avatar
Michael Biebl committed
105 106 107 108 109 110 111 112
                call after use.</p><p><code class="function">sd_session_get_vt()</code>
                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.</p><p>If the <code class="varname">session</code> parameter of
                any of these functions is passed as
                <code class="constant">NULL</code>, the operation is executed
                for the session the calling process is a member of, if
Michael Biebl's avatar
Michael Biebl committed
113
                there is any.</p></div><div class="refsect1"><a name="idm214167746672"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>If the test succeeds,
114 115 116
                <code class="function">sd_session_is_active()</code> and
                <code class="function">sd_session_is_remote()</code> return a
                positive integer; if it fails, 0.  On success,
117 118 119 120 121 122
                <code class="function">sd_session_get_state()</code>,
                <code class="function">sd_session_get_uid()</code>,
                <code class="function">sd_session_get_seat()</code>,
                <code class="function">sd_session_get_service()</code>,
                <code class="function">sd_session_get_type()</code>,
                <code class="function">sd_session_get_class()</code>,
123 124 125
                <code class="function">sd_session_get_display()</code>,
                <code class="function">sd_session_get_remote_user()</code>,
                <code class="function">sd_session_get_remote_host()</code> and
126 127
                <code class="function">sd_session_get_tty()</code> return 0 or
                a positive integer. On failure, these calls return a
Michael Biebl's avatar
Michael Biebl committed
128
                negative errno-style error code.</p></div><div class="refsect1"><a name="idm214167737776"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p>The <code class="function">sd_session_is_active()</code>,
129 130 131 132 133 134
                <code class="function">sd_session_get_state()</code>,
                <code class="function">sd_session_get_uid()</code>,
                <code class="function">sd_session_get_seat()</code>,
                <code class="function">sd_session_get_service()</code>,
                <code class="function">sd_session_get_type()</code>,
                <code class="function">sd_session_get_class()</code>,
135 136 137
                <code class="function">sd_session_get_display()</code>,
                <code class="function">sd_session_get_remote_host()</code>,
                <code class="function">sd_session_get_remote_user()</code> and
138
                <code class="function">sd_session_get_tty()</code>
139
                interfaces are available as a shared library, which can
140
                be compiled and linked to with the
141
                <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
142
                file.</p></div><div class="refsect1"><a name="idm214167728448"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
143 144 145 146
                        <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                        <a href="sd-login.html"><span class="citerefentry"><span class="refentrytitle">sd-login</span>(3)</span></a>,
                        <a href="sd_pid_get_session.html"><span class="citerefentry"><span class="refentrytitle">sd_pid_get_session</span>(3)</span></a>
                </p></div></div></body></html>