<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!ENTITY % entities SYSTEM "custom-entities.ent" >

%entities;

]>

<refentry id="sd-login" conditional='HAVE_PAM'

xmlns:xi="http://www.w3.org/2001/XInclude">

<refentryinfo>

<title>sd-login</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd-login</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd-login</refname>

<refpurpose>APIs for

tracking logins</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>

</funcsynopsis>

<cmdsynopsis>

<command>pkg-config --cflags --libs libsystemd</command>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><filename>sd-login.h</filename> provides APIs to introspect

and monitor seat, login session and user status information on the

local system. </para>

<para>See <ulink

url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat

on Linux</ulink> for an introduction into multi-seat support on

Linux, the background for this set of APIs.</para>

<para>Note that these APIs only allow purely passive access and

monitoring of seats, sessions and users. To actively make changes

to the seat configuration, terminate login sessions, or switch

session on a seat you need to utilize the D-Bus API of

systemd-logind, instead.</para>

<para>These functions synchronously access data in

<filename>/proc</filename>, <filename>/sys/fs/cgroup</filename>

and <filename>/run</filename>. All of these are virtual file

systems, hence the runtime cost of the accesses is relatively

cheap.</para>

<para>It is possible (and often a very good choice) to mix calls

to the synchronous interface of <filename>sd-login.h</filename>

with the asynchronous D-Bus interface of systemd-logind. However,

if this is done you need to think a bit about possible races since

the stream of events from D-Bus and from

<filename>sd-login.h</filename> interfaces such as the login

monitor are asynchronous and not ordered against each

other.</para>

<para>If the functions return string arrays, these are generally

<constant>NULL</constant> terminated and need to be freed by the

caller with the libc

<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use, including the strings referenced therein.

Similarly, individual strings returned need to be freed, as

well.</para>

<para>As a special exception, instead of an empty string array

<constant>NULL</constant> may be returned, which should be treated

equivalent to an empty string array.</para>

<para>See

<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>

for more information about the functions

implemented.</para>

</refsect1>

<xi:include href="libsystemd-pkgconfig.xml" />

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>