Documentation of bsd_signal().

diff --git a/man3/bsd_signal.3 b/man3/bsd_signal.3
new file mode 100644 (file)
index 0000000..275660b
--- /dev/null
+++ b/man3/bsd_signal.3
@@ -0,0 +1,92 @@
+.\" Copyright (c) 2007 Michael Kerrisk <mtk-manpages@gmx.net>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH BSD_SIGNAL 2 2007-05-04 "" "Linux Programmer's Manual"
+.SH NAME
+bsd_signal \- signal handling with BSD semantics
+.SH SYNOPSIS
+.B #define _XOPEN_SOURCE
+.br
+.B #include <signal.h>
+.sp
+.B typedef void (*sighandler_t)(int);
+.sp
+.BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler );
+.SH DESCRIPTION
+The
+.BR bsd_signal ()
+function takes the same arguments, and performs the same task, as
+.BR signal (2).
+
+The difference between the two is that
+.BR bsd_signal ()
+is guaranteed to provide reliable signal semantics, that is:
+a) the disposition of the signal is not reset to the default
+when the handler is invoked;
+b) delivery of further instances of the signal is blocked while
+the signal handler is executing; and
+c) if the handler interrupts a blocking system call,
+then the system call is automatically restarted.
+A portable application cannot rely on
+.BR signal (2)
+to provide these guarantees.
+.SH "RETURN VALUE"
+The
+.BR bsd_signal ()
+function returns the previous value of the signal handler, or
+.B SIG_ERR
+on error.
+.SH ERRORS
+As for
+.BR signal (2).
+.SH NOTES
+Use of
+.BR bsd_signal ()
+should be avoided; use
+.BR sigaction (2)
+instead.
+
+On modern Linux systems,
+.BR bsd_signal ()
+and
+.BR signal (2)
+are equivalent.
+But on older systems, 
+.BR signal (2)
+provided unreliable signal semantics; see
+.BR signal (2)
+for details.
+
+The use of
+.B sighandler_t
+is a GNU extension;
+this type is only defined if 
+the _GNU_SOURCE feature test macro is defined.
+.SH "CONFORMING TO"
+4.2BSD, POSIX.1-2001.
+.SH "SEE ALSO"
+.BR sigaction (2),
+.BR signal (2),
+.BR sysv_signal (3),
+.BR feature_test_macros (7),
+.BR signal (7)
+.\" FIXME add SEE ALSO refs from those pages.