sigdescr_np: New module.

* lib/string.in.h (sigdescr_np): New declaration.
* lib/sigdescr_np.c: New file.
* m4/sigdescr_np.m4: New file.
* m4/string_h.m4 (gl_HEADER_STRING_H_BODY): Test whether sigdescr_np is
declared.
(gl_HEADER_STRING_H_DEFAULTS): Initialize GNULIB_SIGDESCR_NP,
HAVE_SIGDESCR_NP.
* modules/string (Makefile.am): Substitute GNULIB_SIGDESCR_NP,
HAVE_SIGDESCR_NP.
* modules/sigdescr_np: New file.
* tests/test-string-c++.cc: Verify the signature of sigdescr_np.
* doc/glibc-functions/sigdescr_np.texi: Mention the new module.

ChangeLog

@@ -1,3 +1,19 @@
+2020-08-21  Bruno Haible  <bruno@clisp.org>
+
+	sigdescr_np: New module.
+	* lib/string.in.h (sigdescr_np): New declaration.
+	* lib/sigdescr_np.c: New file.
+	* m4/sigdescr_np.m4: New file.
+	* m4/string_h.m4 (gl_HEADER_STRING_H_BODY): Test whether sigdescr_np is
+	declared.
+	(gl_HEADER_STRING_H_DEFAULTS): Initialize GNULIB_SIGDESCR_NP,
+	HAVE_SIGDESCR_NP.
+	* modules/string (Makefile.am): Substitute GNULIB_SIGDESCR_NP,
+	HAVE_SIGDESCR_NP.
+	* modules/sigdescr_np: New file.
+	* tests/test-string-c++.cc: Verify the signature of sigdescr_np.
+	* doc/glibc-functions/sigdescr_np.texi: Mention the new module.
+
 2020-08-20  Bruno Haible  <bruno@clisp.org>
 
 	sigabbrev_np: Add tests.

doc/glibc-functions/sigdescr_np.texi

@@ -10,15 +10,19 @@ Documentation:@*
 @url{https://www.gnu.org/software/libc/manual/html_node/Signal-Messages.html}.
 @end ifnotinfo
 
-Gnulib module: ---
+Gnulib module: sigdescr_np
 
 Portability problems fixed by Gnulib:
 @itemize
-@end itemize
-
-Portability problems not fixed by Gnulib:
-@itemize
 @item
 This function is missing on all non-glibc platforms:
 glibc 2.31, Mac OS X 10.13, FreeBSD 6.4, NetBSD 9.0, OpenBSD 3.8, Minix 3.1.8, AIX 7.1, HP-UX 11.31, IRIX 6.5, Solaris 11.4, Cygwin 2.9, mingw, MSVC 14, Android 9.0.
 @end itemize
+
+Portability problems not fixed by Gnulib:
+@itemize
+@end itemize
+
+Note: This function is hardly useful, because it returns English strings, not
+internationalized strings.  Better use the function @code{strsignal}, which
+returns internationalized strings.

lib/sigdescr_np.c

@@ -0,0 +1,376 @@
+/* English descriptions of signals.
+   Copyright (C) 2020 Free Software Foundation, Inc.
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
+
+/* Written by Bruno Haible <bruno@clisp.org>, 2020.  */
+
+#include <config.h>
+
+/* Specification.  */
+#include <string.h>
+
+#include <signal.h>
+
+const char *
+sigdescr_np (int sig)
+{
+  /* Note: Some platforms (glibc, FreeBSD, NetBSD, OpenBSD, AIX, IRIX, Haiku,
+     Android) have an array 'sys_siglist'.  (On AIX, you need to declare it
+     yourself, and it has fewer than NSIG elements.)  Its contents varies
+     depending on the OS.
+     On other OSes, you can invoke strsignal (sig) in the C locale.
+     In the code below, we show the differences.
+     You can see how cryptic some of these strings are.  We try to pick more
+     understandable wordings.  */
+
+  switch (sig)
+    {
+    /* Signals specified by ISO C.  */
+    case SIGABRT:
+      /* glibc: "Aborted".  *BSD: "Abort trap".  Solaris: "Abort".  */
+      return "Aborted";
+    case SIGFPE:
+      /* glibc, *BSD: "Floating point exception".  Solaris: "Arithmetic exception".
+         The latter is more correct, because of integer division by 0 or -1.  */
+      return "Arithmetic exception";
+    case SIGILL:
+      return "Illegal instruction";
+    case SIGINT:
+      return "Interrupt";
+    case SIGSEGV:
+      return "Segmentation fault";
+    case SIGTERM:
+      return "Terminated";
+
+    /* Signals specified by POSIX.
+       <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html>  */
+    #if defined SIGALRM
+    case SIGALRM:
+      return "Alarm clock";
+    #endif
+    #if defined SIGBUS
+    case SIGBUS:
+      return "Bus error";
+    #endif
+    #if defined SIGCHLD
+    case SIGCHLD:
+      /* glibc, *BSD: "Child exited".  Solaris: "Child status changed".  */
+      return "Child stopped or exited";
+    #endif
+    #if defined SIGCONT
+    case SIGCONT:
+      return "Continued";
+    #endif
+    #if defined SIGHUP
+    case SIGHUP:
+      return "Hangup";
+    #endif
+    #if defined SIGKILL
+    case SIGKILL:
+      return "Killed";
+    #endif
+    #if defined SIGPIPE
+    case SIGPIPE:
+      return "Broken pipe";
+    #endif
+    #if defined SIGQUIT
+    case SIGQUIT:
+      return "Quit";
+    #endif
+    #if defined SIGSTOP
+    case SIGSTOP:
+      /* glibc, Solaris: "Stopped (signal)".  *BSD: "Suspended (signal)".  */
+      return "Stopped (signal)";
+    #endif
+    #if defined SIGTSTP
+    case SIGTSTP:
+      /* glibc: "Stopped".  *BSD: "Suspended".  Solaris: "Stopped (user)".  */
+      return "Stopped";
+    #endif
+    #if defined SIGTTIN
+    case SIGTTIN:
+      return "Stopped (tty input)";
+    #endif
+    #if defined SIGTTOU
+    case SIGTTOU:
+      return "Stopped (tty output)";
+    #endif
+    #if defined SIGUSR1
+    case SIGUSR1:
+      /* glibc, *BSD: "User defined signal 1".  Solaris: "User signal 1".  */
+      return "User defined signal 1";
+    #endif
+    #if defined SIGUSR2
+    case SIGUSR2:
+      /* glibc, *BSD: "User defined signal 2".  Solaris: "User signal 2".  */
+      return "User defined signal 2";
+    #endif
+    #if defined SIGPOLL
+    case SIGPOLL:
+      /* glibc: "I/O possible".  Solaris: "Pollable event".  */
+      return "I/O possible";
+    #endif
+    #if defined SIGPROF
+    case SIGPROF:
+      return "Profiling timer expired";
+    #endif
+    #if defined SIGSYS
+    case SIGSYS:
+      return "Bad system call";
+    #endif
+    #if defined SIGTRAP
+    case SIGTRAP:
+      /* glibc, Solaris: "Trace/breakpoint trap".  *BSD: "Trace/BPT trap".  */
+      return "Trace/breakpoint trap";
+    #endif
+    #if defined SIGURG
+    case SIGURG:
+      /* glibc, *BSD: "Urgent I/O condition".  Solaris: "Urgent socket condition".  */
+      return "Urgent I/O condition";
+    #endif
+    #if defined SIGVTALRM
+    case SIGVTALRM:
+      return "Virtual timer expired";
+    #endif
+    #if defined SIGXCPU
+    case SIGXCPU:
+      /* glibc, *BSD: "CPU time limit exceeded".  Solaris: "Cpu limit exceeded".  */
+      return "CPU time limit exceeded";
+    #endif
+    #if defined SIGXFSZ
+    case SIGXFSZ:
+      return "File size limit exceeded";
+    #endif
+
+    /* Other signals on other systems.  */
+    /* native Windows */
+    #if defined SIGBREAK
+    case SIGBREAK:
+      return "Ctrl-Break";
+    #endif
+    /* IRIX */
+    #if defined SIGCKPT
+    case SIGCKPT:
+      return "Checkpoint"; /* See man 1 cpr, man 3C atcheckpoint */
+    #endif
+    /* Linux, IRIX, Cygwin */
+    #if defined SIGCLD && SIGCLD != SIGCHLD
+    case SIGCLD:
+      return "Child stopped or exited";
+    #endif
+    /* AIX */
+    #if defined SIGCPUFAIL
+    case SIGCPUFAIL:
+      /* AIX: "CPU failure predicted".  */
+      return "CPU going down"; /* See man bindprocessor */
+    #endif
+    /* AIX */
+    #if defined SIGDANGER
+    case SIGDANGER:
+      /* AIX: "Paging space low".  */
+      return "Swap space nearly exhausted";
+    #endif
+    /* Mac OS X, FreeBSD, NetBSD, OpenBSD, Minix, AIX, IRIX, Cygwin, mingw */
+    #if defined SIGEMT
+    case SIGEMT:
+      /* glibc/Hurd, *BSD: "EMT trap".  Solaris: "Emulation trap".  */
+      return "Instruction emulation needed";
+    #endif
+    /* Mac OS X, FreeBSD, NetBSD, OpenBSD, Minix */
+    #if defined SIGINFO
+    case SIGINFO:
+      return "Information request";
+    #endif
+    /* Linux, Mac OS X, FreeBSD, NetBSD, OpenBSD, Minix, AIX, IRIX, Cygwin */
+    #if defined SIGIO && SIGIO != SIGPOLL
+    case SIGIO:
+      return "I/O possible";
+    #endif
+    /* Linux, IRIX, Cygwin, mingw */
+    #if defined SIGIOT && SIGIOT != SIGABRT
+    case SIGIOT:
+      return "IOT instruction"; /* a PDP-11 instruction */
+    #endif
+    /* AIX */
+    #if defined SIGKAP
+    case SIGKAP:
+      /* Process must issue a KSKAPACK ioctl, or will be killed in 30 seconds.  */
+      /* AIX: "Monitor mode granted".  */
+      return "Keep Alive Poll";
+    #endif
+    /* Haiku */
+    #if defined SIGKILLTHR
+    case SIGKILLTHR:
+      return "Kill thread";
+    #endif
+    /* Minix */
+    #if defined SIGKMEM
+    case SIGKMEM:
+      return "Kernel memory request";
+    #endif
+    /* Minix */
+    #if defined SIGKMESS
+    case SIGKMESS:
+      return "Kernel message";
+    #endif
+    /* Minix */
+    #if defined SIGKSIG
+    case SIGKSIG:
+      return "Kernel signal";
+    #endif
+    /* Minix */
+    #if defined SIGKSIGSM
+    case SIGKSIGSM:
+      return "Kernel signal for signal manager";
+    #endif
+    /* FreeBSD */
+    #if defined SIGLIBRT
+    case SIGLIBRT:
+      return "Real-time library interrupt";
+    #endif
+    /* Cygwin */
+    #if defined SIGLOST && SIGLOST != SIGABRT && SIGLOST != SIGPWR
+    case SIGLOST:
+      /* Solaris: "Resource lost".  */
+      return "File lock lost";
+    #endif
+    /* AIX */
+    #if defined SIGMIGRATE
+    case SIGMIGRATE:
+      return "Process migration";
+    #endif
+    /* AIX */
+    #if defined SIGMSG
+    case SIGMSG:
+      /* AIX: "Input device data".  */
+      return "Message in the ring";
+    #endif
+    /* ACM */
+    #if defined SIGPLAN
+    case SIGPLAN:
+      return "Programming language anomaly";
+    #endif
+    /* AIX */
+    #if defined SIGPRE
+    case SIGPRE:
+      return "Programmed exception";
+    #endif
+    /* IRIX */
+    #if defined SIGPTINTR
+    case SIGPTINTR:
+      return "Pthread interrupt";
+    #endif
+    /* IRIX */
+    #if defined SIGPTRESCHED
+    case SIGPTRESCHED:
+      return "Pthread rescheduling";
+    #endif
+    /* Linux, NetBSD, Minix, AIX, IRIX, Cygwin */
+    #if defined SIGPWR
+    case SIGPWR:
+      /* glibc: "Power failure".  NetBSD: "Power fail/restart".  */
+      return "Power failure";
+    #endif
+    /* AIX */
+    #if defined SIGRECONFIG
+    case SIGRECONFIG:
+      return "Dynamic logical partitioning changed";
+    #endif
+    /* AIX */
+    #if defined SIGRECOVERY
+    case SIGRECOVERY:
+      return "Kernel recovery";
+    #endif
+    /* IRIX */
+    #if defined SIGRESTART
+    case SIGRESTART:
+      return "Checkpoint restart"; /* See man 1 cpr, man 3C atrestart */
+    #endif
+    /* AIX */
+    #if defined SIGRETRACT
+    case SIGRETRACT:
+      /* AIX: "Monitor mode retracted".  */
+      return "Retracting Keep Alive Poll";
+    #endif
+    /* AIX */
+    #if defined SIGSAK
+    case SIGSAK:
+      /* AIX: "Secure attention".  */
+      return "Secure Attention Key";
+    #endif
+    /* ACM */
+    #if defined SIGSAM
+    case SIGSAM:
+      return "Symbolic computation failed";
+    #endif
+    /* Minix */
+    #if defined SIGSNDELAY
+    case SIGSNDELAY:
+      return "Done sending message";
+    #endif
+    /* AIX */
+    #if defined SIGSOUND
+    case SIGSOUND:
+      /* AIX: "Sound completed".  */
+      return "Sound configuration changed";
+    #endif
+    /* Linux */
+    #if defined SIGSTKFLT
+    case SIGSTKFLT:
+      return "Stack fault";
+    #endif
+    /* AIX */
+    #if defined SIGSYSERROR
+    case SIGSYSERROR:
+      return "Kernel error";
+    #endif
+    /* AIX */
+    #if defined SIGTALRM
+    case SIGTALRM:
+      return "Thread alarm clock";
+    #endif
+    /* FreeBSD, OpenBSD */
+    #if defined SIGTHR
+    case SIGTHR:
+      /* OpenBSD: "Thread AST".  */
+      return "Thread library interrupt";
+    #endif
+    /* IRIX */
+    #if defined SIGUME
+    case SIGUME:
+      return "Uncorrectable memory error";
+    #endif
+    /* AIX */
+    #if defined SIGVIRT
+    case SIGVIRT:
+      return "Virtual time alarm clock";
+    #endif
+    /* AIX */
+    #if defined SIGWAITING
+    case SIGWAITING:
+      /* AIX: "No runnable lwp".  */
+      return "Thread waiting";
+    #endif
+    /* Linux, Mac OS X, FreeBSD, NetBSD, OpenBSD, Minix, AIX, IRIX, Cygwin, Haiku */
+    #if defined SIGWINCH
+    case SIGWINCH:
+      /* glibc: "Window changed".  *BSD: "Window size changed" or "Window size changes".  */
+      return "Window size changed";
+    #endif
+
+    default:
+      return NULL;
+    }
+}

lib/string.in.h

@@ -1060,6 +1060,21 @@ _GL_WARN_ON_USE (sigabbrev_np, "sigabbrev_np is unportable - "
 # endif
 #endif
 
+/* Return an English description string for the signal number SIG.  */
+#if @GNULIB_SIGDESCR_NP@
+# if ! @HAVE_SIGDESCR_NP@
+_GL_FUNCDECL_SYS (sigdescr_np, const char *, (int sig));
+# endif
+_GL_CXXALIAS_SYS (sigdescr_np, const char *, (int sig));
+_GL_CXXALIASWARN (sigdescr_np);
+#elif defined GNULIB_POSIXCHECK
+# undef sigdescr_np
+# if HAVE_RAW_DECL_SIGDESCR_NP
+_GL_WARN_ON_USE (sigdescr_np, "sigdescr_np is unportable - "
+                 "use gnulib module sigdescr_np for portability");
+# endif
+#endif
+
 #if @GNULIB_STRSIGNAL@
 # if @REPLACE_STRSIGNAL@
 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)

m4/sigdescr_np.m4

@@ -0,0 +1,17 @@
+# sigdescr_np.m4 serial 1
+dnl Copyright (C) 2020 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+AC_DEFUN([gl_FUNC_SIGDESCR_NP],
+[
+  dnl Persuade glibc <string.h> to declare sigdescr_np().
+  AC_REQUIRE([AC_USE_SYSTEM_EXTENSIONS])
+
+  AC_REQUIRE([gl_HEADER_STRING_H_DEFAULTS])
+  AC_CHECK_FUNCS([sigdescr_np])
+  if test $ac_cv_func_sigdescr_np = no; then
+    HAVE_SIGDESCR_NP=0
+  fi
+])

m4/string_h.m4

@@ -5,7 +5,7 @@
 # gives unlimited permission to copy and/or distribute it,
 # with or without modifications, as long as this notice is preserved.
 
-# serial 25
+# serial 26
 
 # Written by Paul Eggert.
 
@@ -28,7 +28,7 @@ AC_DEFUN([gl_HEADER_STRING_H_BODY],
     ]],
     [ffsl ffsll memmem mempcpy memrchr rawmemchr stpcpy stpncpy strchrnul
      strdup strncat strndup strnlen strpbrk strsep strcasestr strtok_r
-     strerror_r sigabbrev_np strsignal strverscmp])
+     strerror_r sigabbrev_np sigdescr_np strsignal strverscmp])
 
   AC_REQUIRE([AC_C_RESTRICT])
 ])
@@ -81,6 +81,7 @@ AC_DEFUN([gl_HEADER_STRING_H_DEFAULTS],
   GNULIB_STRERROR=0;    AC_SUBST([GNULIB_STRERROR])
   GNULIB_STRERROR_R=0;  AC_SUBST([GNULIB_STRERROR_R])
   GNULIB_SIGABBREV_NP=0;AC_SUBST([GNULIB_SIGABBREV_NP])
+  GNULIB_SIGDESCR_NP=0; AC_SUBST([GNULIB_SIGDESCR_NP])
   GNULIB_STRSIGNAL=0;   AC_SUBST([GNULIB_STRSIGNAL])
   GNULIB_STRVERSCMP=0;  AC_SUBST([GNULIB_STRVERSCMP])
   HAVE_MBSLEN=0;        AC_SUBST([HAVE_MBSLEN])
@@ -104,6 +105,7 @@ AC_DEFUN([gl_HEADER_STRING_H_DEFAULTS],
   HAVE_DECL_STRTOK_R=1;         AC_SUBST([HAVE_DECL_STRTOK_R])
   HAVE_DECL_STRERROR_R=1;       AC_SUBST([HAVE_DECL_STRERROR_R])
   HAVE_SIGABBREV_NP=1;          AC_SUBST([HAVE_SIGABBREV_NP])
+  HAVE_SIGDESCR_NP=1;           AC_SUBST([HAVE_SIGDESCR_NP])
   HAVE_DECL_STRSIGNAL=1;        AC_SUBST([HAVE_DECL_STRSIGNAL])
   HAVE_STRVERSCMP=1;            AC_SUBST([HAVE_STRVERSCMP])
   REPLACE_MEMCHR=0;             AC_SUBST([REPLACE_MEMCHR])

modules/sigdescr_np

@@ -0,0 +1,28 @@
+Description:
+sigdescr_np() function: English descriptions of signals.
+
+Files:
+lib/sigdescr_np.c
+m4/sigdescr_np.m4
+
+Depends-on:
+extensions
+string
+
+configure.ac:
+gl_FUNC_SIGDESCR_NP
+if test $HAVE_SIGDESCR_NP = 0; then
+  AC_LIBOBJ([sigdescr_np])
+fi
+gl_STRING_MODULE_INDICATOR([sigdescr_np])
+
+Makefile.am:
+
+Include:
+<string.h>
+
+License:
+LGPLv2+
+
+Maintainer:
+all

modules/string

@@ -67,6 +67,7 @@ string.h: string.in.h $(top_builddir)/config.status $(CXXDEFS_H) $(ARG_NONNULL_H
 	      -e 's/@''GNULIB_STRERROR''@/$(GNULIB_STRERROR)/g' \
 	      -e 's/@''GNULIB_STRERROR_R''@/$(GNULIB_STRERROR_R)/g' \
 	      -e 's/@''GNULIB_SIGABBREV_NP''@/$(GNULIB_SIGABBREV_NP)/g' \
+	      -e 's/@''GNULIB_SIGDESCR_NP''@/$(GNULIB_SIGDESCR_NP)/g' \
 	      -e 's/@''GNULIB_STRSIGNAL''@/$(GNULIB_STRSIGNAL)/g' \
 	      -e 's/@''GNULIB_STRVERSCMP''@/$(GNULIB_STRVERSCMP)/g' \
 	      < $(srcdir)/string.in.h | \
@@ -90,6 +91,7 @@ string.h: string.in.h $(top_builddir)/config.status $(CXXDEFS_H) $(ARG_NONNULL_H
 	      -e 's|@''HAVE_DECL_STRTOK_R''@|$(HAVE_DECL_STRTOK_R)|g' \
 	      -e 's|@''HAVE_DECL_STRERROR_R''@|$(HAVE_DECL_STRERROR_R)|g' \
 	      -e 's|@''HAVE_SIGABBREV_NP''@|$(HAVE_SIGABBREV_NP)|g' \
+	      -e 's|@''HAVE_SIGDESCR_NP''@|$(HAVE_SIGDESCR_NP)|g' \
 	      -e 's|@''HAVE_DECL_STRSIGNAL''@|$(HAVE_DECL_STRSIGNAL)|g' \
 	      -e 's|@''HAVE_STRVERSCMP''@|$(HAVE_STRVERSCMP)|g' \
 	      -e 's|@''REPLACE_MEMCHR''@|$(REPLACE_MEMCHR)|g' \

tests/test-string-c++.cc

@@ -142,6 +142,10 @@ SIGNATURE_CHECK (GNULIB_NAMESPACE::strerror_r, int, (int, char *, size_t));
 SIGNATURE_CHECK (GNULIB_NAMESPACE::sigabbrev_np, const char *, (int));
 #endif
 
+#if GNULIB_TEST_SIGDESCR_NP
+SIGNATURE_CHECK (GNULIB_NAMESPACE::sigdescr_np, const char *, (int));
+#endif
+
 #if GNULIB_TEST_STRSIGNAL
 SIGNATURE_CHECK (GNULIB_NAMESPACE::strsignal, char *, (int));
 #endif