From: Jason McIntyre Subject: Re: [PATCH] man 1 pkill: Add where signals can be found To: tech@openbsd.org Date: Sun, 20 Apr 2025 18:10:58 +0100 On Sun, Apr 20, 2025 at 05:37:35PM +0200, Ingo Schwarze wrote: > Hi Jason, > > Jason McIntyre wrote on Sun, Apr 20, 2025 at 06:43:55AM +0100: > > > regarding the mark up of TERM: kill(1) does not document signals this > > way, and i don;t think pkill(1) should start either. it's inconsistent > > and, if anything, confusing to document the signal name as "-TERM". > > Granted, the signal name is TERM, not -TERM. I meant that -TERM is > the default option, not the default name. But since there was no > consensus for this part of the change, i dropped it when i committing. > > > another choice for documenting sigaction(2) would be - again - to follow > > kill(1) and list some commonly used sig names, and refer to sigaction(2) > > for the full list. that might make less work for the reader and be more > > consistent. then again this program isn;t kill(1) and maybe just the > > hint is enough. > > I don't like duplicating information all that much. I think for kill(1) > it is acceptable because the -s argument is really central there, > but as you say, for pgrep/pkill, -signal is more tangential. > > > i.e. i'm ok with the diff, minus the "-TERM" stuff. > > Thanks for checking, committed. > > Your remarks made me look at kill(1), and i found multiple issues there. > > * We really only want multiple synopses when there is a very strong > reason, typically only when two synopses have completely different > syntax and purpose. For the last two synopses in kill(1), the > syntax is very similar and the purpose is identical to the first > one. Joining all three in the first synopsis makes it clear > that these are merely minor syntax variants, shortens the text, > and even fits comfortable on a single line. > > * Using .Dv in section 1 manuals is usually wrong because > C preprocessor macros normally cannot be used from the shell > command line. Here, it is very wrong because the names in > the CLI do not even match the names in the C API. > The kill(1) manual needs to talk about TERM, not SIGTERM, > and the proper macro is .Cm, not .Dv. > > * Joing the three entries in the option list significantly shortens > the text. Even more importantly, it makes it clearer that the > three syntax variants do not control three different features with > three independent defaults but all control the same feature with > just one single default. > > * Using .Bl -column instead of .Bl -tag avoids ugly spacing > that is too wide in one place and too narrow in another, > makes more sense semantically because this is really a > three-column table, and even the mdoc(7) source code becomes > more compact and more readable. > > * The description of -0 lacks the information that it does not > send a signal (the truth of which is stated in kill(2) and can > also be checked with ktrace(1)), abuses the .Li macro for > something that is not example code but contains a placeholder, > and repeats part of the EXIT STATUS section in a place where > that does not belong. > > OK? > Ingo > hi. no issues with the direction but i seem some problems: - our current usage() does not match either what SYNOPSIS currently is or what you propose. so whichever way you go, we want that fixed - with your proposal, it looks very much like all three versions require "-s", even though only the first does. that ambiguity is present in the current usage() too. it's possible this is the reason why it was split in the first place. we could get away with it in usage()/SYNOPSIS, but i think we'd have to be really clear in the description of -s how it works. either by indicating -s is optional (might make the summary more complex) or maybe by listing it like: -s signal -signame -signum A symbolic name or number ... i'm fine with the other parts. we need to be careful with changing the SYNOPSIS though. jmc > > > Index: kill.1 > =================================================================== > RCS file: /cvs/src/bin/kill/kill.1,v > diff -u -r1.40 kill.1 > --- kill.1 9 Feb 2020 00:21:01 -0000 1.40 > +++ kill.1 20 Apr 2025 15:32:13 -0000 > @@ -41,17 +41,11 @@ > .Nd terminate or signal a process > .Sh SYNOPSIS > .Nm kill > -.Op Fl s Ar signal_name > +.Op Fl s Ar signal_name | Fl Ar signal_name | Fl Ar signal_number > .Ar pid ... > .Nm kill > .Fl l > .Op Ar exit_status > -.Nm kill > -.Fl Ar signal_name > -.Ar pid ... > -.Nm kill > -.Fl Ar signal_number > -.Ar pid ... > .Sh DESCRIPTION > The > .Nm > @@ -59,9 +53,9 @@ > by the > .Ar pid > operand(s). > -If no signal is specified, > -.Dv SIGTERM > -is used. > +If no signal is specified, the > +.Cm TERM > +signal is used. > .Pp > Only the superuser may send signals to other users' processes. > .Pp > @@ -80,18 +74,10 @@ > or a signal number. > .Pp > If no operand is given, display the names of all the signals. > -.It Fl s Ar signal_name > -A symbolic signal name specifying the signal to be sent instead of the > -default > -.Dv SIGTERM . > -.It Fl Ar signal_name > -A symbolic signal name specifying the signal to be sent instead of the > -default > -.Dv SIGTERM . > -.It Fl Ar signal_number > -A non-negative decimal integer specifying the signal to be sent instead > -of the default > -.Dv SIGTERM . > +.It Fl s Ar signal_name | Fl Ar signal_name | Fl Ar signal_number > +A symbolic signal name or a non-negative decimal integer > +specifying the signal to be sent instead of the default > +.Cm TERM . > .El > .Pp > The following PIDs have special meanings: > @@ -108,21 +94,14 @@ > .Pp > Some of the more commonly used signals: > .Pp > -.Bl -tag -width Ds -compact -offset indent > -.It 1 > -HUP (hang up) > -.It 2 > -INT (interrupt) > -.It 3 > -QUIT (quit) > -.It 6 > -ABRT (abort) > -.It 9 > -KILL (non-catchable, non-ignorable kill) > -.It 14 > -ALRM (alarm clock) > -.It 15 > -TERM (software termination signal) > +.Bl -column MM MMMM -compact -offset indent > +.It 1 Ta Cm HUP Ta Pq hang up > +.It 2 Ta Cm INT Ta Pq interrupt > +.It 3 Ta Cm QUIT Ta Pq quit > +.It 6 Ta Cm ABRT Ta Pq abort > +.It 9 Ta Cm KILL Ta Pq non-catchable, non-ignorable kill > +.It 14 Ta Cm ALRM Ta Pq alarm clock > +.It 15 Ta Cm TERM Ta Pq software termination signal > .El > .Pp > For a more complete list, consult the > @@ -130,9 +109,11 @@ > manual page. > .Pp > A signal number of 0 > -.Pq Li kill \-0 pid > -checks the validity of a certain PID, to see if it exists. > -An exit code of 0 means that the specified process exists. > +.Pq Nm kill Fl 0 Ar pid > +does not send a signal, but only checks the validity of a certain PID. > +It succeeds if > +.Ar pid > +exists or raises an error otherwise. > .Sh EXIT STATUS > .Ex -std kill > .Sh EXAMPLES