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 introspect
  66     and monitor seat, login session and user status information on the
  67     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 support on
  72     Linux, the background for this set of APIs.</para>
  73
  74     <para>Note that these APIs only allow purely passive access and
  75     monitoring of seats, sessions and users. To actively make changes
  76     to the seat configuration, terminate login sessions, or switch
  77     session on a seat you need to utilize the D-Bus API of
  78     systemd-logind, instead.</para>
  79
  80     <para>These functions synchronously access data in
  81     <filename>/proc</filename>, <filename>/sys/fs/cgroup</filename>
  82     and <filename>/run</filename>. All of these are virtual file
  83     systems, hence the runtime cost of the accesses is relatively
  84     cheap.</para>
  85
  86     <para>It is possible (and often a very good choice) to mix calls
  87     to the synchronous interface of <filename>sd-login.h</filename>
  88     with the asynchronous D-Bus interface of systemd-logind. However,
  89     if this is done you need to think a bit about possible races since
  90     the stream of events from D-Bus and from
  91     <filename>sd-login.h</filename> interfaces such as the login
  92     monitor are asynchronous and not ordered against each
  93     other.</para>
  94
  95     <para>If the functions return string arrays, these are generally
  96     <constant>NULL</constant> terminated and need to be freed by the
  97     caller with the libc
  98     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  99     call after use, including the strings referenced therein.
 100     Similarly, individual strings returned need to be freed, as
 101     well.</para>
 102
 103     <para>As a special exception, instead of an empty string array
 104     <constant>NULL</constant> may be returned, which should be treated
 105     equivalent to an empty string array.</para>
 106
 107     <para>See
 108     <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 109     <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 110     <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 111     <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 112     <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 113     <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114     for more information about the functions
 115     implemented.</para>
 116   </refsect1>
 117
 118   <xi:include href="libsystemd-pkgconfig.xml" />
 119
 120   <refsect1>
 121     <title>See Also</title>
 122     <para>
 123       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 124       <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 125       <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 126       <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 127       <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 128       <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 129       <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 130       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 131       <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 132     </para>
 133   </refsect1>
 134
 135 </refentry>