1.\" $NetBSD: signalname.3,v 1.2 2017/05/14 12:35:46 wiz 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 79The 80.Fn signalnumber 81function returns the signal number, 82or zero (0) if the name given does not represent a valid signal. 83.Pp 84The 85.Fn signalnext 86function takes a signal number, and returns the number of the 87next available bigger signal number. 88When no higher signal numbers remain, it returns zero (0). 89The parameter 90.Fa sig 91can be given as zero (0), to obtain the smallest implemented 92signal number. 93.Pp 94The 95.Fn signalnext 96function returns minus one (\-1) on error, if the given signal 97.Fa sig 98is neither a valid signal number nor zero. 99It returns zero when the input signal number, 100.Fa sig , 101is the biggest available signal number. 102Otherwise it returns the signal number of an implemented 103signal that is larger than 104.Fa sig 105and such that there are no implemented signals with values 106between 107.Fa sig 108and the value returned. 109.Pp 110The 111.Fn signalnext 112function can also be used to determine if a non-zero signal 113number is valid or not (0 is always invalid, but cannot be 114detected as such this way.) 115Given the non-zero signal number to check as 116.Fa sig , 117if 118.Fn signalnext 119returns anything other than minus one (\-1) 120then 121.Fa sig 122represents a valid signal number. 123If the return value is \-1 then 124.Fa sig 125is invalid. 126.Sh SEE ALSO 127.Xr kill 1 , 128.Xr intro 2 , 129.Xr psignal 3 , 130.Xr strsignal 3 131.Sh HISTORY 132The 133.Fn signalname , 134.Fn signalnext , 135and 136.Fn signalnumber 137functions first appeared in 138.Nx 8.0 . 139