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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu)
  11 .TH strsignal 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 strsignal, sigabbrev_np, sigdescr_np, sys_siglist \-
  14 return string describing signal
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <string.h>
  21 .PP
  22 .BI "char *strsignal(int " sig );
  23 .BI "const char *sigdescr_np(int " sig );
  24 .BI "const char *sigabbrev_np(int " sig );
  25 .PP
  26 .BI "[[deprecated]] extern const char *const " sys_siglist [];
  27 .fi
  28 .PP
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .PP
  34 .BR sigabbrev_np (),
  35 .BR sigdescr_np ():
  36 .nf
  37     _GNU_SOURCE
  38 .fi
  39 .PP
  40 .BR strsignal ():
  41 .nf
  42     From glibc 2.10 to 2.31:
  43         _POSIX_C_SOURCE >= 200809L
  44     Before glibc 2.10:
  45         _GNU_SOURCE
  46 .fi
  47 .PP
  48 .IR sys_siglist :
  49 .nf
  50     Since glibc 2.19:
  51         _DEFAULT_SOURCE
  52     Glibc 2.19 and earlier:
  53         _BSD_SOURCE
  54 .fi
  55 .SH DESCRIPTION
  56 The
  57 .BR strsignal ()
  58 function returns a string describing the signal
  59 number passed in the argument
  60 .IR sig .
  61 The string can be used only until the next call to
  62 .BR strsignal ().
  63 The string returned by
  64 .BR strsignal ()
  65 is localized according to the
  66 .B LC_MESSAGES
  67 category in the current locale.
  68 .PP
  69 The
  70 .BR sigdescr_np ()
  71 function returns a string describing the signal
  72 number passed in the argument
  73 .IR sig .
  74 Unlike
  75 .BR strsignal ()
  76 this string is not influenced by the current locale.
  77 .PP
  78 The
  79 .BR sigabbrev_np ()
  80 function returns the abbreviated name of the signal,
  81 .IR sig .
  82 For example, given the value
  83 .BR SIGINT ,
  84 it returns the string "INT".
  85 .PP
  86 The (deprecated) array
  87 .I sys_siglist
  88 holds the signal description strings
  89 indexed by signal number.
  90 The
  91 .BR strsignal ()
  92 or the
  93 .BR sigdescr_np ()
  94 function should be used instead of this array; see also VERSIONS.
  95 .SH RETURN VALUE
  96 The
  97 .BR strsignal ()
  98 function returns the appropriate description
  99 string, or an unknown signal message if the signal number is invalid.
 100 On some systems (but not on Linux), NULL may instead be
 101 returned for an invalid signal number.
 102 .PP
 103 The
 104 .BR sigdescr_np ()
 105 and
 106 .BR sigabbrev_np ()
 107 functions return the appropriate description string.
 108 The returned string is statically allocated and valid for
 109 the lifetime of the program.
 110 These functions return NULL for an invalid signal number.
 111 .SH VERSIONS
 112 .BR sigdescr_np ()
 113 and
 114 .BR sigabbrev_np ()
 115 first appeared in glibc 2.32.
 116 .PP
 117 Starting with version 2.32,
 118 .\" glibc commit b1ccfc061feee9ce616444ded8e1cd5acf9fa97f
 119 the
 120 .I sys_siglist
 121 symbol is no longer exported by glibc.
 122 .SH ATTRIBUTES
 123 For an explanation of the terms used in this section, see
 124 .BR attributes (7).
 125 .ad l
 126 .nh
 127 .TS
 128 allbox;
 129 lb lb lbx
 130 l l l.
 131 Interface       Attribute       Value
 132 T{
 133 .BR strsignal ()
 134 T}      Thread safety   T{
 135 MT-Unsafe race:strsignal locale
 136 T}
 137 T{
 138 .BR sigdescr_np (),
 139 .BR sigabbrev_np ()
 140 T}      Thread safety   MT-Safe
 141 .TE
 142 .hy
 143 .ad
 144 .sp 1
 145 .SH STANDARDS
 146 .BR strsignal ():
 147 POSIX.1-2008.
 148 Present on Solaris and the BSDs.
 149 .PP
 150 .BR sigdescr_np ()
 151 and
 152 .BR sigabbrev_np ()
 153 are GNU extensions.
 154 .PP
 155 .I sys_siglist
 156 is nonstandard, but present on many other systems.
 157 .SH NOTES
 158 .BR sigdescr_np ()
 159 and
 160 .BR sigabbrev_np ()
 161 are thread-safe and async-signal-safe.
 162 .SH SEE ALSO
 163 .BR psignal (3),
 164 .BR strerror (3)