.\"
.\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition
.\"
-.TH RESTART_SYSCALL 2 2013-07-30 "Linux" "Linux Programmer's Manual"
+.TH RESTART_SYSCALL 2 2014-12-31 "Linux" "Linux Programmer's Manual"
.SH NAME
restart_syscall \- restart a system call after interruption by a stop signal
.SH SYNOPSIS
.\" These system calls correspond to the special internal errno value
.\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart"
.\" helper function that is invoked by restart_syscall().
+.\" Notable (as at Linux 3.17) is that poll() has such a "restart"
+.\" function, but ppoll(), select(), and pselect() do not.
+.\" This means that the latter system calls do not take account of the
+.\" time spent in the stopped state when restarting.
.BR restart_syscall ()
restarts the interrupted system call with a
time argument that is suitably adjusted to account for the
was stopped by a signal).
Without the
.BR restart_syscall ()
-mechanism, restarting these system calls would not correctly deduce the
+mechanism, restarting these system calls would not correctly deduct the
already elapsed time when the process continued execution.
.SH RETURN VALUE
The return value of
.BR restart_syscall ()
system call is present since Linux 2.6.
.SH CONFORMING TO
-This system call is Linux specific.
+This system call is Linux-specific.
.SH NOTES
There is no glibc wrapper for this system call,
because it is intended for use only by the kernel and
should never be called by applications.
+The kernel uses
+.BR restart_syscall ()
+to ensure that when a system call is restarted
+after a process has been stopped by a signal and then resumed by
+.BR SIGCONT ,
+then the time that the process spent in the stopped state is counted
+against the timeout interval specified in the original system call.
+In the case of system calls that take a timeout argument and
+automatically restart after a stop signal plus
+.BR SIGCONT ,
+but which do not have the
+.BR restart_syscall (2)
+mechanism built in, then, after the process resumes execution,
+the time that the process spent in the stop state is
+.I not
+counted against the timeout value.
+Notable examples of system calls that suffer this problem are
+.BR ppoll (2),
+.BR select (2),
+and
+.BR pselect (2).
+
From user space, the operation of
.BR restart_syscall (2)
is largely invisible:
to the process that made the system call that is restarted,
it appears as though that system call executed and
returned in the usual fashion.
-.\"
-.\" FIXME
-.\" There is one oddness in the implementation though, with respect to
-.\" nanosleep() (and probably also clock_nanosleep()). The scenario
-.\" is as follows:
-.\" 1. Start a nanosleep() for (say) 30 seconds,
-.\" 2. Stop the process with (say) SIGTSTP (^Z).
-.\" 3. Resume the process with SIGCONT,
-.\" 4. Upon return, the 'rem' argument of nanosleep() will contain the
-.\" remaining unslept time **at the time when SIGTSTP was delivered**.
-.\" The behavior at point 4 is odd, but doesn't violate the standards, which
-.\" specify the treatment of 'rem' only when the system call returns with
-.\" the error EINTR (i.e., the call was interrupted by a signal handler).
-.\"
.SH SEE ALSO
-.BR sigreturn (2),
.BR sigaction (2),
+.BR sigreturn (2),
.BR signal (7)
-.\" FIXME select(2) should probably get the restart_syscall() treatment:
+.\" FIXME . ppoll(2), select(2), and pselect(2)
+.\" should probably get the restart_syscall() treatment:
.\" If a select() call is suspended by stop-sig+SIGCONT, the time
.\" spent suspended is *not* deducted when the select() is restarted.
-.\" FIXME: check whether recvmmsg() handles stop-sig+SIGCONT properly.
+.\" FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly.
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.