man3/strsignal.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References consulted:
  27 .\"     Linux libc source code
  28 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  29 .\"     386BSD man pages
  30 .\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu)
  31 .TH STRSIGNAL 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  32 .SH NAME
  33 strsignal, sigdescr_np, sigdescr_np, sys_siglist \- return string describing signal
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <string.h>
  37 .PP
  38 .BI "char *strsignal(int " sig );
  39 .BI "const char *sigdescr_np(int " sig );
  40 .BI "const char *sigabbrev_np(int " sig );
  41 .PP
  42 .BI "extern const char *const " sys_siglist [];
  43 .fi
  44 .PP
  45 .RS -4
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .RE
  49 .PP
  50 .BR sigabbrev_np (),
  51 .BR sigdescr_np ():
  52 .nf
  53     _GNU_SOURCE
  54 .fi
  55 .PP
  56 .BR strsignal ():
  57 .nf
  58     From glibc 2.10 to 2.31:
  59         _POSIX_C_SOURCE >= 200809L
  60     Before glibc 2.10:
  61         _GNU_SOURCE
  62 .fi
  63 .PP
  64 .IR sys_siglist :
  65 .nf
  66     Since glibc 2.19:
  67         _DEFAULT_SOURCE
  68     Glibc 2.19 and earlier:
  69         _BSD_SOURCE
  70 .fi
  71 .SH DESCRIPTION
  72 The
  73 .BR strsignal ()
  74 function returns a string describing the signal
  75 number passed in the argument
  76 .IR sig .
  77 The string can be used only until the next call to
  78 .BR strsignal ().
  79 The string returned by
  80 .BR strsignal ()
  81 is localized according to the
  82 .B LC_MESSAGES
  83 category in the current locale.
  84 .PP
  85 The
  86 .BR sigdescr_np ()
  87 function returns a string describing the signal
  88 number passed in the argument
  89 .IR sig .
  90 Unlike
  91 .BR strsignal ()
  92 this string is not influenced by the current locale.
  93 .PP
  94 The
  95 .BR sigabbrev_np ()
  96 function returns the abbreviated name of the signal,
  97 .IR sig .
  98 For example, given the value
  99 .BR SIGINT ,
 100 it returns the string "INT".
 101 .PP
 102 The (deprecated) array
 103 .I sys_siglist
 104 holds the signal description strings
 105 indexed by signal number.
 106 The
 107 .BR strsignal ()
 108 or the
 109 .BR sigdescr_np ()
 110 function should be used instead of this array; see also VERSIONS.
 111 .SH RETURN VALUE
 112 The
 113 .BR strsignal ()
 114 function returns the appropriate description
 115 string, or an unknown signal message if the signal number is invalid.
 116 On some systems (but not on Linux), NULL may instead be
 117 returned for an invalid signal number.
 118 .PP
 119 The
 120 .BR sigdescr_np ()
 121 and
 122 .BR sigdabbrev_np ()
 123 functions return the appropriate description string.
 124 The returned string is statically allocated and valid for
 125 the lifetime of the program.
 126 These functions return NULL for an invalid signal number.
 127 .SH VERSIONS
 128 .BR sigdescr_np ()
 129 and
 130 .BR sigdabbrev_np ()
 131 first appeared in glibc 2.32.
 132 .PP
 133 Starting with version 2.32,
 134 .\" glibc commit b1ccfc061feee9ce616444ded8e1cd5acf9fa97f
 135 the
 136 .I sys_siglist
 137 symbol is no longer exported by glibc.
 138 .SH ATTRIBUTES
 139 For an explanation of the terms used in this section, see
 140 .BR attributes (7).
 141 .ad l
 142 .nh
 143 .TS
 144 allbox;
 145 lb lb lbx
 146 l l l.
 147 Interface       Attribute       Value
 148 T{
 149 .BR strsignal ()
 150 T}      Thread safety   T{
 151 MT-Unsafe race:strsignal locale
 152 T}
 153 T{
 154 .BR sigdescr_np (),
 155 .BR sigabbrev_np ()
 156 T}      Thread safety   MT-Safe
 157 .TE
 158 .hy
 159 .ad
 160 .sp 1
 161 .SH CONFORMING TO
 162 .BR strsignal ():
 163 POSIX.1-2008.
 164 Present on Solaris and the BSDs.
 165 .PP
 166 .BR sigdescr_np ()
 167 and
 168 .BR sigdabbrev_np ()
 169 are GNU extensions.
 170 .PP
 171 .I sys_siglist
 172 is nonstandard, but present on many other systems.
 173 .SH NOTES
 174 .BR sigdescr_np ()
 175 and
 176 .BR sigdabbrev_np ()
 177 are thread-safe and async-signal-safe.
 178 .SH SEE ALSO
 179 .BR psignal (3),
 180 .BR strerror (3)