Merge pull request #18827 from keszybz/a-bunch-of-man-page-updates

A bunch of man page updates

TODO

@@ -1272,6 +1272,7 @@ Features:
   - creating new directories/subvolumes/fifos/device nodes
     should not follow symlinks. None of the other adjustment or creation
     calls follow symlinks.
+  - add --test mode
 
 * make sure systemd-ask-password-wall does not shutdown systemd-ask-password-console too early
 

man/less-variables.xml → man/common-variables.xml

@@ -7,6 +7,80 @@
   <title>Environment</title>
 
   <variablelist class='environment-variables'>
+    <varlistentry id='log-level'>
+      <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
+
+      <listitem><para id='log-level-body'>The maximum log level of emitted messages (messages with a higher
+      log level, i.e. less important ones, will be suppressed). Either one of (in order of decreasing
+      importance) <constant>emerg</constant>, <constant>alert</constant>, <constant>crit</constant>,
+      <constant>err</constant>, <constant>warning</constant>, <constant>notice</constant>,
+      <constant>info</constant>, <constant>debug</constant>, or an integer in the range 0…7. See
+      <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      for more information.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-color'>
+      <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
+
+      <listitem><para id='log-color-body'>A boolean. If true, messages written to the tty will be colored
+      according to priority.</para>
+
+      <para>This setting is only useful when messages are written directly to the terminal, because
+      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+      other tools that display logs will color messages based on the log level on their own.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-time'>
+      <term><varname>$SYSTEMD_LOG_TIME</varname></term>
+
+      <listitem><para id='log-time-body'>A boolean. If true, log messages will be prefixed with a
+      timestamp.</para>
+
+      <para>This setting is only useful when messages are written directly to the terminal or a file, because
+      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+      other tools that display logs will attach timestamps based on the entry metadata on their own.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-location'>
+      <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
+
+      <listitem><para id='log-location-body'>A boolean. If true, messages will be prefixed with a filename
+      and line number in the source code where the message originates.</para>
+
+      <para>Note that the log location is often attached as metadata to journal entries anyway. Including it
+      directly in the message text can nevertheless be convenient when debugging programs.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-tid'>
+      <term><varname>$SYSTEMD_LOG_TID</varname></term>
+
+      <listitem><para id='log-tid-body'>A boolean. If true, messages will be prefixed with the current
+      numerical thread ID (TID).</para>
+
+      <para>Note that the this information is attached as metadata to journal entries anyway. Including it
+      directly in the message text can nevertheless be convenient when debugging programs.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-target'>
+      <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
+
+      <listitem><para id='log-target-body'>The destination for log messages. One of
+      <constant>console</constant> (log to the attached tty), <constant>console-prefixed</constant> (log to
+      the attached tty but with prefixes encoding the log level and "facility", see <citerefentry
+      project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <constant>kmsg</constant> (log to the kernel circular log buffer), <constant>journal</constant> (log to
+      the journal), <constant>journal-or-kmsg</constant> (log to the journal if available, and to kmsg
+      otherwise), <constant>auto</constant> (dermine the appropriate log target automatically, the default),
+      <constant>null</constant> (disable log output).</para>
+      <!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
+      </listitem>
+    </varlistentry>
+
     <varlistentry id='pager'>
       <term><varname>$SYSTEMD_PAGER</varname></term>
 

man/coredumpctl.xml

@@ -324,35 +324,47 @@
     <title>Examples</title>
 
     <example>
-      <title>List all the core dumps of a program named foo</title>
+      <title>List all the core dumps of a program</title>
 
-      <programlisting># coredumpctl list foo</programlisting>
+      <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
+TIME     PID  UID  GID SIG     COREFILE EXE                         SIZE
+Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox   n/a
+Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox   n/a
+Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
+</programlisting>
+
+       <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
+       only the last entry still has an available core file (in external storage on disk).</para>
+
+       <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
+       relevant entries from the journal. Thus, an unprivileged user will normally only see information about
+       crashing programs of this user.</para>
     </example>
 
     <example>
-      <title>Invoke gdb on the last core dump</title>
+      <title>Invoke <command>gdb</command> on the last core dump</title>
 
-      <programlisting># coredumpctl debug</programlisting>
+      <programlisting>$ coredumpctl debug</programlisting>
     </example>
 
     <example>
-      <title>Use gdb to display full register info from the last core dump</title>
+      <title>Use <command>gdb</command> to display full register info from the last core dump</title>
 
-      <programlisting># coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
+      <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
     </example>
 
     <example>
       <title>Show information about a process that dumped core,
       matching by its PID 6654</title>
 
-      <programlisting># coredumpctl info 6654</programlisting>
+      <programlisting>$ coredumpctl info 6654</programlisting>
     </example>
 
     <example>
       <title>Extract the last core dump of /usr/bin/bar to a file named
       <filename index="false">bar.coredump</filename></title>
 
-      <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
+      <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
     </example>
   </refsect1>
 

man/homectl.xml

@@ -848,7 +848,7 @@
     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>Examples</title>

man/journalctl.xml

@@ -992,7 +992,7 @@
     code is returned.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>Examples</title>

man/localectl.xml

@@ -185,7 +185,7 @@
     otherwise.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>See Also</title>

man/loginctl.xml

@@ -415,7 +415,7 @@ Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
     </example>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>See Also</title>

man/machine-info.xml

@@ -37,12 +37,10 @@
     file without implementing a shell compatible execution
     engine.</para>
 
-    <para><filename>/etc/machine-info</filename> contains metadata
-    about the machine that is set by the user or administrator.</para>
-
-    <para>Depending on the operating system other configuration files
-    might be checked for machine information as well, however only as
-    fallback.</para>
+    <para><filename>/etc/machine-info</filename> contains metadata about the machine that is set by the user
+    or administrator. The settings configured here have the highest precedence. When not set, appropriate
+    values may be determined automatically, based on the information about the hardware or other
+    configuration files. It is thus completely fine for this file to not be present.</para>
 
     <para>You may use
     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
@@ -102,13 +100,11 @@
         as well as the special chassis types
         <literal>vm</literal> and
         <literal>container</literal> for
-        virtualized systems that lack an immediate physical chassis.
-        Note that many systems allow detection of the chassis type
-        automatically (based on firmware information or suchlike).
-        This setting (if set) shall take precedence over automatically
-        detected information and is useful to override misdetected
-        configuration or to manually configure the chassis type where
-        automatic detection is not available.</para></listitem>
+        virtualized systems that lack an immediate physical chassis.</para>
+
+        <para>Note that most systems allow detection of the chassis type automatically (based on firmware
+        information or suchlike). This setting should only be used to override a misdetection or to manually
+        configure the chassis type where automatic detection is not available.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/machinectl.xml

@@ -980,7 +980,7 @@
     otherwise.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>See Also</title>

man/portablectl.xml

@@ -428,7 +428,7 @@
     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>See Also</title>

man/systemctl.xml

@@ -2407,12 +2407,17 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
         </para></listitem>
       </varlistentry>
     </variablelist>
-    <xi:include href="less-variables.xml" xpointer="pager"/>
-    <xi:include href="less-variables.xml" xpointer="less"/>
-    <xi:include href="less-variables.xml" xpointer="lesscharset"/>
-    <xi:include href="less-variables.xml" xpointer="lesssecure"/>
-    <xi:include href="less-variables.xml" xpointer="colors"/>
-    <xi:include href="less-variables.xml" xpointer="urlify"/>
+    <xi:include href="common-variables.xml" xpointer="log-level"/>
+    <xi:include href="common-variables.xml" xpointer="log-color"/>
+    <xi:include href="common-variables.xml" xpointer="log-time"/>
+    <xi:include href="common-variables.xml" xpointer="log-location"/>
+    <xi:include href="common-variables.xml" xpointer="log-target"/>
+    <xi:include href="common-variables.xml" xpointer="pager"/>
+    <xi:include href="common-variables.xml" xpointer="less"/>
+    <xi:include href="common-variables.xml" xpointer="lesscharset"/>
+    <xi:include href="common-variables.xml" xpointer="lesssecure"/>
+    <xi:include href="common-variables.xml" xpointer="colors"/>
+    <xi:include href="common-variables.xml" xpointer="urlify"/>
   </refsect1>
 
   <refsect1>

man/systemd-analyze.xml

@@ -782,7 +782,7 @@ Service b@0.service not loaded, b.socket cannot be started.
     otherwise.</para>
   </refsect1>
 
-  <xi:include href="less-variables.xml" />
+  <xi:include href="common-variables.xml" />
 
   <refsect1>
     <title>See Also</title>