sd_session_is_active.xml revision 56ba3c78ae35065064c4289a0c8e22a81256af20
97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml version='1.0'?> <!--*-nxml-*-->
97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
97a9a944b5887e91042b019776c41d5dd74557aferikabele "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive<!--
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive This file is part of systemd.
5a58787efeb02a1c3f06569d019ad81fd2efa06end
5a58787efeb02a1c3f06569d019ad81fd2efa06end Copyright 2010 Lennart Poettering
5a58787efeb02a1c3f06569d019ad81fd2efa06end
5a58787efeb02a1c3f06569d019ad81fd2efa06end systemd is free software; you can redistribute it and/or modify it
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen under the terms of the GNU Lesser General Public License as published by
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen the Free Software Foundation; either version 2.1 of the License, or
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen (at your option) any later version.
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen
5a58787efeb02a1c3f06569d019ad81fd2efa06end systemd is distributed in the hope that it will be useful, but
5a58787efeb02a1c3f06569d019ad81fd2efa06end WITHOUT ANY WARRANTY; without even the implied warranty of
5a58787efeb02a1c3f06569d019ad81fd2efa06end MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5a58787efeb02a1c3f06569d019ad81fd2efa06end Lesser General Public License for more details.
3f08db06526d6901aa08c110b5bc7dde6bc39905nd
5a58787efeb02a1c3f06569d019ad81fd2efa06end You should have received a copy of the GNU Lesser General Public License
5a58787efeb02a1c3f06569d019ad81fd2efa06end along with systemd; If not, see <http://www.gnu.org/licenses/>.
5a58787efeb02a1c3f06569d019ad81fd2efa06end-->
3f08db06526d6901aa08c110b5bc7dde6bc39905nd
5a58787efeb02a1c3f06569d019ad81fd2efa06end<refentry id="sd_session_is_active" conditional='HAVE_PAM'>
a63f0ab647ad2ab72efc9bea7a66e24e9ebc5cc2nd
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <refentryinfo>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <title>sd_session_is_active</title>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <productname>systemd</productname>
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <authorgroup>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <author>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <contrib>Developer</contrib>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <firstname>Lennart</firstname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <surname>Poettering</surname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <email>lennart@poettering.net</email>
5a58787efeb02a1c3f06569d019ad81fd2efa06end </author>
5a58787efeb02a1c3f06569d019ad81fd2efa06end </authorgroup>
5a58787efeb02a1c3f06569d019ad81fd2efa06end </refentryinfo>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive
ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd <refmeta>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refentrytitle>sd_session_is_active</refentrytitle>
ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd <manvolnum>3</manvolnum>
b21197dc8e6b8c764fdcc24d4bae8b0eebb6bc4end </refmeta>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refnamediv>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <refname>sd_session_is_active</refname>
97a9a944b5887e91042b019776c41d5dd74557aferikabele <refname>sd_session_get_state</refname>
f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_session_get_uid</refname>
ffb01336be79c64046b636e59fa8ddca8ec029edsf <refname>sd_session_get_seat</refname>
f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_session_get_service</refname>
f8396ed8364b56ec8adeaa49cac35a929758a29eslive <refname>sd_session_get_type</refname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <refname>sd_session_get_class</refname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <refname>sd_session_get_display</refname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <refname>sd_session_get_tty</refname>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <refpurpose>Determine state of a specific session</refpurpose>
deeee6bb6fd94c0ba5f3730b58abd9d299c89ccdnd </refnamediv>
4db28ee269aa06f7c6232e11cd01f58c3349af23noodl
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <refsynopsisdiv>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcsynopsis>
4a31db3c3a0202003c1b9f87affa7cc143e120e5sf <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd
ffb01336be79c64046b636e59fa8ddca8ec029edsf <funcprototype>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcdef>int <function>sd_session_is_active</function></funcdef>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <paramdef>const char* <parameter>session</parameter></paramdef>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd </funcprototype>
2bc7f1cf720973a67f8ff7a8d523e40569ae5b6cnd
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcprototype>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <funcdef>int <function>sd_session_get_state</function></funcdef>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <paramdef>const char* <parameter>session</parameter></paramdef>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <paramdef>char** <parameter>state</parameter></paramdef>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd </funcprototype>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd
87ffb6e33f3cbef3b9bb406cc2d27039fa336eaatrawick <funcprototype>
4db28ee269aa06f7c6232e11cd01f58c3349af23noodl <funcdef>int <function>sd_session_get_uid</function></funcdef>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <paramdef>const char* <parameter>session</parameter></paramdef>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <paramdef>uid_t* <parameter>uid</parameter></paramdef>
5a58787efeb02a1c3f06569d019ad81fd2efa06end </funcprototype>
5a58787efeb02a1c3f06569d019ad81fd2efa06end
5a58787efeb02a1c3f06569d019ad81fd2efa06end <funcprototype>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <funcdef>int <function>sd_session_get_seat</function></funcdef>
654d8eb036bedc99e90e11910ee02d3421417697rbowen <paramdef>const char* <parameter>session</parameter></paramdef>
5a58787efeb02a1c3f06569d019ad81fd2efa06end <paramdef>char** <parameter>seat</parameter></paramdef>
5a58787efeb02a1c3f06569d019ad81fd2efa06end </funcprototype>
5a58787efeb02a1c3f06569d019ad81fd2efa06end
5a58787efeb02a1c3f06569d019ad81fd2efa06end <funcprototype>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <funcdef>int <function>sd_session_get_service</function></funcdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>const char* <parameter>session</parameter></paramdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>char** <parameter>service</parameter></paramdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick </funcprototype>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <funcprototype>
654d8eb036bedc99e90e11910ee02d3421417697rbowen <funcdef>int <function>sd_session_get_type</function></funcdef>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <paramdef>const char* <parameter>session</parameter></paramdef>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <paramdef>char** <parameter>type</parameter></paramdef>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive </funcprototype>
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive
97a9a944b5887e91042b019776c41d5dd74557aferikabele <funcprototype>
654d8eb036bedc99e90e11910ee02d3421417697rbowen <funcdef>int <function>sd_session_get_class</function></funcdef>
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <paramdef>const char* <parameter>session</parameter></paramdef>
97a9a944b5887e91042b019776c41d5dd74557aferikabele <paramdef>char** <parameter>class</parameter></paramdef>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive </funcprototype>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <funcprototype>
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <funcdef>int <function>sd_session_get_display</function></funcdef>
ffb01336be79c64046b636e59fa8ddca8ec029edsf <paramdef>const char* <parameter>session</parameter></paramdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>char** <parameter>display</parameter></paramdef>
ffb01336be79c64046b636e59fa8ddca8ec029edsf </funcprototype>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <funcprototype>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <funcdef>int <function>sd_session_get_tty</function></funcdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>const char* <parameter>session</parameter></paramdef>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <paramdef>char** <parameter>tty</parameter></paramdef>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf </funcprototype>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick </funcsynopsis>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf </refsynopsisdiv>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf
ffb01336be79c64046b636e59fa8ddca8ec029edsf <refsect1>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <title>Description</title>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <para><function>sd_session_is_active()</function> may
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick be used to determine whether the session identified by
77c77cf89621f21c8e2bbad63058b5eaa5f88d4ajim the specified session identifier is currently active
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick (i.e. currently in the foreground and available for
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf user input) or not.</para>
ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <para><function>sd_session_get_state()</function> may
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf be used to determine the state of the session
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf identified by the specified session identifier. The
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf following states are currently known:
ced7ef1f8c0df1805da0e87dbc5a1b6282910573nd <literal>online</literal> (session logged in, but
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick session not active, i.e. not in the foreground),
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <literal>active</literal> (session logged in and
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick active, i.e. in the foreground),
4a31db3c3a0202003c1b9f87affa7cc143e120e5sf <literal>closing</literal> (session nominally logged
4a31db3c3a0202003c1b9f87affa7cc143e120e5sf out, but some processes belonging to it are still
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick around). In the future additional states might be
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick defined, client code should be written to be robust in
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick regards to additional state strings being
ffb01336be79c64046b636e59fa8ddca8ec029edsf returned. This function is a more generic version of
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <function>sd_session_is_active()</function>. The returned
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive string needs to be freed with the libc
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
97a9a944b5887e91042b019776c41d5dd74557aferikabele call after use.</para>
92510838f2eb125726e15c5eb4f7a23c7a0396e4slive
ea8a727ff298d2f5368b55b7ae8d87091ae106e7nd <para><function>sd_session_get_uid()</function> may be
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick used to determine the user identifier of the Unix user the session
ea8a727ff298d2f5368b55b7ae8d87091ae106e7nd identified by the specified session identifier belongs
ffb01336be79c64046b636e59fa8ddca8ec029edsf to.</para>
ea8a727ff298d2f5368b55b7ae8d87091ae106e7nd
ea8a727ff298d2f5368b55b7ae8d87091ae106e7nd <para><function>sd_session_get_seat()</function> may
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick be used to determine the seat identifier of the seat
ea8a727ff298d2f5368b55b7ae8d87091ae106e7nd the session identified by the specified session
06ba4a61654b3763ad65f52283832ebf058fdf1cslive identifier belongs to. Note that not all sessions are
e8d485701957d5c6de870111c112e168a894d49and attached to a seat, this call will fail for them. The
e8d485701957d5c6de870111c112e168a894d49and returned string needs to be freed with the libc
654d8eb036bedc99e90e11910ee02d3421417697rbowen <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
654d8eb036bedc99e90e11910ee02d3421417697rbowen call after use.</para>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <para><function>sd_session_get_service()</function>
9bcfc3697a91b5215893a7d0206865b13fc72148nd may be used to determine the name of the service (as
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive passed during PAM session setup) that registered the
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive session identified by the specified session
06ba4a61654b3763ad65f52283832ebf058fdf1cslive identifier. The returned string needs to be freed with
4a31db3c3a0202003c1b9f87affa7cc143e120e5sf the libc
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
9b6a3a558cc90ffdaa0b50bd02546ffec424ded7slive call after use.</para>
709e3a21ba73b8433462959cd56c773454b34441trawick
709e3a21ba73b8433462959cd56c773454b34441trawick <para><function>sd_session_get_type()</function> may
709e3a21ba73b8433462959cd56c773454b34441trawick be used to determine the type of the session
709e3a21ba73b8433462959cd56c773454b34441trawick identified by the specified session identifier. The
709e3a21ba73b8433462959cd56c773454b34441trawick returned string is one of <literal>x11</literal>,
709e3a21ba73b8433462959cd56c773454b34441trawick <literal>tty</literal> or
709e3a21ba73b8433462959cd56c773454b34441trawick <literal>unspecified</literal> and needs to be freed
5a58787efeb02a1c3f06569d019ad81fd2efa06end with the libc
5a58787efeb02a1c3f06569d019ad81fd2efa06end <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd call after use.</para>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <para><function>sd_session_get_class()</function> may
e1e8390280254f7f0580d701e583f670643d4f3fnilgun be used to determine the class of the session
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung identified by the specified session identifier. The
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd returned string is one of <literal>user</literal>,
5effc8b39fae5cd169d17f342bfc265705840014rbowen <literal>greeter</literal> or
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen <literal>lock-screen</literal> and needs to be freed
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen with the libc
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen call after use.</para>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen
5a58787efeb02a1c3f06569d019ad81fd2efa06end <para><function>sd_session_get_display()</function>
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
<citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use.</para>
<para><function>sd_session_get_tty()</function>
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
<citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call after use.</para>
<para>If the <literal>session</literal> parameter of
any of these functions is passed as NULL the operation
is executed for the session the calling process is a
member of, if there is any.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>If the test succeeds
<function>sd_session_is_active()</function> returns a
positive integer, if it fails 0. On success
<function>sd_session_get_state()</function>,
<function>sd_session_get_uid()</function>,
<function>sd_session_get_seat()</function>,
<function>sd_session_get_service()</function>,
<function>sd_session_get_type()</function>,
<function>sd_session_get_class()</function>,
<function>sd_session_get_display()</function> and
<function>sd_session_get_tty()</function> return 0 or
a positive integer. On failure, these calls return a
negative errno-style error code.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The <function>sd_session_is_active()</function>,
<function>sd_session_get_state()</function>,
<function>sd_session_get_uid()</function>,
<function>sd_session_get_seat()</function>,
<function>sd_session_get_service()</function>,
<function>sd_session_get_type()</function>,
<function>sd_session_get_class()</function>,
<function>sd_session_get_display()</function> and
<function>sd_session_get_tty()</function>
interfaces are available as shared library, which can
be compiled and linked to with the
<literal>libsystemd-login</literal>
<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</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_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>