From: Bruno Haible <bruno@clisp.org>
Date: Sun, 3 Jul 2011 11:36:43 +0000 (+0200)
Subject: Comments about EINTR.
X-Git-Tag: v0.1~2190
X-Git-Url: http://erislabs.org.uk/gitweb/?a=commitdiff_plain;h=6b147027a1d9870d7d85e8aa8703c1233031a99c;p=gnulib.git

Comments about EINTR.

* lib/safe-read.h: Explain the purpose of this module.
* lib/safe-write.h: Likewise.
* doc/posix-functions/read.texi: Mention EINTR and the 'safe-read'
module.
* doc/posix-functions/write.texi: Mention EINTR and the 'safe-write'
module.
Reported by Ralf Wildenhues <Ralf.Wildenhues@gmx.de>.
---

diff --git a/ChangeLog b/ChangeLog
index fcc2e6efe..79b10becc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2011-07-03  Bruno Haible  <bruno@clisp.org>
+
+	Comments about EINTR.
+	* lib/safe-read.h: Explain the purpose of this module.
+	* lib/safe-write.h: Likewise.
+	* doc/posix-functions/read.texi: Mention EINTR and the 'safe-read'
+	module.
+	* doc/posix-functions/write.texi: Mention EINTR and the 'safe-write'
+	module.
+	Reported by Ralf Wildenhues <Ralf.Wildenhues@gmx.de>.
+
 2011-06-30  Paul Eggert  <eggert@cs.ucla.edu>
 
 	xnanosleep: Rewrite to use new dtotimespec module.
diff --git a/doc/posix-functions/read.texi b/doc/posix-functions/read.texi
index 2f5312de8..2b5aeb2e4 100644
--- a/doc/posix-functions/read.texi
+++ b/doc/posix-functions/read.texi
@@ -17,4 +17,11 @@ mingw.
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+This function may fail with error @code{EINTR}, even in programs that don't
+install any signal handlers, on some platforms:
+MacOS X 10.5.
 @end itemize
+
+For handling @code{EINTR}, Gnulib provides a module @samp{safe-read} with a
+function @code{safe_read}.
diff --git a/doc/posix-functions/write.texi b/doc/posix-functions/write.texi
index 604507d30..e10591733 100644
--- a/doc/posix-functions/write.texi
+++ b/doc/posix-functions/write.texi
@@ -32,4 +32,11 @@ mingw.
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+This function may fail with error @code{EINTR}, even in programs that don't
+install any signal handlers, on some platforms:
+MacOS X 10.5.
 @end itemize
+
+For handling @code{EINTR}, Gnulib provides a module @samp{safe-write} with a
+function @code{safe_write}.
diff --git a/lib/safe-read.h b/lib/safe-read.h
index 1c49c8f33..7174de7e1 100644
--- a/lib/safe-read.h
+++ b/lib/safe-read.h
@@ -14,6 +14,19 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
 
+/* Some system calls may be interrupted and fail with errno = EINTR in the
+   following situations:
+     - The process is stopped and restarted (signal SIGSTOP and SIGCONT, user
+       types Ctrl-Z) on some platforms: MacOS X.
+     - The process receives a signal for which a signal handler was installed
+       with sigaction() with an sa_flags field that does not contain
+       SA_RESTART.
+     - The process receives a signal for which a signal handler was installed
+       with signal() and for which no call to siginterrupt(sig,0) was done,
+       on some platforms: AIX, HP-UX, IRIX, OSF/1, Solaris.
+
+   This module provides a wrapper around read() that handles EINTR.  */
+
 #include <stddef.h>
 
 #ifdef __cplusplus
diff --git a/lib/safe-write.h b/lib/safe-write.h
index 1f1bcd272..07c84ee5c 100644
--- a/lib/safe-write.h
+++ b/lib/safe-write.h
@@ -14,6 +14,19 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
 
+/* Some system calls may be interrupted and fail with errno = EINTR in the
+   following situations:
+     - The process is stopped and restarted (signal SIGSTOP and SIGCONT, user
+       types Ctrl-Z) on some platforms: MacOS X.
+     - The process receives a signal for which a signal handler was installed
+       with sigaction() with an sa_flags field that does not contain
+       SA_RESTART.
+     - The process receives a signal for which a signal handler was installed
+       with signal() and for which no call to siginterrupt(sig,0) was done,
+       on some platforms: AIX, HP-UX, IRIX, OSF/1, Solaris.
+
+   This module provides a wrapper around write() that handles EINTR.  */
+
 #include <stddef.h>
 
 #define SAFE_WRITE_ERROR ((size_t) -1)