NAME

sig2str, str2sig — translate between signal names and numbers

SYNOPSIS

[CX] #include <signal.h>

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() 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 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, sigaction, strsignal

XBD <signal.h>

CHANGE HISTORY

First released in Issue 8.