chiark / gitweb /
man: mention XDG_CONFIG_HOME in systemd.unit
[elogind.git] / man / sd-login.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd-login" conditional='HAVE_PAM'
25         xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>sd-login</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>sd-login</refentrytitle>
43                 <manvolnum>3</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>sd-login</refname>
48                 <refpurpose>APIs for
49                 tracking logins</refpurpose>
50         </refnamediv>
51
52         <refsynopsisdiv>
53                 <funcsynopsis>
54                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
55                 </funcsynopsis>
56
57                 <cmdsynopsis>
58                         <command>pkg-config --cflags --libs libsystemd</command>
59                 </cmdsynopsis>
60         </refsynopsisdiv>
61
62         <refsect1>
63                 <title>Description</title>
64
65                 <para><filename>sd-login.h</filename> provides APIs to
66                 introspect and monitor seat, login session and user
67                 status information on the local system. </para>
68
69                 <para>See <ulink
70                 url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat
71                 on Linux</ulink> for an introduction into multi-seat
72                 support on Linux, the background for this set of APIs.</para>
73
74                 <para>Note that these APIs only allow purely passive access
75                 and monitoring of seats, sessions and users. To
76                 actively make changes to the seat configuration,
77                 terminate login sessions, or switch session on a seat
78                 you need to utilize the D-Bus API of
79                 systemd-logind, instead.</para>
80
81                 <para>These functions synchronously access data in
82                 <filename>/proc</filename>,
83                 <filename>/sys/fs/cgroup</filename> and
84                 <filename>/run</filename>. All of these are virtual
85                 file systems, hence the runtime cost of the accesses
86                 is relatively cheap.</para>
87
88                 <para>It is possible (and often a very good choice) to
89                 mix calls to the synchronous interface of
90                 <filename>sd-login.h</filename> with the asynchronous
91                 D-Bus interface of systemd-logind. However, if this is
92                 done you need to think a bit about possible races
93                 since the stream of events from D-Bus and from
94                 <filename>sd-login.h</filename> interfaces such as the
95                 login monitor are asynchronous and not ordered against
96                 each other.</para>
97
98                 <para>If the functions return string arrays, these are
99                 generally <constant>NULL</constant> terminated and need to be freed by the
100                 caller with the libc
101                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
102                 call after use, including the strings referenced
103                 therein. Similarly, individual strings returned need to
104                 be freed, as well.</para>
105
106                 <para>As a special exception, instead of an empty
107                 string array <constant>NULL</constant> may be returned, which should be
108                 treated equivalent to an empty string array.</para>
109
110                 <para>See
111                 <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
112                 <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
113                 <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
114                 <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
115                 <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
116                 <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
117                 for more information about the functions
118                 implemented.</para>
119         </refsect1>
120
121         <xi:include href="libsystemd-pkgconfig.xml" />
122
123         <refsect1>
124                 <title>See Also</title>
125                 <para>
126                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
127                         <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
128                         <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
129                         <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
130                         <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
131                         <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
132                         <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
133                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
134                         <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
135                         <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
136                 </para>
137         </refsect1>
138
139 </refentry>