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

[christos%astron.com@localhost (Christos Zoulas)]

In article <4777.1493344919%andromeda.noi.kre.to@localhost>,
Robert Elz  <kre%munnari.OZ.AU@localhost> wrote:
>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.

Perhaps signame() -> strsignal_r()?

christos