Clarify how to handle restart processing

The Gentoo developer manual covers how to handle restarts in init
scripts, but this was not officially covered in OpenRc's Documentation.
This commit adds an example to the runscript man page that shows how
this works.

1 files changed, 16 insertions, 2 deletions

diff --git a/man/runscript.8 b/man/runscript.8
index d823e33..c4119d9 100644
--- a/man/runscript.8
+++ b/man/runscript.8
@@ -358,8 +358,8 @@ offset. Otherwise it is undefined.
 .It Va RC_UNAME
 The result of `uname -s`.
 .It Va RC_CMD
-Name of the command like start, stop, restart, ...
-RC_CMD is one way to determine whether it's a restart or normal start/stop.
+This contains the name of the command the init script is executing, such
+as start, stop, restart etc.
 .El
 .Sh FILES
 .Pp
@@ -452,8 +452,22 @@ restart_pre() {
 	...
 }
 
+# This function does any pre-start setup. If it fails, the service will
+# not be started.
+# If you need this function to behave differently for a restart command,
+# you should check the value of RC_CMD for "restart".
+# This also applies to start_post, stop_pre and stop_post.
 start_pre()
 {
+	if [ "$RC_CMD" = restart ]; then
+		# This block will only execute for a restart command. Use a
+		# structure like this if you need special processing for a
+		# restart which you do not need for a normal start.
+		# The function can also fail from here, which will mean that a
+		# restart can fail.
+		# This logic can also be used in start_post, stop_pre and
+		# stop_post.
+	fi
     # Ensure that our dirs are correct
     checkpath --dir --owner foo:foo --mode 0664 \\
 	/var/run/foo /var/cache/foo