NAME
sig2str str2sig
— translate between signal names and
numbers
SYNOPSIS
int sig2str(int signum, char *str); int str2sig(const char *restrict str, int *restrict pnum);
DESCRIPTION
The sig2str () function shall translate
the signal number specified by signum to a signal name and
shall store this string in the location specified by str.
The application shall ensure that str points to a location
that can store the string including the terminating null byte. The symbolic
constant SIG2STR_MAX defined in <signal.h>
gives the maximum number of bytes required.
If signum is equal to 0, the behavior is unspecified.
If signum is equal to one of the symbolic constants listed in the table of signal numbers in <signal.h>, the stored signal name shall be the name of the symbolic constant without the SIG prefix.
If signum is equal to SIGRTMIN or SIGRTMAX, the
stored string shall be "RTMIN" or
"RTMAX", respectively.
If signum is between SIGRTMIN+1 and
(SIGRTMIN+SIGRTMAX)/2 inclusive, the stored string shall be of the form
"RTMIN+n", where n is
the shortest decimal representation of the value of signum
-SIGRTMIN.
If signum is between
(SIGRTMIN+SIGRTMAX)/2 + 1 and SIGRTMAX-1 inclusive, the stored string shall
be either of the form "RTMIN+n" or of the
form "RTMAX-m", where n
is the shortest decimal representation of the value of
signum -SIGRTMIN and
m is the shortest
decimal representation of the value of SIGRTMAX-
signum.
If signum is a valid, supported signal number, is either less than SIGRTMIN or greater than SIGRTMAX, and is not equal to one of the symbolic constants listed in the table of signal numbers in <signal.h>, the stored string shall uniquely identify the signal number signum in an unspecified manner.
The str2sig () function shall translate
the signal name in the string pointed to by str to a
signal number and shall store this value in the location specified by
pnum.
If str points to a string containing the name of one of the symbolic constants listed in the table of signal numbers in <signal.h>, without the SIG prefix, the stored signal number shall be equal to the value of the symbolic constant.
If str points to the string
"RTMIN" or
"RTMAX", the stored value shall be equal
to SIGRTMIN or SIGRTMAX, respectively.
If str points to a string of the form
"RTMIN+n", where n is a
decimal representation of a number between 1 and SIGRTMAX-SIGRTMIN-1
inclusive, the stored value shall be equal to SIGRTMIN+n.
If str points to a string of the form
"RTMAX-n", where n is a
decimal representation of a number between 1 and SIGRTMAX-SIGRTMIN-1
inclusive, the stored value shall be equal to SIGRTMAX-
n.
If str points to a string containing a decimal representation of a valid, supported signal number, the value stored in the location pointed to by pnum shall be equal to that number.
If str points to a string containing a decimal
representation of the value 0 and the string was not returned by a previous
successful call to sig2str () with a
signum argument of 0, the behavior is unspecified.
If str points to a string returned by a previous
successful call to sig2str (
signum, str), the value stored in the
location pointed to by pnum shall be equal to
signum.
If str points to a string that does not meet any
of the above criteria, str2sig () shall store a
value in the location pointed to by pnum if and only if it
recognizes the string as an additional implementation-dependent form of
signal name.
RETURN VALUE
If signum is a valid, supported signal number
(that is, one for which kill(3) does not return -1 with
errno
set to [EINVAL]), the sig2str () function shall
return 0; otherwise, if signum is not equal to 0, it shall
return -1.
If str2sig () stores a value in the
location pointed to by pnum, it shall return 0; otherwise,
it shall return -1.
ERRORS
No errors are defined.
EXAMPLES
None.
APPLICATION USAGE
None.
RATIONALE
Historical versions of these functions translated a
signum value 0 to "EXIT"
(and vice versa), so that they could be used by the shell for the
trap(1) utility. When adding the functions to this
standard, the standard developers felt that they should be aimed at more
general-purpose use, and consequently requiring this behavior did not seem
appropriate and so the behavior in this case has been made unspecified.
FUTURE DIRECTIONS
None.
SEE ALSO
kill(3), sigaction(3), strsignal(3)
XBD <signal.h>
CHANGE HISTORY
First released in Issue 8.