man/sd_bus_get_name_machine_id.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_get_name_machine_id" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_get_name_machine_id</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_get_name_machine_id</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_get_name_machine_id</refname>
  20
  21     <refpurpose>Retrieve a bus client's machine identity</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <funcsynopsis>
  26       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  27
  28       <funcprototype>
  29         <funcdef>int <function>sd_bus_get_name_machine_id</function></funcdef>
  30         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  31         <paramdef>const char *<parameter>name</parameter></paramdef>
  32         <paramdef>sd_id128_t *<parameter>machine</parameter></paramdef>
  33       </funcprototype>
  34     </funcsynopsis>
  35   </refsynopsisdiv>
  36
  37   <refsect1>
  38     <title>Description</title>
  39
  40     <para><function>sd_bus_get_name_machine_id()</function> retrieves the D-Bus machine identity of the
  41     machine that the bus client identified by <parameter>name</parameter> is running on. Internally, it calls
  42     the <function>GetMachineId</function> method of the <constant>org.freedesktop.DBus.Peer</constant>
  43     interface. The D-Bus machine identity is a 128-bit UUID. On Linux systems running systemd, this
  44     corresponds to the contents of <filename>/etc/machine-id</filename>. On success, the machine identity is
  45     stored in <parameter>machine</parameter>.</para>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Return Value</title>
  50
  51     <para>On success, this function returns a non-negative integer. On failure, it returns a negative
  52     errno-style error code.</para>
  53
  54     <refsect2>
  55       <title>Errors</title>
  56
  57       <para>Returned errors may indicate the following problems:</para>
  58
  59       <variablelist>
  60         <varlistentry>
  61           <term><constant>-EINVAL</constant></term>
  62
  63           <listitem><para>An argument is invalid.</para>
  64
  65           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  66         </varlistentry>
  67
  68         <varlistentry>
  69           <term><constant>-ENOPKG</constant></term>
  70
  71           <listitem><para>The bus cannot be resolved.</para>
  72
  73           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  74         </varlistentry>
  75
  76         <varlistentry>
  77           <term><constant>-ECHILD</constant></term>
  78
  79           <listitem><para>The bus was created in a different process, library or module instance.</para>
  80
  81           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  82         </varlistentry>
  83
  84         <varlistentry>
  85           <term><constant>-ENOMEM</constant></term>
  86
  87           <listitem><para>Memory allocation failed.</para>
  88
  89           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  90         </varlistentry>
  91       </variablelist>
  92     </refsect2>
  93   </refsect1>
  94
  95   <xi:include href="libsystemd-pkgconfig.xml" />
  96
  97   <refsect1>
  98     <title>History</title>
  99     <para><function>sd_bus_get_name_machine_id()</function> was added in version 246.</para>
 100   </refsect1>
 101
 102   <refsect1>
 103     <title>See Also</title>
 104
 105     <para><simplelist type="inline">
 106       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 107       <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 108     </simplelist></para>
 109   </refsect1>
 110
 111 </refentry>