]>
Commit | Line | Data |
---|---|---|
663996b3 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
bb4f798a | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
e735f4d4 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
a032b68d | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
663996b3 | 5 | |
b012e921 MB |
6 | <refentry id="sd_seat_get_active" conditional='HAVE_PAM' |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
663996b3 | 8 | |
e735f4d4 MP |
9 | <refentryinfo> |
10 | <title>sd_seat_get_active</title> | |
11 | <productname>systemd</productname> | |
e735f4d4 MP |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>sd_seat_get_active</refentrytitle> | |
16 | <manvolnum>3</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>sd_seat_get_active</refname> | |
21 | <refname>sd_seat_get_sessions</refname> | |
e735f4d4 MP |
22 | <refname>sd_seat_can_tty</refname> |
23 | <refname>sd_seat_can_graphical</refname> | |
24 | <refpurpose>Determine state of a specific seat</refpurpose> | |
25 | </refnamediv> | |
26 | ||
27 | <refsynopsisdiv> | |
28 | <funcsynopsis> | |
29 | <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> | |
30 | ||
31 | <funcprototype> | |
32 | <funcdef>int <function>sd_seat_get_active</function></funcdef> | |
33 | <paramdef>const char *<parameter>seat</parameter></paramdef> | |
34 | <paramdef>char **<parameter>session</parameter></paramdef> | |
35 | <paramdef>uid_t *<parameter>uid</parameter></paramdef> | |
36 | </funcprototype> | |
37 | ||
38 | <funcprototype> | |
39 | <funcdef>int <function>sd_seat_get_sessions</function></funcdef> | |
40 | <paramdef>const char *<parameter>seat</parameter></paramdef> | |
a032b68d MB |
41 | <paramdef>char ***<parameter>ret_sessions</parameter></paramdef> |
42 | <paramdef>uid_t **<parameter>ret_uids</parameter></paramdef> | |
43 | <paramdef>unsigned int *<parameter>ret_n_uids</parameter></paramdef> | |
e735f4d4 MP |
44 | </funcprototype> |
45 | ||
e735f4d4 MP |
46 | <funcprototype> |
47 | <funcdef>int <function>sd_seat_can_tty</function></funcdef> | |
48 | <paramdef>const char *<parameter>seat</parameter></paramdef> | |
49 | </funcprototype> | |
50 | ||
51 | <funcprototype> | |
52 | <funcdef>int <function>sd_seat_can_graphical</function></funcdef> | |
53 | <paramdef>const char *<parameter>seat</parameter></paramdef> | |
54 | </funcprototype> | |
55 | </funcsynopsis> | |
56 | </refsynopsisdiv> | |
57 | ||
58 | <refsect1> | |
59 | <title>Description</title> | |
60 | ||
61 | <para><function>sd_seat_get_active()</function> may be used to | |
62 | determine which session is currently active on a seat, if there is | |
63 | any. Returns the session identifier and the user identifier of the | |
64 | Unix user the session is belonging to. Either the session or the | |
65 | user identifier parameter can be passed <constant>NULL</constant>, | |
66 | in case only one of the parameters shall be queried. The returned | |
67 | string needs to be freed with the libc | |
68 | <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
69 | call after use.</para> | |
70 | ||
a032b68d MB |
71 | <para><function>sd_seat_get_sessions()</function> may be used to determine all sessions on the specified |
72 | seat. Returns two arrays, one (<constant>NULL</constant> terminated) with the session identifiers of the | |
73 | sessions and one with the user identifiers of the Unix users the sessions belong to. An additional | |
74 | parameter may be used to return the number of entries in the latter array. This value is the same as the | |
75 | return value if the return value is nonnegative. The output parameters may be passed as | |
76 | <constant>NULL</constant> in case these output values are not needed. The arrays and the strings | |
77 | referenced by them need to be freed with the libc <citerefentry | |
78 | project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after | |
79 | use. Note that instead of an empty array <constant>NULL</constant> may be returned and should be | |
80 | considered equivalent to an empty array.</para> | |
e735f4d4 | 81 | |
e735f4d4 MP |
82 | <para><function>sd_seat_can_tty()</function> may be used to |
83 | determine whether a specific seat provides TTY functionality, i.e. | |
84 | is useful as a text console.</para> | |
85 | ||
86 | <para><function>sd_seat_can_graphical()</function> may be used to | |
87 | determine whether a specific seat provides graphics functionality, | |
88 | i.e. is useful as a graphics display.</para> | |
89 | ||
90 | <para>If the <varname>seat</varname> parameter of any of these | |
91 | functions is passed as <constant>NULL</constant>, the operation is | |
92 | executed for the seat of the session of the calling process, if | |
93 | there is any.</para> | |
94 | </refsect1> | |
95 | ||
96 | <refsect1> | |
97 | <title>Return Value</title> | |
98 | ||
bb4f798a MB |
99 | <para> On success, <function>sd_seat_get_active()</function> returns 0 or a positive integer. On success, |
100 | <function>sd_seat_get_sessions()</function> returns the number of entries in the session identifier | |
a10f5d05 | 101 | array. If the test succeeds, |
a032b68d | 102 | <function>sd_seat_can_tty()</function> and <function>sd_seat_can_graphical()</function> return a positive |
bb4f798a | 103 | integer, if it fails 0. On failure, these calls return a negative errno-style error code.</para> |
e735f4d4 | 104 | |
bb4f798a MB |
105 | <refsect2> |
106 | <title>Errors</title> | |
d9dfd233 | 107 | |
bb4f798a | 108 | <para>Returned errors may indicate the following problems:</para> |
d9dfd233 | 109 | |
bb4f798a | 110 | <variablelist> |
d9dfd233 | 111 | |
bb4f798a MB |
112 | <varlistentry> |
113 | <term><constant>-ENODATA</constant></term> | |
d9dfd233 | 114 | |
bb4f798a MB |
115 | <listitem><para>The given field is not specified for the described seat.</para> |
116 | </listitem> | |
117 | </varlistentry> | |
d9dfd233 | 118 | |
bb4f798a MB |
119 | <varlistentry> |
120 | <term><constant>-ENXIO</constant></term> | |
d9dfd233 | 121 | |
bb4f798a MB |
122 | <listitem><para>The specified seat is unknown.</para> |
123 | </listitem> | |
124 | </varlistentry> | |
d9dfd233 | 125 | |
bb4f798a MB |
126 | <varlistentry> |
127 | <term><constant>-EINVAL</constant></term> | |
d9dfd233 | 128 | |
bb4f798a MB |
129 | <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where |
130 | that is not accepted).</para></listitem> | |
131 | </varlistentry> | |
d9dfd233 | 132 | |
bb4f798a MB |
133 | <varlistentry> |
134 | <term><constant>-ENOMEM</constant></term> | |
d9dfd233 | 135 | |
bb4f798a MB |
136 | <listitem><para>Memory allocation failed.</para></listitem> |
137 | </varlistentry> | |
138 | </variablelist> | |
139 | </refsect2> | |
d9dfd233 MP |
140 | </refsect1> |
141 | ||
b012e921 | 142 | <xi:include href="libsystemd-pkgconfig.xml" /> |
e735f4d4 | 143 | |
a10f5d05 MB |
144 | <refsect1> |
145 | <title>History</title> | |
146 | ||
147 | <para>In the past, <function>sd_seat_can_multi_session()</function> was used to check whether the seat | |
148 | supports multiple sessions. All seats support that now, so that function has been deprecated and always | |
149 | returns true.</para> | |
150 | </refsect1> | |
151 | ||
e735f4d4 MP |
152 | <refsect1> |
153 | <title>See Also</title> | |
154 | ||
155 | <para> | |
156 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
157 | <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
158 | <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
159 | </para> | |
160 | </refsect1> | |
663996b3 MS |
161 | |
162 | </refentry> |