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