Austin Group Defect Tracker

Aardvark Mark IV

Viewing Issue Simple Details Jump to Notes ] Issue History ] Print ]
ID Category Severity Type Date Submitted Last Update
0001138 [1003.1(2016)/Issue7+TC2] System Interfaces Editorial Enhancement Request 2017-04-27 12:02 2019-01-16 13:36
Reporter joerg View Status public  
Assigned To
Priority normal Resolution Open  
Status New  
Name Jörg Schilling
User Reference
Section System Interfaces
Page Number new interface
Line Number newinterface
Interp Status ---
Final Accepted Text
Summary 0001138: Add strsignal(), sig2str() and str2sig() to the standard.
Description Solaris contains:

char * strsignal(int signum) signal number -> sig destription

int str2sig(const char *s, int *sigp) signal name -> signal number

int sig2str(int i, char *s) signal number -> signal name

We should add these interfaces to permit e.g. the kill command to be implemented with POSIX interfaces.
Desired Action Add strsignal() to string.h
Add sig2str() and str2sig() to signal.h

Add the three functions to the system interfaces descriptions.

We might be able to use the Solaris man pages as a starter for the text.
Tags No tags attached.
Attached Files

- Relationships

-  Notes
joerg (reporter)
2017-04-27 12:11

I forgot: add SIG2STR_MAX to signal.h
schwarze (reporter)
2017-04-27 13:32

schwarze@isnote $ man strsignal | col -b | sed -n '/^STAN/,$p'
     The strsignal() function conforms to IEEE Std 1003.1-2008 (POSIX.1).

     The strsignal() function first appeared in AT&T SystemV Release4 UNIX
     and was reimplemented for NetBSD 1.0.

OpenBSD 6.1 June 5, 2013 OpenBSD 6.1 [^]

Public functions str2sig(3) or sig2str(3) do not exist in FreeBSD or NetBSD, and definitely not in OpenBSD. Regarding DragonFly and the Linux man pages project, i don't see these functions in the manual pages either (while i do see strsignal(3) there).

In FreeBSD, the name str2sig() clashes with at least one static symbol (in usr.bin/fstat/fuser.c). Probably not a big problem, just mentioning it for completeness.

The only systems where i do see evidence for public str2sig(3) and sig2str(3) are illumos and Oracle Solaris 9 to 11.

Is that sufficiently common for standardization? Just asking... As far as i understand, establishing new interfaces is not the typical job of POSIX.
joerg (reporter)
2017-04-27 14:15

Thank you for the hint that I missed to find strsignal() in the standard ;-)

In order to ad a new interface, there should be a need for that interface andI believe that the two functions would help programmers to write portable programs in special as many singal numbers are not unique across platforms.
kre (reporter)
2017-04-27 15:47

Re (note 3680)
    In order to ad a new interface, there should be a need for that interface

Quite correct, but "I believe" is not evidence of that. The way to do it is
to actually implement the interface, and have it actually used (as note 3679

That way we get some real evidence that the interface proposed is the correct

For example, I wouldn't implement either of the 2 proposed new functions with
the function prototype you gave, for me it would be ...

int str2sig(const char *s) signal name -> signal number

int sig2str(int i, char *s, size_t len) signal number -> signal name

(and that still leaves aside the choice of names, str_to_sig() (etc) would
be another possibility - but with naming it tends to be whatever becomes
popular first, as there is no one right answer.)

For str2sig() a return value of 0 would indicate an error (no such sig name)
as the one thing we know about signal numbers is that 0 is not one of them.

And for sig2str() we need a buffer length arg, as while we might "just know"
that SIG2STR_MAX is sufficient, implementing things that way means that
there's no possibility to ever increase that value (or binary compat/safety is
lost.) The constant can still exist, but it should just be for users to size
the buffer, not for the internals of the function to use.

But all of this is just my opinion, the only way we ever really know what
works is for users to use the interface, and be happy enough that they use
it (not just reinvent it) and don't keep asking for changes.
jilles (reporter)
2017-04-27 16:30

Various BSD systems provide an extern const char * const sys_signame[]; from libc, such that sys_signame[SIGHUP] is "HUP", etc.

However, a function interface is superior to an array. Using common ELF linking, non-PIE executables use copy relocations to access the array, which means that changing its size is not binary compatible, and exporting an array like this forces the inefficient pattern of pointers to static data in a shared library, which need to be relocated in every process using the library even if that process does not use the array at all.

Note that signal names, unlike strsignal() messages, are not translatable.

Existing software that needs to work with signal names tends to either use interfaces like sys_signame and sig2str/str2sig, or create its own table using a list of signals that may exist, like

char *table[] = {
#ifdef SIGFOO
        [SIGFOO] = "FOO",
joerg (reporter)
2017-05-04 10:57

For making portable shell implementations easier, it would be a good idea if
the standard also adds a "NSIG" definition that may redirect to a getconf()
kre (reporter)
2017-05-04 12:29

NSIG is not useful unless we also make assumptions about the values
used for the signal numbers, like that they are from 1..NSIG which
the standard avoids doing (and should continue to do.)

I am soon going to delete the earlier note I posted with the proposal I made
to NetBSD developers, and replace it with the current (simpler) version,
which has no need of an NSIG definition.
kre (reporter)
2017-05-10 02:00
edited on: 2017-05-10 02:31

Note that this note replaces an earlier note (3683, and 3684) which described
an earlier proposal.

I have just added, to NetBSD, functions as described in the
man page I am including in this note. If there is ever a desire to add
functions for this purpose to POSIX, please consider these as alternatives
to str2sig() and sig2str() as included above (I am not requesting that they
actually be included, just that I believe these are better than those...)

Complete source (such as it is - quite *BSD dependent, as they use sys_signame
as described by Jilles in note 3682) is available (for a time anyway) from [^] [^]
(files unpack into the current directory, a test program can be built, on
BSD systems anyway, by "cc *.c" - there is no Makefile.)

Note at the end where it says "First appeared in NetBSD 8.0" - 8.0 has
not been released yet (getting closer, but still some way away.)

The functions described are all pure, and thread safe (though depending upon
the implementation might need some internal locking while acquiring the data
from the system). The current NetBSD implementations are async-signal-safe,
but I would not specify them that way, in order to allow the implementation to
use whatever means it desires to initialise its state. And in any case,
there is almost no possible need for these functions in a signal handler,
the signal number is provided (so we know its number, and that it is valid)
and while the name may be of interest, the results of strsignal() are far
more likely to be relevant.


     signalname signalnumber signalnext -- convert between signal numbers and

     Standard C Library (libc, -lc)

     #include <signal.h>

     const char *
     signalname(int sig);

     signalnumber(const char *name);

     signalnext(int sig);

     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, or if the signal number given has no name.

     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.

     The signalnext() function can also be used to determine if a non-zero
     signal number is valid or not (0 is always invalid, but cannot be
     detected as such this way.) Given the non-zero signal number to check as
     sig, if signalnext() returns anything other than minus one (-1) then sig
     represents a valid signal number. If the return value is -1 then sig is

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

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

Don Cragun (manager)
2018-10-11 15:48

After discussing this in the 2018-10-11 conference call, we have asked the Open Group OR to see if The Open Group would sponsor adding sig2str() and str2sig() to a future revision of the standard.
ajosey (manager)
2019-01-16 13:36

The Open Group Base Working group has agreed to sponsor the addition of sig2str() and str2sig() as a new work item. The next stage will be to develop manual page entries for review and eventual approval at The Open Group.

- Issue History
Date Modified Username Field Change
2017-04-27 12:02 joerg New Issue
2017-04-27 12:02 joerg Name => Jörg Schilling
2017-04-27 12:02 joerg Section => System Interfaces
2017-04-27 12:02 joerg Page Number => new interface
2017-04-27 12:02 joerg Line Number => newinterface
2017-04-27 12:11 joerg Note Added: 0003678
2017-04-27 13:32 schwarze Note Added: 0003679
2017-04-27 14:15 joerg Note Added: 0003680
2017-04-27 15:47 kre Note Added: 0003681
2017-04-27 16:30 jilles Note Added: 0003682
2017-04-28 02:14 kre Note Added: 0003683
2017-04-28 02:49 kre Note Added: 0003684
2017-05-04 10:57 joerg Note Added: 0003685
2017-05-04 12:29 kre Note Added: 0003686
2017-05-10 02:00 kre Note Added: 0003688
2017-05-10 02:00 kre Note Deleted: 0003683
2017-05-10 02:00 kre Note Deleted: 0003684
2017-05-10 02:31 kre Note Edited: 0003688
2017-05-10 02:31 kre Note Edited: 0003688
2018-10-11 15:48 Don Cragun Note Added: 0004148
2019-01-16 13:36 ajosey Note Added: 0004212

Mantis 1.1.6[^]
Copyright © 2000 - 2008 Mantis Group
Powered by Mantis Bugtracker