man2/restart_syscall.2

   1 .\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803
   6 .\" From: Linus Torvalds <torvalds <at> transmeta.com>
   7 .\" Subject: Re: [PATCH] compatibility syscall layer (lets try again)
   8 .\" Newsgroups: gmane.linux.kernel
   9 .\" Date: 2002-12-05 02:51:12 GMT
  10 .\"
  11 .\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition
  12 .\"
  13 .TH RESTART_SYSCALL 2 2021-03-22 "Linux man-pages (unreleased)"
  14 .SH NAME
  15 restart_syscall \- restart a system call after interruption by a stop signal
  16 .SH SYNOPSIS
  17 .nf
  18 .B long restart_syscall(void);
  19 .fi
  20 .PP
  21 .IR Note :
  22 There is no glibc wrapper for this system call; see NOTES.
  23 .SH DESCRIPTION
  24 The
  25 .BR restart_syscall ()
  26 system call is used to restart certain system calls
  27 after a process that was stopped by a signal (e.g.,
  28 .B SIGSTOP
  29 or
  30 .BR SIGTSTP )
  31 is later resumed after receiving a
  32 .B SIGCONT
  33 signal.
  34 This system call is designed only for internal use by the kernel.
  35 .PP
  36 .BR restart_syscall ()
  37 is used for restarting only those system calls that,
  38 when restarted, should adjust their time-related parameters\(emnamely
  39 .BR poll (2)
  40 (since Linux 2.6.24),
  41 .BR nanosleep (2)
  42 (since Linux 2.6),
  43 .BR clock_nanosleep (2)
  44 (since Linux 2.6),
  45 and
  46 .BR futex (2),
  47 when employed with the
  48 .B FUTEX_WAIT
  49 (since Linux 2.6.22)
  50 and
  51 .B FUTEX_WAIT_BITSET
  52 (since Linux 2.6.31)
  53 operations.
  54 .\" These system calls correspond to the special internal errno value
  55 .\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart"
  56 .\" helper function that is invoked by restart_syscall().
  57 .\" Notable (as at Linux 3.17) is that poll() has such a "restart"
  58 .\" function, but ppoll(), select(), and pselect() do not.
  59 .\" This means that the latter system calls do not take account of the
  60 .\" time spent in the stopped state when restarting.
  61 .BR restart_syscall ()
  62 restarts the interrupted system call with a
  63 time argument that is suitably adjusted to account for the
  64 time that has already elapsed (including the time where the process
  65 was stopped by a signal).
  66 Without the
  67 .BR restart_syscall ()
  68 mechanism, restarting these system calls would not correctly deduct the
  69 already elapsed time when the process continued execution.
  70 .SH RETURN VALUE
  71 The return value of
  72 .BR restart_syscall ()
  73 is the return value of whatever system call is being restarted.
  74 .SH ERRORS
  75 .I errno
  76 is set as per the errors for whatever system call is being restarted by
  77 .BR restart_syscall ().
  78 .SH VERSIONS
  79 The
  80 .BR restart_syscall ()
  81 system call is present since Linux 2.6.
  82 .SH STANDARDS
  83 This system call is Linux-specific.
  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 .PP
  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 .PP
 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.