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

A bunch of man page updates
man: document \u and \U, say that utf-8 is allowed
2025-10-02 18:24:46 +02:00 · 2021-03-01 22:11:44 +00:00 · 2021-03-01 20:57:36 +01:00 · 2021-03-01 20:57:36 +01:00 · 2021-03-01 20:57:36 +01:00 · 2021-03-01 20:53:57 +01:00
5 changed files with 60 additions and 34 deletions
--- a/docs/ENVIRONMENT.md
+++ b/docs/ENVIRONMENT.md
@ -288,8 +288,16 @@ installed systemd tests:

 `systemd-tmpfiles`:

-* `SYSTEMD_TMPFILES_FORCE_SUBVOL` - if unset, `v`/`q`/`Q` lines will create
+* `SYSTEMD_TMPFILES_FORCE_SUBVOL` — if unset, `v`/`q`/`Q` lines will create
  subvolumes only if the OS itself is installed into a subvolume. If set to `1`
  (or another value interpreted as true), these lines will always create
  subvolumes if the backing filesystem supports them. If set to `0`, these
  lines will always create directories.
+
+`systemd-sysv-generator`:
+
+* `$SYSTEMD_SYSVINIT_PATH` — Controls where `systemd-sysv-generator` looks for
+  SysV init scripts.
+
+* `$SYSTEMD_SYSVRCND_PATH` — Controls where `systemd-sysv-generator` looks for
+  SysV init script runlevel link farms.
--- a/man/systemd-coredump.xml
+++ b/man/systemd-coredump.xml
@ -115,7 +115,7 @@
    handler must be installed on the sender side. For example, in case of
    <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry>, this
    means a <varname>sys.excepthook</varname> must be installed, see
-    <ulink url="https://github.com/keszybz/systemd-coredump-python">systemd-coredump-python</ulink>.
+    <ulink url="https://github.com/systemd/systemd-coredump-python">systemd-coredump-python</ulink>.
    </para>

    <para>The behavior of <command>systemd-coredump</command> itself is configured through the configuration file
@ -178,7 +178,12 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
        <term><varname>COREDUMP_UID=</varname></term>
        <term><varname>COREDUMP_PID=</varname></term>
        <term><varname>COREDUMP_GID=</varname></term>
-        <listitem><para>The process number (PID) and owner (UID and GID) of the crashed process.</para>
+        <listitem><para>The process number (PID), owner user number (UID), and group number (GID) of the
+        crashed process.</para>
+
+        <para>When the crashed process was part of a container (or in a process or user namespace in
+        general), those are the values as seen <emphasis>outside</emphasis>, in the namespace where
+        <filename>systemd-coredump</filename> is running.</para>
        </listitem>
      </varlistentry>

@ -199,6 +204,9 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
        <term><varname>COREDUMP_UNIT=</varname></term>
        <term><varname>COREDUMP_SLICE=</varname></term>
        <listitem><para>The system unit and slice names.</para>
+
+        <para>When the crashed process was in container, those are the units names
+        <emphasis>outside</emphasis>, in the main system manager.</para>
        </listitem>
      </varlistentry>

@ -207,7 +215,11 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
        <listitem><para>Control group information in the format used in
        <filename>/proc/self/cgroup</filename>. On systems with the unified cgroup hierarchy, this is a
        single path prefixed with <literal>0::</literal>, and multiple paths prefixed with controller numbers
-        on legacy systems.</para></listitem>
+        on legacy systems.</para>
+
+        <para>When the crashed process was in a container, this is the full path, as seen outside of the
+        container.</para>
+        </listitem>
      </varlistentry>

      <varlistentry>
@ -215,7 +227,11 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
        <term><varname>COREDUMP_USER_UNIT=</varname></term>
        <listitem><para>The numerical UID of the user owning the login session or systemd user unit of the
        crashed process, and the user manager unit. Both fields are only present for user processes.
-        </para></listitem>
+        </para>
+
+        <para>When the crashed process was in container, those are the values <emphasis>outside</emphasis>,
+        in the main system.</para>
+        </listitem>
      </varlistentry>

      <varlistentry>
@ -232,6 +248,9 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
        <term><varname>COREDUMP_ROOT=</varname></term>

        <listitem><para>The current working directory and root directory of the crashed process.</para>
+
+        <para>When the crashed process is in a container, those paths are relative to the root of the
+        container's mount namespace.</para>
        </listitem>
      </varlistentry>

@ -257,8 +276,17 @@ flags:   ...
      </varlistentry>

      <varlistentry>
-        <term><varname>COREDUMP_COMM=</varname></term>
        <term><varname>COREDUMP_EXE=</varname></term>
+
+        <listitem><para>The destination of the <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
+        symlink.</para>
+
+        <para>When the crashed process is in a container, that path is relative to the root of the
+        container's mount namespace.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>COREDUMP_COMM=</varname></term>
        <term><varname>COREDUMP_PROC_STATUS=</varname></term>
        <term><varname>COREDUMP_PROC_MAPS=</varname></term>
        <term><varname>COREDUMP_PROC_LIMITS=</varname></term>
@ -284,7 +312,10 @@ flags:   ...
      <varlistentry>
        <term><varname>COREDUMP_HOSTNAME=</varname></term>

-        <listitem><para>The system hostname.</para></listitem>
+        <listitem><para>The system hostname.</para>
+
+        <para>When the crashed process was in container, this is the container hostname.</para>
+        </listitem>
      </varlistentry>

      <varlistentry>
--- a/man/systemd-sysv-generator.xml
+++ b/man/systemd-sysv-generator.xml
@ -60,20 +60,6 @@
    <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
  </refsect1>

-  <refsect1>
-    <title>Environment</title>
-
-    <para>Special variables understood by <command>systemd-sysv-generator</command>:</para>
-
-    <variablelist class='environment-variables'>
-      <varlistentry>
-        <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term>
-
-        <listitem><para>Controls where systemd looks for SysV init scripts.</para></listitem>
-      </varlistentry>
-    </variablelist>
-  </refsect1>
-
  <refsect1>
    <title>See Also</title>
    <para>
--- a/man/systemd.syntax.xml
+++ b/man/systemd.syntax.xml
@ -136,14 +136,14 @@ KeyThree=value 3\
    single quotes ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning
    or after whitespace that is not quoted, and the closing quote must be followed by whitespace or the end
    of line), in which case everything until the next matching quote becomes part of the same item. Quotes
-    themselves are removed. C-style escapes are also supported. The table below contains the list of known
-    escape patterns. Only escape patterns which match the syntax in the table are allowed; other patterns may
-    be added in the future and unknown patterns will result in a warning. In particular, any backslashes
-    should be doubled. Finally, a trailing backslash (<literal>\</literal>) may be used to merge lines, as
-    described above.</para>
+    themselves are removed. C-style escapes are supported. The table below contains the list of known escape
+    patterns. Only escape patterns which match the syntax in the table are allowed; other patterns may be
+    added in the future and unknown patterns will result in a warning. In particular, any backslashes should
+    be doubled. Finally, a trailing backslash (<literal>\</literal>) may be used to merge lines, as described
+    above. UTF-8 is accepted, and hence typical unicode characters do not need to be escaped.</para>

    <table>
-      <title>Supported C escapes</title>
+      <title>Supported escapes</title>
      <tgroup cols='2'>
        <colspec colname='escape' />
        <colspec colname='meaning' />
@ -206,6 +206,14 @@ KeyThree=value 3\
            <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
            <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
          </row>
+          <row>
+            <entry><literal>\u<replaceable>nnnn</replaceable></literal></entry>
+            <entry>unicode code point <replaceable>nnnn</replaceable> in hexadecimal encoding</entry>
+          </row>
+          <row>
+            <entry><literal>\U<replaceable>nnnnnnnn</replaceable></literal></entry>
+            <entry>unicode code point <replaceable>nnnnnnnn</replaceable> in hexadecimal encoding</entry>
+          </row>
        </tbody>
      </tgroup>
    </table>
--- a/man/systemd.xml
+++ b/man/systemd.xml
@ -696,13 +696,6 @@
        </para></listitem>
      </varlistentry>

-      <varlistentry>
-        <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term>
-
-        <listitem><para>Controls where systemd looks for SysV init
-        script runlevel link farms.</para></listitem>
-      </varlistentry>
-
      <xi:include href="common-variables.xml" xpointer="pager"/>
      <xi:include href="common-variables.xml" xpointer="less"/>
      <xi:include href="common-variables.xml" xpointer="lesscharset"/>
Author	SHA1	Message	Date
Luca Boccassi	ebf7472569	Merge pull request #18831 from keszybz/a-bunch-of-man-page-updates A bunch of man page updates	2021-03-01 22:11:44 +00:00
Zbigniew Jędrzejewski-Szmek	1447d87a47	man: document \u and \U, say that utf-8 is allowed	2021-03-01 20:57:36 +01:00
Zbigniew Jędrzejewski-Szmek	07dc08c269	man: move two sysv-specific variables to docs https://github.com/systemd/systemd/pull/18827#discussion_r584807684	2021-03-01 20:57:36 +01:00
Zbigniew Jędrzejewski-Szmek	40019c32d7	man: clarify what is inside/outside the container in coredump info	2021-03-01 20:57:36 +01:00
Zbigniew Jędrzejewski-Szmek	a1174b2260	man: update link to systemd-coredump-python This got moved under the systemd umbrella a long time ago. Github redirects from the old path, so the link worked, but it's nicer to use the real location.	2021-03-01 20:53:57 +01:00