1.\" $NetBSD: signalname.3,v 1.3 2020/08/20 22:56:56 kre Exp $ 2.\" 3.\" Available to all and sundry, without restriction on use, or other 4.\" limitations, and without fee. Also without any warranty of fitness 5.\" for any purpose whatever. 6.\" 7.\" Licensed for any use, including redistribution in source 8.\" and binary forms, with or without modifications, subject 9.\" the following agreement: 10.\" 11.\" Licensee agrees to indemnify licensor, and distributor, for 12.\" the full amount of any any claim made by the licensee against 13.\" the licensor or distributor, for any action that results from 14.\" any use or redistribution of this software, plus any costs 15.\" incurred by licensor or distributor resulting from that claim. 16.\" 17.\" This licence must be retained with the software. 18.\" 19.Dd April 28, 2017 20.Dt SIGNALNAME 3 21.Os 22.Sh NAME 23.Nm signalname , 24.Nm signalnumber , 25.Nm signalnext 26.Nd convert between signal numbers and names 27.Sh LIBRARY 28.Lb libc 29.Sh SYNOPSIS 30.In signal.h 31.Ft const char * 32.Fn signalname "int sig" 33.Ft int 34.Fn signalnumber "const char *name" 35.Ft int 36.Fn signalnext "int sig" 37.Sh DESCRIPTION 38The 39.Fn signalname 40function takes a signal number 41.Fa sig , 42and returns the name of that signal. 43The name returned is locale independent, 44and can be the string representation of one of the 45signal names from 46.In signal.h 47such as 48.Dv SIGHUP , 49.Dv SIGSTOP , 50.Dv SIGKILL , 51or some similar name, 52but does not contain the leading 53.Dq Dv SIG 54prefix. 55.Pp 56The return value of 57.Fn signalname 58is 59.Dv NULL 60if 61.Fa sig 62does not represent a valid signal number, 63or if the signal number given has no name. 64.Pp 65The 66.Fn signalnumber 67function converts the signal name 68.Fa name 69to the number corresponding to that signal. 70The 71.Fa name 72is handled in a case-insensitive manner. 73Any leading 74.Dq Dv SIG 75prefix in 76.Fa name 77is ignored. 78.Pp 79This implementation also accepts 80.Dv rtmax Ns \&[\-n] 81and 82.Dv rtmin Ns \&[+n] 83.Po 84where the optional 85.Ar n 86is a decimal integer between 0 and SIGRTMAX\-SIGRTMIN 87.Pc 88to refer to the real time signals. 89.Pp 90The 91.Fn signalnumber 92function returns the signal number, 93or zero (0) if the name given does not represent a valid signal. 94.Pp 95The 96.Fn signalnext 97function takes a signal number, and returns the number of the 98next available bigger signal number. 99When no higher signal numbers remain, it returns zero (0). 100The parameter 101.Fa sig 102can be given as zero (0), to obtain the smallest implemented 103signal number. 104.Pp 105The 106.Fn signalnext 107function returns minus one (\-1) on error, 108that is, if the given signal 109.Fa sig 110is neither a valid signal number nor zero. 111It returns zero when the input signal number, 112.Fa sig , 113is the biggest available signal number. 114Otherwise it returns the signal number of an implemented 115signal that is larger than 116.Fa sig 117and such that there are no implemented signals with values 118between 119.Fa sig 120and the value returned. 121.Pp 122The 123.Fn signalnext 124function can also be used to determine if a non-zero signal 125number is valid or not (0 is always invalid, but cannot be 126detected as such this way.) 127Given the non-zero signal number to check as 128.Fa sig , 129if 130.Fn signalnext 131returns anything other than minus one (\-1) 132then 133.Fa sig 134represents a valid signal number. 135If the return value is \-1 then 136.Fa sig 137is invalid. 138.Sh SEE ALSO 139.Xr kill 1 , 140.Xr intro 2 , 141.Xr psignal 3 , 142.Xr strsignal 3 143.Sh HISTORY 144The 145.Fn signalname , 146.Fn signalnext , 147and 148.Fn signalnumber 149functions first appeared in 150.Nx 8.0 . 151