man/sd_session_is_remote.html

   1 <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>
   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 218</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_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</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_desktop</b>(</code></td><td>const char *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">desktop</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="idm140536242843936"></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                 be used to determine whether the session identified by
  24                 the specified session identifier is currently active
  25                 (i.e. currently in the foreground and available for
  26                 user input) or not.</p><p><code class="function">sd_session_is_remote()</code> may
  27                 be used to determine whether the session identified by
  28                 the specified session identifier is a remote session
  29                 (i.e. its remote host is known) or not.</p><p><code class="function">sd_session_get_state()</code> may
  30                 be used to determine the state of the session
  31                 identified by the specified session identifier. The
  32                 following states are currently known:
  33                 "<code class="literal">online</code>" (session logged in, but
  34                 session not active, i.e. not in the foreground),
  35                 "<code class="literal">active</code>" (session logged in and
  36                 active, i.e. in the foreground),
  37                 "<code class="literal">closing</code>" (session nominally logged
  38                 out, but some processes belonging to it are still
  39                 around). In the future additional states might be
  40                 defined, client code should be written to be robust in
  41                 regards to additional state strings being
  42                 returned. This function is a more generic version of
  43                 <code class="function">sd_session_is_active()</code>. The returned
  44                 string needs to be freed with the libc
  45                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  46                 call after use.</p><p><code class="function">sd_session_get_uid()</code> may be
  47                 used to determine the user identifier of the Unix user the session
  48                 identified by the specified session identifier belongs
  49                 to.</p><p><code class="function">sd_session_get_seat()</code> may
  50                 be used to determine the seat identifier of the seat
  51                 the session identified by the specified session
  52                 identifier belongs to. Note that not all sessions are
  53                 attached to a seat, this call will fail for them. The
  54                 returned string needs to be freed with the libc
  55                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  56                 call after use.</p><p><code class="function">sd_session_get_service()</code>
  57                 may be used to determine the name of the service (as
  58                 passed during PAM session setup) that registered the
  59                 session identified by the specified session
  60                 identifier. The returned string needs to be freed with
  61                 the libc
  62                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  63                 call after use.</p><p><code class="function">sd_session_get_type()</code> may
  64                 be used to determine the type of the session
  65                 identified by the specified session identifier. The
  66                 returned string is one of "<code class="literal">x11</code>",
  67                 "<code class="literal">wayland</code>", "<code class="literal">tty</code>",
  68                 "<code class="literal">mir</code>" or "<code class="literal">unspecified</code>" and
  69                 needs to be freed with the libc
  70                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  71                 call after use.</p><p><code class="function">sd_session_get_class()</code> may
  72                 be used to determine the class of the session
  73                 identified by the specified session identifier. The
  74                 returned string is one of "<code class="literal">user</code>",
  75                 "<code class="literal">greeter</code>",
  76                 "<code class="literal">lock-screen</code>", or
  77                 "<code class="literal">background</code>" and needs to be freed
  78                 with the libc
  79                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  80                 call after use.</p><p><code class="function">sd_session_get_desktop()</code> may
  81                 be used to determine the brand of the desktop running on
  82                 the session identified by the specified session identifier.
  83                 This field can be set freely by desktop environments and
  84                 does not follow any special formatting. However, desktops
  85                 are strongly recommended to use the same identifiers and
  86                 capitalization as for
  87                 <code class="varname">$XDG_CURRENT_DESKTOP</code>, as defined by
  88                 the <a class="ulink" href="http://standards.freedesktop.org/desktop-entry-spec/latest/" target="_top">Desktop
  89                 Entry
  90                 Specification</a>. The returned string needs to be
  91                 freed with the libc
  92                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  93                 call after use.</p><p><code class="function">sd_session_get_display()</code>
  94                 may be used to determine the X11 display of the
  95                 session identified by the specified session
  96                 identifier. The returned string needs to be
  97                 freed with the libc
  98                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
  99                 call after use.</p><p><code class="function">sd_session_get_remote_host()</code>
 100                 may be used to determine the remote hostname of the
 101                 session identified by the specified session
 102                 identifier. The returned string needs to be
 103                 freed with the libc
 104                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
 105                 call after use.</p><p><code class="function">sd_session_get_remote_user()</code>
 106                 may be used to determine the remote username of the
 107                 session identified by the specified session
 108                 identifier. The returned string needs to be
 109                 freed with the libc
 110                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
 111                 call after use. Note that this value is rarely known
 112                 to the system, and even then should not be relied on.</p><p><code class="function">sd_session_get_tty()</code>
 113                 may be used to determine the TTY device of the
 114                 session identified by the specified session
 115                 identifier. The returned string needs to be
 116                 freed with the libc
 117                 <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>
 118                 call after use.</p><p><code class="function">sd_session_get_vt()</code>
 119                 may be used to determine the VT number of the
 120                 session identified by the specified session
 121                 identifier. This function will return an error if
 122                 the seat does not support VTs.</p><p>If the <code class="varname">session</code> parameter of
 123                 any of these functions is passed as
 124                 <code class="constant">NULL</code>, the operation is executed
 125                 for the session the calling process is a member of, if
 126                 there is any.</p></div><div class="refsect1"><a name="idm140536237842848"></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,
 127                 <code class="function">sd_session_is_active()</code> and
 128                 <code class="function">sd_session_is_remote()</code> return a
 129                 positive integer; if it fails, 0.  On success,
 130                 <code class="function">sd_session_get_state()</code>,
 131                 <code class="function">sd_session_get_uid()</code>,
 132                 <code class="function">sd_session_get_seat()</code>,
 133                 <code class="function">sd_session_get_service()</code>,
 134                 <code class="function">sd_session_get_type()</code>,
 135                 <code class="function">sd_session_get_class()</code>,
 136                 <code class="function">sd_session_get_display()</code>,
 137                 <code class="function">sd_session_get_remote_user()</code>,
 138                 <code class="function">sd_session_get_remote_host()</code> and
 139                 <code class="function">sd_session_get_tty()</code> return 0 or
 140                 a positive integer. On failure, these calls return a
 141                 negative errno-style error code.</p></div><div class="refsect1"><a name="idm140536237833952"></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>,
 142                 <code class="function">sd_session_get_state()</code>,
 143                 <code class="function">sd_session_get_uid()</code>,
 144                 <code class="function">sd_session_get_seat()</code>,
 145                 <code class="function">sd_session_get_service()</code>,
 146                 <code class="function">sd_session_get_type()</code>,
 147                 <code class="function">sd_session_get_class()</code>,
 148                 <code class="function">sd_session_get_display()</code>,
 149                 <code class="function">sd_session_get_remote_host()</code>,
 150                 <code class="function">sd_session_get_remote_user()</code> and
 151                 <code class="function">sd_session_get_tty()</code>
 152                 interfaces are available as a shared library, which can
 153                 be compiled and linked to with the
 154                 <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>
 155                 file.</p></div><div class="refsect1"><a name="idm140536237824384"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 156                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 157                         <a href="sd-login.html"><span class="citerefentry"><span class="refentrytitle">sd-login</span>(3)</span></a>,
 158                         <a href="sd_pid_get_session.html"><span class="citerefentry"><span class="refentrytitle">sd_pid_get_session</span>(3)</span></a>
 159                 </p></div></div></body></html>