From: Ingo Schwarze <schwarze@usta.de>
Subject: Re: [PATCH] man 1 pkill: Add where signals can be found
To: Theo Buehler <tb@theobuehler.org>, Theo de Raadt <deraadt@openbsd.org>
Cc: tech@openbsd.org
Date: Tue, 22 Apr 2025 19:07:26 +0200

Hello Theo,

Theo de Raadt wrote on Mon, Apr 21, 2025 at 07:30:31AM -0600:
> Jason McIntyre <jmc@kerhand.co.uk> wrote:
>> On Mon, Apr 21, 2025 at 04:44:20AM +0200, Theo Buehler wrote:

>>> I was wondering why userland tools Xr to sigaction(2) rather than
>>> higher-level signal(3) for this list. The latter seems friendlier to
>>> a non-programmer.

>> i've no idea. the rest of userland seems to prefer signal(3).

> There's a bit of weird history here, I think I can make a guess.
> 
> Ancient unix had racy signal handlers.  This was fixed by the CSRG
> people, and sigaction became atomic.  There was a hope, I guess, that
> sigaction would become the new interface.  I suspect some people
> really took that to heart.

Indeed.  When i had to do signal processing in the past, both in C
and in Perl, i usually needed sigaction(2) and only rarely got away
with signal(3).  And i have fixed many bugs in the past that resulted
from people naively leaving the sa_mask and sa_flags fields (which
signal(3) does not support) at the defaults even though they were
crucial for the task at hand, which they usually are - resulting
in races, lost signals, having code interrupted that shouldn't be,
and all kinds of trouble that is typically hard to reproduce and
hard to diagnose.

So my honest opinion is that people who want to code signal processing
really need to understand sigaction(2) - even when their specific task
ultimately turns out to be one of the rare ones where signal(3) is
sufficient.  Without that understanding, they are likely unable to
figure out whether or not signal(3) is sufficient for their needs.

> In many systems, this resulted in signal(3) being a rather thin document,
> whereas sigaction(2) was much more detailed, exact, and meaty.
> 
> I suspect that's why sigaction(2) was pointed at instead of signal(3).
> 
> Somewhere during that timeframe, we put some effort into adding more
> meat to signal(3).
> 
> I think the manual page should point at signal(3), because the extra
> details in sigaction(2) are irrelevant.

I agree they are irrelevant for users who do not want to write any
signal handling code (in whichever language, be it C or Perl or
whatever), so i just changed sigaction(2) -> signal(3) in the three
section 1 manuals affected by the effect you described.

Yours,
  Ingo