man/sd_get_seats.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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2010 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_get_seats" conditional='HAVE_PAM'
  14           xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <refentryinfo>
  17     <title>sd_get_seats</title>
  18     <productname>systemd</productname>
  19
  20     <authorgroup>
  21       <author>
  22         <contrib>Developer</contrib>
  23         <firstname>Lennart</firstname>
  24         <surname>Poettering</surname>
  25         <email>lennart@poettering.net</email>
  26       </author>
  27     </authorgroup>
  28   </refentryinfo>
  29
  30   <refmeta>
  31     <refentrytitle>sd_get_seats</refentrytitle>
  32     <manvolnum>3</manvolnum>
  33   </refmeta>
  34
  35   <refnamediv>
  36     <refname>sd_get_seats</refname>
  37     <refname>sd_get_sessions</refname>
  38     <refname>sd_get_uids</refname>
  39     <refname>sd_get_machine_names</refname>
  40     <refpurpose>Determine available seats, sessions, logged in users and virtual machines/containers</refpurpose>
  41   </refnamediv>
  42
  43   <refsynopsisdiv>
  44     <funcsynopsis>
  45       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  46
  47       <funcprototype>
  48         <funcdef>int <function>sd_get_seats</function></funcdef>
  49         <paramdef>char ***<parameter>seats</parameter></paramdef>
  50       </funcprototype>
  51
  52       <funcprototype>
  53         <funcdef>int <function>sd_get_sessions</function></funcdef>
  54         <paramdef>char ***<parameter>sessions</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_get_uids</function></funcdef>
  59         <paramdef>uid_t **<parameter>users</parameter></paramdef>
  60       </funcprototype>
  61
  62       <funcprototype>
  63         <funcdef>int <function>sd_get_machine_names</function></funcdef>
  64         <paramdef>char ***<parameter>machines</parameter></paramdef>
  65       </funcprototype>
  66
  67     </funcsynopsis>
  68   </refsynopsisdiv>
  69
  70   <refsect1>
  71     <title>Description</title>
  72
  73     <para><function>sd_get_seats()</function> may be used to determine
  74     all currently available local seats. Returns the number of seat
  75     identifiers and if the input pointer is non-NULL, a
  76     <constant>NULL</constant>-terminated array of seat identifiers
  77     is stored at the address.
  78     The returned array and all strings it references need to be freed
  79     with the libc
  80     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  81     call after use. Note that instead of an empty array
  82     <constant>NULL</constant> may be returned and should be considered
  83     equivalent to an empty array.</para>
  84
  85     <para>Similarly, <function>sd_get_sessions()</function> may be
  86     used to determine all current login sessions.</para>
  87
  88     <para>Similarly, <function>sd_get_uids()</function> may be used to
  89     determine all Unix users who currently have login sessions.</para>
  90
  91     <para>Similarly, <function>sd_get_machine_names()</function> may
  92     be used to determine all current virtual machines and containers
  93     on the system.</para>
  94
  95     <para>Note that the returned lists are not sorted and in an
  96     undefined order.</para>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Return Value</title>
 101
 102     <para>On success, <function>sd_get_seats()</function>,
 103     <function>sd_get_sessions()</function>,
 104     <function>sd_get_uids()</function> and
 105     <function>sd_get_machine_names()</function> return the number of
 106     entries in the arrays. On failure, these calls return a negative
 107     errno-style error code.</para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Errors</title>
 112
 113     <para>Returned errors may indicate the following problems:</para>
 114
 115     <variablelist>
 116
 117       <varlistentry>
 118         <term><constant>-ENOMEM</constant></term>
 119
 120         <listitem><para>Memory allocation failed.</para></listitem>
 121       </varlistentry>
 122     </variablelist>
 123   </refsect1>
 124
 125   <xi:include href="libsystemd-pkgconfig.xml" />
 126
 127   <refsect1>
 128     <title>See Also</title>
 129
 130     <para>
 131       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 132       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 134     </para>
 135   </refsect1>
 136
 137 </refentry>