| 1 |
.\" Copyright 2013, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803 |
| 7 |
.\" From: Linus Torvalds <torvalds <at> transmeta.com> |
| 8 |
.\" Subject: Re: [PATCH] compatibility syscall layer (lets try again) |
| 9 |
.\" Newsgroups: gmane.linux.kernel |
| 10 |
.\" Date: 2002-12-05 02:51:12 GMT |
| 11 |
.\" |
| 12 |
.\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition |
| 13 |
.\" |
| 14 |
.TH restart_syscall 2 2026-02-08 "Linux man-pages 6.18" |
| 15 |
.SH NAME |
| 16 |
restart_syscall \- restart a system call after interruption by a stop signal |
| 17 |
.SH SYNOPSIS |
| 18 |
.nf |
| 19 |
.B long restart_syscall(void); |
| 20 |
.fi |
| 21 |
.P |
| 22 |
.IR Note : |
| 23 |
There is no glibc wrapper for this system call; |
| 24 |
see NOTES. |
| 25 |
.SH DESCRIPTION |
| 26 |
The |
| 27 |
.BR restart_syscall () |
| 28 |
system call is used to restart certain system calls |
| 29 |
after a process that was stopped by a signal (e.g., |
| 30 |
.B SIGSTOP |
| 31 |
or |
| 32 |
.BR SIGTSTP ) |
| 33 |
is later resumed after receiving a |
| 34 |
.B SIGCONT |
| 35 |
signal. |
| 36 |
This system call is designed only for internal use by the kernel. |
| 37 |
.P |
| 38 |
.BR restart_syscall () |
| 39 |
is used for restarting only those system calls that, |
| 40 |
when restarted, should adjust their time-related parameters\[em]namely |
| 41 |
.BR poll (2) |
| 42 |
(since Linux 2.6.24), |
| 43 |
.BR nanosleep (2) |
| 44 |
(since Linux 2.6), |
| 45 |
.BR clock_nanosleep (2) |
| 46 |
(since Linux 2.6), |
| 47 |
and |
| 48 |
.BR futex (2), |
| 49 |
when employed with the |
| 50 |
.B FUTEX_WAIT |
| 51 |
(since Linux 2.6.22) |
| 52 |
and |
| 53 |
.B FUTEX_WAIT_BITSET |
| 54 |
(since Linux 2.6.31) |
| 55 |
operations. |
| 56 |
.\" These system calls correspond to the special internal errno value |
| 57 |
.\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart" |
| 58 |
.\" helper function that is invoked by restart_syscall(). |
| 59 |
.\" Notable (as at Linux 3.17) is that poll() has such a "restart" |
| 60 |
.\" function, but ppoll(), select(), and pselect() do not. |
| 61 |
.\" This means that the latter system calls do not take account of the |
| 62 |
.\" time spent in the stopped state when restarting. |
| 63 |
.BR restart_syscall () |
| 64 |
restarts the interrupted system call with a |
| 65 |
time argument that is suitably adjusted to account for the |
| 66 |
time that has already elapsed (including the time where the process |
| 67 |
was stopped by a signal). |
| 68 |
Without the |
| 69 |
.BR restart_syscall () |
| 70 |
mechanism, restarting these system calls would not correctly deduct the |
| 71 |
already elapsed time when the process continued execution. |
| 72 |
.SH RETURN VALUE |
| 73 |
The return value of |
| 74 |
.BR restart_syscall () |
| 75 |
is the return value of whatever system call is being restarted. |
| 76 |
.SH ERRORS |
| 77 |
.I errno |
| 78 |
is set as per the errors for whatever system call is being restarted by |
| 79 |
.BR restart_syscall (). |
| 80 |
.SH STANDARDS |
| 81 |
Linux. |
| 82 |
.SH HISTORY |
| 83 |
Linux 2.6. |
| 84 |
.SH NOTES |
| 85 |
There is no glibc wrapper for this system call, |
| 86 |
because it is intended for use only by the kernel and |
| 87 |
should never be called by applications. |
| 88 |
.P |
| 89 |
The kernel uses |
| 90 |
.BR restart_syscall () |
| 91 |
to ensure that when a system call is restarted |
| 92 |
after a process has been stopped by a signal and then resumed by |
| 93 |
.BR SIGCONT , |
| 94 |
then the time that the process spent in the stopped state is counted |
| 95 |
against the timeout interval specified in the original system call. |
| 96 |
In the case of system calls that take a timeout argument and |
| 97 |
automatically restart after a stop signal plus |
| 98 |
.BR SIGCONT , |
| 99 |
but which do not have the |
| 100 |
.BR restart_syscall () |
| 101 |
mechanism built in, then, after the process resumes execution, |
| 102 |
the time that the process spent in the stop state is |
| 103 |
.I not |
| 104 |
counted against the timeout value. |
| 105 |
Notable examples of system calls that suffer this problem are |
| 106 |
.BR ppoll (2), |
| 107 |
.BR select (2), |
| 108 |
and |
| 109 |
.BR pselect (2). |
| 110 |
.P |
| 111 |
From user space, the operation of |
| 112 |
.BR restart_syscall () |
| 113 |
is largely invisible: |
| 114 |
to the process that made the system call that is restarted, |
| 115 |
it appears as though that system call executed and |
| 116 |
returned in the usual fashion. |
| 117 |
.SH SEE ALSO |
| 118 |
.BR sigaction (2), |
| 119 |
.BR sigreturn (2), |
| 120 |
.BR signal (7) |
| 121 |
.\" FIXME . ppoll(2), select(2), and pselect(2) |
| 122 |
.\" should probably get the restart_syscall() treatment: |
| 123 |
.\" If a select() call is suspended by stop-sig+SIGCONT, the time |
| 124 |
.\" spent suspended is *not* deducted when the select() is restarted. |
| 125 |
.\" FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly. |