Re: Proposal: new libc/libutil functions to map SIGXXXX <-> "XXXX"

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Wed, 3 May 2017 13:17:29 +0200
    From:        Joerg Sonnenberger <joerg%bec.de@localhost>
    Message-ID:  <20170503111729.GB6044%britannica.bec.de@localhost>

  | It might be useful to mention in the man page that the signal names are
  | locale independent.

I enclose a new man page below (and as before
	ftp://munnari.oz.au/kre/signame.tgz
has been updated).

I am not sure I like the wording, but English (or any other natural language)
is not what I am supposed to be competent at...   So, all suggestions
appreciated.

I am also going to defer implementing this for a few more days, as I have
added to the interface spec (one additional function).

As specified by POSIX, all we know is that there are (26 I think it is)
signals defined to exist (and more can be added, which we have done). plus
at least RTSIG_MAX real time signals, with values between SIGRTMIN and SIGRTMAX.

That's it, aside from not being 0, and (I think) all being different, there
is no specification at all of what values they have.   I don't even see
anything that prevents them being negative.

What's more, as I understand it, <signal.h> cannot export NSIG without
some other feature test macro (like _NETBSD_SOURCE) being defined to allow
it - so portable applications cannot use NSIG.   That really isn't a problem,
as just knowing that there are 63 signals (or whatever) doesn't help at all
when you have no idea what values they are.

[Aside: it is possible to implement sigset_t regardless of the values that
are assigned to SIGINT, SIGHUP, etc - it may not be quite as efficient as
when the signals are consecutive small integers, but it is possible.]

This isn't a problem for a program that just wants
	signal(SIGINT, SIG_IGN);
or similar - for that we don't care what the value of SIGINT is.

But for programs with a need to enumerate signals, catch all that are
catchable, or similar, there is no way defined currently to achieve that.

So, I added a function that can be used to enumerate the signals that
exist in the implementation, for those applications that need it.

As long as (in addition to 0) signal numbers cannot be -1 (allowing that
would be a real mess) the API actually works for any values at all,
including negative ones, even though at first glance it seems not to.
(The man page wording, however, is not so great!)

The current implementation however assumes NetBSD, and its SIGXXX values.

The implementations of these things (included in the tgz file above) are
very NetBSD (or at least, *BSD) specific, and rely upon existing libc
functionality, but they can be changed any time, if we come up with a
better way, without breaking programs that use this API.

Once again, comments & suggestions appreciated.

kre

SIGNALNAME(3)		   Library Functions Manual		 SIGNALNAME(3)

NAME
     signalname signalnumber signalnext -- convert between signal numbers and
     names

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <signal.h>

     const char *
     signalname(int sig);

     int
     signalnumber(const char *name);

     int
     signalnext(int sig);

DESCRIPTION
     The signalname() function takes a signal number sig, and returns the name
     of that signal.  The name returned is locale independent, and can be the
     string representation of one of the signal names from <signal.h> such as
     SIGHUP, SIGSTOP, SIGKILL, or some similar name, but does not contain the
     leading ``SIG'' prefix.

     The return value of signalname() is NULL if sig does not represent a
     valid signal number.

     The signalnumber() function converts the signal name name to the number
     corresponding to that signal.  The name is handled in a case-insensitive
     manner.  Any leading ``SIG'' prefix in name is ignored.

     The signalnumber() function returns the signal number, or zero (0) if the
     name given does not represent a valid signal.

     The signalnext() function takes a signal number, and returns the number
     of the next available bigger signal number.  When no higher signal
     numbers remain, it returns zero (0).  The parameter sig can be given as
     zero (0), to obtain the smallest implemented signal number.

     The signalnext() function returns minus one (-1) on error, if the given
     signal sig is neither a valid signal number, nor zero.  It returns zero
     when the input signal number, sig, is the biggest available signal
     number.  Otherwise it returns the signal number of an implemented signal
     that is larger than sig and such that there are no implemented signals
     with values between sig and the value returned.

SEE ALSO
     kill(1), intro(2), psignal(3), strsignal(3)

HISTORY
     The signalname(), signalnumber() and signalnext() functions first
     appeared in NetBSD 8.0.