--- 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.

--- a/doc/posix-functions/read.texi
+++ b/doc/posix-functions/read.texi
@@ -17,4 +17,11 @@
 
 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}.

--- a/doc/posix-functions/write.texi
+++ b/doc/posix-functions/write.texi
@@ -32,4 +32,11 @@
 
 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}.

--- 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

--- 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)