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></listitem>
64        </varlistentry>
65
66        <varlistentry>
67          <term><constant>-ENOPKG</constant></term>
68
69          <listitem><para>The bus cannot be resolved.</para></listitem>
70        </varlistentry>
71
72        <varlistentry>
73          <term><constant>-ECHILD</constant></term>
74
75          <listitem><para>The bus was created in a different process.</para></listitem>
76        </varlistentry>
77
78        <varlistentry>
79          <term><constant>-ENOMEM</constant></term>
80
81          <listitem><para>Memory allocation failed.</para></listitem>
82        </varlistentry>
83      </variablelist>
84    </refsect2>
85  </refsect1>
86
87  <xi:include href="libsystemd-pkgconfig.xml" />
88
89  <refsect1>
90    <title>See Also</title>
91
92    <para>
93      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
94      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
95    </para>
96  </refsect1>
97
98</refentry>
99