man/sd_machine_get_class.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 2014 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_machine_get_class">
  27
  28   <refentryinfo>
  29     <title>sd_machine_get_class</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_machine_get_class</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_machine_get_class</refname>
  49     <refname>sd_machine_get_ifindices</refname>
  50     <refpurpose>Determine the class and network interface indices of a
  51     locally running virtual machine or container.</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_machine_get_class</function></funcdef>
  60         <paramdef>const char* <parameter>machine</parameter></paramdef>
  61         <paramdef>char **<parameter>class</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_machine_get_ifindices</function></funcdef>
  66         <paramdef>const char* <parameter>machine</parameter></paramdef>
  67         <paramdef>int **<parameter>ifindices</parameter></paramdef>
  68       </funcprototype>
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para><function>sd_machine_get_class()</function> may be used to
  76     determine the class of a locally running virtual machine or
  77     container that is registered with
  78     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  79     The string returned is either <literal>vm</literal> or
  80     <literal>container</literal>. The returned string needs to be
  81     freed with the libc <citerefentry
  82     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  83     call after use.</para>
  84
  85     <para><function>sd_machine_get_ifindices()</function> may be used
  86     to determine the numeric indices of the network interfaces on the
  87     host that are pointing towards the specified locally running
  88     virtual machine or container that is registered with
  89     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  90     The returned array needs to be freed with the libc <citerefentry
  91     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  92     call after use.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Return Value</title>
  97
  98     <para>On success, these calls return 0 or a positive integer. On
  99     failure, these calls return a negative errno-style error
 100     code.</para>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>Errors</title>
 105
 106     <para>Returned errors may indicate the following problems:</para>
 107
 108     <variablelist>
 109
 110       <varlistentry>
 111         <term><constant>-ENXIO</constant></term>
 112
 113         <listitem><para>The specified machine does not exist or is currently not running.</para>
 114         </listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><constant>-EINVAL</constant></term>
 119
 120         <listitem><para>An input parameter was invalid (out of range,
 121         or NULL, where that is not accepted).</para></listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term><constant>-ENOMEM</constant></term>
 126
 127         <listitem><para>Memory allocation failed.</para></listitem>
 128       </varlistentry>
 129     </variablelist>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>Notes</title>
 134
 135     <para>The <function>sd_machine_get_class()</function> and
 136     <function>sd_machine_get_ifindices()</function> interfaces are
 137     available as a shared library, which can be compiled and linked to
 138     with the
 139     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 140     file.</para>
 141   </refsect1>
 142
 143   <refsect1>
 144     <title>See Also</title>
 145
 146     <para>
 147       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 148       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 151     </para>
 152   </refsect1>
 153
 154 </refentry>