]>
Commit | Line | Data |
---|---|---|
92f30072 MK |
1 | .\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
24 | .\" | |
25 | .\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803 | |
26 | .\" From: Linus Torvalds <torvalds <at> transmeta.com> | |
27 | .\" Subject: Re: [PATCH] compatibility syscall layer (lets try again) | |
28 | .\" Newsgroups: gmane.linux.kernel | |
29 | .\" Date: 2002-12-05 02:51:12 GMT | |
30 | .\" | |
31 | .\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition | |
32 | .\" | |
4b8c67d9 | 33 | .TH RESTART_SYSCALL 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
92f30072 MK |
34 | .SH NAME |
35 | restart_syscall \- restart a system call after interruption by a stop signal | |
36 | .SH SYNOPSIS | |
37 | .B int restart_syscall(void); | |
dbfe9c70 | 38 | .PP |
92f30072 MK |
39 | .IR Note : |
40 | There is no glibc wrapper for this system call; see NOTES. | |
41 | .SH DESCRIPTION | |
42 | The | |
43 | .BR restart_syscall () | |
44 | system call is used to restart certain system calls | |
45 | after a process that was stopped by a signal (e.g., | |
46 | .BR SIGSTOP | |
47 | or | |
48 | .BR SIGTSTP ) | |
49 | is later resumed after receiving a | |
50 | .BR SIGCONT | |
51 | signal. | |
52 | This system call is designed only for internal use by the kernel. | |
efeece04 | 53 | .PP |
92f30072 MK |
54 | .BR restart_syscall () |
55 | is used for restarting only those system calls that, | |
56 | when restarted, should adjust their time-related parameters\(emnamely | |
57 | .BR poll (2) | |
58 | (since Linux 2.6.24), | |
59 | .BR nanosleep (2) | |
60 | (since Linux 2.6), | |
61 | .BR clock_nanosleep (2) | |
62 | (since Linux 2.6), | |
63 | and | |
64 | .BR futex (2), | |
65 | when employed with the | |
66 | .BR FUTEX_WAIT | |
67 | (since Linux 2.6.22) | |
68 | and | |
69 | .BR FUTEX_WAIT_BITSET | |
70 | (since Linux 2.6.31) | |
71 | operations. | |
72 | .\" These system calls correspond to the special internal errno value | |
73 | .\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart" | |
74 | .\" helper function that is invoked by restart_syscall(). | |
d7f14b33 MK |
75 | .\" Notable (as at Linux 3.17) is that poll() has such a "restart" |
76 | .\" function, but ppoll(), select(), and pselect() do not. | |
77 | .\" This means that the latter system calls do not take account of the | |
78 | .\" time spent in the stopped state when restarting. | |
92f30072 MK |
79 | .BR restart_syscall () |
80 | restarts the interrupted system call with a | |
81 | time argument that is suitably adjusted to account for the | |
82 | time that has already elapsed (including the time where the process | |
83 | was stopped by a signal). | |
84 | Without the | |
85 | .BR restart_syscall () | |
5a3a8699 | 86 | mechanism, restarting these system calls would not correctly deduct the |
92f30072 MK |
87 | already elapsed time when the process continued execution. |
88 | .SH RETURN VALUE | |
89 | The return value of | |
90 | .BR restart_syscall () | |
91 | is the return value of whatever system call is being restarted. | |
92 | .SH ERRORS | |
93 | .I errno | |
94 | is set as per the errors for whatever system call is being restarted by | |
95 | .BR restart_syscall (). | |
96 | .SH VERSIONS | |
97 | The | |
98 | .BR restart_syscall () | |
99 | system call is present since Linux 2.6. | |
100 | .SH CONFORMING TO | |
76c637e1 | 101 | This system call is Linux-specific. |
92f30072 MK |
102 | .SH NOTES |
103 | There is no glibc wrapper for this system call, | |
104 | because it is intended for use only by the kernel and | |
105 | should never be called by applications. | |
efeece04 | 106 | .PP |
3026ef70 MK |
107 | The kernel uses |
108 | .BR restart_syscall () | |
109 | to ensure that when a system call is restarted | |
110 | after a process has been stopped by a signal and then resumed by | |
111 | .BR SIGCONT , | |
112 | then the time that the process spent in the stopped state is counted | |
113 | against the timeout interval specified in the original system call. | |
114 | In the case of system calls that take a timeout argument and | |
115 | automatically restart after a stop signal plus | |
116 | .BR SIGCONT , | |
117 | but which do not have the | |
bf7bc8b8 | 118 | .BR restart_syscall () |
3026ef70 MK |
119 | mechanism built in, then, after the process resumes execution, |
120 | the time that the process spent in the stop state is | |
121 | .I not | |
122 | counted against the timeout value. | |
123 | Notable examples of system calls that suffer this problem are | |
124 | .BR ppoll (2), | |
125 | .BR select (2), | |
126 | and | |
127 | .BR pselect (2). | |
efeece04 | 128 | .PP |
92f30072 | 129 | From user space, the operation of |
97c0185b | 130 | .BR restart_syscall () |
92f30072 MK |
131 | is largely invisible: |
132 | to the process that made the system call that is restarted, | |
133 | it appears as though that system call executed and | |
134 | returned in the usual fashion. | |
92f30072 | 135 | .SH SEE ALSO |
92f30072 | 136 | .BR sigaction (2), |
0ec954ee | 137 | .BR sigreturn (2), |
92f30072 | 138 | .BR signal (7) |
795b8267 MK |
139 | .\" FIXME . ppoll(2), select(2), and pselect(2) |
140 | .\" should probably get the restart_syscall() treatment: | |
92f30072 MK |
141 | .\" If a select() call is suspended by stop-sig+SIGCONT, the time |
142 | .\" spent suspended is *not* deducted when the select() is restarted. | |
bea08fec | 143 | .\" FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly. |