From 30281ba43b3d843cc02113f84602c09fe0702674 Mon Sep 17 00:00:00 2001 From: "Z. Liu" Date: Wed, 28 Aug 2024 15:09:50 +0800 Subject: add/update doc & man page of chpst and runsv 1. fix error in runsv for log/finish: Log ./finish script is not actually invoked. It is not clear, whether this limitation is worth lifting. 2. add options -t and -V to chpst man page; ignore -r since it's obsolete. 3. clarify in runsv.8 manpage how signal override works with control/dx copied from debian's patch: 0009-fix-error-in-manpage.patch 0027-Clarify-runsv-8-control-dx.patch 0027-Add-missing-options-to-chpst-manpage.patch links of debian's patches is: https://salsa.debian.org/debian/runit/-/tree/master/debian/patches --- doc/chpst.8.html | 14 ++++++++++---- doc/runsv.8.html | 20 +++++++++++++++++--- man/chpst.8 | 18 +++++++++++++++--- man/runsv.8 | 37 ++++++++++++++++++++++++++++++++----- src/chpst.c | 2 +- src/chpst.dist | 4 ++-- 6 files changed, 77 insertions(+), 18 deletions(-) diff --git a/doc/chpst.8.html b/doc/chpst.8.html index 97d90f2..c481ce2 100644 --- a/doc/chpst.8.html +++ b/doc/chpst.8.html @@ -11,9 +11,9 @@

Name

chpst - runs a program with a changed process state

Synopsis

-chpst [-vP012] +chpst [-vVP012] [-u user] [-U user] [-b argv0] [-e dir] [-/ root] [-n inc] [-l|-L lock] [-m bytes] [-d bytes] -[-o n] [-p n] [-f bytes] [-c bytes] prog +[-o n] [-p n] [-f bytes] [-c bytes] [-t seconds] prog

Description

prog consists of one or more arguments.

@@ -30,7 +30,7 @@ and a group, set the gid to group’s gid, as found in /etc of user’s gid. If group consists of a colon-separated list of group names, chpst sets the group ids of all listed groups. If user is prefixed with a colon, the user and all group arguments are interpreted as uid and gids -respectivly, and not looked up in the password or group file. All initial +respectively, and not looked up in the password or group file. All initial supplementary groups are removed.

-U [:]user[:group]
@@ -38,7 +38,7 @@ supplementary groups are removed. variables $UID and $GID to the user’s uid and gid, as found in /etc/passwd. If user is followed by a colon and a group, set $GID to the group’s gid, as found in /etc/group, instead of user’s gid. If user is prefixed with a -colon, the user and group arguments are interpreted as uid and gid respectivly, +colon, the user and group arguments are interpreted as uid and gid respectively, and not looked up in the password or group file.
-b argv0
@@ -98,10 +98,16 @@ the output file size to bytes bytes.
limit core size. Limit the core file size to bytes bytes.
+
-t seconds
+
limit CPU time. Limit CPU time to seconds seconds, delivering a SIGXCPU thereafter.
+
-v
verbose. Print verbose messages to standard error. This includes warnings about limits unsupported by the system.
+
-V
+
version string. Print a version string to standard error.
+
-P
pgrphack. Run prog in a new process group.
diff --git a/doc/runsv.8.html b/doc/runsv.8.html index d27deeb..04f299e 100644 --- a/doc/runsv.8.html +++ b/doc/runsv.8.html @@ -115,15 +115,29 @@ to send a TERM signal to the socklog-unix service, either do # sv term printf(1) usually blocks if no runsv process is running in the service directory.

Customize Control

-For each control character c sent to the control +For each control character c except "d" and "x" sent to the control pipe, runsv first checks if service/control/c exists and is executable. If so, it starts service/control/c and waits for it to terminate, before interpreting the command. If the program exits with return code 0, runsv refrains from sending the service the corresponding signal. The command o is always considered as command u. On command d first service/control/t is checked, and then service/control/d. On command x first service/control/t -is checked, and then service/control/x. The control of the optional log -service cannot be customized. +is checked, and then service/control/x. Specifically:
+

+

1.
+
runsv checks whether service/control/t exists and is executable and runs it if yes.
+ +
2.
+
If service/control/t exits nonzero, or is not executable or doesn't exist, runsv sends + the service a TERM signal.
+ +
3.
+
runsv sends the service a CONT signal, disregarding service/control/c even if it exists and is executable.
+ +
4.
+
runsv checks whether service/control/d (or control/x) exists and is executable and runs it if yes. Its exit status is ignored.
+

+The control of the optional log service cannot be customized.

Signals

If runsv receives a TERM signal, it acts as if the character x was written to the control pipe. diff --git a/man/chpst.8 b/man/chpst.8 index 43c0b8d..26c1a1d 100644 --- a/man/chpst.8 +++ b/man/chpst.8 @@ -3,7 +3,7 @@ chpst \- runs a program with a changed process state .SH SYNOPSIS .B chpst -[\-vP012] +[\-vVP012] [\-u .IR user ] [\-U @@ -30,6 +30,8 @@ chpst \- runs a program with a changed process state .IR bytes ] [-c .IR bytes ] +[-t +.IR seconds ] .I prog .SH DESCRIPTION .I prog @@ -68,7 +70,7 @@ is prefixed with a colon, the .I user and all .I group -arguments are interpreted as uid and gids respectivly, and not looked up in +arguments are interpreted as uid and gids respectively, and not looked up in the password or group file. All initial supplementary groups are removed. .TP @@ -95,7 +97,7 @@ is prefixed with a colon, the .I user and .I group -arguments are interpreted as uid and gid respectivly, and not looked up in +arguments are interpreted as uid and gid respectively, and not looked up in the password or group file. .TP .B \-b \fIargv0 @@ -208,11 +210,21 @@ Limit the core file size to .I bytes bytes. .TP +.B \-t \fIseconds +limit CPU time. +Limit CPU time to +.I seconds +seconds, delivering a SIGXCPU thereafter. +.TP .B \-v verbose. Print verbose messages to standard error. This includes warnings about limits unsupported by the system. .TP +.B \-V +version string. +Print a version string to standard error. +.TP .B \-P pgrphack. Run diff --git a/man/runsv.8 b/man/runsv.8 index 7c5abfc..43ab396 100644 --- a/man/runsv.8 +++ b/man/runsv.8 @@ -54,10 +54,8 @@ and .IR service /finish's standard output to the pipe, switches to the directory .IR service /log -and starts ./run (and ./finish) exactly as described above for the -.I service -directory. -The standard input of the log service is redirected to read from the pipe. +and starts ./run script. The standard input of the log service +is redirected to read from the pipe. .P .B runsv maintains status information in a binary format (compatible to the @@ -168,7 +166,7 @@ process is running in the service directory. .SH CUSTOMIZE CONTROL For each control character .I c -sent to the control pipe, +except "d" and "x" sent to the control pipe, .B runsv first checks if .I service\fR/control/\fIc @@ -195,6 +193,35 @@ first .I service\fR/control/t is checked, and then .I service\fR/control/x. +Specifically: +.P +If the service is running or paused, control characters "d" and "x" are handled as follows: +.TP +.B 1. +.B runsv +checks whether +.I service\fR/control/t +exists and is executable and runs it if yes. +.TP +.B 2. +If +.I service\fR/control/t +exits nonzero, or is not executable or doesn't exist, +.B runsv +sends the service a TERM signal. +.TP +.B 3. +.B runsv +sends the service a CONT signal, disregarding +.I service\fR/control/c +even if it exists and is executable. +.TP +.B 4. +.B runsv +checks whether +.I service\fR/control/d (or control/x) +exists and is executable and runs it if yes. Its exit status is ignored. +.P The control of the optional log service cannot be customized. .SH SIGNALS If diff --git a/src/chpst.c b/src/chpst.c index cb4e7a9..86032bc 100644 --- a/src/chpst.c +++ b/src/chpst.c @@ -20,7 +20,7 @@ #include "openreadclose.h" #include "direntry.h" -#define USAGE_MAIN " [-vP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] prog" +#define USAGE_MAIN " [-vVP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] [-t n] prog" #define FATAL "chpst: fatal: " #define WARNING "chpst: warning: " diff --git a/src/chpst.dist b/src/chpst.dist index 6779bfd..606264c 100644 --- a/src/chpst.dist +++ b/src/chpst.dist @@ -1,8 +1,8 @@ -usage: chpst [-vP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] prog +usage: chpst [-vVP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] [-t n] prog 100 $Id: f279d44141c981dd7535a12260efcf1ef7beed26 $ -usage: chpst [-vP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] prog +usage: chpst [-vVP012] [-u user[:group]] [-U user[:group]] [-b argv0] [-e dir] [-/ root] [-n nice] [-l|-L lock] [-m n] [-d n] [-o n] [-p n] [-f n] [-c n] [-t n] prog 100 test=1 -- cgit 1.4.1