Adding upstream version 4.23.0.upstream/4.23.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 37 insertions, 34 deletions

diff --git a/upstream/fedora-rawhide/man5/systemd.service.5 b/upstream/fedora-rawhide/man5/systemd.service.5
index 098eba50..a53894ed 100644
--- a/upstream/fedora-rawhide/man5/systemd.service.5
+++ b/upstream/fedora-rawhide/man5/systemd.service.5
@@ -1,5 +1,5 @@
 '\" t
-.TH "SYSTEMD\&.SERVICE" "5" "" "systemd 255" "systemd.service"
+.TH "SYSTEMD\&.SERVICE" "5" "" "systemd 256~rc3" "systemd.service"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -1079,7 +1079,13 @@ If set to
 \fBon\-abnormal\fR, the service will be restarted when the process is terminated by a signal (including on core dump, excluding the aforementioned four signals), when an operation times out, or when the watchdog timeout is triggered\&. If set to
 \fBon\-abort\fR, the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status\&. If set to
 \fBon\-watchdog\fR, the service will be restarted only if the watchdog timeout for the service expires\&. If set to
-\fBalways\fR, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout\&.
+\fBalways\fR, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout\&. Note that
+\fIType=oneshot\fR
+services will never be restarted on a clean exit status, i\&.e\&.
+\fBalways\fR
+and
+\fBon\-success\fR
+are rejected for them\&.
 .sp
 .it 1 an-trap
 .nr an-no-space-flag 1
@@ -1316,21 +1322,9 @@ Added in version 189\&.
 \fIRestartPreventExitStatus=\fR
 .RS 4
 Takes a list of exit status definitions that, when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with
-\fIRestart=\fR\&. Exit status definitions can either be numeric exit codes or termination signal names, and are separated by spaces\&. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic\&. For example:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-RestartPreventExitStatus=1 6 SIGABRT
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-ensures that exit codes 1 and 6 and the termination signal
-\fBSIGABRT\fR
-will not result in automatic service restarting\&. This option may appear more than once, in which case the list of restart\-preventing statuses is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect\&.
+\fIRestart=\fR\&. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces\&. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic\&.
+.PP \fBExample\ \&2.\ \&A service with the \fIRestartPreventExitStatus=\fR setting\fR .sp .if n \{\ .RS 4 .\} .nf RestartPreventExitStatus=TEMPFAIL 250 SIGKILL .fi .if n \{\ .RE .\} .sp Exit status 75 (\fBTEMPFAIL\fR), 250, and the termination signal \fBSIGKILL\fR will not result in automatic service restarting\&.
+This option may appear more than once, in which case the list of restart\-preventing statuses is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect\&.
 .sp
 Note that this setting has no effect on processes configured via
 \fIExecStartPre=\fR,
@@ -1353,6 +1347,10 @@ Takes a list of exit status definitions that, when returned by the main service
 \fIRestart=\fR\&. The argument format is similar to
 \fIRestartPreventExitStatus=\fR\&.
 .sp
+Note that for
+\fIType=oneshot\fR
+services, a success exit status will prevent them from auto\-restarting, no matter whether the corresponding exit statuses are listed in this option or not\&.
+.sp
 Added in version 215\&.
 .RE
 .PP
@@ -1731,7 +1729,7 @@ T}
 T{
 ":"
 T}:T{
-If the executable path is prefixed with ":", environment variable substitution (as described by the "Command Lines" section below) is not applied\&.
+If the executable path is prefixed with ":", environment variable substitution (as described below this table) is not applied\&.
 T}
 T{
 "+"
@@ -1929,7 +1927,7 @@ with five arguments:
 "ls"\&.
 .SH "EXAMPLES"
 .PP
-\fBExample\ \&2.\ \&Simple service\fR
+\fBExample\ \&3.\ \&Simple service\fR
 .PP
 The following unit file creates a service that will execute
 /usr/sbin/foo\-daemon\&. Since no
@@ -1973,7 +1971,7 @@ if the service can background itself or
 \fIType=\fR\fBdbus\fR
 if the unit acquires a DBus name once initialization is complete\&. See below\&.
 .PP
-\fBExample\ \&3.\ \&Oneshot service\fR
+\fBExample\ \&4.\ \&Oneshot service\fR
 .PP
 Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot\&. For this,
 \fIType=\fR\fBoneshot\fR
@@ -2013,7 +2011,7 @@ are
 \fInot\fR
 allowed\&.
 .PP
-\fBExample\ \&4.\ \&Stoppable oneshot service\fR
+\fBExample\ \&5.\ \&Stoppable oneshot service\fR
 .PP
 Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains active while they are considered "started"\&. Network configuration can sometimes fall into this category\&. Another use case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time\&.
 .PP
@@ -2049,7 +2047,7 @@ Since the unit is considered to be running after the start action has exited, in
 \fBsystemctl start\fR
 on that unit again will cause no action to be taken\&.
 .PP
-\fBExample\ \&5.\ \&Traditional forking services\fR
+\fBExample\ \&6.\ \&Traditional forking services\fR
 .PP
 Many traditional daemons/services background (i\&.e\&. fork, daemonize) themselves when starting\&. Set
 \fIType=\fR\fBforking\fR
@@ -2092,7 +2090,7 @@ Please see
 \fBsystemd.kill\fR(5)
 for details on how you can influence the way systemd terminates the service\&.
 .PP
-\fBExample\ \&6.\ \&DBus services\fR
+\fBExample\ \&7.\ \&DBus services\fR
 .PP
 For services that acquire a name on the DBus system bus, use
 \fIType=\fR\fBdbus\fR
@@ -2143,7 +2141,7 @@ Please see
 \fBsystemd.kill\fR(5)
 for details on how you can influence the way systemd terminates the service\&.
 .PP
-\fBExample\ \&7.\ \&Services that notify systemd about their initialization\fR
+\fBExample\ \&8.\ \&Services that notify systemd about their initialization\fR
 .PP
 \fIType=\fR\fBsimple\fR
 services are really easy to write, but have the major disadvantage of systemd not being able to tell when initialization of the given service is complete\&. For this reason, systemd supports a simple notification protocol that allows daemons to make systemd aware that they are done initializing\&. Use
@@ -2160,7 +2158,7 @@ for this\&. A typical service file for such a daemon would look like this:
 Description=Simple notifying service
 
 [Service]
-Type=notify
+Type=notify\-reload
 ExecStart=/usr/sbin/simple\-notifying\-service
 
 [Install]
@@ -2176,17 +2174,17 @@ Note that the daemon has to support systemd\*(Aqs notification protocol, else sy
 Please see
 \fBsystemd.kill\fR(5)
 for details on how you can influence the way systemd terminates the service\&.
+.PP
+To avoid code duplication, it is preferable to use
+\fBsd_notify\fR(3)
+when possible, especially when other APIs provided by
+\fBlibsystemd\fR(3)
+are also used, but note that the notification protocol is very simple and guaranteed to be stable as per the
+\m[blue]\fBInterface Portability and Stability Promise\fR\m[]\&\s-2\u[4]\d\s+2, so it can be reimplemented by services with no external dependencies\&. For a self\-contained example, see
+\fBsd_notify\fR(3)\&.
 .SH "SEE ALSO"
 .PP
-\fBsystemd\fR(1),
-\fBsystemctl\fR(1),
-\fBsystemd-system.conf\fR(5),
-\fBsystemd.unit\fR(5),
-\fBsystemd.exec\fR(5),
-\fBsystemd.resource-control\fR(5),
-\fBsystemd.kill\fR(5),
-\fBsystemd.directives\fR(7),
-\fBsystemd-run\fR(1)
+\fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd-system.conf\fR(5), \fBsystemd.unit\fR(5), \fBsystemd.exec\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.kill\fR(5), \fBsystemd.directives\fR(7), \fBsystemd-run\fR(1)
 .SH "NOTES"
 .IP " 1." 4
 File Descriptor Store
@@ -2203,3 +2201,8 @@ Control Group v2
 .RS 4
 \%https://docs.kernel.org/admin-guide/cgroup-v2.html
 .RE
+.IP " 4." 4
+Interface Portability and Stability Promise
+.RS 4
+\%https://systemd.io/PORTABILITY_AND_STABILITY/
+.RE