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

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

Currently on NetBSD (and most other BSDs I believe) the only way to
map between signal numbers (SIGHUP etc) and their string names ("HUP"
or "SIGHUP") is via use of the sys_signame[] array provided from libc.

That's crude and ugly, and requires building in the size of that array
(so the signal number can be bounds checked before use as an index, even
if for no other reason) - and relies upon the same NSIG being defined in
the current libc as was used when the application was compiled.

There was a proposal on the austin (POSIX standards maintainers) list to
add new functions to fill the gap (not all systems even have sys_signame.)
That group do not invent new interfaces (or should not, and usually don't)
but it turns out that recent Solaris (and Illuminos) has functions called
str2sig() and sig2str() with somewhat ugly interfaces (sig2str stores into
a buffer passed in with no accompanying length for example.)

I'd like to see something better than that, so I am proposing adding to
NetBSD functions as described in the following man page.  This is written
as if the functions are to go in libc, but that's just because I had to
pick somewhere to make the man page complete, we could also put them in
libutil if that is preferred.

These functions would be used in programs like the shell, kill, ...
which allow users to specify signal names (they currently roll their own.)

I enclose the cat (formated man) page below.   The entire current sources
(which includes the man page source, sources for the two functions, and a
fairly dumb test prog) are available at:
	ftp://munnari.oz.au/kre/signame.tgz
That does not contain the diffs which will be needed to add prototypes
and a new #define to <signal.h>  however (those are trivial...)
For now all this is _NETBSD_SOURCE of course.  (The tgz file is just 2410
bytes long, so don't assume when you fetch something that short that it
somehow got truncated!)

There is no makefile - just "cc *.c" works (on NetBSD -- this code depends
upon sys_signame[] so is not expected to be particularly portable.)
Eventually these would be added to the appropriate lib*/Makefile of course.

Comments (particularly upon the interface API, names, etc, but also upon
the actual implementation, such as it is -- this stuff is trivial, it took
me 10 times as long to write the manual as the code...) are welcome.

kre

ps: this cat page (output from mandoc) has been piped through col -b
so formatting additions (underlining, ...) have been removed for the
purposes of this e-mail.  These is no real need to comment on wording (etc)
of this manual page, that can be fixed later if we keep this.  None of
this has been spell checked (yet.)

SIGNAME(3)		   Library Functions Manual		    SIGNAME(3)

NAME
     signame signumber -- convert between signal numbers and names

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <signal.h>

     int
     signame(int sig, char *name, size_t namelen);

     int
     signumber(const char *name);

DESCRIPTION
     The signame() function takes a signal number sig, places the name of that
     signal in the buffer given by name (which contains namelen bytes) or as
     much of the signal name as will fit in that buffer, and still allow it to
     be nul (`\0') terminated.	Signal names returned do not contain a leading
     ``SIG'' prefix.

     The return value of signame() is zero (0) if sig does not represent a
     valid signal number, otherwise it is the length of the name of the signal
     corresponding to that number.  Note: this can be longer than namelen,
     which allows applications to determine whether the buffer provided was
     large enough.  If the return value is greater than 0, and less than
     namelen then the complete signal name has been returned in name.
     Otherise if the return value is namelen or larger, a truncated name has
     been returned.  If the return value is 0, sig was not a valid signal
     number, and the buffer at name is unchanged.

     The signumber() function converts the signal name name to the number
     corresponding to that signal.  Any leading ``SIG'' prefix in name is
     ignored.  The name is compared in a case independent manner.  The
     signumber() function returns the signal number, or zero (0) if the name
     given does not represent a valid signal.

     The file <signal.h> defines the constant MAX_SIG_NAME_LEN which may be
     used by applications to size the buffer for use by the signame()
     function.	However, applications should be aware that this information is
     valid only in relation to the particular system upon which, and at the
     particular time at which, compilation is performed.  When signame() is
     actually invoked, signals with longer names may exist.  signame() may be
     invoked with a namelen of zero (0) to determine the size of the buffer
     actually required to hold the nul-terminated name of signal sig.  In this
     case the name parameter is not used, and may be NULL.

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

HISTORY
     The signame() and signumber() functions first appeared in NetBSD 8.0.