From efeb864cb547a2cbf96dc0053a8bdb4d9190b364 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 12 Jun 2024 05:50:45 +0200
Subject: Merging upstream version 256.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 man/org.freedesktop.hostname1.xml | 62 +++++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 22 deletions(-)

(limited to 'man/org.freedesktop.hostname1.xml')

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index 0c5b0f2..d16ae9a 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY % entities SYSTEM "custom-entities.ent" >
 %entities;
 ]>
@@ -99,6 +99,8 @@ node /org/freedesktop/hostname1 {
       readonly ay MachineID = [...];
       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
       readonly ay BootID = [...];
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
+      readonly u VSockCID = ...;
   };
   interface org.freedesktop.DBus.Peer { ... };
   interface org.freedesktop.DBus.Introspectable { ... };
@@ -106,24 +108,6 @@ node /org/freedesktop/hostname1 {
 };
     </programlisting>
 
-    <!--method GetHardwareSerial is not documented!-->
-
-    <!--property OperatingSystemSupportEnd is not documented!-->
-
-    <!--property HardwareVendor is not documented!-->
-
-    <!--property HardwareModel is not documented!-->
-
-    <!--property FirmwareVersion is not documented!-->
-
-    <!--property FirmwareVendor is not documented!-->
-
-    <!--property FirmwareDate is not documented!-->
-
-    <!--property MachineID is not documented!-->
-
-    <!--property BootID is not documented!-->
-
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
@@ -196,6 +180,8 @@ node /org/freedesktop/hostname1 {
 
     <variablelist class="dbus-property" generated="True" extra-ref="BootID"/>
 
+    <variablelist class="dbus-property" generated="True" extra-ref="VSockCID"/>
+
     <!--End of Autogenerated section-->
 
     <para>Whenever the hostname or other metadata is changed via the daemon,
@@ -287,6 +273,34 @@ node /org/freedesktop/hostname1 {
     purpose of those properties is to allow remote clients to access this information over D-Bus. Local
     clients can access the information directly.</para>
 
+    <para><varname>MachineID</varname> expose the 128bit machine ID, see
+    <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details.</para>
+
+    <para><varname>BootID</varname> expose the 128bit boot ID, as per
+    <filename>/proc/sys/kernel/random/boot_id</filename>.</para>
+
+    <para><varname>VSockCID</varname> exposes the system's local <constant>AF_VSOCK</constant> CID (Context
+    Identifier, i.e. address) for the system, if one is available in the virtual machine environment. Set to
+    <constant>UINT32_MAX</constant> otherwise. See <citerefentry project="man-pages"><refentrytitle>vsock</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details.</para>
+
+    <para><varname>OperatingSystemSupportEnd</varname> exposes when the OS' vendor support ends, if this
+    information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If this information
+    is not known carries the value 2^64-1, i.e. <constant>UINT64_MAX</constant>.</para>
+
+    <para><varname>HardwareVendor</varname> and <varname>HardwareModel</varname> expose information about the
+    vendor of the hardware of the system. If no such information can be determined these properties are set
+    to empty strings.</para>
+
+    <para><varname>FirmwareVersion</varname> and <varname>FirmwareVendor</varname> expose information about
+    the system's firmware, i.e. a version string and a vendor name. If no such information can be determined
+    these properties are set to empty strings.</para>
+
+    <para><varname>FirmwareDate</varname> exposes the firmware build date, if that information is known. It's
+    an unsigned 64bit value, in µs since the UNIX epoch, UTC. If not known
+    <constant>UNIT64_MAX</constant>.</para>
+
     <refsect2>
       <title>Methods</title>
 
@@ -321,6 +335,10 @@ node /org/freedesktop/hostname1 {
       requires root privileges, and this method allows access to unprivileged clients through the polkit
       framework.</para>
 
+      <para><function>GetHardwareSerial()</function> returns the "hardware serial" as exposed by the kernel
+      based on DMI information. Reading the file directly requires root privileges, and this method allows
+      access to unprivileged clients through the polkit framework.</para>
+
       <para><function>Describe()</function> returns a JSON representation of all properties in one.</para>
     </refsect2>
 
@@ -425,7 +443,7 @@ node /org/freedesktop/hostname1 {
   </refsect1>
 
   <refsect1>
-    <title>See also</title>
+    <title>See Also</title>
 
     <para>David Zeuthen's original Fedora
     <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
@@ -440,8 +458,8 @@ node /org/freedesktop/hostname1 {
       <para><varname>OperatingSystemSupportEnd</varname>,
       <varname>FirmwareVendor</varname>, and
       <varname>FirmwareDate</varname> were added in version 253.</para>
-      <para><varname>MachineID</varname>, and
-      <varname>BootID</varname> were added in version 256.</para>
+      <para><varname>MachineID</varname>, <varname>BootID</varname> and
+      <varname>VSockCID</varname> were added in version 256.</para>
     </refsect2>
   </refsect1>
 </refentry>
-- 
cgit v1.2.3