From 0df8512124b05ed2d3be1537a4023e89ec33f0f7 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 27 Sep 2022 12:18:43 +0200
Subject: [PATCH] man: document the Dump() calls of the PID 1 D-Bus interface,
 and what they are

---
 man/org.freedesktop.systemd1.xml | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index 741a72d2649..6127541f8bf 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -562,10 +562,6 @@ node /org/freedesktop/systemd1 {
 
     <!--method ListUnitsByNames is not documented!-->
 
-    <!--method Dump is not documented!-->
-
-    <!--method DumpByFileDescriptor is not documented!-->
-
     <!--method ListUnitFilesByPatterns is not documented!-->
 
     <!--method PresetUnitFilesWithMode is not documented!-->
@@ -1336,6 +1332,20 @@ node /org/freedesktop/systemd1 {
       all clients which previously asked for <function>Subscribe()</function> either closed their connection
       to the bus or invoked <function>Unsubscribe()</function>.</para>
 
+      <para><function>Dump()</function> returns a text dump of the internal service manager state. This is a
+      privileged, low-level debugging interface only. The returned string is supposed to be readable
+      exclusively by developers, and not programmatically. There's no interface stability on the returned
+      string guaranteed, and new fields may be added any time, and old fields removed. The general structure
+      may be rearranged drastically between releases. This is exposed by
+      <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+      <command>dump</command> command. The <function>DumpByFileDescriptor()</function> method is identical to
+      <function>Dump()</function> but returns the data serialized into a file descriptor (the client should
+      read the text data from it until hitting EOF). Given the size limits on D-Bus messages and the possibly
+      large size of the returned string, <function>DumpByFileDescriptor()</function> is usually the
+      preferable interface, since it ensures the data can be passed reliably from the service manager to the
+      client. (Note though that <function>DumpByFileDescriptor()</function> cannot work when communicating
+      with the service manager remotely, as file descriptors are strictly local to a system.)</para>
+
       <para><function>Reload()</function> may be invoked to reload all unit files.</para>
 
       <para><function>Reexecute()</function> may be invoked to reexecute the main manager process. It will
-- 
2.47.3