restart_syscall.2: New page for restart_syscall(2) system call

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 130 insertions, 0 deletions

diff --git a/man2/restart_syscall.2 b/man2/restart_syscall.2
new file mode 100644
index 00000000..89584766
--- /dev/null
+++ b/man2/restart_syscall.2
@@ -0,0 +1,130 @@
+.\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" 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.
+.\" %%%LICENSE_END
+.\"
+.\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803
+.\" From: Linus Torvalds <torvalds <at> transmeta.com>
+.\" Subject: Re: [PATCH] compatibility syscall layer (lets try again)
+.\" Newsgroups: gmane.linux.kernel
+.\" Date: 2002-12-05 02:51:12 GMT
+.\"
+.\" 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"
+.SH NAME
+restart_syscall \- restart a system call after interruption by a stop signal
+.SH SYNOPSIS
+.B int restart_syscall(void);
+
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
+.SH DESCRIPTION
+The
+.BR restart_syscall ()
+system call is used to restart certain system calls
+after a process that was stopped by a signal (e.g.,
+.BR SIGSTOP
+or
+.BR SIGTSTP )
+is later resumed after receiving a
+.BR SIGCONT
+signal.
+This system call is designed only for internal use by the kernel.
+
+.BR restart_syscall ()
+is used for restarting only those system calls that,
+when restarted, should adjust their time-related parameters\(emnamely
+.BR poll (2)
+(since Linux 2.6.24),
+.BR nanosleep (2)
+(since Linux 2.6),
+.BR clock_nanosleep (2)
+(since Linux 2.6),
+and
+.BR futex (2),
+when employed with the
+.BR FUTEX_WAIT
+(since Linux 2.6.22)
+and
+.BR FUTEX_WAIT_BITSET
+(since Linux 2.6.31)
+operations.
+.\" 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().
+.BR restart_syscall ()
+restarts the interrupted system call with a
+time argument that is suitably adjusted to account for the
+time that has already elapsed (including the time where the process
+was stopped by a signal).
+Without the
+.BR restart_syscall ()
+mechanism, restarting these system calls would not correctly deduce the
+already elapsed time when the process continued execution.
+.SH RETURN VALUE
+The return value of
+.BR restart_syscall ()
+is the return value of whatever system call is being restarted.
+.SH ERRORS
+.I errno
+is set as per the errors for whatever system call is being restarted by
+.BR restart_syscall ().
+.SH VERSIONS
+The
+.BR restart_syscall ()
+system call is present since Linux 2.6.
+.SH CONFORMING TO
+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.
+
+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 signal (7)
+.\" FIXME select(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.