From bc0d5df316ed16de594fd03631a1dc4ae7fead57 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Sun, 27 May 2007 21:03:48 +0000
Subject: [PATCH] Strengthen warning against the use of signal(). Add
 siginterrupt(3) to SEE ALSO list.

---
 man2/signal.2 | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/man2/signal.2 b/man2/signal.2
index 56d2db32e..0f5c5051c 100644
--- a/man2/signal.2
+++ b/man2/signal.2
@@ -24,8 +24,9 @@
 .\"
 .\" Modified 2004-11-19, mtk:
 .\" added pointer to sigaction.2 for details of ignoring SIGCHLD
+.\" 2007-06-03, mtk: strengthened portability warning.
 .\"
-.TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual"
+.TH SIGNAL 2 2007-06-03 "Linux" "Linux Programmer's Manual"
 .SH NAME
 signal \- ANSI C signal handling
 .SH SYNOPSIS
@@ -35,6 +36,15 @@ signal \- ANSI C signal handling
 .sp
 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
 .SH DESCRIPTION
+The behaviour of 
+.BR signal ()
+varies across Unix versions,
+and has also varied historically across different versions of Linux.
+\fBAvoid its use\fP: use
+.BR sigaction (2)
+instead.
+See \fIPortability\fP below.
+
 The
 .BR signal ()
 system call installs a new signal handler for the signal with number
@@ -74,9 +84,8 @@ and
 .B SIGSTOP
 cannot be caught or ignored.
 .SH "RETURN VALUE"
-The
 .BR signal ()
-function returns the previous value of the signal handler, or
+returns the previous value of the signal handler, or
 .B SIG_ERR
 on error.
 .SH "CONFORMING TO"
@@ -90,11 +99,10 @@ ignores a
 .BR SIGILL ,
 or
 .B SIGSEGV
-signal that was not generated by the
+signal that was not generated by
 .BR kill (2)
 or the
-.BR raise (3)
-functions.
+.BR raise (3).
 Integer division by zero has undefined result.
 On some architectures it will generate a
 .B SIGFPE
@@ -142,25 +150,19 @@ instead of
 then
 .BR signal ()
 is redefined as
-.B __bsd_signal
-and signal has the BSD semantics.
+.BR __bsd_signal ()
+and
+.BR signal ()
+has the BSD semantics.
 This is not recommended.
 
 If one on a glibc2 system defines a feature test
 macro such as
 .B _XOPEN_SOURCE
 or uses a separate
-.B sysv_signal
+.BR sysv_signal (3)
 function, one obtains classical behaviour.
 This is not recommended.
-
-Trying to change the semantics of this call using
-defines and includes is not a good idea.
-It is better to avoid
-.BR signal ()
-altogether, and use
-.BR sigaction (2)
-instead.
 .SH "SEE ALSO"
 .BR kill (1),
 .BR alarm (2),
@@ -174,6 +176,7 @@ instead.
 .BR bsd_signal (3),
 .BR killpg (3),
 .BR raise (3),
+.BR siginterrupt (3),
 .BR sigsetops (3),
 .BR sigvec (3),
 .BR sysv_signal (3),