Add a section describing system call restarting, and noting

which system calls are affected by SA_RESTART, and which
system calls are never restarted.

man7/signal.7

@@ -35,7 +35,7 @@
 .\" 2006-04-24, mtk, Added text on changing signal dispositions,
 .\"		signal mask, and pending signals.
 .\"
-.TH SIGNAL 7  2008-06-02 "Linux" "Linux Programmer's Manual"
+.TH SIGNAL 7  2008-07-04 "Linux" "Linux Programmer's Manual"
 .SH NAME
 signal \- list of available signals
 .SH DESCRIPTION
@@ -471,6 +471,143 @@ waitpid()
 write()
 .fi
 .in
+.SS Interruption of System Calls and Library Functions by Signal Handlers
+If a signal handler is invoked while a system call or library function
+call is blocked, then the system call may fail with the error
+.BR EINTR .
+The details depend on the interface
+(in particular, whether the genealogy of the interface is System V or BSD)
+and whether or not the signal handler was established using the
+.BR SA_RESTART
+flag (see
+.BR sigaction (2)).
+The details vary across Unix systems.
+
+For the following interfaces,
+if the
+.BR SA_RESTART
+flag was used,
+then a blocked call will be restarted after being interrupted
+by a signal handler;
+otherwise the call will fail with the error
+.BR EINTR :
+.\" The following system calls use ERESTARTSYS,
+.\" so that they are restartable
+.RS 4
+.IP * 2
+.BR read (2),
+.BR readv (2),
+.BR write (2),
+.BR writev (2),
+and
+.BR ioctl (2)
+calls on "slow" devices.
+A "slow" device is one where the I/O call may block for an indefinite time,
+for example, a terminal, pipe, or socket.
+(A disk is not a slow device according to this definition.)
+If an I/O call on a slow device has already transferred some data by the
+time it is interrupted by a signal handler,
+then the call will return a success status
+(normally, the number of bytes transferred).
+.IP *
+.BR open (2),
+if it can block (e.g., for a FIFO; see
+.BR fifo (7)).
+.IP *
+.BR wait (2),
+.BR wait3 (2),
+.BR wait4 (2),
+.BR waitid (2),
+and
+.BR waitpid (2).
+.IP *
+Socket interfaces:
+.\" If a timeout i(setsockopt()) is in effect on the socket, then these
+.\" system calls switch to using EINTR.  Consequently, they and are not
+.\" automatically restarted, and they show the stop/cont behavior
+.\" described below.  (Verified from 2.6.26 source, and by experiment; mtk)
+.BR accept (2),
+.BR connect (2),
+.BR recv (2),
+.BR recvfrom (2),
+.BR recvmsg (2),
+.BR send (2),
+.BR sendto (2),
+and
+.BR sendmsg (2).
+.IP *
+File locking interfaces:
+.BR flock (2)
+and
+.BR fcntl (2)
+.BR F_SETLKW .
+.IP *
+POSIX message queue interfaces:
+.BR mq_receive (),
+.BR mq_timedreceive (),
+.BR mq_send (),
+and
+.BR mq_timedsend ().
+.IP *
+.BR futex (2)
+.B FUTEX_WAIT
+(since Linux 2.6.22; beforehand, always failed with
+.BR EINTR ).
+.IP *
+POSIX semaphore interfaces:
+.BR sem_wait (3)
+and
+.BR sem_timedwait (3)
+(since Linux 2.6.22; beforehand, always failed with
+.BR EINTR ).
+.RE
+.PP
+The following interfaces are never restarted after
+being interrupted by a signal handler,
+regardless of the use of
+.BR SA_RESTART :
+.\" These are the system calls that give EINTR or ERESTARTNOHAND
+.\" on interruption by a signal handler.
+.RS 4
+.IP * 2
+Interfaces used to wait for signals:
+.BR pause (2),
+.BR sigsuspend (2),
+.BR sigtimedwat (2),
+and
+.BR sigwaitinfo (2).
+.IP *
+File descriptor multiplexing interfaces:
+.BR epoll_wait (2),
+.BR epoll_pwait (2),
+.BR poll (2),
+.BR ppoll (2),
+.BR select (2),
+and
+.BR pselect (2).
+.IP *
+System V IPC calls:
+.\" On some other systems, SA_RESTART does restart these system calls
+.BR msgrcv (2),
+.BR msgsnd (2),
+.BR semop (2),
+and
+.BR semtimedop (2).
+.IP *
+Sleep interfaces:
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR sleep (3),
+and
+.BR usleep (3).
+.IP *
+.BR read (2)
+from an
+.BR inotify (7)
+file descriptor.
+.IP *
+.BR io_getevents (2).
+.RE
 .SH "CONFORMING TO"
 POSIX.1
 .SH BUGS
@@ -480,30 +617,30 @@ and
 have the same value.
 The latter is commented out in the kernel source, but
 the build process of some software still thinks that
-signal 29 is
+Lsignal 29 is
 .BR SIGLOST .
 .SH "SEE ALSO"
 .BR kill (1),
 .BR kill (2),
-.BR kill\%pg (2),
-.BR set\%itimer (2),
-.BR set\%rlimit (2),
-.BR sget\%mask (2),
-.BR sig\%action (2),
-.BR sig\%nal (2),
+.BR killpg (2),
+.BR setitimer (2),
+.BR setrlimit (2),
+.BR sgetmask (2),
+.BR sigaction (2),
+.BR signal (2),
 .BR signalfd (2),
-.BR sig\%pend\%ing (2),
-.BR sig\%proc\%mask (2),
-.BR sig\%queue (2),
-.BR sig\%suspend (2),
-.BR sig\%waitinfo (2),
-.BR bsd\%_signal (3),
+.BR sigpending (2),
+.BR sigprocmask (2),
+.BR sigqueue (2),
+.BR sigsuspend (2),
+.BR sigwaitinfo (2),
+.BR bsd_signal (3),
 .BR raise (3),
-.BR sig\%vec (3),
-.BR sig\%set (3),
+.BR sigvec (3),
+.BR sigset (3),
 .BR sigwait (3),
-.BR str\%signal (3),
-.BR sysv\%_signal (3),
+.BR strsignal (3),
+.BR sysv_signal (3),
 .BR core (5),
 .BR proc (5),
 .BR pthreads (7)