journalctl: add new --sync switch for syncing the journal to disk

With this new "--sync" switch we add a synchronous way to sync
everything queued to disk, and return only after that's complete. This
command gives the guarantee that anything queued before has hit the disk
before the command returns.

While we are at it, also improve the man pages and help text for
journalctl a bit.

2 files changed, 40 insertions, 7 deletions

diff --git a/man/journalctl.xml b/man/journalctl.xml
index a3192539dc..2160f3cba2 100644
--- a/man/journalctl.xml
+++ b/man/journalctl.xml
@@ -773,13 +773,31 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>--sync</option></term>
+
+        <listitem><para>Ask the journal daemon to write all yet
+        unwritten journal data to the backing file system and
+        synchronize all journals. This call does not return until the
+        operation is complete. This command guarantees that any log
+        messages written before its invocation are safely stored on
+        disk at the time it returns.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>--flush</option></term>
 
         <listitem><para>Asks the journal daemon to flush any log data
         stored in <filename>/run/log/journal</filename> into
-        <filename>/var/log/journal</filename>, if persistent storage is
-        enabled. This call does not return until the operation is
-        complete.</para></listitem>
+        <filename>/var/log/journal</filename>, if persistent storage
+        is enabled. This call does not return until the operation is
+        complete. Note that this call is idempotent: the data is only
+        flushed from <filename>/run/log/journal</filename> into
+        <filename>/var/log/journal</filename> once during system
+        runtime, and this command exits cleanly without executing any
+        operation if this has already has happened. This command
+        effectively guarantees that all data is flushed to
+        <filename>/var/log/journal</filename> at the time it
+        returns.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml
index 21fd684b8b..f1054b03bb 100644
--- a/man/systemd-journald.service.xml
+++ b/man/systemd-journald.service.xml
@@ -131,15 +131,30 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting>
         this is enabled). This must be used after
         <filename>/var/</filename> is mounted, as otherwise log data
         from <filename>/run</filename> is never flushed to
-        <filename>/var</filename> regardless of the
-        configuration.</para></listitem>
+        <filename>/var</filename> regardless of the configuration. The
+        <command>journalctl --flush</command> command uses this signal
+        to request flushing of the journal files, and then waits for
+        the operation to complete. See
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for details.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term>SIGUSR2</term>
 
         <listitem><para>Request immediate rotation of the journal
-        files.</para></listitem>
+        files. The <command>journalctl --rotate</command> command uses
+        this signal to request journal file
+        rotation.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>SIGRTMIN+1</term>
+
+        <listitem><para>Request that all unwritten log data is written
+        to disk. The <command>journalctl --sync</command> command uses
+        this signal to trigger journal synchronization, and then waits
+        for the operation to complete.</para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
@@ -261,7 +276,7 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting>
       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
-      <command>pydoc systemd.journal</command>.
+      <command>pydoc systemd.journal</command>
     </para>
   </refsect1>