1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2015-02-04 23:33+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man3/bsd_signal.3:25
26 #: build/C/man3/bsd_signal.3:25
32 #: build/C/man3/bsd_signal.3:25 build/C/man2/eventfd.2:22 build/C/man2/getitimer.2:12 build/C/man3/gsignal.3:27 build/C/man2/kill.2:44 build/C/man2/killpg.2:42 build/C/man2/pause.2:30 build/C/man2/prctl.2:54 build/C/man3/profil.3:28 build/C/man3/psignal.3:30 build/C/man3/raise.3:29 build/C/man2/restart_syscall.2:33 build/C/man2/rt_sigqueueinfo.2:25 build/C/man2/s390_runtime_instr.2:25 build/C/man2/sgetmask.2:26 build/C/man2/sigaction.2:49 build/C/man2/sigaltstack.2:27 build/C/man7/sigevent.7:26 build/C/man3/siginterrupt.3:31 build/C/man2/signal.2:36 build/C/man7/signal.7:46 build/C/man2/signalfd.2:20 build/C/man3/sigpause.3:25 build/C/man2/sigpending.2:29 build/C/man2/sigprocmask.2:29 build/C/man3/sigqueue.3:28 build/C/man2/sigreturn.2:30 build/C/man3/sigset.3:26 build/C/man3/sigsetops.3:31 build/C/man2/sigsuspend.2:29 build/C/man3/sigvec.3:26 build/C/man3/sigwait.3:26 build/C/man2/sigwaitinfo.2:25 build/C/man3/sysv_signal.3:25 build/C/man2/timer_create.2:33 build/C/man2/timer_delete.2:26 build/C/man2/timer_getoverrun.2:26 build/C/man2/timer_settime.2:26 build/C/man2/timerfd_create.2:22 build/C/man2/tkill.2:29 build/C/man2/wait.2:49 build/C/man2/wait4.2:33
34 msgid "Linux Programmer's Manual"
38 #: build/C/man3/bsd_signal.3:26 build/C/man2/eventfd.2:23 build/C/man2/getitimer.2:13 build/C/man3/gsignal.3:28 build/C/man2/kill.2:45 build/C/man2/killpg.2:43 build/C/man2/pause.2:31 build/C/man2/prctl.2:55 build/C/man3/profil.3:29 build/C/man3/psignal.3:31 build/C/man3/raise.3:30 build/C/man2/restart_syscall.2:34 build/C/man2/rt_sigqueueinfo.2:26 build/C/man2/s390_runtime_instr.2:26 build/C/man2/sgetmask.2:27 build/C/man2/sigaction.2:50 build/C/man2/sigaltstack.2:28 build/C/man7/sigevent.7:27 build/C/man3/siginterrupt.3:32 build/C/man2/signal.2:37 build/C/man7/signal.7:47 build/C/man2/signalfd.2:21 build/C/man3/sigpause.3:26 build/C/man2/sigpending.2:30 build/C/man2/sigprocmask.2:30 build/C/man3/sigqueue.3:29 build/C/man2/sigreturn.2:31 build/C/man3/sigset.3:27 build/C/man3/sigsetops.3:32 build/C/man2/sigsuspend.2:30 build/C/man3/sigvec.3:27 build/C/man3/sigwait.3:27 build/C/man2/sigwaitinfo.2:26 build/C/man3/sysv_signal.3:26 build/C/man2/timer_create.2:34 build/C/man2/timer_delete.2:27 build/C/man2/timer_getoverrun.2:27 build/C/man2/timer_settime.2:27 build/C/man2/timerfd_create.2:23 build/C/man2/tkill.2:30 build/C/man2/wait.2:50 build/C/man2/wait4.2:34
44 #: build/C/man3/bsd_signal.3:28
45 msgid "bsd_signal - signal handling with BSD semantics"
49 #: build/C/man3/bsd_signal.3:28 build/C/man2/eventfd.2:25 build/C/man2/getitimer.2:15 build/C/man3/gsignal.3:30 build/C/man2/kill.2:47 build/C/man2/killpg.2:45 build/C/man2/pause.2:33 build/C/man2/prctl.2:57 build/C/man3/profil.3:31 build/C/man3/psignal.3:33 build/C/man3/raise.3:32 build/C/man2/restart_syscall.2:36 build/C/man2/rt_sigqueueinfo.2:28 build/C/man2/s390_runtime_instr.2:28 build/C/man2/sgetmask.2:29 build/C/man2/sigaction.2:52 build/C/man2/sigaltstack.2:30 build/C/man7/sigevent.7:29 build/C/man3/siginterrupt.3:34 build/C/man2/signal.2:39 build/C/man2/signalfd.2:23 build/C/man3/sigpause.3:28 build/C/man2/sigpending.2:32 build/C/man2/sigprocmask.2:32 build/C/man3/sigqueue.3:31 build/C/man2/sigreturn.2:33 build/C/man3/sigset.3:29 build/C/man3/sigsetops.3:35 build/C/man2/sigsuspend.2:32 build/C/man3/sigvec.3:29 build/C/man3/sigwait.3:29 build/C/man2/sigwaitinfo.2:28 build/C/man3/sysv_signal.3:28 build/C/man2/timer_create.2:36 build/C/man2/timer_delete.2:29 build/C/man2/timer_getoverrun.2:29 build/C/man2/timer_settime.2:30 build/C/man2/timerfd_create.2:26 build/C/man2/tkill.2:32 build/C/man2/wait.2:52 build/C/man2/wait4.2:36
55 #: build/C/man3/bsd_signal.3:30
56 msgid "B<#define _XOPEN_SOURCE> /* See feature_test_macros(7) */"
60 #: build/C/man3/bsd_signal.3:32 build/C/man2/killpg.2:47 build/C/man2/sigaltstack.2:32 build/C/man2/signal.2:41 build/C/man2/sigpending.2:34 build/C/man2/sigprocmask.2:34 build/C/man3/sigqueue.3:33 build/C/man3/sigset.3:31 build/C/man3/sigsetops.3:37 build/C/man2/sigsuspend.2:34 build/C/man3/sigvec.3:31 build/C/man3/sysv_signal.3:32
61 msgid "B<#include E<lt>signal.hE<gt>>"
65 #: build/C/man3/bsd_signal.3:34 build/C/man2/signal.2:43 build/C/man3/sigset.3:33 build/C/man3/sysv_signal.3:34
66 msgid "B<typedef void (*sighandler_t)(int);>"
70 #: build/C/man3/bsd_signal.3:36
71 msgid "B<sighandler_t bsd_signal(int >I<signum>B<, sighandler_t >I<handler>B<);>"
75 #: build/C/man3/bsd_signal.3:36 build/C/man2/eventfd.2:29 build/C/man2/getitimer.2:24 build/C/man3/gsignal.3:49 build/C/man2/kill.2:65 build/C/man2/killpg.2:60 build/C/man2/pause.2:37 build/C/man2/prctl.2:64 build/C/man3/profil.3:46 build/C/man3/psignal.3:56 build/C/man3/raise.3:38 build/C/man2/restart_syscall.2:41 build/C/man2/rt_sigqueueinfo.2:38 build/C/man2/s390_runtime_instr.2:34 build/C/man2/sgetmask.2:36 build/C/man2/sigaction.2:72 build/C/man2/sigaltstack.2:51 build/C/man7/sigevent.7:52 build/C/man3/siginterrupt.3:55 build/C/man2/signal.2:45 build/C/man7/signal.7:49 build/C/man2/signalfd.2:27 build/C/man3/sigpause.3:36 build/C/man2/sigpending.2:46 build/C/man2/sigprocmask.2:47 build/C/man3/sigqueue.3:43 build/C/man2/sigreturn.2:35 build/C/man3/sigset.3:58 build/C/man3/sigsetops.3:63 build/C/man2/sigsuspend.2:46 build/C/man3/sigvec.3:49 build/C/man3/sigwait.3:45 build/C/man2/sigwaitinfo.2:46 build/C/man3/sysv_signal.3:36 build/C/man2/timer_create.2:54 build/C/man2/timer_delete.2:45 build/C/man2/timer_getoverrun.2:45 build/C/man2/timer_settime.2:50 build/C/man2/timerfd_create.2:38 build/C/man2/tkill.2:41 build/C/man2/wait.2:83 build/C/man2/wait4.2:67
81 #: build/C/man3/bsd_signal.3:41
83 "The B<bsd_signal>() function takes the same arguments, and performs the "
84 "same task, as B<signal>(2)."
88 #: build/C/man3/bsd_signal.3:54
90 "The difference between the two is that B<bsd_signal>() is guaranteed to "
91 "provide reliable signal semantics, that is: a) the disposition of the signal "
92 "is not reset to the default when the handler is invoked; b) delivery of "
93 "further instances of the signal is blocked while the signal handler is "
94 "executing; and c) if the handler interrupts a blocking system call, then the "
95 "system call is automatically restarted. A portable application cannot rely "
96 "on B<signal>(2) to provide these guarantees."
100 #: build/C/man3/bsd_signal.3:54 build/C/man2/eventfd.2:222 build/C/man2/getitimer.2:129 build/C/man2/kill.2:100 build/C/man2/killpg.2:89 build/C/man2/pause.2:42 build/C/man2/prctl.2:892 build/C/man3/profil.3:68 build/C/man3/psignal.3:89 build/C/man3/raise.3:61 build/C/man2/restart_syscall.2:88 build/C/man2/rt_sigqueueinfo.2:129 build/C/man2/s390_runtime_instr.2:54 build/C/man2/sgetmask.2:59 build/C/man2/sigaction.2:728 build/C/man2/sigaltstack.2:133 build/C/man3/siginterrupt.3:73 build/C/man2/signal.2:97 build/C/man2/signalfd.2:251 build/C/man3/sigpause.3:48 build/C/man2/sigpending.2:53 build/C/man2/sigprocmask.2:93 build/C/man3/sigqueue.3:83 build/C/man2/sigreturn.2:65 build/C/man3/sigset.3:129 build/C/man3/sigsetops.3:107 build/C/man2/sigsuspend.2:70 build/C/man3/sigvec.3:199 build/C/man3/sigwait.3:69 build/C/man2/sigwaitinfo.2:105 build/C/man3/sysv_signal.3:51 build/C/man2/timer_create.2:169 build/C/man2/timer_delete.2:53 build/C/man2/timer_getoverrun.2:82 build/C/man2/timer_settime.2:173 build/C/man2/timerfd_create.2:294 build/C/man2/tkill.2:88 build/C/man2/wait.2:355 build/C/man2/wait4.2:132
106 #: build/C/man3/bsd_signal.3:60
108 "The B<bsd_signal>() function returns the previous value of the signal "
109 "handler, or B<SIG_ERR> on error."
113 #: build/C/man3/bsd_signal.3:60 build/C/man2/eventfd.2:229 build/C/man2/getitimer.2:134 build/C/man2/kill.2:105 build/C/man2/killpg.2:94 build/C/man2/pause.2:53 build/C/man2/prctl.2:912 build/C/man2/restart_syscall.2:92 build/C/man2/rt_sigqueueinfo.2:134 build/C/man2/s390_runtime_instr.2:65 build/C/man2/sgetmask.2:64 build/C/man2/sigaction.2:733 build/C/man2/sigaltstack.2:137 build/C/man3/siginterrupt.3:83 build/C/man2/signal.2:105 build/C/man2/signalfd.2:265 build/C/man2/sigpending.2:59 build/C/man2/sigprocmask.2:99 build/C/man3/sigqueue.3:91 build/C/man3/sigset.3:154 build/C/man3/sigsetops.3:127 build/C/man2/sigsuspend.2:76 build/C/man3/sigvec.3:216 build/C/man3/sigwait.3:74 build/C/man2/sigwaitinfo.2:114 build/C/man3/sysv_signal.3:57 build/C/man2/timer_create.2:177 build/C/man2/timer_delete.2:60 build/C/man2/timer_getoverrun.2:90 build/C/man2/timer_settime.2:182 build/C/man2/timerfd_create.2:309 build/C/man2/tkill.2:92 build/C/man2/wait.2:385 build/C/man2/wait4.2:135
119 #: build/C/man3/bsd_signal.3:63 build/C/man3/sysv_signal.3:60
120 msgid "As for B<signal>(2)."
124 #: build/C/man3/bsd_signal.3:63 build/C/man3/raise.3:64 build/C/man3/siginterrupt.3:87 build/C/man3/sigpause.3:56 build/C/man3/sigqueue.3:114 build/C/man3/sigsetops.3:132 build/C/man3/sigvec.3:221 build/C/man3/sigwait.3:80 build/C/man3/sysv_signal.3:60
130 #: build/C/man3/bsd_signal.3:64 build/C/man3/raise.3:65 build/C/man3/siginterrupt.3:88 build/C/man3/sigpause.3:57 build/C/man3/sigqueue.3:115 build/C/man3/sigsetops.3:133 build/C/man3/sigvec.3:222 build/C/man3/sigwait.3:81 build/C/man3/sysv_signal.3:61
132 msgid "Multithreading (see pthreads(7))"
136 #: build/C/man3/bsd_signal.3:68
137 msgid "The B<bsd_signal>() function is thread-safe."
141 #: build/C/man3/bsd_signal.3:68 build/C/man2/eventfd.2:266 build/C/man2/getitimer.2:155 build/C/man3/gsignal.3:95 build/C/man2/kill.2:121 build/C/man2/killpg.2:111 build/C/man2/pause.2:57 build/C/man2/prctl.2:1190 build/C/man3/profil.3:70 build/C/man3/psignal.3:99 build/C/man3/raise.3:69 build/C/man2/restart_syscall.2:100 build/C/man2/rt_sigqueueinfo.2:176 build/C/man2/s390_runtime_instr.2:81 build/C/man2/sgetmask.2:73 build/C/man2/sigaction.2:745 build/C/man2/sigaltstack.2:158 build/C/man7/sigevent.7:130 build/C/man3/siginterrupt.3:93 build/C/man2/signal.2:110 build/C/man7/signal.7:878 build/C/man2/signalfd.2:307 build/C/man3/sigpause.3:61 build/C/man2/sigpending.2:64 build/C/man2/sigprocmask.2:112 build/C/man3/sigqueue.3:119 build/C/man2/sigreturn.2:68 build/C/man3/sigset.3:173 build/C/man3/sigsetops.3:145 build/C/man2/sigsuspend.2:84 build/C/man3/sigvec.3:241 build/C/man3/sigwait.3:85 build/C/man2/sigwaitinfo.2:133 build/C/man3/sysv_signal.3:65 build/C/man2/timer_create.2:195 build/C/man2/timer_delete.2:67 build/C/man2/timer_getoverrun.2:97 build/C/man2/timer_settime.2:207 build/C/man2/timerfd_create.2:378 build/C/man2/tkill.2:109 build/C/man2/wait.2:423 build/C/man2/wait4.2:138
143 msgid "CONFORMING TO"
147 #: build/C/man3/bsd_signal.3:75
149 "4.2BSD, POSIX.1-2001. POSIX.1-2008 removes the specification of "
150 "B<bsd_signal>(), recommending the use of B<sigaction>(2) instead."
154 #: build/C/man3/bsd_signal.3:75 build/C/man2/eventfd.2:271 build/C/man2/getitimer.2:165 build/C/man2/kill.2:123 build/C/man2/killpg.2:115 build/C/man3/raise.3:71 build/C/man2/restart_syscall.2:102 build/C/man2/rt_sigqueueinfo.2:178 build/C/man2/s390_runtime_instr.2:84 build/C/man2/sgetmask.2:75 build/C/man2/sigaction.2:748 build/C/man2/sigaltstack.2:160 build/C/man2/signal.2:112 build/C/man2/signalfd.2:312 build/C/man3/sigpause.3:65 build/C/man2/sigpending.2:66 build/C/man2/sigprocmask.2:114 build/C/man3/sigqueue.3:121 build/C/man2/sigreturn.2:74 build/C/man3/sigset.3:190 build/C/man3/sigsetops.3:147 build/C/man2/sigsuspend.2:86 build/C/man3/sigvec.3:247 build/C/man3/sigwait.3:87 build/C/man2/sigwaitinfo.2:135 build/C/man3/sysv_signal.3:67 build/C/man2/timer_create.2:197 build/C/man2/timer_getoverrun.2:99 build/C/man2/tkill.2:115 build/C/man2/wait.2:425 build/C/man2/wait4.2:147
160 #: build/C/man3/bsd_signal.3:81
161 msgid "Use of B<bsd_signal>() should be avoided; use B<sigaction>(2) instead."
165 #: build/C/man3/bsd_signal.3:92
167 "On modern Linux systems, B<bsd_signal>() and B<signal>(2) are equivalent. "
168 "But on older systems, B<signal>(2) provided unreliable signal semantics; "
169 "see B<signal>(2) for details."
173 #: build/C/man3/bsd_signal.3:99 build/C/man3/sysv_signal.3:92
175 "The use of I<sighandler_t> is a GNU extension; this type is defined only if "
176 "the B<_GNU_SOURCE> feature test macro is defined."
180 #: build/C/man3/bsd_signal.3:99 build/C/man2/eventfd.2:417 build/C/man2/getitimer.2:246 build/C/man3/gsignal.3:103 build/C/man2/kill.2:171 build/C/man2/killpg.2:134 build/C/man2/pause.2:59 build/C/man2/prctl.2:1204 build/C/man3/profil.3:81 build/C/man3/psignal.3:113 build/C/man3/raise.3:82 build/C/man2/restart_syscall.2:135 build/C/man2/rt_sigqueueinfo.2:188 build/C/man2/s390_runtime_instr.2:88 build/C/man2/sgetmask.2:89 build/C/man2/sigaction.2:861 build/C/man2/sigaltstack.2:234 build/C/man7/sigevent.7:132 build/C/man3/siginterrupt.3:102 build/C/man2/signal.2:278 build/C/man7/signal.7:890 build/C/man2/signalfd.2:433 build/C/man3/sigpause.3:111 build/C/man2/sigpending.2:91 build/C/man2/sigprocmask.2:144 build/C/man3/sigqueue.3:154 build/C/man2/sigreturn.2:123 build/C/man3/sigset.3:266 build/C/man3/sigsetops.3:186 build/C/man2/sigsuspend.2:108 build/C/man3/sigvec.3:272 build/C/man3/sigwait.3:94 build/C/man2/sigwaitinfo.2:201 build/C/man3/sysv_signal.3:92 build/C/man2/timer_create.2:410 build/C/man2/timer_delete.2:69 build/C/man2/timer_getoverrun.2:131 build/C/man2/timer_settime.2:212 build/C/man2/timerfd_create.2:548 build/C/man2/tkill.2:124 build/C/man2/wait.2:635 build/C/man2/wait4.2:165
186 #: build/C/man3/bsd_signal.3:104
187 msgid "B<sigaction>(2), B<signal>(2), B<sysv_signal>(3), B<signal>(7)"
191 #: build/C/man3/bsd_signal.3:104 build/C/man2/eventfd.2:428 build/C/man2/getitimer.2:253 build/C/man3/gsignal.3:107 build/C/man2/kill.2:181 build/C/man2/killpg.2:140 build/C/man2/pause.2:64 build/C/man2/prctl.2:1207 build/C/man3/profil.3:87 build/C/man3/psignal.3:118 build/C/man3/raise.3:89 build/C/man2/restart_syscall.2:144 build/C/man2/rt_sigqueueinfo.2:196 build/C/man2/s390_runtime_instr.2:91 build/C/man2/sgetmask.2:92 build/C/man2/sigaction.2:883 build/C/man2/sigaltstack.2:241 build/C/man7/sigevent.7:142 build/C/man3/siginterrupt.3:104 build/C/man2/signal.2:297 build/C/man7/signal.7:925 build/C/man2/signalfd.2:446 build/C/man3/sigpause.3:119 build/C/man2/sigpending.2:99 build/C/man2/sigprocmask.2:155 build/C/man3/sigqueue.3:162 build/C/man2/sigreturn.2:130 build/C/man3/sigset.3:276 build/C/man3/sigsetops.3:191 build/C/man2/sigsuspend.2:118 build/C/man3/sigvec.3:282 build/C/man3/sigwait.3:102 build/C/man2/sigwaitinfo.2:213 build/C/man3/sysv_signal.3:97 build/C/man2/timer_create.2:425 build/C/man2/timer_delete.2:75 build/C/man2/timer_getoverrun.2:141 build/C/man2/timer_settime.2:216 build/C/man2/timerfd_create.2:560 build/C/man2/tkill.2:129 build/C/man2/wait.2:647 build/C/man2/wait4.2:172
197 #: build/C/man3/bsd_signal.3:112 build/C/man2/eventfd.2:436 build/C/man2/getitimer.2:261 build/C/man3/gsignal.3:115 build/C/man2/kill.2:189 build/C/man2/killpg.2:148 build/C/man2/pause.2:72 build/C/man2/prctl.2:1215 build/C/man3/profil.3:95 build/C/man3/psignal.3:126 build/C/man3/raise.3:97 build/C/man2/restart_syscall.2:152 build/C/man2/rt_sigqueueinfo.2:204 build/C/man2/s390_runtime_instr.2:99 build/C/man2/sgetmask.2:100 build/C/man2/sigaction.2:891 build/C/man2/sigaltstack.2:249 build/C/man7/sigevent.7:150 build/C/man3/siginterrupt.3:112 build/C/man2/signal.2:305 build/C/man7/signal.7:933 build/C/man2/signalfd.2:454 build/C/man3/sigpause.3:127 build/C/man2/sigpending.2:107 build/C/man2/sigprocmask.2:163 build/C/man3/sigqueue.3:170 build/C/man2/sigreturn.2:138 build/C/man3/sigset.3:284 build/C/man3/sigsetops.3:199 build/C/man2/sigsuspend.2:126 build/C/man3/sigvec.3:290 build/C/man3/sigwait.3:110 build/C/man2/sigwaitinfo.2:221 build/C/man3/sysv_signal.3:105 build/C/man2/timer_create.2:433 build/C/man2/timer_delete.2:83 build/C/man2/timer_getoverrun.2:149 build/C/man2/timer_settime.2:224 build/C/man2/timerfd_create.2:568 build/C/man2/tkill.2:137 build/C/man2/wait.2:655 build/C/man2/wait4.2:180
199 "This page is part of release 3.79 of the Linux I<man-pages> project. A "
200 "description of the project, information about reporting bugs, and the latest "
201 "version of this page, can be found at "
202 "\\%http://www.kernel.org/doc/man-pages/."
206 #: build/C/man2/eventfd.2:22
212 #: build/C/man2/eventfd.2:22 build/C/man2/getitimer.2:12 build/C/man3/profil.3:28 build/C/man2/signalfd.2:20
218 #: build/C/man2/eventfd.2:22 build/C/man2/getitimer.2:12 build/C/man2/kill.2:44 build/C/man2/killpg.2:42 build/C/man2/pause.2:30 build/C/man2/prctl.2:54 build/C/man3/profil.3:28 build/C/man2/restart_syscall.2:33 build/C/man2/rt_sigqueueinfo.2:25 build/C/man2/sgetmask.2:26 build/C/man2/sigaction.2:49 build/C/man2/sigaltstack.2:27 build/C/man2/signal.2:36 build/C/man7/signal.7:46 build/C/man2/signalfd.2:20 build/C/man3/sigpause.3:25 build/C/man2/sigpending.2:29 build/C/man2/sigprocmask.2:29 build/C/man3/sigqueue.3:28 build/C/man2/sigreturn.2:30 build/C/man3/sigset.3:26 build/C/man3/sigsetops.3:31 build/C/man2/sigsuspend.2:29 build/C/man3/sigvec.3:26 build/C/man3/sigwait.3:26 build/C/man2/sigwaitinfo.2:25 build/C/man2/timer_create.2:33 build/C/man2/timer_delete.2:26 build/C/man2/timer_getoverrun.2:26 build/C/man2/timer_settime.2:26 build/C/man2/timerfd_create.2:22 build/C/man2/tkill.2:29 build/C/man2/wait.2:49 build/C/man2/wait4.2:33
224 #: build/C/man2/eventfd.2:25
225 msgid "eventfd - create a file descriptor for event notification"
229 #: build/C/man2/eventfd.2:27
230 msgid "B<#include E<lt>sys/eventfd.hE<gt>>"
234 #: build/C/man2/eventfd.2:29
235 msgid "B<int eventfd(unsigned int >I<initval>B<, int >I<flags>B<);>"
239 #: build/C/man2/eventfd.2:39
241 "B<eventfd>() creates an \"eventfd object\" that can be used as an event "
242 "wait/notify mechanism by user-space applications, and by the kernel to "
243 "notify user-space applications of events. The object contains an unsigned "
244 "64-bit integer (I<uint64_t>) counter that is maintained by the kernel. "
245 "This counter is initialized with the value specified in the argument "
250 #: build/C/man2/eventfd.2:44
252 "The following values may be bitwise ORed in I<flags> to change the behavior "
257 #: build/C/man2/eventfd.2:44
259 msgid "B<EFD_CLOEXEC> (since Linux 2.6.27)"
263 #: build/C/man2/eventfd.2:54 build/C/man2/signalfd.2:95 build/C/man2/timerfd_create.2:110
265 "Set the close-on-exec (B<FD_CLOEXEC>) flag on the new file descriptor. See "
266 "the description of the B<O_CLOEXEC> flag in B<open>(2) for reasons why this "
271 #: build/C/man2/eventfd.2:54
273 msgid "B<EFD_NONBLOCK> (since Linux 2.6.27)"
277 #: build/C/man2/eventfd.2:62 build/C/man2/signalfd.2:85 build/C/man2/timerfd_create.2:100
279 "Set the B<O_NONBLOCK> file status flag on the new open file description. "
280 "Using this flag saves extra calls to B<fcntl>(2) to achieve the same "
285 #: build/C/man2/eventfd.2:62
287 msgid "B<EFD_SEMAPHORE> (since Linux 2.6.30)"
291 #: build/C/man2/eventfd.2:66
293 "Provide semaphore-like semantics for reads from the new file descriptor. "
298 #: build/C/man2/eventfd.2:70 build/C/man2/signalfd.2:99
300 "In Linux up to version 2.6.26, the I<flags> argument is unused, and must be "
305 #: build/C/man2/eventfd.2:76
307 "As its return value, B<eventfd>() returns a new file descriptor that can be "
308 "used to refer to the eventfd object. The following operations can be "
309 "performed on the file descriptor:"
313 #: build/C/man2/eventfd.2:76 build/C/man2/signalfd.2:102 build/C/man2/timerfd_create.2:218
319 #: build/C/man2/eventfd.2:86
321 "Each successful B<read>(2) returns an 8-byte integer. A B<read>(2) will "
322 "fail with the error B<EINVAL> if the size of the supplied buffer is less "
327 #: build/C/man2/eventfd.2:91
329 "The value returned by B<read>(2) is in host byte order\\(emthat is, the "
330 "native byte order for integers on the host machine."
334 #: build/C/man2/eventfd.2:98
336 "The semantics of B<read>(2) depend on whether the eventfd counter currently "
337 "has a nonzero value and whether the B<EFD_SEMAPHORE> flag was specified when "
338 "creating the eventfd file descriptor:"
342 #: build/C/man2/eventfd.2:99 build/C/man2/eventfd.2:106 build/C/man2/eventfd.2:113 build/C/man2/eventfd.2:158 build/C/man2/eventfd.2:168 build/C/man2/eventfd.2:178 build/C/man2/prctl.2:978 build/C/man2/prctl.2:983 build/C/man2/prctl.2:988 build/C/man2/prctl.2:998 build/C/man3/psignal.3:105 build/C/man3/psignal.3:109 build/C/man2/sigaction.2:318 build/C/man2/sigaction.2:333 build/C/man2/sigaction.2:349 build/C/man2/sigaction.2:364 build/C/man2/sigaction.2:411 build/C/man2/sigaction.2:458 build/C/man2/sigaction.2:472 build/C/man2/signal.2:68 build/C/man2/signal.2:73 build/C/man2/signal.2:80 build/C/man2/signal.2:224 build/C/man2/signal.2:228 build/C/man2/signal.2:244 build/C/man7/signal.7:149 build/C/man7/signal.7:157 build/C/man7/signal.7:615 build/C/man7/signal.7:617 build/C/man7/signal.7:638 build/C/man7/signal.7:672 build/C/man7/signal.7:676 build/C/man7/signal.7:683 build/C/man7/signal.7:701 build/C/man7/signal.7:711 build/C/man7/signal.7:718 build/C/man7/signal.7:723 build/C/man7/signal.7:725 build/C/man7/signal.7:729 build/C/man7/signal.7:748 build/C/man7/signal.7:762 build/C/man7/signal.7:773 build/C/man7/signal.7:780 build/C/man7/signal.7:789 build/C/man7/signal.7:797 build/C/man7/signal.7:803 build/C/man7/signal.7:823 build/C/man7/signal.7:837 build/C/man7/signal.7:848 build/C/man7/signal.7:851 build/C/man7/signal.7:854 build/C/man7/signal.7:857 build/C/man7/signal.7:864 build/C/man7/signal.7:870 build/C/man7/signal.7:874 build/C/man3/sigwait.3:62 build/C/man3/sigwait.3:67 build/C/man2/timer_create.2:218 build/C/man2/timer_create.2:221 build/C/man2/timer_create.2:224 build/C/man2/timer_create.2:228 build/C/man2/timer_create.2:231 build/C/man2/timer_create.2:246 build/C/man2/timer_create.2:250
348 #: build/C/man2/eventfd.2:106
350 "If B<EFD_SEMAPHORE> was not specified and the eventfd counter has a nonzero "
351 "value, then a B<read>(2) returns 8 bytes containing that value, and the "
352 "counter's value is reset to zero."
356 #: build/C/man2/eventfd.2:113
358 "If B<EFD_SEMAPHORE> was specified and the eventfd counter has a nonzero "
359 "value, then a B<read>(2) returns 8 bytes containing the value 1, and the "
360 "counter's value is decremented by 1."
364 #: build/C/man2/eventfd.2:123
366 "If the eventfd counter is zero at the time of the call to B<read>(2), then "
367 "the call either blocks until the counter becomes nonzero (at which time, the "
368 "B<read>(2) proceeds as described above) or fails with the error B<EAGAIN> "
369 "if the file descriptor has been made nonblocking."
373 #: build/C/man2/eventfd.2:124
379 #: build/C/man2/eventfd.2:141
381 "A B<write>(2) call adds the 8-byte integer value supplied in its buffer to "
382 "the counter. The maximum value that may be stored in the counter is the "
383 "largest unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). If the "
384 "addition would cause the counter's value to exceed the maximum, then the "
385 "B<write>(2) either blocks until a B<read>(2) is performed on the file "
386 "descriptor, or fails with the error B<EAGAIN> if the file descriptor has "
387 "been made nonblocking."
391 #: build/C/man2/eventfd.2:148
393 "A B<write>(2) will fail with the error B<EINVAL> if the size of the "
394 "supplied buffer is less than 8 bytes, or if an attempt is made to write the "
395 "value 0xffffffffffffffff."
399 #: build/C/man2/eventfd.2:148 build/C/man2/signalfd.2:140 build/C/man2/timerfd_create.2:251
401 msgid "B<poll>(2), B<select>(2) (and similar)"
405 #: build/C/man2/eventfd.2:157
407 "The returned file descriptor supports B<poll>(2) (and analogously "
408 "B<epoll>(7)) and B<select>(2), as follows:"
412 #: build/C/man2/eventfd.2:168
414 "The file descriptor is readable (the B<select>(2) I<readfds> argument; the "
415 "B<poll>(2) B<POLLIN> flag) if the counter has a value greater than 0."
419 #: build/C/man2/eventfd.2:178
421 "The file descriptor is writable (the B<select>(2) I<writefds> argument; the "
422 "B<poll>(2) B<POLLOUT> flag) if it is possible to write a value of at least "
423 "\"1\" without blocking."
427 #: build/C/man2/eventfd.2:198
429 "If an overflow of the counter value was detected, then B<select>(2) "
430 "indicates the file descriptor as being both readable and writable, and "
431 "B<poll>(2) returns a B<POLLERR> event. As noted above, B<write>(2) can "
432 "never overflow the counter. However an overflow can occur if 2^64 eventfd "
433 "\"signal posts\" were performed by the KAIO subsystem (theoretically "
434 "possible, but practically unlikely). If an overflow has occurred, then "
435 "B<read>(2) will return that maximum I<uint64_t> value (i.e., "
436 "0xffffffffffffffff)."
440 #: build/C/man2/eventfd.2:205
442 "The eventfd file descriptor also supports the other file-descriptor "
443 "multiplexing APIs: B<pselect>(2) and B<ppoll>(2)."
447 #: build/C/man2/eventfd.2:205 build/C/man2/signalfd.2:160 build/C/man2/timerfd_create.2:269
453 #: build/C/man2/eventfd.2:210
455 "When the file descriptor is no longer required it should be closed. When "
456 "all file descriptors associated with the same eventfd object have been "
457 "closed, the resources for object are freed by the kernel."
461 #: build/C/man2/eventfd.2:222
463 "A copy of the file descriptor created by B<eventfd>() is inherited by the "
464 "child produced by B<fork>(2). The duplicate file descriptor is associated "
465 "with the same eventfd object. File descriptors created by B<eventfd>() are "
466 "preserved across B<execve>(2), unless the close-on-exec flag has been set."
470 #: build/C/man2/eventfd.2:229
472 "On success, B<eventfd>() returns a new eventfd file descriptor. On error, "
473 "-1 is returned and I<errno> is set to indicate the error."
477 #: build/C/man2/eventfd.2:230 build/C/man2/getitimer.2:142 build/C/man2/kill.2:106 build/C/man2/killpg.2:95 build/C/man2/prctl.2:930 build/C/man2/prctl.2:935 build/C/man2/prctl.2:947 build/C/man2/prctl.2:952 build/C/man2/prctl.2:961 build/C/man2/prctl.2:971 build/C/man2/prctl.2:1011 build/C/man2/prctl.2:1021 build/C/man2/prctl.2:1029 build/C/man2/prctl.2:1040 build/C/man2/prctl.2:1049 build/C/man2/prctl.2:1063 build/C/man2/prctl.2:1075 build/C/man2/prctl.2:1086 build/C/man2/rt_sigqueueinfo.2:141 build/C/man2/s390_runtime_instr.2:66 build/C/man2/sigaction.2:738 build/C/man2/sigaltstack.2:142 build/C/man3/siginterrupt.3:84 build/C/man2/signal.2:106 build/C/man2/signalfd.2:271 build/C/man2/signalfd.2:279 build/C/man2/sigprocmask.2:107 build/C/man3/sigqueue.3:98 build/C/man3/sigsetops.3:128 build/C/man3/sigwait.3:75 build/C/man2/sigwaitinfo.2:129 build/C/man2/timer_create.2:181 build/C/man2/timer_delete.2:61 build/C/man2/timer_getoverrun.2:91 build/C/man2/timer_settime.2:191 build/C/man2/timer_settime.2:199 build/C/man2/timerfd_create.2:312 build/C/man2/timerfd_create.2:320 build/C/man2/timerfd_create.2:356 build/C/man2/timerfd_create.2:363 build/C/man2/timerfd_create.2:369 build/C/man2/tkill.2:93 build/C/man2/wait.2:418
483 #: build/C/man2/eventfd.2:234
484 msgid "An unsupported value was specified in I<flags>."
488 #: build/C/man2/eventfd.2:234 build/C/man2/signalfd.2:286 build/C/man2/timerfd_create.2:327
494 #: build/C/man2/eventfd.2:237
495 msgid "The per-process limit on open file descriptors has been reached."
499 #: build/C/man2/eventfd.2:237 build/C/man2/signalfd.2:289 build/C/man2/timerfd_create.2:330
505 #: build/C/man2/eventfd.2:241 build/C/man2/signalfd.2:293 build/C/man2/timerfd_create.2:334
506 msgid "The system-wide limit on the total number of open files has been reached."
510 #: build/C/man2/eventfd.2:241 build/C/man2/signalfd.2:293 build/C/man2/timerfd_create.2:334
516 #: build/C/man2/eventfd.2:249 build/C/man2/signalfd.2:296 build/C/man2/timerfd_create.2:337
517 msgid "Could not mount (internal) anonymous inode device."
521 #: build/C/man2/eventfd.2:249 build/C/man2/s390_runtime_instr.2:73 build/C/man2/sigaltstack.2:147 build/C/man2/signalfd.2:296 build/C/man2/timer_create.2:189 build/C/man2/timerfd_create.2:337
527 #: build/C/man2/eventfd.2:253
528 msgid "There was insufficient memory to create a new eventfd file descriptor."
532 #: build/C/man2/eventfd.2:253 build/C/man2/prctl.2:1185 build/C/man3/psignal.3:95 build/C/man2/restart_syscall.2:96 build/C/man2/rt_sigqueueinfo.2:169 build/C/man2/s390_runtime_instr.2:79 build/C/man2/sgetmask.2:66 build/C/man2/signalfd.2:299 build/C/man3/sigqueue.3:112 build/C/man3/sigvec.3:234 build/C/man2/timer_create.2:193 build/C/man2/timer_delete.2:65 build/C/man2/timer_getoverrun.2:95 build/C/man2/timer_settime.2:205 build/C/man2/timerfd_create.2:375 build/C/man2/tkill.2:104
537 #. eventfd() is in glibc 2.7, but reportedly does not build
539 #: build/C/man2/eventfd.2:266
541 "B<eventfd>() is available on Linux since kernel 2.6.22. Working support is "
542 "provided in glibc since version 2.8. The B<eventfd2>() system call (see "
543 "NOTES) is available on Linux since kernel 2.6.27. Since version 2.9, the "
544 "glibc B<eventfd>() wrapper will employ the B<eventfd2>() system call, if "
545 "it is supported by the kernel."
549 #: build/C/man2/eventfd.2:271
550 msgid "B<eventfd>() and B<eventfd2>() are Linux-specific."
554 #: build/C/man2/eventfd.2:279
556 "Applications can use an eventfd file descriptor instead of a pipe (see "
557 "B<pipe>(2)) in all cases where a pipe is used simply to signal events. The "
558 "kernel overhead of an eventfd file descriptor is much lower than that of a "
559 "pipe, and only one file descriptor is required (versus the two required for "
563 #. or eventually syslets/threadlets
565 #: build/C/man2/eventfd.2:285
567 "When used in the kernel, an eventfd file descriptor can provide a bridge "
568 "from kernel to user space, allowing, for example, functionalities like KAIO "
569 "(kernel AIO) to signal to a file descriptor that some operation is "
574 #: build/C/man2/eventfd.2:302
576 "A key point about an eventfd file descriptor is that it can be monitored "
577 "just like any other file descriptor using B<select>(2), B<poll>(2), or "
578 "B<epoll>(7). This means that an application can simultaneously monitor the "
579 "readiness of \"traditional\" files and the readiness of other kernel "
580 "mechanisms that support the eventfd interface. (Without the B<eventfd>() "
581 "interface, these mechanisms could not be multiplexed via B<select>(2), "
582 "B<poll>(2), or B<epoll>(7).)"
586 #: build/C/man2/eventfd.2:302 build/C/man2/signalfd.2:326 build/C/man2/sigwaitinfo.2:183 build/C/man2/timer_create.2:243 build/C/man2/wait.2:525
588 msgid "C library/kernel ABI differences"
592 #: build/C/man2/eventfd.2:316
594 "There are two underlying Linux system calls: B<eventfd>() and the more "
595 "recent B<eventfd2>(). The former system call does not implement a I<flags> "
596 "argument. The latter system call implements the I<flags> values described "
597 "above. The glibc wrapper function will use B<eventfd2>() where it is "
602 #: build/C/man2/eventfd.2:316
604 msgid "Additional glibc features"
608 #: build/C/man2/eventfd.2:320
610 "The GNU C library defines an additional type, and two functions that attempt "
611 "to abstract some of the details of reading and writing on an eventfd file "
616 #: build/C/man2/eventfd.2:324
618 msgid "typedef uint64_t eventfd_t;\n"
622 #: build/C/man2/eventfd.2:327
625 "int eventfd_read(int fd, eventfd_t *value);\n"
626 "int eventfd_write(int fd, eventfd_t value);\n"
630 #: build/C/man2/eventfd.2:334
632 "The functions perform the read and write operations on an eventfd file "
633 "descriptor, returning 0 if the correct number of bytes was transferred, or "
638 #: build/C/man2/eventfd.2:334 build/C/man2/sigaction.2:858 build/C/man2/sigaltstack.2:217 build/C/man2/signalfd.2:360 build/C/man3/sigwait.3:91 build/C/man2/timer_create.2:264 build/C/man2/timer_getoverrun.2:128 build/C/man2/timer_settime.2:209 build/C/man2/timerfd_create.2:386 build/C/man2/wait.2:552
644 #: build/C/man2/eventfd.2:343
646 "The following program creates an eventfd file descriptor and then forks to "
647 "create a child process. While the parent briefly sleeps, the child writes "
648 "each of the integers supplied in the program's command-line arguments to the "
649 "eventfd file descriptor. When the parent has finished sleeping, it reads "
650 "from the eventfd file descriptor."
654 #: build/C/man2/eventfd.2:345
655 msgid "The following shell session shows a sample run of the program:"
659 #: build/C/man2/eventfd.2:357
662 "$B< ./a.out 1 2 4 7 14>\n"
663 "Child writing 1 to efd\n"
664 "Child writing 2 to efd\n"
665 "Child writing 4 to efd\n"
666 "Child writing 7 to efd\n"
667 "Child writing 14 to efd\n"
668 "Child completed write loop\n"
669 "Parent about to read\n"
670 "Parent read 28 (0x1c) from efd\n"
674 #: build/C/man2/eventfd.2:359 build/C/man2/signalfd.2:383 build/C/man2/timer_create.2:295 build/C/man2/timerfd_create.2:414 build/C/man2/wait.2:587
676 msgid "Program source"
680 #: build/C/man2/eventfd.2:367
683 "#include E<lt>sys/eventfd.hE<gt>\n"
684 "#include E<lt>unistd.hE<gt>\n"
685 "#include E<lt>stdlib.hE<gt>\n"
686 "#include E<lt>stdio.hE<gt>\n"
687 "#include E<lt>stdint.hE<gt> /* Definition of uint64_t */\n"
691 #: build/C/man2/eventfd.2:370 build/C/man2/signalfd.2:394
694 "#define handle_error(msg) \\e\n"
695 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
699 #: build/C/man2/eventfd.2:377
703 "main(int argc, char *argv[])\n"
711 #: build/C/man2/eventfd.2:382
714 " if (argc E<lt> 2) {\n"
715 " fprintf(stderr, \"Usage: %s E<lt>numE<gt>...\\en\", argv[0]);\n"
716 " exit(EXIT_FAILURE);\n"
721 #: build/C/man2/eventfd.2:386
724 " efd = eventfd(0, 0);\n"
726 " handle_error(\"eventfd\");\n"
730 #: build/C/man2/eventfd.2:398
733 " switch (fork()) {\n"
735 " for (j = 1; j E<lt> argc; j++) {\n"
736 " printf(\"Child writing %s to efd\\en\", argv[j]);\n"
737 " u = strtoull(argv[j], NULL, 0);\n"
738 " /* strtoull() allows various bases */\n"
739 " s = write(efd, &u, sizeof(uint64_t));\n"
740 " if (s != sizeof(uint64_t))\n"
741 " handle_error(\"write\");\n"
743 " printf(\"Child completed write loop\\en\");\n"
747 #: build/C/man2/eventfd.2:400
749 msgid " exit(EXIT_SUCCESS);\n"
753 #: build/C/man2/eventfd.2:403
761 #: build/C/man2/eventfd.2:411
764 " printf(\"Parent about to read\\en\");\n"
765 " s = read(efd, &u, sizeof(uint64_t));\n"
766 " if (s != sizeof(uint64_t))\n"
767 " handle_error(\"read\");\n"
768 " printf(\"Parent read %llu (0x%llx) from efd\\en\",\n"
769 " (unsigned long long) u, (unsigned long long) u);\n"
770 " exit(EXIT_SUCCESS);\n"
774 #: build/C/man2/eventfd.2:416
778 " handle_error(\"fork\");\n"
784 #: build/C/man2/eventfd.2:428
786 "B<futex>(2), B<pipe>(2), B<poll>(2), B<read>(2), B<select>(2), "
787 "B<signalfd>(2), B<timerfd_create>(2), B<write>(2), B<epoll>(7), "
792 #: build/C/man2/getitimer.2:12
798 #: build/C/man2/getitimer.2:15
799 msgid "getitimer, setitimer - get or set value of an interval timer"
803 #: build/C/man2/getitimer.2:18
805 msgid "B<#include E<lt>sys/time.hE<gt>>\n"
809 #: build/C/man2/getitimer.2:20
811 msgid "B<int getitimer(int >I<which>B<, struct itimerval *>I<curr_value>B<);>\n"
815 #: build/C/man2/getitimer.2:23
818 "B<int setitimer(int >I<which>B<, const struct itimerval *>I<new_value>B<,>\n"
819 "B< struct itimerval *>I<old_value>B<);>\n"
823 #: build/C/man2/getitimer.2:29
825 "The system provides each process with three interval timers, each "
826 "decrementing in a distinct time domain. When a timer expires, a signal is "
827 "sent to the process, and the timer is reset to the specified interval (if "
832 #: build/C/man2/getitimer.2:29
834 msgid "B<ITIMER_REAL>"
838 #: build/C/man2/getitimer.2:34
839 msgid "decrements in real time, and delivers B<SIGALRM> upon expiration."
843 #: build/C/man2/getitimer.2:34
845 msgid "B<ITIMER_VIRTUAL>"
849 #: build/C/man2/getitimer.2:39
851 "decrements only when the process is executing, and delivers B<SIGVTALRM> "
856 #: build/C/man2/getitimer.2:39
858 msgid "B<ITIMER_PROF>"
862 #: build/C/man2/getitimer.2:49
864 "decrements both when the process executes and when the system is executing "
865 "on behalf of the process. Coupled with B<ITIMER_VIRTUAL>, this timer is "
866 "usually used to profile the time spent by the application in user and kernel "
867 "space. B<SIGPROF> is delivered upon expiration."
871 #: build/C/man2/getitimer.2:51
872 msgid "Timer values are defined by the following structures:"
876 #: build/C/man2/getitimer.2:59
879 "struct itimerval {\n"
880 " struct timeval it_interval; /* Interval for periodic timer */\n"
881 " struct timeval it_value; /* Time until next expiration */\n"
886 #: build/C/man2/getitimer.2:64
890 " time_t tv_sec; /* seconds */\n"
891 " suseconds_t tv_usec; /* microseconds */\n"
896 #: build/C/man2/getitimer.2:90
898 "The function B<getitimer>() fills the structure pointed to by I<curr_value> "
899 "with the current value (i.e., the amount of time remaining until the next "
900 "expiration) of the timer specified by I<which> (one of B<ITIMER_REAL>, "
901 "B<ITIMER_VIRTUAL>, or B<ITIMER_PROF>). The subfields of the field "
902 "I<it_value> are set to the amount of time remaining on the timer, or zero if "
903 "the timer is disabled. The I<it_interval> field is set to the timer "
904 "interval (period); a value of zero returned in (both subfields of) this "
905 "field indicates that this is a single-shot timer."
909 #: build/C/man2/getitimer.2:101
911 "The function B<setitimer>() sets the specified timer to the value in "
912 "I<new_value>. If I<old_value> is non-NULL, the old value of the timer "
913 "(i.e., the same information as returned by B<getitimer>()) is stored there."
917 #: build/C/man2/getitimer.2:111
919 "Timers decrement from I<it_value> to zero, generate a signal, and reset to "
920 "I<it_interval>. A timer which is set to zero (I<it_value> is zero or the "
921 "timer expires and I<it_interval> is zero) stops."
925 #: build/C/man2/getitimer.2:117
927 "Both I<tv_sec> and I<tv_usec> are significant in determining the duration of "
932 #: build/C/man2/getitimer.2:129
934 "Timers will never expire before the requested time, but may expire some "
935 "(short) time afterward, which depends on the system timer resolution and on "
936 "the system load; see B<time>(7). (But see BUGS below.) Upon expiration, a "
937 "signal will be generated and the timer reset. If the timer expires while "
938 "the process is active (always true for B<ITIMER_VIRTUAL>), the signal will "
939 "be delivered immediately when generated. Otherwise, the delivery will be "
940 "offset by a small time dependent on the system loading."
944 #: build/C/man2/getitimer.2:134 build/C/man2/killpg.2:94 build/C/man2/tkill.2:92
946 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
951 #: build/C/man2/getitimer.2:135 build/C/man2/prctl.2:913 build/C/man2/prctl.2:917 build/C/man2/sigaction.2:734 build/C/man2/sigaltstack.2:138 build/C/man2/sigpending.2:60 build/C/man2/sigprocmask.2:100 build/C/man2/sigsuspend.2:77 build/C/man2/timer_settime.2:184 build/C/man2/timerfd_create.2:349
957 #: build/C/man2/getitimer.2:142 build/C/man2/timerfd_create.2:356
958 msgid "I<new_value>, I<old_value>, or I<curr_value> is not valid a pointer."
962 #: build/C/man2/getitimer.2:155
964 "I<which> is not one of B<ITIMER_REAL>, B<ITIMER_VIRTUAL>, or B<ITIMER_PROF>; "
965 "or (since Linux 2.6.22) one of the I<tv_usec> fields in the structure "
966 "pointed to by I<new_value> contains a value outside the range 0 to 999999."
970 #: build/C/man2/getitimer.2:165
972 "POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). "
973 "POSIX.1-2008 marks B<getitimer>() and B<setitimer>() obsolete, "
974 "recommending the use of the POSIX timers API (B<timer_gettime>(2), "
975 "B<timer_settime>(2), etc.) instead."
979 #: build/C/man2/getitimer.2:171
981 "A child created via B<fork>(2) does not inherit its parent's interval "
982 "timers. Interval timers are preserved across an B<execve>(2)."
986 #: build/C/man2/getitimer.2:181
988 "POSIX.1 leaves the interaction between B<setitimer>() and the three "
989 "interfaces B<alarm>(2), B<sleep>(3), and B<usleep>(3) unspecified."
993 #: build/C/man2/getitimer.2:183
994 msgid "The standards are silent on the meaning of the call:"
998 #: build/C/man2/getitimer.2:185
1000 msgid " setitimer(which, NULL, &old_value);\n"
1004 #: build/C/man2/getitimer.2:188
1006 "Many systems (Solaris, the BSDs, and perhaps others) treat this as "
1011 #: build/C/man2/getitimer.2:190
1013 msgid " getitimer(which, &old_value);\n"
1017 #: build/C/man2/getitimer.2:196
1019 "In Linux, this is treated as being equivalent to a call in which the "
1020 "I<new_value> fields are zero; that is, the timer is disabled. I<Don't use "
1021 "this Linux misfeature>: it is nonportable and unnecessary."
1025 #: build/C/man2/getitimer.2:196 build/C/man2/kill.2:161 build/C/man3/profil.3:72 build/C/man3/psignal.3:101 build/C/man2/sigaction.2:849 build/C/man2/signalfd.2:352 build/C/man2/sigpending.2:85 build/C/man3/sigset.3:232 build/C/man2/timer_getoverrun.2:115 build/C/man2/timerfd_create.2:380 build/C/man2/wait.2:537
1031 #: build/C/man2/getitimer.2:205
1033 "The generation and delivery of a signal are distinct, and only one instance "
1034 "of each of the signals listed above may be pending for a process. Under "
1035 "very heavy loading, an B<ITIMER_REAL> timer may expire before the signal "
1036 "from a previous expiration has been delivered. The second signal in such an "
1037 "event will be lost."
1041 #: build/C/man2/getitimer.2:220
1043 "On Linux kernels before 2.6.16, timer values are represented in jiffies. If "
1044 "a request is made set a timer with a value whose jiffies representation "
1045 "exceeds B<MAX_SEC_IN_JIFFIES> (defined in I<include/linux/jiffies.h>), then "
1046 "the timer is silently truncated to this ceiling value. On Linux/i386 "
1047 "(where, since Linux 2.6.13, the default jiffy is 0.004 seconds), this means "
1048 "that the ceiling value for a timer is approximately 99.42 days. Since Linux "
1049 "2.6.16, the kernel uses a different internal representation for times, and "
1050 "this ceiling is removed."
1053 #. 4 Jul 2005: It looks like this bug may remain in 2.4.x.
1054 #. http://lkml.org/lkml/2005/7/1/165
1056 #: build/C/man2/getitimer.2:227
1058 "On certain systems (including i386), Linux kernels before version 2.6.12 "
1059 "have a bug which will produce premature timer expirations of up to one jiffy "
1060 "under some circumstances. This bug is fixed in kernel 2.6.12."
1063 #. Bugzilla report 25 Apr 2006:
1064 #. http://bugzilla.kernel.org/show_bug.cgi?id=6443
1065 #. "setitimer() should reject noncanonical arguments"
1067 #: build/C/man2/getitimer.2:246
1069 "POSIX.1-2001 says that B<setitimer>() should fail if a I<tv_usec> value is "
1070 "specified that is outside of the range 0 to 999999. However, in kernels up "
1071 "to and including 2.6.21, Linux does not give an error, but instead silently "
1072 "adjusts the corresponding seconds value for the timer. From kernel 2.6.22 "
1073 "onward, this nonconformance has been repaired: an improper I<tv_usec> value "
1074 "results in an B<EINVAL> error."
1078 #: build/C/man2/getitimer.2:253
1080 "B<gettimeofday>(2), B<sigaction>(2), B<signal>(2), B<timer_create>(2), "
1081 "B<timerfd_create>(2), B<time>(7)"
1085 #: build/C/man3/gsignal.3:27
1091 #: build/C/man3/gsignal.3:27
1097 #: build/C/man3/gsignal.3:30
1098 msgid "gsignal, ssignal - software signal facility"
1102 #: build/C/man3/gsignal.3:33 build/C/man2/kill.2:52 build/C/man3/psignal.3:36 build/C/man3/raise.3:35 build/C/man2/sigaction.2:55 build/C/man3/siginterrupt.3:37 build/C/man3/sigpause.3:31 build/C/man3/sigwait.3:32 build/C/man2/sigwaitinfo.2:31
1104 msgid "B<#include E<lt>signal.hE<gt>>\n"
1108 #: build/C/man3/gsignal.3:35
1110 msgid "B<typedef void (*sighandler_t)(int);>\n"
1114 #: build/C/man3/gsignal.3:37
1116 msgid "B<int gsignal(int >I<signum>B<);>\n"
1120 #: build/C/man3/gsignal.3:39
1122 msgid "B<sighandler_t ssignal(int >I<signum>B<, sighandler_t >I<action>B<);>\n"
1126 #: build/C/man3/gsignal.3:44 build/C/man2/kill.2:59 build/C/man2/killpg.2:53 build/C/man3/profil.3:42 build/C/man3/psignal.3:46 build/C/man2/sigaction.2:63 build/C/man2/sigaltstack.2:38 build/C/man3/siginterrupt.3:44 build/C/man2/sigpending.2:40 build/C/man2/sigprocmask.2:41 build/C/man3/sigqueue.3:39 build/C/man3/sigset.3:45 build/C/man3/sigsetops.3:51 build/C/man2/sigsuspend.2:40 build/C/man3/sigvec.3:45 build/C/man3/sigwait.3:39 build/C/man2/sigwaitinfo.2:41 build/C/man2/timer_create.2:50 build/C/man2/timer_delete.2:41 build/C/man2/timer_getoverrun.2:41 build/C/man2/timer_settime.2:45 build/C/man2/wait.2:69 build/C/man2/wait4.2:53
1127 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
1131 #: build/C/man3/gsignal.3:49
1132 msgid "B<gsignal>(), B<ssignal>(): _SVID_SOURCE"
1136 #: build/C/man3/gsignal.3:57
1138 "Don't use these functions under Linux. Due to a historical mistake, under "
1139 "Linux these functions are aliases for B<raise>(3) and B<signal>(2), "
1144 #: build/C/man3/gsignal.3:95
1146 "Elsewhere, on System V-like systems, these functions implement software "
1147 "signaling, entirely independent of the classical B<signal>(2) and "
1148 "B<kill>(2) functions. The function B<ssignal>() defines the action to "
1149 "take when the software signal with number I<signum> is raised using the "
1150 "function B<gsignal>(), and returns the previous such action or B<SIG_DFL>. "
1151 "The function B<gsignal>() does the following: if no action (or the action "
1152 "B<SIG_DFL>) was specified for I<signum>, then it does nothing and returns "
1153 "0. If the action B<SIG_IGN> was specified for I<signum>, then it does "
1154 "nothing and returns 1. Otherwise, it resets the action to B<SIG_DFL> and "
1155 "calls the action function with argument I<signum>, and returns the value "
1156 "returned by that function. The range of possible values I<signum> varies "
1157 "(often 1-15 or 1-17)."
1161 #: build/C/man3/gsignal.3:103
1163 "These functions are available under AIX, DG/UX, HP-UX, SCO, Solaris, Tru64. "
1164 "They are called obsolete under most of these systems, and are broken under "
1165 "Linux libc and glibc. Some systems also have B<gsignal_r>() and "
1170 #: build/C/man3/gsignal.3:107
1171 msgid "B<kill>(2), B<signal>(2), B<raise>(3)"
1175 #: build/C/man2/kill.2:44
1181 #: build/C/man2/kill.2:44
1187 #: build/C/man2/kill.2:47
1188 msgid "kill - send signal to a process"
1192 #: build/C/man2/kill.2:50
1194 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
1198 #: build/C/man2/kill.2:54
1200 msgid "B<int kill(pid_t >I<pid>B<, int >I<sig>B<);>\n"
1204 #: build/C/man2/kill.2:64
1205 msgid "B<kill>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
1209 #: build/C/man2/kill.2:70
1211 "The B<kill>() system call can be used to send any signal to any process "
1216 #: build/C/man2/kill.2:73
1218 "If I<pid> is positive, then signal I<sig> is sent to the process with the ID "
1219 "specified by I<pid>."
1223 #: build/C/man2/kill.2:76
1225 "If I<pid> equals 0, then I<sig> is sent to every process in the process "
1226 "group of the calling process."
1230 #: build/C/man2/kill.2:80
1232 "If I<pid> equals -1, then I<sig> is sent to every process for which the "
1233 "calling process has permission to send signals, except for process 1 "
1234 "(I<init>), but see below."
1238 #: build/C/man2/kill.2:83
1240 "If I<pid> is less than -1, then I<sig> is sent to every process in the "
1241 "process group whose ID is I<-pid>."
1245 #: build/C/man2/kill.2:88
1247 "If I<sig> is 0, then no signal is sent, but error checking is still "
1248 "performed; this can be used to check for the existence of a process ID or "
1253 #: build/C/man2/kill.2:100
1255 "For a process to have permission to send a signal it must either be "
1256 "privileged (under Linux: have the B<CAP_KILL> capability), or the real or "
1257 "effective user ID of the sending process must equal the real or saved "
1258 "set-user-ID of the target process. In the case of B<SIGCONT> it suffices "
1259 "when the sending and receiving processes belong to the same session. "
1260 "(Historically, the rules were different; see NOTES.)"
1264 #: build/C/man2/kill.2:105
1266 "On success (at least one signal was sent), zero is returned. On error, -1 "
1267 "is returned, and I<errno> is set appropriately."
1271 #: build/C/man2/kill.2:109
1272 msgid "An invalid signal was specified."
1276 #: build/C/man2/kill.2:109 build/C/man2/killpg.2:99 build/C/man2/prctl.2:1098 build/C/man2/prctl.2:1110 build/C/man2/prctl.2:1120 build/C/man2/prctl.2:1128 build/C/man2/rt_sigqueueinfo.2:148 build/C/man2/sigaltstack.2:153 build/C/man3/sigqueue.3:102 build/C/man2/tkill.2:96
1282 #: build/C/man2/kill.2:113 build/C/man2/killpg.2:103
1284 "The process does not have permission to send the signal to any of the target "
1289 #: build/C/man2/kill.2:113 build/C/man2/killpg.2:103 build/C/man2/killpg.2:107 build/C/man2/rt_sigqueueinfo.2:156 build/C/man3/sigqueue.3:108 build/C/man2/tkill.2:101
1295 #: build/C/man2/kill.2:121
1297 "The pid or process group does not exist. Note that an existing process "
1298 "might be a zombie, a process which already committed termination, but has "
1299 "not yet been B<wait>(2)ed for."
1303 #: build/C/man2/kill.2:123 build/C/man2/pause.2:59 build/C/man2/wait.2:425
1304 msgid "SVr4, 4.3BSD, POSIX.1-2001."
1308 #: build/C/man2/kill.2:131
1310 "The only signals that can be sent to process ID 1, the I<init> process, are "
1311 "those for which I<init> has explicitly installed signal handlers. This is "
1312 "done to assure the system is not brought down accidentally."
1316 #: build/C/man2/kill.2:137
1318 "POSIX.1-2001 requires that I<kill(-1,sig)> send I<sig> to all processes that "
1319 "the calling process may send signals to, except possibly for some "
1320 "implementation-defined system processes. Linux allows a process to signal "
1321 "itself, but on Linux the call I<kill(-1,sig)> does not signal the calling "
1326 #: build/C/man2/kill.2:147
1328 "POSIX.1-2001 requires that if a process sends a signal to itself, and the "
1329 "sending thread does not have the signal blocked, and no other thread has it "
1330 "unblocked or is waiting for it in B<sigwait>(3), at least one unblocked "
1331 "signal must be delivered to the sending thread before the B<kill>() "
1336 #: build/C/man2/kill.2:147 build/C/man3/sigpause.3:82 build/C/man2/wait.2:480
1341 #. In the 0.* kernels things chopped and changed quite
1342 #. a bit - MTK, 24 Jul 02
1344 #: build/C/man2/kill.2:161
1346 "Across different kernel versions, Linux has enforced different rules for the "
1347 "permissions required for an unprivileged process to send a signal to another "
1348 "process. In kernels 1.0 to 1.2.2, a signal could be sent if the effective "
1349 "user ID of the sender matched effective user ID of the target, or the real "
1350 "user ID of the sender matched the real user ID of the target. From kernel "
1351 "1.2.3 until 1.3.77, a signal could be sent if the effective user ID of the "
1352 "sender matched either the real or effective user ID of the target. The "
1353 "current rules, which conform to POSIX.1-2001, were adopted in kernel 1.3.78."
1357 #: build/C/man2/kill.2:171
1359 "In 2.6 kernels up to and including 2.6.7, there was a bug that meant that "
1360 "when sending signals to a process group, B<kill>() failed with the error "
1361 "B<EPERM> if the caller did not have permission to send the signal to I<any> "
1362 "(rather than I<all>) of the members of the process group. Notwithstanding "
1363 "this error return, the signal was still delivered to all of the processes "
1364 "for which the caller had permission to signal."
1368 #: build/C/man2/kill.2:181
1370 "B<_exit>(2), B<killpg>(2), B<signal>(2), B<tkill>(2), B<exit>(3), "
1371 "B<sigqueue>(3), B<capabilities>(7), B<credentials>(7), B<signal>(7)"
1375 #: build/C/man2/killpg.2:42
1381 #: build/C/man2/killpg.2:42 build/C/man3/sigset.3:26
1387 #: build/C/man2/killpg.2:45
1388 msgid "killpg - send signal to a process group"
1392 #: build/C/man2/killpg.2:49
1393 msgid "B<int killpg(int >I<pgrp>B<, int >I<sig>B<);>"
1397 #: build/C/man2/killpg.2:55
1399 msgid "B<killpg>():"
1403 #: build/C/man2/killpg.2:59 build/C/man2/sigaltstack.2:46 build/C/man3/siginterrupt.3:51 build/C/man2/wait4.2:60
1405 "_BSD_SOURCE || _XOPEN_SOURCE\\ E<gt>=\\ 500 || _XOPEN_SOURCE\\ &&\\ "
1406 "_XOPEN_SOURCE_EXTENDED"
1410 #: build/C/man2/killpg.2:69
1412 "B<killpg>() sends the signal I<sig> to the process group I<pgrp>. See "
1413 "B<signal>(7) for a list of signals."
1417 #: build/C/man2/killpg.2:78
1419 "If I<pgrp> is 0, B<killpg>() sends the signal to the calling process's "
1420 "process group. (POSIX says: If I<pgrp> is less than or equal to 1, the "
1421 "behavior is undefined.)"
1425 #: build/C/man2/killpg.2:89
1427 "For a process to have permission to send a signal it must either be "
1428 "privileged (under Linux: have the B<CAP_KILL> capability), or the real or "
1429 "effective user ID of the sending process must equal the real or saved "
1430 "set-user-ID of the target process. In the case of B<SIGCONT> it suffices "
1431 "when the sending and receiving processes belong to the same session."
1435 #: build/C/man2/killpg.2:99
1436 msgid "I<sig> is not a valid signal number."
1440 #: build/C/man2/killpg.2:107
1441 msgid "No process can be found in the process group specified by I<pgrp>."
1445 #: build/C/man2/killpg.2:111
1447 "The process group was given as 0 but the sending process does not have a "
1452 #: build/C/man2/killpg.2:115
1454 "SVr4, 4.4BSD (the B<killpg>() function call first appeared in 4BSD), "
1459 #: build/C/man2/killpg.2:129
1461 "There are various differences between the permission checking in BSD-type "
1462 "systems and System\\ V-type systems. See the POSIX rationale for "
1463 "B<kill>(). A difference not mentioned by POSIX concerns the return value "
1464 "B<EPERM>: BSD documents that no signal is sent and B<EPERM> returned when "
1465 "the permission check failed for at least one target process, while POSIX "
1466 "documents B<EPERM> only when the permission check failed for all target "
1471 #: build/C/man2/killpg.2:134
1473 "On Linux, B<killpg>() is implemented as a library function that makes the "
1474 "call I<kill(-pgrp,\\ sig)>."
1478 #: build/C/man2/killpg.2:140
1480 "B<getpgrp>(2), B<kill>(2), B<signal>(2), B<capabilities>(7), "
1485 #: build/C/man2/pause.2:30
1491 #: build/C/man2/pause.2:30
1497 #: build/C/man2/pause.2:33
1498 msgid "pause - wait for signal"
1502 #: build/C/man2/pause.2:35
1503 msgid "B<#include E<lt>unistd.hE<gt>>"
1507 #: build/C/man2/pause.2:37
1508 msgid "B<int pause(void);>"
1512 #: build/C/man2/pause.2:42
1514 "B<pause>() causes the calling process (or thread) to sleep until a signal "
1515 "is delivered that either terminates the process or causes the invocation of "
1516 "a signal-catching function."
1519 #. .BR ERESTARTNOHAND .
1521 #: build/C/man2/pause.2:53
1523 "B<pause>() returns only when a signal was caught and the signal-catching "
1524 "function returned. In this case, B<pause>() returns -1, and I<errno> is "
1529 #: build/C/man2/pause.2:54 build/C/man2/sigsuspend.2:81 build/C/man2/sigwaitinfo.2:123 build/C/man2/wait.2:411
1535 #: build/C/man2/pause.2:57
1536 msgid "a signal was caught and the signal-catching function returned."
1540 #: build/C/man2/pause.2:64
1541 msgid "B<kill>(2), B<select>(2), B<signal>(2), B<sigsuspend>(2)"
1545 #: build/C/man2/prctl.2:54
1551 #: build/C/man2/prctl.2:54 build/C/man7/signal.7:46
1557 #: build/C/man2/prctl.2:57
1558 msgid "prctl - operations on a process"
1562 #: build/C/man2/prctl.2:60
1564 msgid "B<#include E<lt>sys/prctl.hE<gt>>\n"
1568 #: build/C/man2/prctl.2:63
1571 "B<int prctl(int >I<option>B<, unsigned long >I<arg2>B<, unsigned long "
1573 "B< unsigned long >I<arg4>B<, unsigned long >I<arg5>B<);>\n"
1577 #: build/C/man2/prctl.2:70
1579 "B<prctl>() is called with a first argument describing what to do (with "
1580 "values defined in I<E<lt>linux/prctl.hE<gt>>), and further arguments with a "
1581 "significance depending on the first one. The first argument can be:"
1585 #: build/C/man2/prctl.2:70
1587 msgid "B<PR_CAPBSET_READ> (since Linux 2.6.25)"
1591 #: build/C/man2/prctl.2:82
1593 "Return (as the function result) 1 if the capability specified in I<arg2> is "
1594 "in the calling thread's capability bounding set, or 0 if it is not. (The "
1595 "capability constants are defined in I<E<lt>linux/capability.hE<gt>>.) The "
1596 "capability bounding set dictates whether the process can receive the "
1597 "capability through a file's permitted capability set on a subsequent call to "
1602 #: build/C/man2/prctl.2:87
1604 "If the capability specified in I<arg2> is not valid, then the call fails "
1605 "with the error B<EINVAL>."
1609 #: build/C/man2/prctl.2:87
1611 msgid "B<PR_CAPBSET_DROP> (since Linux 2.6.25)"
1615 #: build/C/man2/prctl.2:96
1617 "If the calling thread has the B<CAP_SETPCAP> capability, then drop the "
1618 "capability specified by I<arg2> from the calling thread's capability "
1619 "bounding set. Any children of the calling thread will inherit the newly "
1620 "reduced bounding set."
1624 #: build/C/man2/prctl.2:108
1626 "The call fails with the error: B<EPERM> if the calling thread does not have "
1627 "the B<CAP_SETPCAP>; B<EINVAL> if I<arg2> does not represent a valid "
1628 "capability; or B<EINVAL> if file capabilities are not enabled in the kernel, "
1629 "in which case bounding sets are not supported."
1633 #: build/C/man2/prctl.2:108
1635 msgid "B<PR_SET_CHILD_SUBREAPER> (since Linux 3.4)"
1638 #. commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b
1640 #: build/C/man2/prctl.2:133
1642 "If I<arg2> is nonzero, set the \"child subreaper\" attribute of the calling "
1643 "process; if I<arg2> is zero, unset the attribute. When a process is marked "
1644 "as a child subreaper, all of the children that it creates, and their "
1645 "descendants, will be marked as having a subreaper. In effect, a subreaper "
1646 "fulfills the role of B<init>(1) for its descendant processes. Upon "
1647 "termination of a process that is orphaned (i.e., its immediate parent has "
1648 "already terminated) and marked as having a subreaper, the nearest still "
1649 "living ancestor subreaper will receive a B<SIGCHLD> signal and be able to "
1650 "B<wait>(2) on the process to discover its termination status."
1654 #: build/C/man2/prctl.2:133
1656 msgid "B<PR_GET_CHILD_SUBREAPER> (since Linux 3.4)"
1660 #: build/C/man2/prctl.2:138
1662 "Return the \"child subreaper\" setting of the caller, in the location "
1663 "pointed to by I<(int\\ *) arg2>."
1667 #: build/C/man2/prctl.2:138
1669 msgid "B<PR_SET_DUMPABLE> (since Linux 2.3.20)"
1672 #. See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
1673 #. Subject: Fix prctl privilege escalation (CVE-2006-2451)
1674 #. From: Marcel Holtmann <marcel () holtmann ! org>
1675 #. Date: 2006-07-12 11:12:00
1677 #: build/C/man2/prctl.2:164
1679 "Set the state of the flag determining whether core dumps are produced for "
1680 "the calling process upon delivery of a signal whose default behavior is to "
1681 "produce a core dump. (Normally, this flag is set for a process by default, "
1682 "but it is cleared when a set-user-ID or set-group-ID program is executed and "
1683 "also by various system calls that manipulate process UIDs and GIDs). In "
1684 "kernels up to and including 2.6.12, I<arg2> must be either 0 (process is not "
1685 "dumpable) or 1 (process is dumpable). Between kernels 2.6.13 and 2.6.17, "
1686 "the value 2 was also permitted, which caused any binary which normally would "
1687 "not be dumped to be dumped readable by root only; for security reasons, this "
1688 "feature has been removed. (See also the description of "
1689 "I</proc/sys/fs/suid_dumpable> in B<proc>(5).) Processes that are not "
1690 "dumpable can not be attached via B<ptrace>(2) B<PTRACE_ATTACH>."
1694 #: build/C/man2/prctl.2:164
1696 msgid "B<PR_GET_DUMPABLE> (since Linux 2.3.20)"
1699 #. Since Linux 2.6.13, the dumpable flag can have the value 2,
1700 #. but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
1701 #. flags has a nonzero value. This was fixed in 2.6.14.
1703 #: build/C/man2/prctl.2:171
1705 "Return (as the function result) the current state of the calling process's "
1710 #: build/C/man2/prctl.2:171
1712 msgid "B<PR_SET_ENDIAN> (since Linux 2.6.18, PowerPC only)"
1715 #. Respectively 0, 1, 2
1717 #: build/C/man2/prctl.2:181
1719 "Set the endian-ness of the calling process to the value given in I<arg2>, "
1720 "which should be one of the following: B<PR_ENDIAN_BIG>, B<PR_ENDIAN_LITTLE>, "
1721 "or B<PR_ENDIAN_PPC_LITTLE> (PowerPC pseudo little endian)."
1725 #: build/C/man2/prctl.2:181
1727 msgid "B<PR_GET_ENDIAN> (since Linux 2.6.18, PowerPC only)"
1731 #: build/C/man2/prctl.2:186
1733 "Return the endian-ness of the calling process, in the location pointed to by "
1734 "I<(int\\ *) arg2>."
1738 #: build/C/man2/prctl.2:186
1740 msgid "B<PR_SET_FPEMU> (since Linux 2.4.18, 2.5.9, only on ia64)"
1744 #: build/C/man2/prctl.2:193
1746 "Set floating-point emulation control bits to I<arg2>. Pass "
1747 "B<PR_FPEMU_NOPRINT> to silently emulate fp operations accesses, or "
1748 "B<PR_FPEMU_SIGFPE> to not emulate fp operations and send B<SIGFPE> instead."
1752 #: build/C/man2/prctl.2:193
1754 msgid "B<PR_GET_FPEMU> (since Linux 2.4.18, 2.5.9, only on ia64)"
1758 #: build/C/man2/prctl.2:198
1760 "Return floating-point emulation control bits, in the location pointed to by "
1761 "I<(int\\ *) arg2>."
1765 #: build/C/man2/prctl.2:198
1767 msgid "B<PR_SET_FPEXC> (since Linux 2.4.21, 2.5.32, only on PowerPC)"
1771 #: build/C/man2/prctl.2:211
1773 "Set floating-point exception mode to I<arg2>. Pass B<PR_FP_EXC_SW_ENABLE> "
1774 "to use FPEXC for FP exception enables, B<PR_FP_EXC_DIV> for floating-point "
1775 "divide by zero, B<PR_FP_EXC_OVF> for floating-point overflow, "
1776 "B<PR_FP_EXC_UND> for floating-point underflow, B<PR_FP_EXC_RES> for "
1777 "floating-point inexact result, B<PR_FP_EXC_INV> for floating-point invalid "
1778 "operation, B<PR_FP_EXC_DISABLED> for FP exceptions disabled, "
1779 "B<PR_FP_EXC_NONRECOV> for async nonrecoverable exception mode, "
1780 "B<PR_FP_EXC_ASYNC> for async recoverable exception mode, "
1781 "B<PR_FP_EXC_PRECISE> for precise exception mode."
1785 #: build/C/man2/prctl.2:211
1787 msgid "B<PR_GET_FPEXC> (since Linux 2.4.21, 2.5.32, only on PowerPC)"
1791 #: build/C/man2/prctl.2:216
1793 "Return floating-point exception mode, in the location pointed to by I<(int\\ "
1798 #: build/C/man2/prctl.2:216
1800 msgid "B<PR_SET_KEEPCAPS> (since Linux 2.2.18)"
1804 #: build/C/man2/prctl.2:234
1806 "Set the state of the thread's \"keep capabilities\" flag, which determines "
1807 "whether the threads's permitted capability set is cleared when a change is "
1808 "made to the threads's user IDs such that the threads's real UID, effective "
1809 "UID, and saved set-user-ID all become nonzero when at least one of them "
1810 "previously had the value 0. By default, the permitted capability set is "
1811 "cleared when such a change is made; setting the \"keep capabilities\" flag "
1812 "prevents it from being cleared. I<arg2> must be either 0 (permitted "
1813 "capabilities are cleared) or 1 (permitted capabilities are kept). (A "
1814 "thread's I<effective> capability set is always cleared when such a "
1815 "credential change is made, regardless of the setting of the \"keep "
1816 "capabilities\" flag.) The \"keep capabilities\" value will be reset to 0 on "
1817 "subsequent calls to B<execve>(2)."
1821 #: build/C/man2/prctl.2:234
1823 msgid "B<PR_GET_KEEPCAPS> (since Linux 2.2.18)"
1827 #: build/C/man2/prctl.2:238
1829 "Return (as the function result) the current state of the calling threads's "
1830 "\"keep capabilities\" flag."
1834 #: build/C/man2/prctl.2:238
1836 msgid "B<PR_SET_NAME> (since Linux 2.6.9)"
1839 #. TASK_COMM_LEN in include/linux/sched.h
1841 #: build/C/man2/prctl.2:257
1843 "Set the name of the calling thread, using the value in the location pointed "
1844 "to by I<(char\\ *) arg2>. The name can be up to 16 bytes long, including "
1845 "the terminating null byte. (If the length of the string, including the "
1846 "terminating null byte, exceeds 16 bytes, the string is silently truncated.) "
1847 "This is the same attribute that can be set via B<pthread_setname_np>(3) and "
1848 "retrieved using B<pthread_getname_np>(3). The attribute is likewise "
1849 "accessible via I</proc/self/task/[tid]/comm>, where I<tid> is the name of "
1850 "the calling thread."
1854 #: build/C/man2/prctl.2:257
1856 msgid "B<PR_GET_NAME> (since Linux 2.6.11)"
1860 #: build/C/man2/prctl.2:264
1862 "Return the name of the calling thread, in the buffer pointed to by I<(char\\ "
1863 "*) arg2>. The buffer should allow space for up to 16 bytes; the returned "
1864 "string will be null-terminated."
1868 #: build/C/man2/prctl.2:264
1870 msgid "B<PR_SET_NO_NEW_PRIVS> (since Linux 3.5)"
1874 #: build/C/man2/prctl.2:287
1876 "Set the calling process's I<no_new_privs> bit to the value in I<arg2>. With "
1877 "I<no_new_privs> set to 1, B<execve>(2) promises not to grant privileges to "
1878 "do anything that could not have been done without the B<execve>(2) call "
1879 "(for example, rendering the set-user-ID and set-group-ID permission bits, "
1880 "and file capabilities non-functional). Once set, this bit cannot be unset. "
1881 "The setting of this bit is inherited by children created by B<fork>(2) and "
1882 "B<clone>(2), and preserved across B<execve>(2)."
1886 #: build/C/man2/prctl.2:290
1888 "For more information, see the kernel source file "
1889 "I<Documentation/prctl/no_new_privs.txt>."
1893 #: build/C/man2/prctl.2:290
1895 msgid "B<PR_GET_NO_NEW_PRIVS> (since Linux 3.5)"
1899 #: build/C/man2/prctl.2:301
1901 "Return (as the function result) the value of the I<no_new_privs> bit for the "
1902 "current process. A value of 0 indicates the regular B<execve>(2) "
1903 "behavior. A value of 1 indicates B<execve>(2) will operate in the "
1904 "privilege-restricting mode described above."
1908 #: build/C/man2/prctl.2:301
1910 msgid "B<PR_SET_PDEATHSIG> (since Linux 2.1.57)"
1914 #: build/C/man2/prctl.2:314
1916 "Set the parent process death signal of the calling process to I<arg2> "
1917 "(either a signal value in the range 1..maxsig, or 0 to clear). This is the "
1918 "signal that the calling process will get when its parent dies. This value "
1919 "is cleared for the child of a B<fork>(2) and (since Linux 2.4.36 / 2.6.23) "
1920 "when executing a set-user-ID or set-group-ID binary. This value is "
1921 "preserved across B<execve>(2)."
1925 #: build/C/man2/prctl.2:314
1927 msgid "B<PR_GET_PDEATHSIG> (since Linux 2.3.15)"
1931 #: build/C/man2/prctl.2:319
1933 "Return the current value of the parent process death signal, in the location "
1934 "pointed to by I<(int\\ *) arg2>."
1938 #: build/C/man2/prctl.2:319
1940 msgid "B<PR_SET_PTRACER> (since Linux 3.4)"
1943 #. commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
1944 #. commit bf06189e4d14641c0148bea16e9dd24943862215
1946 #: build/C/man2/prctl.2:344
1948 "This is meaningful only when the Yama LSM is enabled and in mode 1 "
1949 "(\"restricted ptrace\", visible via I</proc/sys/kernel/yama/ptrace_scope>). "
1950 "When a \"ptracer process ID\" is passed in I<arg2>, the caller is declaring "
1951 "that the ptracer process can B<ptrace>(2) the calling process as if it were "
1952 "a direct process ancestor. Each B<PR_SET_PTRACER> operation replaces the "
1953 "previous \"ptracer process ID\". Employing B<PR_SET_PTRACER> with I<arg2> "
1954 "set to 0 clears the caller's \"ptracer process ID\". If I<arg2> is "
1955 "B<PR_SET_PTRACER_ANY>, the ptrace restrictions introduced by Yama are "
1956 "effectively disabled for the calling process."
1960 #: build/C/man2/prctl.2:347
1962 "For further information, see the kernel source file "
1963 "I<Documentation/security/Yama.txt>."
1967 #: build/C/man2/prctl.2:347
1969 msgid "B<PR_SET_SECCOMP> (since Linux 2.6.23)"
1972 #. See http://thread.gmane.org/gmane.linux.kernel/542632
1973 #. [PATCH 0 of 2] seccomp updates
1974 #. andrea@cpushare.com
1976 #: build/C/man2/prctl.2:358
1978 "Set the secure computing (seccomp) mode for the calling thread, to limit the "
1979 "available system calls. The more recent B<seccomp>(2) system call provides "
1980 "a superset of the functionality of B<PR_SET_SECCOMP>."
1984 #: build/C/man2/prctl.2:363
1986 "The seccomp mode is selected via I<arg2>. (The seccomp constants are "
1987 "defined in I<E<lt>linux/seccomp.hE<gt>>.)"
1991 #: build/C/man2/prctl.2:384
1993 "With I<arg2> set to B<SECCOMP_MODE_STRICT>, the only system calls that the "
1994 "thread is permitted to make are B<read>(2), B<write>(2), B<_exit>(2), and "
1995 "B<sigreturn>(2). Other system calls result in the delivery of a B<SIGKILL> "
1996 "signal. Strict secure computing mode is useful for number-crunching "
1997 "applications that may need to execute untrusted byte code, perhaps obtained "
1998 "by reading from a pipe or socket. This operation is available only if the "
1999 "kernel is configured with B<CONFIG_SECCOMP> enabled."
2003 #: build/C/man2/prctl.2:399
2005 "With I<arg2> set to B<SECCOMP_MODE_FILTER> (since Linux 3.5), the system "
2006 "calls allowed are defined by a pointer to a Berkeley Packet Filter passed in "
2007 "I<arg3>. This argument is a pointer to I<struct sock_fprog>; it can be "
2008 "designed to filter arbitrary system calls and system call arguments. This "
2009 "mode is available only if the kernel is configured with "
2010 "B<CONFIG_SECCOMP_FILTER> enabled."
2014 #: build/C/man2/prctl.2:414
2016 "If B<SECCOMP_MODE_FILTER> filters permit B<fork>(2), then the seccomp mode "
2017 "is inherited by children created by B<fork>(2); if B<execve>(2) is "
2018 "permitted, then the seccomp mode is preserved across B<execve>(2). If the "
2019 "filters permit B<prctl>() calls, then additional filters can be added; they "
2020 "are run in order until the first non-allow result is seen."
2024 #: build/C/man2/prctl.2:417
2026 "For further information, see the kernel source file "
2027 "I<Documentation/prctl/seccomp_filter.txt>."
2031 #: build/C/man2/prctl.2:417
2033 msgid "B<PR_GET_SECCOMP> (since Linux 2.6.23)"
2037 #: build/C/man2/prctl.2:435
2039 "Return (as the function result) the secure computing mode of the calling "
2040 "thread. If the caller is not in secure computing mode, this operation "
2041 "returns 0; if the caller is in strict secure computing mode, then the "
2042 "B<prctl>() call will cause a B<SIGKILL> signal to be sent to the process. "
2043 "If the caller is in filter mode, and this system call is allowed by the "
2044 "seccomp filters, it returns 2; otherwise, the process is killed with a "
2045 "B<SIGKILL> signal. This operation is available only if the kernel is "
2046 "configured with B<CONFIG_SECCOMP> enabled."
2050 #: build/C/man2/prctl.2:443
2052 "Since Linux 3.8, the I<Seccomp> field of the I</proc/[pid]/status> file "
2053 "provides a method of obtaining the same information, without the risk that "
2054 "the process is killed; see B<proc>(5)."
2058 #: build/C/man2/prctl.2:443
2060 msgid "B<PR_SET_SECUREBITS> (since Linux 2.6.26)"
2064 #: build/C/man2/prctl.2:449
2066 "Set the \"securebits\" flags of the calling thread to the value supplied in "
2067 "I<arg2>. See B<capabilities>(7)."
2071 #: build/C/man2/prctl.2:449
2073 msgid "B<PR_GET_SECUREBITS> (since Linux 2.6.26)"
2077 #: build/C/man2/prctl.2:455
2079 "Return (as the function result) the \"securebits\" flags of the calling "
2080 "thread. See B<capabilities>(7)."
2084 #: build/C/man2/prctl.2:455
2086 msgid "B<PR_SET_THP_DISABLE> (since Linux 3.15)"
2089 #. commit a0715cc22601e8830ace98366c0c2bd8da52af52
2091 #: build/C/man2/prctl.2:471
2093 "Set the state of the \"THP disable\" flag for the calling thread. If "
2094 "I<arg2> has a nonzero value, the flag is set, otherwise it is cleared. "
2095 "Setting this flag provides a method for disabling transparent huge pages for "
2096 "jobs where the code cannot be modified, and using a malloc hook with "
2097 "B<madvise>(2) is not an option (i.e., statically allocated data). The "
2098 "setting of the \"THP disable\" flag is inherited by a child created via "
2099 "B<fork>(2) and is preserved across B<execve>(2)."
2103 #: build/C/man2/prctl.2:471
2105 msgid "B<PR_GET_THP_DISABLE> (since Linux 3.15)"
2109 #: build/C/man2/prctl.2:476
2111 "Return (via the function result) the current setting of the \"THP disable\" "
2112 "flag for the calling thread: either 1, if the flag is set, or 0, if it is "
2117 #: build/C/man2/prctl.2:476
2119 msgid "B<PR_GET_TID_ADDRESS> (since Linux 3.5)"
2122 #. commit 300f786b2683f8bb1ec0afb6e1851183a479c86d
2124 #: build/C/man2/prctl.2:491
2126 "Retrieve the I<clear_child_tid> address set by B<set_tid_address>(2) and "
2127 "the B<clone>(2) B<CLONE_CHILD_CLEARTID> flag, in the location pointed to by "
2128 "I<(int\\ **)\\ arg2>. This feature is available only if the kernel is built "
2129 "with the B<CONFIG_CHECKPOINT_RESTORE> option enabled."
2133 #: build/C/man2/prctl.2:491
2135 msgid "B<PR_SET_TIMERSLACK> (since Linux 2.6.28)"
2138 #. See https://lwn.net/Articles/369549/
2139 #. commit 6976675d94042fbd446231d1bd8b7de71a980ada
2140 #. It seems that it's not possible to set the timer slack to zero;
2141 #. The minimum value is 1? Seems a little strange.
2143 #: build/C/man2/prctl.2:510
2145 "Set the current timer slack for the calling thread to the nanosecond value "
2146 "supplied in I<arg2>. If I<arg2> is less than or equal to zero, reset the "
2147 "current timer slack to the thread's default timer slack value. The timer "
2148 "slack is used by the kernel to group timer expirations for the calling "
2149 "thread that are close to one another; as a consequence, timer expirations "
2150 "for the thread may be up to the specified number of nanoseconds late (but "
2151 "will never expire early). Grouping timer expirations can help reduce system "
2152 "power consumption by minimizing CPU wake-ups."
2155 #. List obtained by grepping for futex usage in glibc source
2157 #: build/C/man2/prctl.2:530
2159 "The timer expirations affected by timer slack are those set by B<select>(2), "
2160 "B<pselect>(2), B<poll>(2), B<ppoll>(2), B<epoll_wait>(2), B<epoll_pwait>(2), "
2161 "B<clock_nanosleep>(2), B<nanosleep>(2), and B<futex>(2) (and thus the "
2162 "library functions implemented via futexes, including "
2163 "B<pthread_cond_timedwait>(3), B<pthread_mutex_timedlock>(3), "
2164 "B<pthread_rwlock_timedrdlock>(3), B<pthread_rwlock_timedwrlock>(3), and "
2165 "B<sem_timedwait>(3))."
2169 #: build/C/man2/prctl.2:534
2171 "Timer slack is not applied to threads that are scheduled under a real-time "
2172 "scheduling policy (see B<sched_setscheduler>(2))."
2176 #: build/C/man2/prctl.2:551
2178 "Each thread has two associated timer slack values: a \"default\" value, and "
2179 "a \"current\" value. The current value is the one that governs grouping of "
2180 "timer expirations. When a new thread is created, the two timer slack values "
2181 "are made the same as the current value of the creating thread. Thereafter, "
2182 "a thread can adjust its current timer slack value via B<PR_SET_TIMERSLACK> "
2183 "(the default value can't be changed). The timer slack values of I<init> "
2184 "(PID 1), the ancestor of all processes, are 50,000 nanoseconds (50 "
2185 "microseconds). The timer slack values are preserved across B<execve>(2)."
2189 #: build/C/man2/prctl.2:551
2191 msgid "B<PR_GET_TIMERSLACK> (since Linux 2.6.28)"
2195 #: build/C/man2/prctl.2:555
2197 "Return (as the function result) the current timer slack value of the "
2202 #: build/C/man2/prctl.2:555
2204 msgid "B<PR_SET_TIMING> (since Linux 2.6.0-test4)"
2209 #. PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
2210 #. and looking at the patch history, it appears
2211 #. that it never did anything.
2213 #: build/C/man2/prctl.2:572
2215 "Set whether to use (normal, traditional) statistical process timing or "
2216 "accurate timestamp-based process timing, by passing B<PR_TIMING_STATISTICAL> "
2217 "or B<PR_TIMING_TIMESTAMP> to I<arg2>. B<PR_TIMING_TIMESTAMP> is not "
2218 "currently implemented (attempting to set this mode will yield the error "
2223 #: build/C/man2/prctl.2:572
2225 msgid "B<PR_GET_TIMING> (since Linux 2.6.0-test4)"
2229 #: build/C/man2/prctl.2:576
2231 "Return (as the function result) which process timing method is currently in "
2236 #: build/C/man2/prctl.2:576
2238 msgid "B<PR_TASK_PERF_EVENTS_DISABLE> (since Linux 2.6.31)"
2242 #: build/C/man2/prctl.2:585
2244 "Disable all performance counters attached to the calling process, regardless "
2245 "of whether the counters were created by this process or another process. "
2246 "Performance counters created by the calling process for other processes are "
2247 "unaffected. For more information on performance counters, see the Linux "
2248 "kernel source file I<tools/perf/design.txt>."
2251 #. commit 1d1c7ddbfab358445a542715551301b7fc363e28
2253 #: build/C/man2/prctl.2:591
2255 "Originally called B<PR_TASK_PERF_COUNTERS_DISABLE>; renamed (with same "
2256 "numerical value) in Linux 2.6.32."
2260 #: build/C/man2/prctl.2:591
2262 msgid "B<PR_TASK_PERF_EVENTS_ENABLE> (since Linux 2.6.31)"
2266 #: build/C/man2/prctl.2:596
2268 "The converse of B<PR_TASK_PERF_EVENTS_DISABLE>; enable performance counters "
2269 "attached to the calling process."
2272 #. commit 1d1c7ddbfab358445a542715551301b7fc363e28
2273 #. commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
2275 #: build/C/man2/prctl.2:603
2276 msgid "Originally called B<PR_TASK_PERF_COUNTERS_ENABLE>; renamed in Linux 2.6.32."
2280 #: build/C/man2/prctl.2:603
2282 msgid "B<PR_SET_TSC> (since Linux 2.6.26, x86 only)"
2286 #: build/C/man2/prctl.2:616
2288 "Set the state of the flag determining whether the timestamp counter can be "
2289 "read by the process. Pass B<PR_TSC_ENABLE> to I<arg2> to allow it to be "
2290 "read, or B<PR_TSC_SIGSEGV> to generate a B<SIGSEGV> when the process tries "
2291 "to read the timestamp counter."
2295 #: build/C/man2/prctl.2:616
2297 msgid "B<PR_GET_TSC> (since Linux 2.6.26, x86 only)"
2301 #: build/C/man2/prctl.2:622
2303 "Return the state of the flag determining whether the timestamp counter can "
2304 "be read, in the location pointed to by I<(int\\ *) arg2>."
2308 #: build/C/man2/prctl.2:622
2310 msgid "B<PR_SET_UNALIGN>"
2314 #: build/C/man2/prctl.2:632
2316 "(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15; PowerPC, "
2317 "since Linux 2.6.18; Alpha, since Linux 2.6.22) Set unaligned access control "
2318 "bits to I<arg2>. Pass B<PR_UNALIGN_NOPRINT> to silently fix up unaligned "
2319 "user accesses, or B<PR_UNALIGN_SIGBUS> to generate B<SIGBUS> on unaligned "
2324 #: build/C/man2/prctl.2:632
2326 msgid "B<PR_GET_UNALIGN>"
2330 #: build/C/man2/prctl.2:639
2332 "(see B<PR_SET_UNALIGN> for information on versions and architectures) "
2333 "Return unaligned access control bits, in the location pointed to by I<(int\\ "
2338 #: build/C/man2/prctl.2:639
2340 msgid "B<PR_MCE_KILL> (since Linux 2.6.32)"
2344 #: build/C/man2/prctl.2:679
2346 "Set the machine check memory corruption kill policy for the current thread. "
2347 "If I<arg2> is B<PR_MCE_KILL_CLEAR>, clear the thread memory corruption kill "
2348 "policy and use the system-wide default. (The system-wide default is defined "
2349 "by I</proc/sys/vm/memory_failure_early_kill>; see B<proc>(5).) If I<arg2> "
2350 "is B<PR_MCE_KILL_SET>, use a thread-specific memory corruption kill policy. "
2351 "In this case, I<arg3> defines whether the policy is I<early kill> "
2352 "(B<PR_MCE_KILL_EARLY>), I<late kill> (B<PR_MCE_KILL_LATE>), or the "
2353 "system-wide default (B<PR_MCE_KILL_DEFAULT>). Early kill means that the "
2354 "thread receives a B<SIGBUS> signal as soon as hardware memory corruption is "
2355 "detected inside its address space. In late kill mode, the process is killed "
2356 "only when it accesses a corrupted page. See B<sigaction>(2) for more "
2357 "information on the B<SIGBUS> signal. The policy is inherited by children. "
2358 "The remaining unused B<prctl>() arguments must be zero for future "
2363 #: build/C/man2/prctl.2:679
2365 msgid "B<PR_MCE_KILL_GET> (since Linux 2.6.32)"
2369 #: build/C/man2/prctl.2:685
2371 "Return the current per-process machine check kill policy. All unused "
2372 "B<prctl>() arguments must be zero."
2376 #: build/C/man2/prctl.2:685
2378 msgid "B<PR_SET_MM> (since Linux 3.3)"
2381 #. commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036
2383 #: build/C/man2/prctl.2:706
2385 "Modify certain kernel memory map descriptor fields of the calling process. "
2386 "Usually these fields are set by the kernel and dynamic loader (see "
2387 "B<ld.so>(8) for more information) and a regular application should not use "
2388 "this feature. However, there are cases, such as self-modifying programs, "
2389 "where a program might find it useful to change its own memory map. This "
2390 "feature is available only if the kernel is built with the "
2391 "B<CONFIG_CHECKPOINT_RESTORE> option enabled. The calling process must have "
2392 "the B<CAP_SYS_RESOURCE> capability. The value in I<arg2> is one of the "
2393 "options below, while I<arg3> provides a new value for the option."
2397 #: build/C/man2/prctl.2:707
2399 msgid "B<PR_SET_MM_START_CODE>"
2403 #: build/C/man2/prctl.2:716
2405 "Set the address above which the program text can run. The corresponding "
2406 "memory area must be readable and executable, but not writable or sharable "
2407 "(see B<mprotect>(2) and B<mmap>(2) for more information)."
2411 #: build/C/man2/prctl.2:716
2413 msgid "B<PR_SET_MM_END_CODE>"
2417 #: build/C/man2/prctl.2:721
2419 "Set the address below which the program text can run. The corresponding "
2420 "memory area must be readable and executable, but not writable or sharable."
2424 #: build/C/man2/prctl.2:721
2426 msgid "B<PR_SET_MM_START_DATA>"
2430 #: build/C/man2/prctl.2:727
2432 "Set the address above which initialized and uninitialized (bss) data are "
2433 "placed. The corresponding memory area must be readable and writable, but "
2434 "not executable or sharable."
2438 #: build/C/man2/prctl.2:727
2440 msgid "B<PR_SET_MM_END_DATA>"
2444 #: build/C/man2/prctl.2:733
2446 "Set the address below which initialized and uninitialized (bss) data are "
2447 "placed. The corresponding memory area must be readable and writable, but "
2448 "not executable or sharable."
2452 #: build/C/man2/prctl.2:733
2454 msgid "B<PR_SET_MM_START_STACK>"
2458 #: build/C/man2/prctl.2:737
2460 "Set the start address of the stack. The corresponding memory area must be "
2461 "readable and writable."
2465 #: build/C/man2/prctl.2:737
2467 msgid "B<PR_SET_MM_START_BRK>"
2471 #: build/C/man2/prctl.2:749
2473 "Set the address above which the program heap can be expanded with B<brk>(2) "
2474 "call. The address must be greater than the ending address of the current "
2475 "program data segment. In addition, the combined size of the resulting heap "
2476 "and the size of the data segment can't exceed the B<RLIMIT_DATA> resource "
2477 "limit (see B<setrlimit>(2))."
2481 #: build/C/man2/prctl.2:749
2483 msgid "B<PR_SET_MM_BRK>"
2487 #: build/C/man2/prctl.2:757
2489 "Set the current B<brk>(2) value. The requirements for the address are the "
2490 "same as for the B<PR_SET_MM_START_BRK> option."
2493 #. commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7
2495 #: build/C/man2/prctl.2:760
2496 msgid "The following options are available since Linux 3.5."
2500 #: build/C/man2/prctl.2:760
2502 msgid "B<PR_SET_MM_ARG_START>"
2506 #: build/C/man2/prctl.2:763
2507 msgid "Set the address above which the program command line is placed."
2511 #: build/C/man2/prctl.2:763
2513 msgid "B<PR_SET_MM_ARG_END>"
2517 #: build/C/man2/prctl.2:766
2518 msgid "Set the address below which the program command line is placed."
2522 #: build/C/man2/prctl.2:766
2524 msgid "B<PR_SET_MM_ENV_START>"
2528 #: build/C/man2/prctl.2:769
2529 msgid "Set the address above which the program environment is placed."
2533 #: build/C/man2/prctl.2:769
2535 msgid "B<PR_SET_MM_ENV_END>"
2539 #: build/C/man2/prctl.2:772
2540 msgid "Set the address below which the program environment is placed."
2544 #: build/C/man2/prctl.2:785
2546 "The address passed with B<PR_SET_MM_ARG_START>, B<PR_SET_MM_ARG_END>, "
2547 "B<PR_SET_MM_ENV_START>, and B<PR_SET_MM_ENV_END> should belong to a process "
2548 "stack area. Thus, the corresponding memory area must be readable, writable, "
2549 "and (depending on the kernel configuration) have the B<MAP_GROWSDOWN> "
2550 "attribute set (see B<mmap>(2))."
2554 #: build/C/man2/prctl.2:785
2556 msgid "B<PR_SET_MM_AUXV>"
2560 #: build/C/man2/prctl.2:794
2562 "Set a new auxiliary vector. The I<arg3> argument should provide the address "
2563 "of the vector. The I<arg4> is the size of the vector."
2567 #: build/C/man2/prctl.2:794
2569 msgid "B<PR_SET_MM_EXE_FILE>"
2572 #. commit b32dfe377102ce668775f8b6b1461f7ad428f8b6
2574 #: build/C/man2/prctl.2:806
2576 "Supersede the I</proc/pid/exe> symbolic link with a new one pointing to a "
2577 "new executable file identified by the file descriptor provided in I<arg3> "
2578 "argument. The file descriptor should be obtained with a regular B<open>(2) "
2583 #: build/C/man2/prctl.2:813
2585 "To change the symbolic link, one needs to unmap all existing executable "
2586 "memory areas, including those created by the kernel itself (for example the "
2587 "kernel usually creates at least one executable memory area for the ELF "
2588 "I<.text> section)."
2592 #: build/C/man2/prctl.2:819
2594 "The second limitation is that such transitions can be done only once in a "
2595 "process life time. Any further attempts will be rejected. This should help "
2596 "system administrators monitor unusual symbolic-link transitions over all "
2597 "processes running on a system."
2601 #: build/C/man2/prctl.2:820
2603 msgid "B<PR_MPX_ENABLE_MANAGEMENT>, B<PR_MPX_DISABLE_MANAGEMENT> (since Linux 3.19) "
2606 #. commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c
2607 #. See also http://lwn.net/Articles/582712/
2608 #. See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler
2609 #. commit e9d1b4f3c60997fe197bf0243cb4a41a44387a88
2611 #: build/C/man2/prctl.2:835
2613 "Enable or disable kernel management of Memory Protection eXtensions (MPX) "
2614 "bounds tables. The I<arg2>, I<arg3>, I<arg4>, and I<arg5> arguments must be "
2619 #: build/C/man2/prctl.2:848
2621 "MPX is a hardware-assisted mechanism for performing bounds checking on "
2622 "pointers. It consists of a set of registers storing bounds information and "
2623 "a set of special instruction prefixes that tell the CPU on which "
2624 "instructions it should do bounds enforcement. There is a limited number of "
2625 "these registers and when there are more pointers than registers, their "
2626 "contents must be \"spilled\" into a set of tables. These tables are called "
2627 "\"bounds tables\" and the MPX B<prctl>() operations control whether the "
2628 "kernel manages their allocation and freeing."
2632 #: build/C/man2/prctl.2:858
2634 "When management is enabled, the kernel will take over allocation and freeing "
2635 "of the bounds tables. It does this by trapping the #BR exceptions that "
2636 "result at first use of missing bounds tables and instead of delivering the "
2637 "exception to user space, it allocates the table and populates the bounds "
2638 "directory with the location of the new table. For freeing, the kernel "
2639 "checks to see if bounds tables are present for memory which is not "
2640 "allocated, and frees them if so."
2644 #: build/C/man2/prctl.2:865
2646 "Before enabling MPX management using B<PR_MPX_ENABLE_MANAGEMENT>, the "
2647 "application must first have allocated a user-space buffer for the bounds "
2648 "directory and placed the location of that directory in the I<bndcfgu> "
2653 #: build/C/man2/prctl.2:872
2655 "These calls will fail if the CPU or kernel does not support MPX. Kernel "
2656 "support for MPX is enabled via the B<CONFIG_X86_INTEL_MPX> configuration "
2657 "option. You can check whether the CPU supports MPX by looking for the 'mpx' "
2658 "CPUID bit, like with the following command:"
2662 #: build/C/man2/prctl.2:874
2663 msgid " cat /proc/cpuinfo | grep ' mpx '"
2667 #: build/C/man2/prctl.2:877
2669 "A thread may not switch in or out of long (64-bit) mode while MPX is "
2674 #: build/C/man2/prctl.2:879
2675 msgid "All threads in a process are affected by these calls."
2679 #: build/C/man2/prctl.2:888
2681 "The child of a B<fork>(2) inherits the state of MPX management. During "
2682 "B<execve>(2), MPX management is reset to a state as if "
2683 "B<PR_MPX_DISABLE_MANAGEMENT> had been called."
2687 #: build/C/man2/prctl.2:892
2689 "For further information on Intel MPX, see the kernel source file "
2690 "I<Documentation/x86/intel_mpx.txt>."
2694 #: build/C/man2/prctl.2:912
2696 "On success, B<PR_GET_DUMPABLE>, B<PR_GET_KEEPCAPS>, B<PR_GET_NO_NEW_PRIVS>, "
2697 "B<PR_GET_THP_DISABLE>, B<PR_CAPBSET_READ>, B<PR_GET_TIMING>, "
2698 "B<PR_GET_TIMERSLACK>, B<PR_GET_SECUREBITS>, B<PR_MCE_KILL_GET>, and (if it "
2699 "returns) B<PR_GET_SECCOMP> return the nonnegative values described above. "
2700 "All other I<option> values return 0 on success. On error, -1 is returned, "
2701 "and I<errno> is set appropriately."
2705 #: build/C/man2/prctl.2:917
2706 msgid "I<arg2> is an invalid address."
2710 #: build/C/man2/prctl.2:930
2712 "I<option> is B<PR_SET_SECCOMP>, I<arg2> is B<SECCOMP_MODE_FILTER>, the "
2713 "system was built with B<CONFIG_SECCOMP_FILTER>, and I<arg3> is an invalid "
2718 #: build/C/man2/prctl.2:935
2719 msgid "The value of I<option> is not recognized."
2723 #: build/C/man2/prctl.2:947
2725 "I<option> is B<PR_MCE_KILL> or B<PR_MCE_KILL_GET> or B<PR_SET_MM>, and "
2726 "unused B<prctl>() arguments were not specified as zero."
2730 #: build/C/man2/prctl.2:952
2731 msgid "I<arg2> is not valid value for this I<option>."
2735 #: build/C/man2/prctl.2:961
2737 "I<option> is B<PR_SET_SECCOMP> or B<PR_GET_SECCOMP>, and the kernel was not "
2738 "configured with B<CONFIG_SECCOMP>."
2742 #: build/C/man2/prctl.2:971
2744 "I<option> is B<PR_SET_SECCOMP>, I<arg2> is B<SECCOMP_MODE_FILTER>, and the "
2745 "kernel was not configured with B<CONFIG_SECCOMP_FILTER>."
2749 #: build/C/man2/prctl.2:977
2750 msgid "I<option> is B<PR_SET_MM>, and one of the following is true"
2754 #: build/C/man2/prctl.2:983
2755 msgid "I<arg4> or I<arg5> is nonzero;"
2759 #: build/C/man2/prctl.2:988
2761 "I<arg3> is greater than B<TASK_SIZE> (the limit on the size of the user "
2762 "address space for this architecture);"
2766 #: build/C/man2/prctl.2:998
2768 "I<arg2> is B<PR_SET_MM_START_CODE>, B<PR_SET_MM_END_CODE>, "
2769 "B<PR_SET_MM_START_DATA>, B<PR_SET_MM_END_DATA>, or B<PR_SET_MM_START_STACK>, "
2770 "and the permissions of the corresponding memory area are not as required;"
2774 #: build/C/man2/prctl.2:1010
2776 "I<arg2> is B<PR_SET_MM_START_BRK> or B<PR_SET_MM_BRK>, and I<arg3> is less "
2777 "than or equal to the end of the data segment or specifies a value that would "
2778 "cause the B<RLIMIT_DATA> resource limit to be exceeded."
2782 #: build/C/man2/prctl.2:1021
2784 "I<option> is B<PR_SET_PTRACER> and I<arg2> is not 0, B<PR_SET_PTRACER_ANY>, "
2785 "or the PID of an existing process."
2789 #: build/C/man2/prctl.2:1029
2790 msgid "I<option> is B<PR_SET_PDEATHSIG> and I<arg2> is not a valid signal number."
2794 #: build/C/man2/prctl.2:1040
2796 "I<option> is B<PR_SET_DUMPABLE> and I<arg2> is neither B<SUID_DUMP_DISABLE> "
2797 "nor B<SUID_DUMP_USER>."
2801 #: build/C/man2/prctl.2:1049
2802 msgid "I<option> is B<PR_SET_TIMING> and I<arg2> is not B<PR_TIMING_STATISTICAL>."
2806 #: build/C/man2/prctl.2:1063
2808 "I<option> is B<PR_SET_NO_NEW_PRIVS> and I<arg2> is not equal to 1 or "
2809 "I<arg3>, I<arg4>, or I<arg5> is nonzero."
2813 #: build/C/man2/prctl.2:1075
2815 "I<option> is B<PR_GET_NO_NEW_PRIVS> and I<arg2>, I<arg3>, I<arg4>, or "
2816 "I<arg5> is nonzero."
2820 #: build/C/man2/prctl.2:1086
2822 "I<option> is B<PR_SET_THP_DISABLE> and I<arg3>, I<arg4>, or I<arg5> is "
2827 #: build/C/man2/prctl.2:1098
2829 "I<option> is B<PR_GET_THP_DISABLE> and I<arg2>, I<arg3>, I<arg4>, or I<arg5> "
2834 #: build/C/man2/prctl.2:1110
2836 "I<option> is B<PR_SET_SECUREBITS>, and the caller does not have the "
2837 "B<CAP_SETPCAP> capability, or tried to unset a \"locked\" flag, or tried to "
2838 "set a flag whose corresponding locked flag was set (see B<capabilities>(7))."
2842 #: build/C/man2/prctl.2:1120
2844 "I<option> is B<PR_SET_KEEPCAPS>, and the callers's "
2845 "B<SECURE_KEEP_CAPS_LOCKED> flag is set (see B<capabilities>(7))."
2849 #: build/C/man2/prctl.2:1128
2851 "I<option> is B<PR_CAPBSET_DROP>, and the caller does not have the "
2852 "B<CAP_SETPCAP> capability."
2856 #: build/C/man2/prctl.2:1136
2858 "I<option> is B<PR_SET_MM>, and the caller does not have the "
2859 "B<CAP_SYS_RESOURCE> capability."
2863 #: build/C/man2/prctl.2:1136
2869 #: build/C/man2/prctl.2:1146
2871 "I<option> is B<PR_SET_MM>, and I<arg3> is B<PR_SET_MM_EXE_FILE>, the file is "
2876 #: build/C/man2/prctl.2:1146
2882 #: build/C/man2/prctl.2:1157
2884 "I<option> is B<PR_SET_MM>, I<arg3> is B<PR_SET_MM_EXE_FILE>, and this the "
2885 "second attempt to change the I</proc/pid/exe> symbolic link, which is "
2890 #: build/C/man2/prctl.2:1157 build/C/man2/signalfd.2:266 build/C/man2/timerfd_create.2:345
2895 #. The following can't actually happen, because prctl() in
2896 #. seccomp mode will cause SIGKILL.
2901 #. .BR PR_SET_SECCOMP ,
2902 #. and secure computing mode is already 1.
2904 #: build/C/man2/prctl.2:1176
2906 "I<option> is B<PR_SET_MM>, I<arg3> is B<PR_SET_MM_EXE_FILE>, and the file "
2907 "descriptor passed in I<arg4> is not valid."
2911 #: build/C/man2/prctl.2:1176
2917 #: build/C/man2/prctl.2:1185
2919 "I<option> was B<PR_MPX_ENABLE_MANAGEMENT> or B<PR_MPX_DISABLE_MANAGEMENT> "
2920 "and the kernel or the CPU does not support MPX management. Check that the "
2921 "kernel and processor have MPX support."
2924 #. The library interface was added in glibc 2.0.6
2926 #: build/C/man2/prctl.2:1190
2927 msgid "The B<prctl>() system call was introduced in Linux 2.1.57."
2931 #: build/C/man2/prctl.2:1197
2933 "This call is Linux-specific. IRIX has a B<prctl>() system call (also "
2934 "introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture), with "
2939 #: build/C/man2/prctl.2:1199
2940 msgid "B<ptrdiff_t prctl(int >I<option>B<, int >I<arg2>B<, int >I<arg3>B<);>"
2944 #: build/C/man2/prctl.2:1204
2946 "and options to get the maximum number of processes per user, get the maximum "
2947 "number of processors the calling process can use, find out whether a "
2948 "specified process is currently blocked, get or set the maximum stack size, "
2953 #: build/C/man2/prctl.2:1207
2954 msgid "B<signal>(2), B<core>(5)"
2958 #: build/C/man3/profil.3:28
2964 #: build/C/man3/profil.3:31
2965 msgid "profil - execution time profile"
2969 #: build/C/man3/profil.3:34
2971 msgid "B<#include E<lt>unistd.hE<gt>>\n"
2975 #: build/C/man3/profil.3:37
2978 "B<int profil(unsigned short *>I<buf>B<, size_t >I<bufsiz>B<,>\n"
2979 "B< size_t >I<offset>B<, unsigned int >I<scale>B<);>\n"
2983 #: build/C/man3/profil.3:46
2984 msgid "B<profil>(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\\ E<lt>\\ 500)"
2988 #: build/C/man3/profil.3:68
2990 "This routine provides a means to find out in what areas your program spends "
2991 "most of its time. The argument I<buf> points to I<bufsiz> bytes of core. "
2992 "Every virtual 10 milliseconds, the user's program counter (PC) is examined: "
2993 "I<offset> is subtracted and the result is multiplied by I<scale> and divided "
2994 "by 65536. If the resulting value is less than I<bufsiz>, then the "
2995 "corresponding entry in I<buf> is incremented. If I<buf> is NULL, profiling "
3000 #: build/C/man3/profil.3:70
3001 msgid "Zero is always returned."
3005 #: build/C/man3/profil.3:72
3006 msgid "Similar to a call in SVr4 (but not POSIX.1-2001)."
3010 #: build/C/man3/profil.3:78
3012 "B<profil>() cannot be used on a program that also uses B<ITIMER_PROF> "
3013 "interval timers (see B<setitimer>(2))."
3017 #: build/C/man3/profil.3:81
3019 "True kernel profiling provides more accurate results. Libc 4.4 contained a "
3020 "kernel patch providing a system call profil."
3024 #: build/C/man3/profil.3:87
3025 msgid "B<gprof>(1), B<sprof>(1), B<setitimer>(2), B<sigaction>(2), B<signal>(2)"
3029 #: build/C/man3/psignal.3:30
3035 #: build/C/man3/psignal.3:30
3041 #: build/C/man3/psignal.3:30 build/C/man3/raise.3:29 build/C/man7/sigevent.7:26
3047 #: build/C/man3/psignal.3:33
3048 msgid "psignal, psiginfo - print signal message"
3052 #: build/C/man3/psignal.3:39
3055 "B<void psignal(int >I<sig>B<, const char *>I<s>B<);>\n"
3056 "B<void psiginfo(const siginfo_t *>I<pinfo>B<, const char *>I<s>B<);>\n"
3060 #: build/C/man3/psignal.3:41
3062 msgid "B<extern const char *const >I<sys_siglist>B<[];>\n"
3066 #: build/C/man3/psignal.3:50
3067 msgid "B<psignal>(): _SVID_SOURCE || _BSD_SOURCE"
3071 #: build/C/man3/psignal.3:53
3073 "B<psiginfo>(): _XOPEN_SOURCE\\ E<gt>=\\ 700 || _POSIX_C_SOURCE\\ E<gt>=\\ "
3078 #: build/C/man3/psignal.3:56
3079 msgid "I<sys_siglist>: _BSD_SOURCE"
3083 #: build/C/man3/psignal.3:65
3085 "The B<psignal>() function displays a message on I<stderr> consisting of the "
3086 "string I<s>, a colon, a space, a string describing the signal number I<sig>, "
3087 "and a trailing newline. If the string I<s> is NULL or empty, the colon and "
3088 "space are omitted. If I<sig> is invalid, the message displayed will "
3089 "indicate an unknown signal."
3093 #: build/C/man3/psignal.3:86
3095 "The B<psiginfo>() function is like B<psignal>(), except that it displays "
3096 "information about the signal described by I<pinfo>, which should point to a "
3097 "valid I<siginfo_t> structure. As well as the signal description, "
3098 "B<psiginfo>() displays information about the origin of the signal, and "
3099 "other information relevant to the signal (e.g., the relevant memory address "
3100 "for hardware-generated signals, the child process ID for B<SIGCHLD>, and the "
3101 "user ID and process ID of the sender, for signals set using B<kill>(2) or "
3106 #: build/C/man3/psignal.3:89
3108 "The array I<sys_siglist> holds the signal description strings indexed by "
3113 #: build/C/man3/psignal.3:95
3114 msgid "The B<psignal>() and B<psiginfo>() functions return no value."
3118 #: build/C/man3/psignal.3:99
3119 msgid "The B<psiginfo>() function was added to glibc in version 2.10."
3123 #: build/C/man3/psignal.3:101
3124 msgid "POSIX.1-2008, 4.3BSD."
3128 #: build/C/man3/psignal.3:105
3129 msgid "In glibc versions up to 2.12, B<psiginfo>() had the following bugs:"
3132 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12107
3133 #. Reportedly now fixed; check glibc 2.13
3135 #: build/C/man3/psignal.3:109
3136 msgid "In some circumstances, a trailing newline is not printed."
3139 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12108
3140 #. Reportedly now fixed; check glibc 2.13
3142 #: build/C/man3/psignal.3:113
3143 msgid "Additional details are not displayed for real-time signals."
3147 #: build/C/man3/psignal.3:118
3148 msgid "B<sigaction>(2), B<perror>(3), B<strsignal>(3), B<signal>(7)"
3152 #: build/C/man3/raise.3:29
3158 #: build/C/man3/raise.3:29
3164 #: build/C/man3/raise.3:32
3165 msgid "raise - send a signal to the caller"
3169 #: build/C/man3/raise.3:37
3171 msgid "B<int raise(int >I<sig>B<);>\n"
3175 #: build/C/man3/raise.3:43
3177 "The B<raise>() function sends a signal to the calling process or thread. "
3178 "In a single-threaded program it is equivalent to"
3182 #: build/C/man3/raise.3:47
3184 msgid "kill(getpid(), sig);\n"
3188 #: build/C/man3/raise.3:51
3189 msgid "In a multithreaded program it is equivalent to"
3193 #: build/C/man3/raise.3:55
3195 msgid "pthread_kill(pthread_self(), sig);\n"
3199 #: build/C/man3/raise.3:61
3201 "If the signal causes a handler to be called, B<raise>() will return only "
3202 "after the signal handler has returned."
3206 #: build/C/man3/raise.3:64
3207 msgid "B<raise>() returns 0 on success, and nonzero for failure."
3211 #: build/C/man3/raise.3:69
3212 msgid "The B<raise>() function is thread-safe."
3216 #: build/C/man3/raise.3:71 build/C/man2/signal.2:112
3217 msgid "C89, C99, POSIX.1-2001."
3220 #. 2.3.2 used the obsolete tkill(), if available.
3222 #: build/C/man3/raise.3:82
3224 "Since version 2.3.3, glibc implements B<raise>() by calling B<tgkill>(2), "
3225 "if the kernel supports that system call. Older glibc versions implemented "
3226 "B<raise>() using B<kill>(2)."
3230 #: build/C/man3/raise.3:89
3232 "B<getpid>(2), B<kill>(2), B<sigaction>(2), B<signal>(2), B<pthread_kill>(3), "
3237 #: build/C/man2/restart_syscall.2:33
3239 msgid "RESTART_SYSCALL"
3243 #: build/C/man2/restart_syscall.2:33 build/C/man2/sgetmask.2:26 build/C/man2/sigreturn.2:30 build/C/man3/sigvec.3:26 build/C/man2/tkill.2:29
3249 #: build/C/man2/restart_syscall.2:36
3250 msgid "restart_syscall - restart a system call after interruption by a stop signal"
3254 #: build/C/man2/restart_syscall.2:38
3255 msgid "B<int restart_syscall(void);>"
3259 #: build/C/man2/restart_syscall.2:41
3260 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
3264 #: build/C/man2/restart_syscall.2:53
3266 "The B<restart_syscall>() system call is used to restart certain system "
3267 "calls after a process that was stopped by a signal (e.g., B<SIGSTOP> or "
3268 "B<SIGTSTP>) is later resumed after receiving a B<SIGCONT> signal. This "
3269 "system call is designed only for internal use by the kernel."
3272 #. These system calls correspond to the special internal errno value
3273 #. ERESTART_RESTARTBLOCK. Each of the system calls has a "restart"
3274 #. helper function that is invoked by restart_syscall().
3275 #. Notable (as at Linux 3.17) is that poll() has such a "restart"
3276 #. function, but ppoll(), select(), and pselect() do not.
3277 #. This means that the latter system calls do not take account of the
3278 #. time spent in the stopped state when restarting.
3280 #: build/C/man2/restart_syscall.2:88
3282 "B<restart_syscall>() is used for restarting only those system calls that, "
3283 "when restarted, should adjust their time-related parameters\\(emnamely "
3284 "B<poll>(2) (since Linux 2.6.24), B<nanosleep>(2) (since Linux 2.6), "
3285 "B<clock_nanosleep>(2) (since Linux 2.6), and B<futex>(2), when employed "
3286 "with the B<FUTEX_WAIT> (since Linux 2.6.22) and B<FUTEX_WAIT_BITSET> (since "
3287 "Linux 2.6.31) operations. B<restart_syscall>() restarts the interrupted "
3288 "system call with a time argument that is suitably adjusted to account for "
3289 "the time that has already elapsed (including the time where the process was "
3290 "stopped by a signal). Without the B<restart_syscall>() mechanism, "
3291 "restarting these system calls would not correctly deduct the already elapsed "
3292 "time when the process continued execution."
3296 #: build/C/man2/restart_syscall.2:92
3298 "The return value of B<restart_syscall>() is the return value of whatever "
3299 "system call is being restarted."
3303 #: build/C/man2/restart_syscall.2:96
3305 "I<errno> is set as per the errors for whatever system call is being "
3306 "restarted by B<restart_syscall>()."
3310 #: build/C/man2/restart_syscall.2:100
3311 msgid "The B<restart_syscall>() system call is present since Linux 2.6."
3315 #: build/C/man2/restart_syscall.2:102
3316 msgid "This system call is Linux-specific."
3320 #: build/C/man2/restart_syscall.2:106
3322 "There is no glibc wrapper for this system call, because it is intended for "
3323 "use only by the kernel and should never be called by applications."
3327 #: build/C/man2/restart_syscall.2:128
3329 "The kernel uses B<restart_syscall>() to ensure that when a system call is "
3330 "restarted after a process has been stopped by a signal and then resumed by "
3331 "B<SIGCONT>, then the time that the process spent in the stopped state is "
3332 "counted against the timeout interval specified in the original system call. "
3333 "In the case of system calls that take a timeout argument and automatically "
3334 "restart after a stop signal plus B<SIGCONT>, but which do not have the "
3335 "B<restart_syscall>() mechanism built in, then, after the process resumes "
3336 "execution, the time that the process spent in the stop state is I<not> "
3337 "counted against the timeout value. Notable examples of system calls that "
3338 "suffer this problem are B<ppoll>(2), B<select>(2), and B<pselect>(2)."
3342 #: build/C/man2/restart_syscall.2:135
3344 "From user space, the operation of B<restart_syscall>() is largely "
3345 "invisible: to the process that made the system call that is restarted, it "
3346 "appears as though that system call executed and returned in the usual "
3350 #. FIXME . ppoll(2), select(2), and pselect(2)
3351 #. should probably get the restart_syscall() treatment:
3352 #. If a select() call is suspended by stop-sig+SIGCONT, the time
3353 #. spent suspended is *not* deducted when the select() is restarted.
3354 #. FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly.
3356 #: build/C/man2/restart_syscall.2:144
3357 msgid "B<sigaction>(2), B<sigreturn>(2), B<signal>(7)"
3361 #: build/C/man2/rt_sigqueueinfo.2:25
3363 msgid "RT_SIGQUEUEINFO"
3367 #: build/C/man2/rt_sigqueueinfo.2:25
3373 #: build/C/man2/rt_sigqueueinfo.2:28
3374 msgid "rt_sigqueueinfo, rt_tgsigqueueinfo - queue a signal and data"
3378 #: build/C/man2/rt_sigqueueinfo.2:31
3381 "B<int rt_sigqueueinfo(pid_t >I<tgid>B<, int >I<sig>B<, siginfo_t "
3386 #: build/C/man2/rt_sigqueueinfo.2:34
3389 "B<int rt_tgsigqueueinfo(pid_t >I<tgid>B<, pid_t >I<tid>B<, int >I<sig>B<,>\n"
3390 "B< siginfo_t *>I<uinfo>B<);>\n"
3394 #: build/C/man2/rt_sigqueueinfo.2:38 build/C/man2/sgetmask.2:36 build/C/man2/tkill.2:41
3395 msgid "I<Note>: There are no glibc wrappers for these system calls; see NOTES."
3399 #: build/C/man2/rt_sigqueueinfo.2:50
3401 "The B<rt_sigqueueinfo>() and B<rt_tgsigqueueinfo>() system calls are the "
3402 "low-level interfaces used to send a signal plus data to a process or "
3403 "thread. The receiver of the signal can obtain the accompanying data by "
3404 "establishing a signal handler with the B<sigaction>(2) B<SA_SIGINFO> flag."
3408 #: build/C/man2/rt_sigqueueinfo.2:56
3410 "These system calls are not intended for direct application use; they are "
3411 "provided to allow the implementation of B<sigqueue>(3) and "
3412 "B<pthread_sigqueue>(3)."
3416 #: build/C/man2/rt_sigqueueinfo.2:68
3418 "The B<rt_sigqueueinfo>() system call sends the signal I<sig> to the thread "
3419 "group with the ID I<tgid>. (The term \"thread group\" is synonymous with "
3420 "\"process\", and I<tid> corresponds to the traditional UNIX process ID.) "
3421 "The signal will be delivered to an arbitrary member of the thread group "
3422 "(i.e., one of the threads that is not currently blocking the signal)."
3426 #: build/C/man2/rt_sigqueueinfo.2:79
3428 "The I<uinfo> argument specifies the data to accompany the signal. This "
3429 "argument is a pointer to a structure of type I<siginfo_t>, described in "
3430 "B<sigaction>(2) (and defined by including I<E<lt>sigaction.hE<gt>>). The "
3431 "caller should set the following fields in this structure:"
3435 #: build/C/man2/rt_sigqueueinfo.2:79 build/C/man7/sigevent.7:88 build/C/man2/wait.2:316
3442 #: build/C/man2/rt_sigqueueinfo.2:95
3444 "This must be one of the B<SI_*> codes in the Linux kernel source file "
3445 "I<include/asm-generic/siginfo.h>, with the restriction that the code must be "
3446 "negative (i.e., cannot be B<SI_USER>, which is used by the kernel to "
3447 "indicate a signal sent by B<kill>(2)) and cannot (since Linux 2.6.39) be "
3448 "B<SI_TKILL> (which is used by the kernel to indicate a signal sent using "
3453 #: build/C/man2/rt_sigqueueinfo.2:95 build/C/man2/wait.2:295
3459 #: build/C/man2/rt_sigqueueinfo.2:99
3460 msgid "This should be set to a process ID, typically the process ID of the sender."
3464 #: build/C/man2/rt_sigqueueinfo.2:99 build/C/man2/wait.2:298
3470 #: build/C/man2/rt_sigqueueinfo.2:103
3471 msgid "This should be set to a user ID, typically the real user ID of the sender."
3475 #: build/C/man2/rt_sigqueueinfo.2:103 build/C/man7/sigevent.7:96
3481 #: build/C/man2/rt_sigqueueinfo.2:110
3483 "This field contains the user data to accompany the signal. For more "
3484 "information, see the description of the last (I<union sigval>) argument of "
3489 #: build/C/man2/rt_sigqueueinfo.2:117
3491 "Internally, the kernel sets the I<si_signo> field to the value specified in "
3492 "I<sig>, so that the receiver of the signal can also obtain the signal number "
3497 #: build/C/man2/rt_sigqueueinfo.2:129
3499 "The B<rt_tgsigqueueinfo>() system call is like B<rt_sigqueueinfo>(), but "
3500 "sends the signal and data to the single thread specified by the combination "
3501 "of I<tgid>, a thread group ID, and I<tid>, a thread in that thread group."
3505 #: build/C/man2/rt_sigqueueinfo.2:134
3507 "On success, these system calls return 0. On error, they return -1 and "
3508 "I<errno> is set to indicate the error."
3512 #: build/C/man2/rt_sigqueueinfo.2:135 build/C/man3/sigqueue.3:92 build/C/man2/sigwaitinfo.2:115 build/C/man2/timer_create.2:178
3518 #: build/C/man2/rt_sigqueueinfo.2:141 build/C/man3/sigqueue.3:98
3520 "The limit of signals which may be queued has been reached. (See "
3521 "B<signal>(7) for further information.)"
3525 #: build/C/man2/rt_sigqueueinfo.2:148
3526 msgid "I<sig>, I<tgid>, or I<tid> was invalid."
3530 #: build/C/man2/rt_sigqueueinfo.2:156
3532 "The caller does not have permission to send the signal to the target. For "
3533 "the required permissions, see B<kill>(2). Or: I<uinfo-E<gt>si_code> is "
3538 #: build/C/man2/rt_sigqueueinfo.2:162
3539 msgid "B<rt_sigqueueinfo>(): No thread group matching I<tgid> was found."
3543 #: build/C/man2/rt_sigqueueinfo.2:169
3544 msgid "B<rt_tgsigqueinfo>(): No thread matching I<tgid> and I<tid> was found."
3548 #: build/C/man2/rt_sigqueueinfo.2:176
3550 "The B<rt_sigqueueinfo>() system call was added to Linux in version 2.2. "
3551 "The B<rt_tgsigqueueinfo>() system call was added to Linux in version "
3556 #: build/C/man2/rt_sigqueueinfo.2:178 build/C/man2/sgetmask.2:75 build/C/man2/timerfd_create.2:380
3557 msgid "These system calls are Linux-specific."
3561 #: build/C/man2/rt_sigqueueinfo.2:183
3563 "Since these system calls are not intended for application use, there are no "
3564 "glibc wrapper functions; use B<syscall>(2) in the unlikely case that you "
3565 "want to call them directly."
3569 #: build/C/man2/rt_sigqueueinfo.2:188
3571 "As with B<kill>(2), the null signal (0) can be used to check if the "
3572 "specified process or thread exists."
3576 #: build/C/man2/rt_sigqueueinfo.2:196
3578 "B<kill>(2), B<sigaction>(2), B<sigprocmask>(2), B<tgkill>(2), "
3579 "B<pthread_sigqueue>(3), B<sigqueue>(3), B<signal>(7)"
3583 #: build/C/man2/s390_runtime_instr.2:25
3585 msgid "S390_RUNTIME_INSTR"
3589 #: build/C/man2/s390_runtime_instr.2:25
3595 #: build/C/man2/s390_runtime_instr.2:28
3596 msgid "s390_runtime_instr - enable/disable s390 CPU run-time instrumentation"
3600 #: build/C/man2/s390_runtime_instr.2:31
3602 msgid "B<#include E<lt>asm/runtime_instr.hE<gt>>\n"
3606 #: build/C/man2/s390_runtime_instr.2:33
3608 msgid "B<int s390_runtime_instr(int >I<command>B<, int >I<signum>B<);>\n"
3612 #: build/C/man2/s390_runtime_instr.2:39
3614 "The B<s390_runtime_instr>() system call starts or stops CPU run-time "
3615 "instrumentation for the calling thread."
3619 #: build/C/man2/s390_runtime_instr.2:47
3621 "The I<command> argument controls whether run-time instrumentation is started "
3622 "(B<S390_RUNTIME_INSTR_START>, 1) or stopped (B<S390_RUNTIME_INSTR_STOP>, 2) "
3623 "for the calling thread."
3627 #: build/C/man2/s390_runtime_instr.2:54
3629 "The I<signum> argument specifies the number of a real-time signal. The "
3630 "real-time signal is sent to the thread if the run-time instrumentation "
3631 "buffer is full or if the run-time-instrumentation-halted interrupt occurred."
3635 #: build/C/man2/s390_runtime_instr.2:65
3637 "On success, B<s390_runtime_instr>() returns 0 and enables the thread for "
3638 "run-time instrumentation by assigning the thread a default run-time "
3639 "instrumentation control block. The caller can then read and modify the "
3640 "control block and start the run-time instrumentation. On error, -1 is "
3641 "returned and I<errno> is set to one of the error codes listed below."
3645 #: build/C/man2/s390_runtime_instr.2:73
3647 "The value specified in I<command> is not a valid command or the value "
3648 "specified in I<signum> is not a real-time signal number."
3652 #: build/C/man2/s390_runtime_instr.2:76
3653 msgid "Allocating memory for the run-time instrumentation control block failed."
3657 #: build/C/man2/s390_runtime_instr.2:76
3659 msgid "B<EOPNOTSUPP>"
3663 #: build/C/man2/s390_runtime_instr.2:79
3664 msgid "The run-time instrumentation facility is not available."
3668 #: build/C/man2/s390_runtime_instr.2:81
3669 msgid "This system call is available since Linux 3.7."
3673 #: build/C/man2/s390_runtime_instr.2:84
3675 "This Linux-specific system call is available only on the s390 architecture. "
3676 "The run-time instrumentation facility is available beginning with System z "
3681 #: build/C/man2/s390_runtime_instr.2:88
3683 "Glibc does not provide a wrapper for this system call, use B<syscall>(2) to "
3688 #: build/C/man2/s390_runtime_instr.2:91
3689 msgid "B<syscall>(2), B<signal>(7)"
3693 #: build/C/man2/sgetmask.2:26
3699 #: build/C/man2/sgetmask.2:29
3700 msgid "sgetmask, ssetmask - manipulation of signal mask (obsolete)"
3704 #: build/C/man2/sgetmask.2:31
3705 msgid "B<long sgetmask(void);>"
3709 #: build/C/man2/sgetmask.2:33
3710 msgid "B<long ssetmask(long >I<newmask>B<);>"
3714 #: build/C/man2/sgetmask.2:42
3716 "These system calls are obsolete. I<Do not use them>; use B<sigprocmask>(2) "
3721 #: build/C/man2/sgetmask.2:45
3722 msgid "B<sgetmask>() returns the signal mask of the calling process."
3726 #: build/C/man2/sgetmask.2:50
3728 "B<ssetmask>() sets the signal mask of the calling process to the value "
3729 "given in I<newmask>. The previous signal mask is returned."
3733 #: build/C/man2/sgetmask.2:59
3735 "The signal masks dealt with by these two system calls are plain bit masks "
3736 "(unlike the I<sigset_t> used by B<sigprocmask>(2)); use B<sigmask>(3) to "
3737 "create and inspect these masks."
3741 #: build/C/man2/sgetmask.2:64
3743 "B<sgetmask>() always successfully returns the signal mask. B<ssetmask>() "
3744 "always succeeds, and returns the previous signal mask."
3748 #: build/C/man2/sgetmask.2:66
3749 msgid "These system calls always succeed."
3752 #. f6187769dae48234f3877df3c4d99294cc2254fa
3754 #: build/C/man2/sgetmask.2:73
3756 "Since Linux 3.16, support for these system calls is optional, depending on "
3757 "whether the kernel was built with the B<CONFIG_SGETMASK_SYSCALL> option."
3761 #: build/C/man2/sgetmask.2:79
3763 "Glibc does not provide wrappers for these obsolete system calls; in the "
3764 "unlikely event that you want to call them, use B<syscall>(2)."
3768 #: build/C/man2/sgetmask.2:82
3770 "These system calls are unaware of signal numbers greater than 31 (i.e., "
3771 "real-time signals)."
3775 #: build/C/man2/sgetmask.2:84
3776 msgid "These system calls do not exist on x86-64."
3780 #: build/C/man2/sgetmask.2:89
3781 msgid "It is not possible to block B<SIGSTOP> or B<SIGKILL>."
3785 #: build/C/man2/sgetmask.2:92
3786 msgid "B<sigprocmask>(2), B<signal>(7)"
3790 #: build/C/man2/sigaction.2:49
3796 #: build/C/man2/sigaction.2:49
3802 #: build/C/man2/sigaction.2:52
3803 msgid "sigaction - examine and change a signal action"
3807 #: build/C/man2/sigaction.2:58
3810 "B<int sigaction(int >I<signum>B<, const struct sigaction *>I<act>B<,>\n"
3811 "B< struct sigaction *>I<oldact>B<);>\n"
3815 #: build/C/man2/sigaction.2:68
3817 "B<sigaction>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || "
3822 #: build/C/man2/sigaction.2:71
3823 msgid "I<siginfo_t>: _POSIX_C_SOURCE E<gt>= 199309L"
3827 #: build/C/man2/sigaction.2:80
3829 "The B<sigaction>() system call is used to change the action taken by a "
3830 "process on receipt of a specific signal. (See B<signal>(7) for an overview "
3835 #: build/C/man2/sigaction.2:86
3837 "I<signum> specifies the signal and can be any valid signal except B<SIGKILL> "
3842 #: build/C/man2/sigaction.2:97
3844 "If I<act> is non-NULL, the new action for signal I<signum> is installed from "
3845 "I<act>. If I<oldact> is non-NULL, the previous action is saved in "
3850 #: build/C/man2/sigaction.2:101
3851 msgid "The I<sigaction> structure is defined as something like:"
3855 #: build/C/man2/sigaction.2:111
3858 "struct sigaction {\n"
3859 " void (*sa_handler)(int);\n"
3860 " void (*sa_sigaction)(int, siginfo_t *, void *);\n"
3861 " sigset_t sa_mask;\n"
3863 " void (*sa_restorer)(void);\n"
3868 #: build/C/man2/sigaction.2:118
3870 "On some architectures a union is involved: do not assign to both "
3871 "I<sa_handler> and I<sa_sigaction>."
3875 #: build/C/man2/sigaction.2:127
3877 "The I<sa_restorer> field is not intended for application use. (POSIX does "
3878 "not specify a I<sa_restorer> field.) Some further details of purpose of "
3879 "this field can be found in B<sigreturn>(2)."
3883 #: build/C/man2/sigaction.2:137
3885 "I<sa_handler> specifies the action to be associated with I<signum> and may "
3886 "be B<SIG_DFL> for the default action, B<SIG_IGN> to ignore this signal, or a "
3887 "pointer to a signal handling function. This function receives the signal "
3888 "number as its only argument."
3892 #: build/C/man2/sigaction.2:159
3894 "If B<SA_SIGINFO> is specified in I<sa_flags>, then I<sa_sigaction> (instead "
3895 "of I<sa_handler>) specifies the signal-handling function for I<signum>. "
3896 "This function receives the signal number as its first argument, a pointer to "
3897 "a I<siginfo_t> as its second argument and a pointer to a I<ucontext_t> (cast "
3898 "to I<void\\ *>) as its third argument. (Commonly, the handler function "
3899 "doesn't make any use of the third argument. See B<getcontext>(3) for "
3900 "further information about I<ucontext_t>.)"
3904 #: build/C/man2/sigaction.2:169
3906 "I<sa_mask> specifies a mask of signals which should be blocked (i.e., added "
3907 "to the signal mask of the thread in which the signal handler is invoked) "
3908 "during execution of the signal handler. In addition, the signal which "
3909 "triggered the handler will be blocked, unless the B<SA_NODEFER> flag is "
3914 #: build/C/man2/sigaction.2:173
3916 "I<sa_flags> specifies a set of flags which modify the behavior of the "
3917 "signal. It is formed by the bitwise OR of zero or more of the following:"
3921 #: build/C/man2/sigaction.2:174
3923 msgid "B<SA_NOCLDSTOP>"
3927 #: build/C/man2/sigaction.2:191
3929 "If I<signum> is B<SIGCHLD>, do not receive notification when child processes "
3930 "stop (i.e., when they receive one of B<SIGSTOP>, B<SIGTSTP>, B<SIGTTIN>, or "
3931 "B<SIGTTOU>) or resume (i.e., they receive B<SIGCONT>) (see B<wait>(2)). "
3932 "This flag is meaningful only when establishing a handler for B<SIGCHLD>."
3936 #: build/C/man2/sigaction.2:191
3938 msgid "B<SA_NOCLDWAIT> (since Linux 2.6)"
3941 #. To be precise: Linux 2.5.60 -- MTK
3943 #: build/C/man2/sigaction.2:205
3945 "If I<signum> is B<SIGCHLD>, do not transform children into zombies when they "
3946 "terminate. See also B<waitpid>(2). This flag is meaningful only when "
3947 "establishing a handler for B<SIGCHLD>, or when setting that signal's "
3948 "disposition to B<SIG_DFL>."
3952 #: build/C/man2/sigaction.2:217
3954 "If the B<SA_NOCLDWAIT> flag is set when establishing a handler for "
3955 "B<SIGCHLD>, POSIX.1 leaves it unspecified whether a B<SIGCHLD> signal is "
3956 "generated when a child process terminates. On Linux, a B<SIGCHLD> signal is "
3957 "generated in this case; on some other implementations, it is not."
3961 #: build/C/man2/sigaction.2:217
3963 msgid "B<SA_NODEFER>"
3967 #: build/C/man2/sigaction.2:224
3969 "Do not prevent the signal from being received from within its own signal "
3970 "handler. This flag is meaningful only when establishing a signal handler. "
3971 "B<SA_NOMASK> is an obsolete, nonstandard synonym for this flag."
3975 #: build/C/man2/sigaction.2:224
3977 msgid "B<SA_ONSTACK>"
3981 #: build/C/man2/sigaction.2:230
3983 "Call the signal handler on an alternate signal stack provided by "
3984 "B<sigaltstack>(2). If an alternate stack is not available, the default "
3985 "stack will be used. This flag is meaningful only when establishing a signal "
3990 #: build/C/man2/sigaction.2:230
3992 msgid "B<SA_RESETHAND>"
3996 #: build/C/man2/sigaction.2:236
3998 "Restore the signal action to the default upon entry to the signal handler. "
3999 "This flag is meaningful only when establishing a signal handler. "
4000 "B<SA_ONESHOT> is an obsolete, nonstandard synonym for this flag."
4004 #: build/C/man2/sigaction.2:236
4006 msgid "B<SA_RESTART>"
4010 #: build/C/man2/sigaction.2:244
4012 "Provide behavior compatible with BSD signal semantics by making certain "
4013 "system calls restartable across signals. This flag is meaningful only when "
4014 "establishing a signal handler. See B<signal>(7) for a discussion of system "
4019 #: build/C/man2/sigaction.2:244
4021 msgid "B<SA_RESTORER>"
4025 #: build/C/man2/sigaction.2:253
4027 "I<Not intended for application use>. This flag is used by C libraries to "
4028 "indicate that the I<sa_restorer> field contains the address of a \"signal "
4029 "trampoline\". See B<sigreturn>(2) for more details."
4033 #: build/C/man2/sigaction.2:253
4035 msgid "B<SA_SIGINFO> (since Linux 2.2)"
4040 #. field was added in Linux 2.1.86.)
4042 #: build/C/man2/sigaction.2:264
4044 "The signal handler takes three arguments, not one. In this case, "
4045 "I<sa_sigaction> should be set instead of I<sa_handler>. This flag is "
4046 "meaningful only when establishing a signal handler."
4050 #: build/C/man2/sigaction.2:271
4052 "The I<siginfo_t> argument to I<sa_sigaction> is a struct with the following "
4057 #. The siginfo_t 'si_trapno' field seems to be used only on SPARC and Alpha;
4058 #. this page could use a little more detail on its purpose there.
4059 #. In the kernel: si_tid
4061 #: build/C/man2/sigaction.2:309
4065 " int si_signo; /* Signal number */\n"
4066 " int si_errno; /* An errno value */\n"
4067 " int si_code; /* Signal code */\n"
4068 " int si_trapno; /* Trap number that caused\n"
4069 " hardware-generated signal\n"
4070 " (unused on most architectures) */\n"
4071 " pid_t si_pid; /* Sending process ID */\n"
4072 " uid_t si_uid; /* Real user ID of sending process */\n"
4073 " int si_status; /* Exit value or signal */\n"
4074 " clock_t si_utime; /* User time consumed */\n"
4075 " clock_t si_stime; /* System time consumed */\n"
4076 " sigval_t si_value; /* Signal value */\n"
4077 " int si_int; /* POSIX.1b signal */\n"
4078 " void *si_ptr; /* POSIX.1b signal */\n"
4079 " int si_overrun; /* Timer overrun count;\n"
4080 " POSIX.1b timers */\n"
4081 " int si_timerid; /* Timer ID; POSIX.1b timers */\n"
4082 " void *si_addr; /* Memory location which caused fault */\n"
4083 " long si_band; /* Band event (was I<int> in\n"
4084 " glibc 2.3.2 and earlier) */\n"
4085 " int si_fd; /* File descriptor */\n"
4086 " short si_addr_lsb; /* Least significant bit of address\n"
4087 " (since Linux 2.6.32) */\n"
4088 " void *si_call_addr; /* Address of system call instruction\n"
4089 " (since Linux 3.5) */\n"
4090 " int si_syscall; /* Number of attempted system call\n"
4091 " (since Linux 3.5) */\n"
4092 " unsigned int si_arch; /* Architecture of attempted system call\n"
4093 " (since Linux 3.5) */\n"
4098 #: build/C/man2/sigaction.2:318
4100 "I<si_signo>, I<si_errno> and I<si_code> are defined for all signals. "
4101 "(I<si_errno> is generally unused on Linux.) The rest of the struct may be a "
4102 "union, so that one should read only the fields that are meaningful for the "
4107 #: build/C/man2/sigaction.2:333
4109 "Signals sent with B<kill>(2) and B<sigqueue>(3) fill in I<si_pid> and "
4110 "I<si_uid>. In addition, signals sent with B<sigqueue>(3) fill in I<si_int> "
4111 "and I<si_ptr> with the values specified by the sender of the signal; see "
4112 "B<sigqueue>(3) for more details."
4116 #: build/C/man2/sigaction.2:349
4118 "Signals sent by POSIX.1b timers (since Linux 2.6) fill in I<si_overrun> and "
4119 "I<si_timerid>. The I<si_timerid> field is an internal ID used by the kernel "
4120 "to identify the timer; it is not the same as the timer ID returned by "
4121 "B<timer_create>(2). The I<si_overrun> field is the timer overrun count; "
4122 "this is the same information as is obtained by a call to "
4123 "B<timer_getoverrun>(2). These fields are nonstandard Linux extensions."
4127 #: build/C/man2/sigaction.2:364
4129 "Signals sent for message queue notification (see the description of "
4130 "B<SIGEV_SIGNAL> in B<mq_notify>(3)) fill in I<si_int>/I<si_ptr>, with the "
4131 "I<sigev_value> supplied to B<mq_notify>(3); I<si_pid>, with the process ID "
4132 "of the message sender; and I<si_uid>, with the real user ID of the message "
4137 #. When si_utime and si_stime where originally implemented, the
4138 #. measurement unit was HZ, which was the same as clock ticks
4139 #. (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and
4140 #. was *still* used as the unit to return the info these fields,
4141 #. with the result that the field values depended on the the
4142 #. configured HZ. Of course, the should have been measured in
4143 #. USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to
4144 #. convert to seconds. I have a queued patch to fix this:
4145 #. http://thread.gmane.org/gmane.linux.kernel/698061/ .
4146 #. This patch made it into 2.6.27.
4147 #. But note that these fields still don't return the times of
4148 #. waited-for children (as is done by getrusage() and times()
4149 #. and wait4()). Solaris 8 does include child times.
4151 #: build/C/man2/sigaction.2:411
4153 "B<SIGCHLD> fills in I<si_pid>, I<si_uid>, I<si_status>, I<si_utime>, and "
4154 "I<si_stime>, providing information about the child. The I<si_pid> field is "
4155 "the process ID of the child; I<si_uid> is the child's real user ID. The "
4156 "I<si_status> field contains the exit status of the child (if I<si_code> is "
4157 "B<CLD_EXITED>), or the signal number that caused the process to change "
4158 "state. The I<si_utime> and I<si_stime> contain the user and system CPU time "
4159 "used by the child process; these fields do not include the times used by "
4160 "waited-for children (unlike B<getrusage>(2) and B<times>(2)). In kernels "
4161 "up to 2.6, and since 2.6.27, these fields report CPU time in units of "
4162 "I<sysconf(_SC_CLK_TCK)>. In 2.6 kernels before 2.6.27, a bug meant that "
4163 "these fields reported time in units of the (configurable) system jiffy (see "
4168 #: build/C/man2/sigaction.2:458
4170 "B<SIGILL>, B<SIGFPE>, B<SIGSEGV>, B<SIGBUS>, and B<SIGTRAP> fill in "
4171 "I<si_addr> with the address of the fault. On some architectures, these "
4172 "signals also fill in the I<si_trapno> field. Some suberrors of B<SIGBUS>, "
4173 "in particular B<BUS_MCEERR_AO> and B<BUS_MCEERR_AR>, also fill in "
4174 "I<si_addr_lsb>. This field indicates the least significant bit of the "
4175 "reported address and therefore the extent of the corruption. For example, "
4176 "if a full page was corrupted, I<si_addr_lsb> contains "
4177 "I<log2(sysconf(_SC_PAGESIZE))>. When B<SIGTRAP> is delivered in response to "
4178 "a B<ptrace>(2) event (PTRACE_EVENT_foo), I<si_addr> is not populated, but "
4179 "I<si_pid> and I<si_uid> are populated with the respective process ID and "
4180 "user ID responsible for delivering the trap. In the case of B<seccomp>(2), "
4181 "the tracee will be shown as delivering the event. B<BUS_MCEERR_*> and "
4182 "I<si_addr_lsb> are Linux-specific extensions."
4186 #: build/C/man2/sigaction.2:472
4188 "B<SIGIO>/B<SIGPOLL> (the two names are synonyms on Linux) fills in "
4189 "I<si_band> and I<si_fd>. The I<si_band> event is a bit mask containing the "
4190 "same values as are filled in the I<revents> field by B<poll>(2). The "
4191 "I<si_fd> field indicates the file descriptor for which the I/O event "
4195 #. commit a0727e8ce513fe6890416da960181ceb10fbfae6
4197 #: build/C/man2/sigaction.2:485
4199 "B<SIGSYS>, generated (since Linux 3.5) when a seccomp filter returns "
4200 "B<SECCOMP_RET_TRAP>, fills in I<si_call_addr>, I<si_syscall>, I<si_arch>, "
4201 "I<si_errno>, and other fields as described in B<seccomp>(2)."
4205 #: build/C/man2/sigaction.2:495
4207 "I<si_code> is a value (not a bit mask) indicating why this signal was sent. "
4208 "For a B<ptrace>(2) event, I<si_code> will contain B<SIGTRAP> and have the "
4209 "ptrace event in the high byte:"
4213 #: build/C/man2/sigaction.2:498
4215 msgid " (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
4219 #: build/C/man2/sigaction.2:504
4221 "For a regular signal, the following list shows the values which can be "
4222 "placed in I<si_code> for any signal, along with reason that the signal was "
4227 #: build/C/man2/sigaction.2:505
4233 #: build/C/man2/sigaction.2:508
4238 #: build/C/man2/sigaction.2:508
4240 msgid "B<SI_KERNEL>"
4244 #: build/C/man2/sigaction.2:511
4245 msgid "Sent by the kernel."
4249 #: build/C/man2/sigaction.2:511
4255 #: build/C/man2/sigaction.2:514
4256 msgid "B<sigqueue>(3)."
4260 #: build/C/man2/sigaction.2:514
4266 #: build/C/man2/sigaction.2:517
4267 msgid "POSIX timer expired."
4271 #: build/C/man2/sigaction.2:517
4273 msgid "B<SI_MESGQ> (since Linux 2.6.6)"
4277 #: build/C/man2/sigaction.2:521
4278 msgid "POSIX message queue state changed; see B<mq_notify>(3)."
4282 #: build/C/man2/sigaction.2:521
4284 msgid "B<SI_ASYNCIO>"
4288 #: build/C/man2/sigaction.2:524
4289 msgid "AIO completed."
4293 #: build/C/man2/sigaction.2:524
4299 #: build/C/man2/sigaction.2:533
4301 "Queued B<SIGIO> (only in kernels up to Linux 2.2; from Linux 2.4 onward "
4302 "B<SIGIO>/B<SIGPOLL> fills in I<si_code> as described below)."
4306 #: build/C/man2/sigaction.2:533
4308 msgid "B<SI_TKILL> (since Linux 2.4.19)"
4311 #. SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
4312 #. It appears to have been an idea that was tried during 2.5.6
4313 #. through to 2.5.24 and then was backed out.
4315 #: build/C/man2/sigaction.2:541
4316 msgid "B<tkill>(2) or B<tgkill>(2)."
4320 #: build/C/man2/sigaction.2:548
4321 msgid "The following values can be placed in I<si_code> for a B<SIGILL> signal:"
4325 #: build/C/man2/sigaction.2:549
4327 msgid "B<ILL_ILLOPC>"
4331 #: build/C/man2/sigaction.2:552
4332 msgid "Illegal opcode."
4336 #: build/C/man2/sigaction.2:552
4338 msgid "B<ILL_ILLOPN>"
4342 #: build/C/man2/sigaction.2:555
4343 msgid "Illegal operand."
4347 #: build/C/man2/sigaction.2:555
4349 msgid "B<ILL_ILLADR>"
4353 #: build/C/man2/sigaction.2:558
4354 msgid "Illegal addressing mode."
4358 #: build/C/man2/sigaction.2:558
4360 msgid "B<ILL_ILLTRP>"
4364 #: build/C/man2/sigaction.2:561
4365 msgid "Illegal trap."
4369 #: build/C/man2/sigaction.2:561
4371 msgid "B<ILL_PRVOPC>"
4375 #: build/C/man2/sigaction.2:564
4376 msgid "Privileged opcode."
4380 #: build/C/man2/sigaction.2:564
4382 msgid "B<ILL_PRVREG>"
4386 #: build/C/man2/sigaction.2:567
4387 msgid "Privileged register."
4391 #: build/C/man2/sigaction.2:567
4393 msgid "B<ILL_COPROC>"
4397 #: build/C/man2/sigaction.2:570
4398 msgid "Coprocessor error."
4402 #: build/C/man2/sigaction.2:570
4404 msgid "B<ILL_BADSTK>"
4408 #: build/C/man2/sigaction.2:573
4409 msgid "Internal stack error."
4413 #: build/C/man2/sigaction.2:580
4414 msgid "The following values can be placed in I<si_code> for a B<SIGFPE> signal:"
4418 #: build/C/man2/sigaction.2:581
4420 msgid "B<FPE_INTDIV>"
4424 #: build/C/man2/sigaction.2:584
4425 msgid "Integer divide by zero."
4429 #: build/C/man2/sigaction.2:584
4431 msgid "B<FPE_INTOVF>"
4435 #: build/C/man2/sigaction.2:587
4436 msgid "Integer overflow."
4440 #: build/C/man2/sigaction.2:587
4442 msgid "B<FPE_FLTDIV>"
4446 #: build/C/man2/sigaction.2:590
4447 msgid "Floating-point divide by zero."
4451 #: build/C/man2/sigaction.2:590
4453 msgid "B<FPE_FLTOVF>"
4457 #: build/C/man2/sigaction.2:593
4458 msgid "Floating-point overflow."
4462 #: build/C/man2/sigaction.2:593
4464 msgid "B<FPE_FLTUND>"
4468 #: build/C/man2/sigaction.2:596
4469 msgid "Floating-point underflow."
4473 #: build/C/man2/sigaction.2:596
4475 msgid "B<FPE_FLTRES>"
4479 #: build/C/man2/sigaction.2:599
4480 msgid "Floating-point inexact result."
4484 #: build/C/man2/sigaction.2:599
4486 msgid "B<FPE_FLTINV>"
4490 #: build/C/man2/sigaction.2:602
4491 msgid "Floating-point invalid operation."
4495 #: build/C/man2/sigaction.2:602
4497 msgid "B<FPE_FLTSUB>"
4501 #: build/C/man2/sigaction.2:605
4502 msgid "Subscript out of range."
4506 #: build/C/man2/sigaction.2:612
4507 msgid "The following values can be placed in I<si_code> for a B<SIGSEGV> signal:"
4511 #: build/C/man2/sigaction.2:613
4513 msgid "B<SEGV_MAPERR>"
4517 #: build/C/man2/sigaction.2:616
4518 msgid "Address not mapped to object."
4522 #: build/C/man2/sigaction.2:616
4524 msgid "B<SEGV_ACCERR>"
4528 #: build/C/man2/sigaction.2:619
4529 msgid "Invalid permissions for mapped object."
4533 #: build/C/man2/sigaction.2:626
4534 msgid "The following values can be placed in I<si_code> for a B<SIGBUS> signal:"
4538 #: build/C/man2/sigaction.2:627
4540 msgid "B<BUS_ADRALN>"
4544 #: build/C/man2/sigaction.2:630
4545 msgid "Invalid address alignment."
4549 #: build/C/man2/sigaction.2:630
4551 msgid "B<BUS_ADRERR>"
4555 #: build/C/man2/sigaction.2:633
4556 msgid "Nonexistent physical address."
4560 #: build/C/man2/sigaction.2:633
4562 msgid "B<BUS_OBJERR>"
4566 #: build/C/man2/sigaction.2:636
4567 msgid "Object-specific hardware error."
4571 #: build/C/man2/sigaction.2:636
4573 msgid "B<BUS_MCEERR_AR> (since Linux 2.6.32)"
4577 #: build/C/man2/sigaction.2:639
4578 msgid "Hardware memory error consumed on a machine check; action required."
4582 #: build/C/man2/sigaction.2:639
4584 msgid "B<BUS_MCEERR_AO> (since Linux 2.6.32)"
4588 #: build/C/man2/sigaction.2:642
4589 msgid "Hardware memory error detected in process but not consumed; action optional."
4593 #: build/C/man2/sigaction.2:649
4594 msgid "The following values can be placed in I<si_code> for a B<SIGTRAP> signal:"
4598 #: build/C/man2/sigaction.2:650
4600 msgid "B<TRAP_BRKPT>"
4604 #: build/C/man2/sigaction.2:653
4605 msgid "Process breakpoint."
4609 #: build/C/man2/sigaction.2:653
4611 msgid "B<TRAP_TRACE>"
4615 #: build/C/man2/sigaction.2:656
4616 msgid "Process trace trap."
4620 #: build/C/man2/sigaction.2:656
4622 msgid "B<TRAP_BRANCH> (since Linux 2.4)"
4626 #: build/C/man2/sigaction.2:659
4627 msgid "Process taken branch trap."
4631 #: build/C/man2/sigaction.2:659
4633 msgid "B<TRAP_HWBKPT> (since Linux 2.4)"
4637 #: build/C/man2/sigaction.2:662
4638 msgid "Hardware breakpoint/watchpoint."
4642 #: build/C/man2/sigaction.2:669
4643 msgid "The following values can be placed in I<si_code> for a B<SIGCHLD> signal:"
4647 #: build/C/man2/sigaction.2:670
4649 msgid "B<CLD_EXITED>"
4653 #: build/C/man2/sigaction.2:673
4654 msgid "Child has exited."
4658 #: build/C/man2/sigaction.2:673
4660 msgid "B<CLD_KILLED>"
4664 #: build/C/man2/sigaction.2:676
4665 msgid "Child was killed."
4669 #: build/C/man2/sigaction.2:676
4671 msgid "B<CLD_DUMPED>"
4675 #: build/C/man2/sigaction.2:679
4676 msgid "Child terminated abnormally."
4680 #: build/C/man2/sigaction.2:679
4682 msgid "B<CLD_TRAPPED>"
4686 #: build/C/man2/sigaction.2:682
4687 msgid "Traced child has trapped."
4691 #: build/C/man2/sigaction.2:682
4693 msgid "B<CLD_STOPPED>"
4697 #: build/C/man2/sigaction.2:685
4698 msgid "Child has stopped."
4702 #: build/C/man2/sigaction.2:685
4704 msgid "B<CLD_CONTINUED> (since Linux 2.6.9)"
4708 #: build/C/man2/sigaction.2:688
4709 msgid "Stopped child has continued."
4713 #: build/C/man2/sigaction.2:695
4715 "The following values can be placed in I<si_code> for a B<SIGIO>/B<SIGPOLL> "
4720 #: build/C/man2/sigaction.2:696
4726 #: build/C/man2/sigaction.2:699
4727 msgid "Data input available."
4731 #: build/C/man2/sigaction.2:699
4737 #: build/C/man2/sigaction.2:702
4738 msgid "Output buffers available."
4742 #: build/C/man2/sigaction.2:702
4748 #: build/C/man2/sigaction.2:705
4749 msgid "Input message available."
4753 #: build/C/man2/sigaction.2:705
4759 #: build/C/man2/sigaction.2:708
4764 #: build/C/man2/sigaction.2:708
4770 #: build/C/man2/sigaction.2:711
4771 msgid "High priority input available."
4775 #: build/C/man2/sigaction.2:711
4781 #: build/C/man2/sigaction.2:714
4782 msgid "Device disconnected."
4786 #: build/C/man2/sigaction.2:721
4787 msgid "The following value can be placed in I<si_code> for a B<SIGSYS> signal:"
4791 #: build/C/man2/sigaction.2:722
4793 msgid "B<SYS_SECCOMP> (since Linux 3.5)"
4797 #: build/C/man2/sigaction.2:727
4798 msgid "Triggered by a B<seccomp>(2) filter rule."
4802 #: build/C/man2/sigaction.2:733
4804 "B<sigaction>() returns 0 on success; on error, -1 is returned, and I<errno> "
4805 "is set to indicate the error."
4809 #: build/C/man2/sigaction.2:738
4811 "I<act> or I<oldact> points to memory which is not a valid part of the "
4812 "process address space."
4816 #: build/C/man2/sigaction.2:745
4818 "An invalid signal was specified. This will also be generated if an attempt "
4819 "is made to change the action for B<SIGKILL> or B<SIGSTOP>, which cannot be "
4820 "caught or ignored."
4823 #. SVr4 does not document the EINTR condition.
4825 #: build/C/man2/sigaction.2:748
4826 msgid "POSIX.1-2001, SVr4."
4830 #: build/C/man2/sigaction.2:756 build/C/man7/signal.7:105
4832 "A child created via B<fork>(2) inherits a copy of its parent's signal "
4833 "dispositions. During an B<execve>(2), the dispositions of handled signals "
4834 "are reset to the default; the dispositions of ignored signals are left "
4839 #: build/C/man2/sigaction.2:774 build/C/man2/signal.2:134
4841 "According to POSIX, the behavior of a process is undefined after it ignores "
4842 "a B<SIGFPE>, B<SIGILL>, or B<SIGSEGV> signal that was not generated by "
4843 "B<kill>(2) or B<raise>(3). Integer division by zero has undefined result. "
4844 "On some architectures it will generate a B<SIGFPE> signal. (Also dividing "
4845 "the most negative integer by -1 may generate B<SIGFPE>.) Ignoring this "
4846 "signal might lead to an endless loop."
4850 #: build/C/man2/sigaction.2:791
4852 "POSIX.1-1990 disallowed setting the action for B<SIGCHLD> to B<SIG_IGN>. "
4853 "POSIX.1-2001 allows this possibility, so that ignoring B<SIGCHLD> can be "
4854 "used to prevent the creation of zombies (see B<wait>(2)). Nevertheless, the "
4855 "historical BSD and System\\ V behaviors for ignoring B<SIGCHLD> differ, so "
4856 "that the only completely portable method of ensuring that terminated "
4857 "children do not become zombies is to catch the B<SIGCHLD> signal and perform "
4858 "a B<wait>(2) or similar."
4862 #: build/C/man2/sigaction.2:804
4864 "POSIX.1-1990 specified only B<SA_NOCLDSTOP>. POSIX.1-2001 added "
4865 "B<SA_NOCLDWAIT>, B<SA_RESETHAND>, B<SA_NODEFER>, and B<SA_SIGINFO>. Use of "
4866 "these latter values in I<sa_flags> may be less portable in applications "
4867 "intended for older UNIX implementations."
4871 #: build/C/man2/sigaction.2:808
4872 msgid "The B<SA_RESETHAND> flag is compatible with the SVr4 flag of the same name."
4876 #: build/C/man2/sigaction.2:818
4878 "The B<SA_NODEFER> flag is compatible with the SVr4 flag of the same name "
4879 "under kernels 1.3.9 and newer. On older kernels the Linux implementation "
4880 "allowed the receipt of any signal, not just the one we are installing "
4881 "(effectively overriding any I<sa_mask> settings)."
4885 #: build/C/man2/sigaction.2:824
4887 "B<sigaction>() can be called with a NULL second argument to query the "
4888 "current signal handler. It can also be used to check whether a given signal "
4889 "is valid for the current machine by calling it with NULL second and third "
4894 #: build/C/man2/sigaction.2:830
4896 "It is not possible to block B<SIGKILL> or B<SIGSTOP> (by specifying them in "
4897 "I<sa_mask>). Attempts to do so are silently ignored."
4901 #: build/C/man2/sigaction.2:834 build/C/man2/sigpending.2:70 build/C/man2/sigprocmask.2:144 build/C/man2/sigsuspend.2:108
4902 msgid "See B<sigsetops>(3) for details on manipulating signal sets."
4906 #: build/C/man2/sigaction.2:839
4908 "See B<signal>(7) for a list of the async-signal-safe functions that can be "
4909 "safely called inside from inside a signal handler."
4913 #: build/C/man2/sigaction.2:839
4915 msgid "Undocumented"
4919 #: build/C/man2/sigaction.2:849
4921 "Before the introduction of B<SA_SIGINFO> it was also possible to get some "
4922 "additional information, namely by using a I<sa_handler> with second argument "
4923 "of type I<struct sigcontext>. See the relevant Linux kernel sources for "
4924 "details. This use is obsolete now."
4928 #: build/C/man2/sigaction.2:858
4930 "In kernels up to and including 2.6.13, specifying B<SA_NODEFER> in "
4931 "I<sa_flags> prevents not only the delivered signal from being masked during "
4932 "execution of the handler, but also the signals specified in I<sa_mask>. "
4933 "This bug was fixed in kernel 2.6.14."
4937 #: build/C/man2/sigaction.2:861
4938 msgid "See B<mprotect>(2)."
4942 #: build/C/man2/sigaction.2:883
4944 "B<kill>(1), B<kill>(2), B<killpg>(2), B<pause>(2), B<restart_syscall>(2), "
4945 "B<seccomp>(2) B<sigaltstack>(2), B<signal>(2), B<signalfd>(2), "
4946 "B<sigpending>(2), B<sigreturn>(2), B<sigprocmask>(2), B<sigsuspend>(2), "
4947 "B<wait>(2), B<raise>(3), B<siginterrupt>(3), B<sigqueue>(3), "
4948 "B<sigsetops>(3), B<sigvec>(3), B<core>(5), B<signal>(7)"
4952 #: build/C/man2/sigaltstack.2:27
4958 #: build/C/man2/sigaltstack.2:27
4964 #: build/C/man2/sigaltstack.2:30
4965 msgid "sigaltstack - set and/or get signal stack context"
4969 #: build/C/man2/sigaltstack.2:34
4970 msgid "B<int sigaltstack(const stack_t *>I<ss>B<, stack_t *>I<oss>B<);>"
4974 #: build/C/man2/sigaltstack.2:41
4975 msgid "B<sigaltstack>():"
4979 #: build/C/man2/sigaltstack.2:48 build/C/man3/siginterrupt.3:53 build/C/man2/wait.2:80
4980 msgid "|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\\ E<gt>=\\ 200809L"
4984 #: build/C/man2/sigaltstack.2:60
4986 "B<sigaltstack>() allows a process to define a new alternate signal stack "
4987 "and/or retrieve the state of an existing alternate signal stack. An "
4988 "alternate signal stack is used during the execution of a signal handler if "
4989 "the establishment of that handler (see B<sigaction>(2)) requested it."
4993 #: build/C/man2/sigaltstack.2:63
4995 "The normal sequence of events for using an alternate signal stack is the "
5000 #: build/C/man2/sigaltstack.2:63 build/C/man7/signal.7:387
5006 #: build/C/man2/sigaltstack.2:67
5007 msgid "Allocate an area of memory to be used for the alternate signal stack."
5011 #: build/C/man2/sigaltstack.2:67 build/C/man7/signal.7:391
5017 #: build/C/man2/sigaltstack.2:73
5019 "Use B<sigaltstack>() to inform the system of the existence and location of "
5020 "the alternate signal stack."
5024 #: build/C/man2/sigaltstack.2:73 build/C/man7/signal.7:411
5030 #: build/C/man2/sigaltstack.2:80
5032 "When establishing a signal handler using B<sigaction>(2), inform the system "
5033 "that the signal handler should be executed on the alternate signal stack by "
5034 "specifying the B<SA_ONSTACK> flag."
5038 #: build/C/man2/sigaltstack.2:88
5040 "The I<ss> argument is used to specify a new alternate signal stack, while "
5041 "the I<oss> argument is used to retrieve information about the currently "
5042 "established signal stack. If we are interested in performing just one of "
5043 "these tasks, then the other argument can be specified as NULL. Each of "
5044 "these arguments is a structure of the following type:"
5048 #: build/C/man2/sigaltstack.2:96
5051 "typedef struct {\n"
5052 " void *ss_sp; /* Base address of stack */\n"
5053 " int ss_flags; /* Flags */\n"
5054 " size_t ss_size; /* Number of bytes in stack */\n"
5059 #: build/C/man2/sigaltstack.2:107
5061 "To establish a new alternate signal stack, I<ss.ss_flags> is set to zero, "
5062 "and I<ss.ss_sp> and I<ss.ss_size> specify the starting address and size of "
5063 "the stack. The constant B<SIGSTKSZ> is defined to be large enough to cover "
5064 "the usual size requirements for an alternate signal stack, and the constant "
5065 "B<MINSIGSTKSZ> defines the minimum size required to execute a signal "
5070 #: build/C/man2/sigaltstack.2:111
5072 "When a signal handler is invoked on the alternate stack, the kernel "
5073 "automatically aligns the address given in I<ss.ss_sp> to a suitable address "
5074 "boundary for the underlying hardware architecture."
5078 #: build/C/man2/sigaltstack.2:116
5080 "To disable an existing stack, specify I<ss.ss_flags> as B<SS_DISABLE>. In "
5081 "this case, the remaining fields in I<ss> are ignored."
5085 #: build/C/man2/sigaltstack.2:124
5087 "If I<oss> is not NULL, then it is used to return information about the "
5088 "alternate signal stack which was in effect prior to the call to "
5089 "B<sigaltstack>(). The I<oss.ss_sp> and I<oss.ss_size> fields return the "
5090 "starting address and size of that stack. The I<oss.ss_flags> may return "
5091 "either of the following values:"
5095 #: build/C/man2/sigaltstack.2:124
5097 msgid "B<SS_ONSTACK>"
5101 #: build/C/man2/sigaltstack.2:130
5103 "The process is currently executing on the alternate signal stack. (Note "
5104 "that it is not possible to change the alternate signal stack if the process "
5105 "is currently executing on it.)"
5109 #: build/C/man2/sigaltstack.2:130
5111 msgid "B<SS_DISABLE>"
5115 #: build/C/man2/sigaltstack.2:133
5116 msgid "The alternate signal stack is currently disabled."
5120 #: build/C/man2/sigaltstack.2:137
5122 "B<sigaltstack>() returns 0 on success, or -1 on failure with I<errno> set "
5123 "to indicate the error."
5127 #: build/C/man2/sigaltstack.2:142
5129 "Either I<ss> or I<oss> is not NULL and points to an area outside of the "
5130 "process's address space."
5134 #: build/C/man2/sigaltstack.2:147
5136 "I<ss> is not NULL and the I<ss_flags> field contains a nonzero value other "
5137 "than B<SS_DISABLE>."
5141 #: build/C/man2/sigaltstack.2:153
5143 "The specified size of the new alternate signal stack I<ss.ss_size> was less "
5148 #: build/C/man2/sigaltstack.2:158
5150 "An attempt was made to change the alternate signal stack while it was active "
5151 "(i.e., the process was already executing on the current alternate signal "
5156 #: build/C/man2/sigaltstack.2:160
5157 msgid "SUSv2, SVr4, POSIX.1-2001."
5161 #: build/C/man2/sigaltstack.2:168
5163 "The most common usage of an alternate signal stack is to handle the "
5164 "B<SIGSEGV> signal that is generated if the space available for the normal "
5165 "process stack is exhausted: in this case, a signal handler for B<SIGSEGV> "
5166 "cannot be invoked on the process stack; if we wish to handle it, we must use "
5167 "an alternate signal stack."
5171 #: build/C/man2/sigaltstack.2:178
5173 "Establishing an alternate signal stack is useful if a process expects that "
5174 "it may exhaust its standard stack. This may occur, for example, because the "
5175 "stack grows so large that it encounters the upwardly growing heap, or it "
5176 "reaches a limit established by a call to B<setrlimit(RLIMIT_STACK, &rlim)>. "
5177 "If the standard stack is exhausted, the kernel sends the process a "
5178 "B<SIGSEGV> signal. In these circumstances the only way to catch this signal "
5179 "is on an alternate signal stack."
5183 #: build/C/man2/sigaltstack.2:184
5185 "On most hardware architectures supported by Linux, stacks grow downward. "
5186 "B<sigaltstack>() automatically takes account of the direction of stack "
5191 #: build/C/man2/sigaltstack.2:193
5193 "Functions called from a signal handler executing on an alternate signal "
5194 "stack will also use the alternate signal stack. (This also applies to any "
5195 "handlers invoked for other signals while the process is executing on the "
5196 "alternate signal stack.) Unlike the standard stack, the system does not "
5197 "automatically extend the alternate signal stack. Exceeding the allocated "
5198 "size of the alternate signal stack will lead to unpredictable results."
5202 #: build/C/man2/sigaltstack.2:201
5204 "A successful call to B<execve>(2) removes any existing alternate signal "
5205 "stack. A child process created via B<fork>(2) inherits a copy of its "
5206 "parent's alternate signal stack settings."
5210 #: build/C/man2/sigaltstack.2:210
5212 "B<sigaltstack>() supersedes the older B<sigstack>() call. For backward "
5213 "compatibility, glibc also provides B<sigstack>(). All new applications "
5214 "should be written using B<sigaltstack>()."
5218 #: build/C/man2/sigaltstack.2:210 build/C/man3/sigpause.3:66
5224 #: build/C/man2/sigaltstack.2:217
5226 "4.2BSD had a B<sigstack>() system call. It used a slightly different "
5227 "struct, and had the major disadvantage that the caller had to know the "
5228 "direction of stack growth."
5232 #: build/C/man2/sigaltstack.2:220
5233 msgid "The following code segment demonstrates the use of B<sigaltstack>():"
5237 #: build/C/man2/sigaltstack.2:224
5239 msgid "stack_t ss;\n"
5243 #: build/C/man2/sigaltstack.2:232
5246 "ss.ss_sp = malloc(SIGSTKSZ);\n"
5247 "if (ss.ss_sp == NULL)\n"
5248 " /* Handle error */;\n"
5249 "ss.ss_size = SIGSTKSZ;\n"
5250 "ss.ss_flags = 0;\n"
5251 "if (sigaltstack(&ss, NULL) == -1)\n"
5252 " /* Handle error */;\n"
5256 #: build/C/man2/sigaltstack.2:241
5258 "B<execve>(2), B<setrlimit>(2), B<sigaction>(2), B<siglongjmp>(3), "
5259 "B<sigsetjmp>(3), B<signal>(7)"
5263 #: build/C/man7/sigevent.7:26
5269 #: build/C/man7/sigevent.7:26
5275 #: build/C/man7/sigevent.7:29
5276 msgid "sigevent - structure for notification from asynchronous routines"
5280 #: build/C/man7/sigevent.7:36
5283 "union sigval { /* Data passed with notification */\n"
5284 " int sival_int; /* Integer value */\n"
5285 " void *sival_ptr; /* Pointer value */\n"
5290 #: build/C/man7/sigevent.7:51
5293 "struct sigevent {\n"
5294 " int sigev_notify; /* Notification method */\n"
5295 " int sigev_signo; /* Notification signal */\n"
5296 " union sigval sigev_value; /* Data passed with\n"
5297 " notification */\n"
5298 " void (*sigev_notify_function) (union sigval);\n"
5299 " /* Function used for thread\n"
5300 " notification (SIGEV_THREAD) */\n"
5301 " void *sigev_notify_attributes;\n"
5302 " /* Attributes for notification thread\n"
5303 " (SIGEV_THREAD) */\n"
5304 " pid_t sigev_notify_thread_id;\n"
5305 " /* ID of thread to signal (SIGEV_THREAD_ID) */\n"
5310 #: build/C/man7/sigevent.7:60
5312 "The I<sigevent> structure is used by various APIs to describe the way a "
5313 "process is to be notified about an event (e.g., completion of an "
5314 "asynchronous request, expiration of a timer, or the arrival of a message)."
5318 #: build/C/man7/sigevent.7:68
5320 "The definition shown in the SYNOPSIS is approximate: some of the fields in "
5321 "the I<sigevent> structure may be defined as part of a union. Programs "
5322 "should employ only those fields relevant to the value specified in "
5327 #: build/C/man7/sigevent.7:73
5329 "The I<sigev_notify> field specifies how notification is to be performed. "
5330 "This field can have one of the following values:"
5334 #: build/C/man7/sigevent.7:73 build/C/man2/timer_create.2:109
5336 msgid "B<SIGEV_NONE>"
5340 #: build/C/man7/sigevent.7:76
5341 msgid "A \"null\" notification: don't do anything when the event occurs."
5345 #: build/C/man7/sigevent.7:76 build/C/man2/timer_create.2:114
5347 msgid "B<SIGEV_SIGNAL>"
5351 #: build/C/man7/sigevent.7:80
5352 msgid "Notify the process by sending the signal specified in I<sigev_signo>."
5356 #: build/C/man7/sigevent.7:87
5358 "If the signal is caught with a signal handler that was registered using the "
5359 "B<sigaction>(2) B<SA_SIGINFO> flag, then the following fields are set in "
5360 "the I<siginfo_t> structure that is passed as the second argument of the "
5365 #: build/C/man7/sigevent.7:92
5367 "This field is set to a value that depends on the API delivering the "
5372 #: build/C/man7/sigevent.7:92 build/C/man2/wait.2:302
5378 #: build/C/man7/sigevent.7:96
5380 "This field is set to the signal number (i.e., the same value as in "
5385 #: build/C/man7/sigevent.7:100
5386 msgid "This field is set to the value specified in I<sigev_value>."
5390 #: build/C/man7/sigevent.7:105
5392 "Depending on the API, other fields may also be set in the I<siginfo_t> "
5397 #: build/C/man7/sigevent.7:108
5399 "The same information is also available if the signal is accepted using "
5400 "B<sigwaitinfo>(2)."
5404 #: build/C/man7/sigevent.7:108 build/C/man2/timer_create.2:132
5406 msgid "B<SIGEV_THREAD>"
5410 #: build/C/man7/sigevent.7:125
5412 "Notify the process by invoking I<sigev_notify_function> \"as if\" it were "
5413 "the start function of a new thread. (Among the implementation possibilities "
5414 "here are that each timer notification could result in the creation of a new "
5415 "thread, or that a single thread is created to receive all notifications.) "
5416 "The function is invoked with I<sigev_value> as its sole argument. If "
5417 "I<sigev_notify_attributes> is not NULL, it should point to a "
5418 "I<pthread_attr_t> structure that defines attributes for the new thread (see "
5419 "B<pthread_attr_init>(3))."
5423 #: build/C/man7/sigevent.7:125 build/C/man2/timer_create.2:140
5425 msgid "B<SIGEV_THREAD_ID> (Linux-specific)"
5428 #. | SIGEV_SIGNAL vs not?
5430 #: build/C/man7/sigevent.7:130
5431 msgid "Currently used only by POSIX timers; see B<timer_create>(2)."
5435 #: build/C/man7/sigevent.7:132 build/C/man2/sigpending.2:66 build/C/man2/sigprocmask.2:114 build/C/man3/sigqueue.3:121 build/C/man3/sigsetops.3:147 build/C/man2/sigsuspend.2:86 build/C/man3/sigwait.3:87 build/C/man2/sigwaitinfo.2:135 build/C/man2/timer_create.2:197 build/C/man2/timer_delete.2:69 build/C/man2/timer_getoverrun.2:99 build/C/man2/timer_settime.2:209
5436 msgid "POSIX.1-2001."
5440 #: build/C/man7/sigevent.7:142
5442 "B<timer_create>(2), B<aio_fsync>(3), B<aio_read>(3), B<aio_write>(3), "
5443 "B<getaddrinfo_a>(3), B<lio_listio>(3), B<mq_notify>(3), B<aio>(7), "
5448 #: build/C/man3/siginterrupt.3:31
5450 msgid "SIGINTERRUPT"
5454 #: build/C/man3/siginterrupt.3:31
5460 #: build/C/man3/siginterrupt.3:34
5461 msgid "siginterrupt - allow signals to interrupt system calls"
5465 #: build/C/man3/siginterrupt.3:39
5467 msgid "B<int siginterrupt(int >I<sig>B<, int >I<flag>B<);>\n"
5471 #: build/C/man3/siginterrupt.3:47
5472 msgid "B<siginterrupt>():"
5476 #: build/C/man3/siginterrupt.3:64
5478 "The B<siginterrupt>() function changes the restart behavior when a system "
5479 "call is interrupted by the signal I<sig>. If the I<flag> argument is false "
5480 "(0), then system calls will be restarted if interrupted by the specified "
5481 "signal I<sig>. This is the default behavior in Linux."
5485 #: build/C/man3/siginterrupt.3:69
5487 "If the I<flag> argument is true (1) and no data has been transferred, then a "
5488 "system call interrupted by the signal I<sig> will return -1 and I<errno> "
5489 "will be set to B<EINTR>."
5493 #: build/C/man3/siginterrupt.3:73
5495 "If the I<flag> argument is true (1) and data transfer has started, then the "
5496 "system call will be interrupted and will return the actual amount of data "
5501 #: build/C/man3/siginterrupt.3:83
5503 "The B<siginterrupt>() function returns 0 on success. It returns -1 if the "
5504 "signal number I<sig> is invalid, with I<errno> set to indicate the cause of "
5509 #: build/C/man3/siginterrupt.3:87
5510 msgid "The specified signal number is invalid."
5514 #: build/C/man3/siginterrupt.3:93
5516 "The B<siginterrupt>() function uses a global variable that is not "
5517 "protected, so it is not thread-safe."
5521 #: build/C/man3/siginterrupt.3:102
5523 "4.3BSD, POSIX.1-2001. POSIX.1-2008 marks B<siginterrupt>() as obsolete, "
5524 "recommending the use of B<sigaction>(2) with the B<SA_RESTART> flag "
5529 #: build/C/man3/siginterrupt.3:104
5530 msgid "B<signal>(2)"
5534 #: build/C/man2/signal.2:36 build/C/man7/signal.7:46
5540 #: build/C/man2/signal.2:36 build/C/man3/sigpause.3:25 build/C/man2/sigwaitinfo.2:25 build/C/man2/timer_create.2:33 build/C/man2/wait.2:49
5546 #: build/C/man2/signal.2:39
5547 msgid "signal - ANSI C signal handling"
5551 #: build/C/man2/signal.2:45
5552 msgid "B<sighandler_t signal(int >I<signum>B<, sighandler_t >I<handler>B<);>"
5556 #: build/C/man2/signal.2:54
5558 "The behavior of B<signal>() varies across UNIX versions, and has also "
5559 "varied historically across different versions of Linux. B<Avoid its use>: "
5560 "use B<sigaction>(2) instead. See I<Portability> below."
5564 #: build/C/man2/signal.2:64
5566 "B<signal>() sets the disposition of the signal I<signum> to I<handler>, "
5567 "which is either B<SIG_IGN>, B<SIG_DFL>, or the address of a "
5568 "programmer-defined function (a \"signal handler\")."
5572 #: build/C/man2/signal.2:68
5574 "If the signal I<signum> is delivered to the process, then one of the "
5575 "following happens:"
5579 #: build/C/man2/signal.2:73
5580 msgid "If the disposition is set to B<SIG_IGN>, then the signal is ignored."
5584 #: build/C/man2/signal.2:80
5586 "If the disposition is set to B<SIG_DFL>, then the default action associated "
5587 "with the signal (see B<signal>(7)) occurs."
5591 #: build/C/man2/signal.2:91
5593 "If the disposition is set to a function, then first either the disposition "
5594 "is reset to B<SIG_DFL>, or the signal is blocked (see I<Portability> below), "
5595 "and then I<handler> is called with argument I<signum>. If invocation of the "
5596 "handler caused the signal to be blocked, then the signal is unblocked upon "
5597 "return from the handler."
5601 #: build/C/man2/signal.2:97
5602 msgid "The signals B<SIGKILL> and B<SIGSTOP> cannot be caught or ignored."
5606 #: build/C/man2/signal.2:105
5608 "B<signal>() returns the previous value of the signal handler, or B<SIG_ERR> "
5609 "on error. In the event of an error, I<errno> is set to indicate the cause."
5613 #: build/C/man2/signal.2:110
5614 msgid "I<signum> is invalid."
5618 #: build/C/man2/signal.2:116
5619 msgid "The effects of B<signal>() in a multithreaded process are unspecified."
5623 #: build/C/man2/signal.2:141
5625 "See B<sigaction>(2) for details on what happens when B<SIGCHLD> is set to "
5630 #: build/C/man2/signal.2:146
5632 "See B<signal>(7) for a list of the async-signal-safe functions that can be "
5633 "safely called from inside a signal handler."
5636 #. libc4 and libc5 define
5637 #. .IR SignalHandler ;
5639 #: build/C/man2/signal.2:162
5641 "The use of I<sighandler_t> is a GNU extension, exposed if B<_GNU_SOURCE> is "
5642 "defined; glibc also defines (the BSD-derived) I<sig_t> if B<_BSD_SOURCE> is "
5643 "defined. Without use of such a type, the declaration of B<signal>() is the "
5644 "somewhat harder to read:"
5648 #: build/C/man2/signal.2:166
5651 "B<void ( *>I<signal>B<(int >I<signum>B<, void (*>I<handler>B<)(int)) ) "
5656 #: build/C/man2/signal.2:168
5662 #: build/C/man2/signal.2:180
5664 "The only portable use of B<signal>() is to set a signal's disposition to "
5665 "B<SIG_DFL> or B<SIG_IGN>. The semantics when using B<signal>() to "
5666 "establish a signal handler vary across systems (and POSIX.1 explicitly "
5667 "permits this variation); B<do not use it for this purpose.>"
5671 #: build/C/man2/signal.2:186
5673 "POSIX.1 solved the portability mess by specifying B<sigaction>(2), which "
5674 "provides explicit control of the semantics when a signal handler is invoked; "
5675 "use that interface instead of B<signal>()."
5679 #: build/C/man2/signal.2:196
5681 "In the original UNIX systems, when a handler that was established using "
5682 "B<signal>() was invoked by the delivery of a signal, the disposition of the "
5683 "signal would be reset to B<SIG_DFL>, and the system did not block delivery "
5684 "of further instances of the signal. This is equivalent to calling "
5685 "B<sigaction>(2) with the following flags:"
5689 #: build/C/man2/signal.2:198
5691 msgid " sa.sa_flags = SA_RESETHAND | SA_NODEFER;\n"
5695 #: build/C/man2/signal.2:205
5697 "System\\ V also provides these semantics for B<signal>(). This was bad "
5698 "because the signal might be delivered again before the handler had a chance "
5699 "to reestablish itself. Furthermore, rapid deliveries of the same signal "
5700 "could result in recursive invocations of the handler."
5704 #: build/C/man2/signal.2:220
5706 "BSD improved on this situation, but unfortunately also changed the semantics "
5707 "of the existing B<signal>() interface while doing so. On BSD, when a "
5708 "signal handler is invoked, the signal disposition is not reset, and further "
5709 "instances of the signal are blocked from being delivered while the handler "
5710 "is executing. Furthermore, certain blocking system calls are automatically "
5711 "restarted if interrupted by a signal handler (see B<signal>(7)). The BSD "
5712 "semantics are equivalent to calling B<sigaction>(2) with the following "
5717 #: build/C/man2/signal.2:222
5719 msgid " sa.sa_flags = SA_RESTART;\n"
5723 #: build/C/man2/signal.2:224
5724 msgid "The situation on Linux is as follows:"
5728 #: build/C/man2/signal.2:228
5729 msgid "The kernel's B<signal>() system call provides System\\ V semantics."
5733 #: build/C/man2/signal.2:244
5735 "By default, in glibc 2 and later, the B<signal>() wrapper function does not "
5736 "invoke the kernel system call. Instead, it calls B<sigaction>(2) using "
5737 "flags that supply BSD semantics. This default behavior is provided as long "
5738 "as the B<_BSD_SOURCE> feature test macro is defined. By default, "
5739 "B<_BSD_SOURCE> is defined; it is also implicitly defined if one defines "
5740 "B<_GNU_SOURCE>, and can of course be explicitly defined."
5744 #. System V semantics are also provided if one uses the separate
5745 #. .BR sysv_signal (3)
5750 #. function in Linux libc4 and libc5 provide System\ V semantics.
5751 #. If one on a libc5 system includes
5752 #. .I <bsd/signal.h>
5757 #. provides BSD semantics.
5759 #: build/C/man2/signal.2:278
5761 "On glibc 2 and later, if the B<_BSD_SOURCE> feature test macro is not "
5762 "defined, then B<signal>() provides System\\ V semantics. (The default "
5763 "implicit definition of B<_BSD_SOURCE> is not provided if one invokes "
5764 "B<gcc>(1) in one of its standard modes (I<-std=xxx> or I<-ansi>) or "
5765 "defines various other feature test macros such as B<_POSIX_SOURCE>, "
5766 "B<_XOPEN_SOURCE>, or B<_SVID_SOURCE>; see B<feature_test_macros>(7).)"
5770 #: build/C/man2/signal.2:297
5772 "B<kill>(1), B<alarm>(2), B<kill>(2), B<killpg>(2), B<pause>(2), "
5773 "B<sigaction>(2), B<signalfd>(2), B<sigpending>(2), B<sigprocmask>(2), "
5774 "B<sigsuspend>(2), B<bsd_signal>(3), B<raise>(3), B<siginterrupt>(3), "
5775 "B<sigqueue>(3), B<sigsetops>(3), B<sigvec>(3), B<sysv_signal>(3), "
5780 #: build/C/man7/signal.7:49
5781 msgid "signal - overview of signals"
5785 #: build/C/man7/signal.7:52
5787 "Linux supports both POSIX reliable signals (hereinafter \"standard "
5788 "signals\") and POSIX real-time signals."
5792 #: build/C/man7/signal.7:52
5794 msgid "Signal dispositions"
5798 #: build/C/man7/signal.7:57
5800 "Each signal has a current I<disposition>, which determines how the process "
5801 "behaves when it is delivered the signal."
5805 #: build/C/man7/signal.7:60
5807 "The entries in the \"Action\" column of the tables below specify the default "
5808 "disposition for each signal, as follows:"
5812 #: build/C/man7/signal.7:60
5818 #: build/C/man7/signal.7:62
5819 msgid "Default action is to terminate the process."
5823 #: build/C/man7/signal.7:62
5829 #: build/C/man7/signal.7:64
5830 msgid "Default action is to ignore the signal."
5834 #: build/C/man7/signal.7:64
5840 #: build/C/man7/signal.7:67
5841 msgid "Default action is to terminate the process and dump core (see B<core>(5))."
5845 #: build/C/man7/signal.7:67
5851 #: build/C/man7/signal.7:69
5852 msgid "Default action is to stop the process."
5856 #: build/C/man7/signal.7:69
5862 #: build/C/man7/signal.7:71
5863 msgid "Default action is to continue the process if it is currently stopped."
5867 #: build/C/man7/signal.7:93
5869 "A process can change the disposition of a signal using B<sigaction>(2) or "
5870 "B<signal>(2). (The latter is less portable when establishing a signal "
5871 "handler; see B<signal>(2) for details.) Using these system calls, a "
5872 "process can elect one of the following behaviors to occur on delivery of the "
5873 "signal: perform the default action; ignore the signal; or catch the signal "
5874 "with a I<signal handler>, a programmer-defined function that is "
5875 "automatically invoked when the signal is delivered. (By default, the signal "
5876 "handler is invoked on the normal process stack. It is possible to arrange "
5877 "that the signal handler uses an alternate stack; see B<sigaltstack>(2) for "
5878 "a discussion of how to do this and when it might be useful.)"
5882 #: build/C/man7/signal.7:97
5884 "The signal disposition is a per-process attribute: in a multithreaded "
5885 "application, the disposition of a particular signal is the same for all "
5890 #: build/C/man7/signal.7:105
5892 msgid "Sending a signal"
5896 #: build/C/man7/signal.7:108
5898 "The following system calls and library functions allow the caller to send a "
5903 #: build/C/man7/signal.7:108
5909 #: build/C/man7/signal.7:111
5910 msgid "Sends a signal to the calling thread."
5914 #: build/C/man7/signal.7:111
5920 #: build/C/man7/signal.7:116
5922 "Sends a signal to a specified process, to all members of a specified process "
5923 "group, or to all processes on the system."
5927 #: build/C/man7/signal.7:116
5929 msgid "B<killpg>(2)"
5933 #: build/C/man7/signal.7:119
5934 msgid "Sends a signal to all of the members of a specified process group."
5938 #: build/C/man7/signal.7:119
5940 msgid "B<pthread_kill>(3)"
5944 #: build/C/man7/signal.7:123
5946 "Sends a signal to a specified POSIX thread in the same process as the "
5951 #: build/C/man7/signal.7:123
5953 msgid "B<tgkill>(2)"
5957 #: build/C/man7/signal.7:128
5959 "Sends a signal to a specified thread within a specific process. (This is "
5960 "the system call used to implement B<pthread_kill>(3).)"
5964 #: build/C/man7/signal.7:128
5966 msgid "B<sigqueue>(3)"
5970 #: build/C/man7/signal.7:131
5971 msgid "Sends a real-time signal with accompanying data to a specified process."
5975 #: build/C/man7/signal.7:131
5977 msgid "Waiting for a signal to be caught"
5981 #: build/C/man7/signal.7:135
5983 "The following system calls suspend execution of the calling process or "
5984 "thread until a signal is caught (or an unhandled signal terminates the "
5989 #: build/C/man7/signal.7:135
5995 #: build/C/man7/signal.7:138
5996 msgid "Suspends execution until any signal is caught."
6000 #: build/C/man7/signal.7:138
6002 msgid "B<sigsuspend>(2)"
6006 #: build/C/man7/signal.7:142
6008 "Temporarily changes the signal mask (see below) and suspends execution until "
6009 "one of the unmasked signals is caught."
6013 #: build/C/man7/signal.7:142
6015 msgid "Synchronously accepting a signal"
6019 #: build/C/man7/signal.7:149
6021 "Rather than asynchronously catching a signal via a signal handler, it is "
6022 "possible to synchronously accept the signal, that is, to block execution "
6023 "until the signal is delivered, at which point the kernel returns information "
6024 "about the signal to the caller. There are two general ways to do this:"
6028 #: build/C/man7/signal.7:157
6030 "B<sigwaitinfo>(2), B<sigtimedwait>(2), and B<sigwait>(3) suspend execution "
6031 "until one of the signals in a specified set is delivered. Each of these "
6032 "calls returns information about the delivered signal."
6036 #: build/C/man7/signal.7:170
6038 "B<signalfd>(2) returns a file descriptor that can be used to read "
6039 "information about signals that are delivered to the caller. Each B<read>(2) "
6040 "from this file descriptor blocks until one of the signals in the set "
6041 "specified in the B<signalfd>(2) call is delivered to the caller. The "
6042 "buffer returned by B<read>(2) contains a structure describing the signal."
6046 #: build/C/man7/signal.7:170
6048 msgid "Signal mask and pending signals"
6052 #: build/C/man7/signal.7:177
6054 "A signal may be I<blocked>, which means that it will not be delivered until "
6055 "it is later unblocked. Between the time when it is generated and when it is "
6056 "delivered a signal is said to be I<pending>."
6060 #: build/C/man7/signal.7:186
6062 "Each thread in a process has an independent I<signal mask>, which indicates "
6063 "the set of signals that the thread is currently blocking. A thread can "
6064 "manipulate its signal mask using B<pthread_sigmask>(3). In a traditional "
6065 "single-threaded application, B<sigprocmask>(2) can be used to manipulate "
6070 #: build/C/man7/signal.7:192 build/C/man2/sigprocmask.2:126
6072 "A child created via B<fork>(2) inherits a copy of its parent's signal mask; "
6073 "the signal mask is preserved across B<execve>(2)."
6077 #: build/C/man7/signal.7:209
6079 "A signal may be generated (and thus pending) for a process as a whole "
6080 "(e.g., when sent using B<kill>(2)) or for a specific thread (e.g., certain "
6081 "signals, such as B<SIGSEGV> and B<SIGFPE>, generated as a consequence of "
6082 "executing a specific machine-language instruction are thread directed, as "
6083 "are signals targeted at a specific thread using B<pthread_kill>(3)). A "
6084 "process-directed signal may be delivered to any one of the threads that does "
6085 "not currently have the signal blocked. If more than one of the threads has "
6086 "the signal unblocked, then the kernel chooses an arbitrary thread to which "
6087 "to deliver the signal."
6091 #: build/C/man7/signal.7:216
6093 "A thread can obtain the set of signals that it currently has pending using "
6094 "B<sigpending>(2). This set will consist of the union of the set of pending "
6095 "process-directed signals and the set of signals pending for the calling "
6100 #: build/C/man7/signal.7:222 build/C/man2/sigpending.2:85
6102 "A child created via B<fork>(2) initially has an empty pending signal set; "
6103 "the pending signal set is preserved across an B<execve>(2)."
6107 #: build/C/man7/signal.7:222
6109 msgid "Standard signals"
6113 #: build/C/man7/signal.7:234
6115 "Linux supports the standard signals listed below. Several signal numbers "
6116 "are architecture-dependent, as indicated in the \"Value\" column. (Where "
6117 "three values are given, the first one is usually valid for alpha and sparc, "
6118 "the middle one for x86, arm, and most other architectures, and the last one "
6119 "for mips. (Values for parisc are I<not> shown; see the Linux kernel source "
6120 "for signal numbering on that architecture.) A - denotes that a signal is "
6121 "absent on the corresponding architecture.)"
6125 #: build/C/man7/signal.7:236
6126 msgid "First the signals described in the original POSIX.1-1990 standard."
6130 #: build/C/man7/signal.7:240 build/C/man7/signal.7:276 build/C/man7/signal.7:305
6132 msgid "Signal\tValue\tAction\tComment\n"
6136 #: build/C/man7/signal.7:241
6138 msgid "SIGHUP\t\\01\tTerm\tHangup detected on controlling terminal\n"
6142 #: build/C/man7/signal.7:242
6144 msgid "\t\t\tor death of controlling process\n"
6148 #: build/C/man7/signal.7:243
6150 msgid "SIGINT\t\\02\tTerm\tInterrupt from keyboard\n"
6154 #: build/C/man7/signal.7:244
6156 msgid "SIGQUIT\t\\03\tCore\tQuit from keyboard\n"
6160 #: build/C/man7/signal.7:245
6162 msgid "SIGILL\t\\04\tCore\tIllegal Instruction\n"
6166 #: build/C/man7/signal.7:246
6168 msgid "SIGABRT\t\\06\tCore\tAbort signal from B<abort>(3)\n"
6172 #: build/C/man7/signal.7:247
6174 msgid "SIGFPE\t\\08\tCore\tFloating point exception\n"
6178 #: build/C/man7/signal.7:248
6180 msgid "SIGKILL\t\\09\tTerm\tKill signal\n"
6184 #: build/C/man7/signal.7:249
6186 msgid "SIGSEGV\t11\tCore\tInvalid memory reference\n"
6190 #: build/C/man7/signal.7:250
6192 msgid "SIGPIPE\t13\tTerm\tBroken pipe: write to pipe with no\n"
6196 #: build/C/man7/signal.7:251
6198 msgid "\t\t\treaders\n"
6202 #: build/C/man7/signal.7:252
6204 msgid "SIGALRM\t14\tTerm\tTimer signal from B<alarm>(2)\n"
6208 #: build/C/man7/signal.7:253
6210 msgid "SIGTERM\t15\tTerm\tTermination signal\n"
6214 #: build/C/man7/signal.7:254
6216 msgid "SIGUSR1\t30,10,16\tTerm\tUser-defined signal 1\n"
6220 #: build/C/man7/signal.7:255
6222 msgid "SIGUSR2\t31,12,17\tTerm\tUser-defined signal 2\n"
6226 #: build/C/man7/signal.7:256
6228 msgid "SIGCHLD\t20,17,18\tIgn\tChild stopped or terminated\n"
6232 #: build/C/man7/signal.7:257
6234 msgid "SIGCONT\t19,18,25\tCont\tContinue if stopped\n"
6238 #: build/C/man7/signal.7:258
6240 msgid "SIGSTOP\t17,19,23\tStop\tStop process\n"
6244 #: build/C/man7/signal.7:259
6246 msgid "SIGTSTP\t18,20,24\tStop\tStop typed at terminal\n"
6250 #: build/C/man7/signal.7:260
6252 msgid "SIGTTIN\t21,21,26\tStop\tTerminal input for background process\n"
6256 #: build/C/man7/signal.7:261
6258 msgid "SIGTTOU\t22,22,27\tStop\tTerminal output for background process\n"
6262 #: build/C/man7/signal.7:269
6263 msgid "The signals B<SIGKILL> and B<SIGSTOP> cannot be caught, blocked, or ignored."
6267 #: build/C/man7/signal.7:272
6269 "Next the signals not in the POSIX.1-1990 standard but described in SUSv2 and "
6274 #: build/C/man7/signal.7:277
6276 msgid "SIGBUS\t10,7,10\tCore\tBus error (bad memory access)\n"
6280 #: build/C/man7/signal.7:278
6282 msgid "SIGPOLL\t\tTerm\tPollable event (Sys V).\n"
6286 #: build/C/man7/signal.7:279
6288 msgid "\t\t\tSynonym for B<SIGIO>\n"
6292 #: build/C/man7/signal.7:280
6294 msgid "SIGPROF\t27,27,29\tTerm\tProfiling timer expired\n"
6298 #: build/C/man7/signal.7:281
6300 msgid "SIGSYS\t12,31,12\tCore\tBad argument to routine (SVr4)\n"
6304 #: build/C/man7/signal.7:282
6306 msgid "SIGTRAP\t5\tCore\tTrace/breakpoint trap\n"
6310 #: build/C/man7/signal.7:283
6312 msgid "SIGURG\t16,23,21\tIgn\tUrgent condition on socket (4.2BSD)\n"
6316 #: build/C/man7/signal.7:284
6318 msgid "SIGVTALRM\t26,26,28\tTerm\tVirtual alarm clock (4.2BSD)\n"
6322 #: build/C/man7/signal.7:285
6324 msgid "SIGXCPU\t24,24,30\tCore\tCPU time limit exceeded (4.2BSD)\n"
6328 #: build/C/man7/signal.7:286
6330 msgid "SIGXFSZ\t25,25,31\tCore\tFile size limit exceeded (4.2BSD)\n"
6334 #: build/C/man7/signal.7:299
6336 "Up to and including Linux 2.2, the default behavior for B<SIGSYS>, "
6337 "B<SIGXCPU>, B<SIGXFSZ>, and (on architectures other than SPARC and MIPS) "
6338 "B<SIGBUS> was to terminate the process (without a core dump). (On some "
6339 "other UNIX systems the default action for B<SIGXCPU> and B<SIGXFSZ> is to "
6340 "terminate the process without a core dump.) Linux 2.4 conforms to the "
6341 "POSIX.1-2001 requirements for these signals, terminating the process with a "
6346 #: build/C/man7/signal.7:301
6347 msgid "Next various other signals."
6351 #: build/C/man7/signal.7:306
6353 msgid "SIGIOT\t6\tCore\tIOT trap. A synonym for B<SIGABRT>\n"
6357 #: build/C/man7/signal.7:307
6359 msgid "SIGEMT\t7,-,7\tTerm\n"
6363 #: build/C/man7/signal.7:308
6365 msgid "SIGSTKFLT\t-,16,-\tTerm\tStack fault on coprocessor (unused)\n"
6369 #: build/C/man7/signal.7:309
6371 msgid "SIGIO\t23,29,22\tTerm\tI/O now possible (4.2BSD)\n"
6375 #: build/C/man7/signal.7:310
6377 msgid "SIGCLD\t-,-,18\tIgn\tA synonym for B<SIGCHLD>\n"
6381 #: build/C/man7/signal.7:311
6383 msgid "SIGPWR\t29,30,19\tTerm\tPower failure (System V)\n"
6387 #: build/C/man7/signal.7:312
6389 msgid "SIGINFO\t29,-,-\t\tA synonym for B<SIGPWR>\n"
6393 #: build/C/man7/signal.7:313
6395 msgid "SIGLOST\t-,-,-\tTerm\tFile lock lost (unused)\n"
6399 #: build/C/man7/signal.7:314
6401 msgid "SIGWINCH\t28,28,20\tIgn\tWindow resize signal (4.3BSD, Sun)\n"
6405 #: build/C/man7/signal.7:315
6407 msgid "SIGUNUSED\t-,31,-\tCore\tSynonymous with B<SIGSYS>\n"
6411 #: build/C/man7/signal.7:325
6412 msgid "(Signal 29 is B<SIGINFO> / B<SIGPWR> on an alpha but B<SIGLOST> on a sparc.)"
6416 #: build/C/man7/signal.7:331
6418 "B<SIGEMT> is not specified in POSIX.1-2001, but nevertheless appears on most "
6419 "other UNIX systems, where its default action is typically to terminate the "
6420 "process with a core dump."
6424 #: build/C/man7/signal.7:335
6426 "B<SIGPWR> (which is not specified in POSIX.1-2001) is typically ignored by "
6427 "default on those other UNIX systems where it appears."
6431 #: build/C/man7/signal.7:339
6433 "B<SIGIO> (which is not specified in POSIX.1-2001) is ignored by default on "
6434 "several other UNIX systems."
6437 #. parisc is the only exception: SIGSYS is 12, SIGUNUSED is 31
6439 #: build/C/man7/signal.7:346
6441 "Where defined, B<SIGUNUSED> is synonymous with B<SIGSYS> on most "
6446 #: build/C/man7/signal.7:346
6448 msgid "Real-time signals"
6452 #: build/C/man7/signal.7:356
6454 "Linux supports real-time signals as originally defined in the POSIX.1b "
6455 "real-time extensions (and now included in POSIX.1-2001). The range of "
6456 "supported real-time signals is defined by the macros B<SIGRTMIN> and "
6457 "B<SIGRTMAX>. POSIX.1-2001 requires that an implementation support at least "
6458 "B<_POSIX_RTSIG_MAX> (8) real-time signals."
6462 #: build/C/man7/signal.7:378
6464 "The Linux kernel supports a range of 32 different real-time signals, "
6465 "numbered 33 to 64. However, the glibc POSIX threads implementation "
6466 "internally uses two (for NPTL) or three (for LinuxThreads) real-time signals "
6467 "(see B<pthreads>(7)), and adjusts the value of B<SIGRTMIN> suitably (to 34 "
6468 "or 35). Because the range of available real-time signals varies according "
6469 "to the glibc threading implementation (and this variation can occur at run "
6470 "time according to the available kernel and glibc), and indeed the range of "
6471 "real-time signals varies across UNIX systems, programs should I<never refer "
6472 "to real-time signals using hard-coded numbers>, but instead should always "
6473 "refer to real-time signals using the notation B<SIGRTMIN>+n, and include "
6474 "suitable (run-time) checks that B<SIGRTMIN>+n does not exceed B<SIGRTMAX>."
6478 #: build/C/man7/signal.7:382
6480 "Unlike standard signals, real-time signals have no predefined meanings: the "
6481 "entire set of real-time signals can be used for application-defined "
6486 #: build/C/man7/signal.7:385
6488 "The default action for an unhandled real-time signal is to terminate the "
6489 "receiving process."
6493 #: build/C/man7/signal.7:387
6494 msgid "Real-time signals are distinguished by the following:"
6498 #: build/C/man7/signal.7:391
6500 "Multiple instances of real-time signals can be queued. By contrast, if "
6501 "multiple instances of a standard signal are delivered while that signal is "
6502 "currently blocked, then only one instance is queued."
6506 #: build/C/man7/signal.7:411
6508 "If the signal is sent using B<sigqueue>(3), an accompanying value (either an "
6509 "integer or a pointer) can be sent with the signal. If the receiving process "
6510 "establishes a handler for this signal using the B<SA_SIGINFO> flag to "
6511 "B<sigaction>(2), then it can obtain this data via the I<si_value> field of "
6512 "the I<siginfo_t> structure passed as the second argument to the handler. "
6513 "Furthermore, the I<si_pid> and I<si_uid> fields of this structure can be "
6514 "used to obtain the PID and real user ID of the process sending the signal."
6518 #: build/C/man7/signal.7:420
6520 "Real-time signals are delivered in a guaranteed order. Multiple real-time "
6521 "signals of the same type are delivered in the order they were sent. If "
6522 "different real-time signals are sent to a process, they are delivered "
6523 "starting with the lowest-numbered signal. (I.e., low-numbered signals have "
6524 "highest priority.) By contrast, if multiple standard signals are pending "
6525 "for a process, the order in which they are delivered is unspecified."
6529 #: build/C/man7/signal.7:425
6531 "If both standard and real-time signals are pending for a process, POSIX "
6532 "leaves it unspecified which is delivered first. Linux, like many other "
6533 "implementations, gives priority to standard signals in this case."
6537 #: build/C/man7/signal.7:448
6539 "According to POSIX, an implementation should permit at least "
6540 "B<_POSIX_SIGQUEUE_MAX> (32) real-time signals to be queued to a process. "
6541 "However, Linux does things differently. In kernels up to and including "
6542 "2.6.7, Linux imposes a system-wide limit on the number of queued real-time "
6543 "signals for all processes. This limit can be viewed and (with privilege) "
6544 "changed via the I</proc/sys/kernel/rtsig-max> file. A related file, "
6545 "I</proc/sys/kernel/rtsig-nr>, can be used to find out how many real-time "
6546 "signals are currently queued. In Linux 2.6.8, these I</proc> interfaces "
6547 "were replaced by the B<RLIMIT_SIGPENDING> resource limit, which specifies a "
6548 "per-user limit for queued signals; see B<setrlimit>(2) for further details."
6552 #: build/C/man7/signal.7:448
6554 msgid "Async-signal-safe functions"
6558 #: build/C/man7/signal.7:457
6560 "A signal handler function must be very careful, since processing elsewhere "
6561 "may be interrupted at some arbitrary point in the execution of the program. "
6562 "POSIX has the concept of \"safe function\". If a signal interrupts the "
6563 "execution of an unsafe function, and I<handler> calls an unsafe function, "
6564 "then the behavior of the program is undefined."
6568 #: build/C/man7/signal.7:461
6570 "POSIX.1-2004 (also known as POSIX.1-2001 Technical Corrigendum 2) requires "
6571 "an implementation to guarantee that the following functions can be safely "
6572 "called inside a signal handler:"
6576 #: build/C/man7/signal.7:582
6636 "posix_trace_event()\n"
6686 "timer_getoverrun()\n"
6700 #: build/C/man7/signal.7:587
6702 "POSIX.1-2008 removes fpathconf(), pathconf(), and sysconf() from the above "
6703 "list, and adds the following functions:"
6707 #: build/C/man7/signal.7:610
6733 #: build/C/man7/signal.7:612
6735 msgid "Interruption of system calls and library functions by signal handlers"
6739 #: build/C/man7/signal.7:615
6741 "If a signal handler is invoked while a system call or library function call "
6742 "is blocked, then either:"
6746 #: build/C/man7/signal.7:617
6747 msgid "the call is automatically restarted after the signal handler returns; or"
6751 #: build/C/man7/signal.7:620
6752 msgid "the call fails with the error B<EINTR>."
6756 #: build/C/man7/signal.7:628
6758 "Which of these two behaviors occurs depends on the interface and whether or "
6759 "not the signal handler was established using the B<SA_RESTART> flag (see "
6760 "B<sigaction>(2)). The details vary across UNIX systems; below, the details "
6764 #. The following system calls use ERESTARTSYS,
6765 #. so that they are restartable
6767 #: build/C/man7/signal.7:637
6769 "If a blocked call to one of the following interfaces is interrupted by a "
6770 "signal handler, then the call will be automatically restarted after the "
6771 "signal handler returns if the B<SA_RESTART> flag was used; otherwise the "
6772 "call will fail with the error B<EINTR>:"
6775 #. commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
6777 #: build/C/man7/signal.7:672
6779 "B<read>(2), B<readv>(2), B<write>(2), B<writev>(2), and B<ioctl>(2) calls "
6780 "on \"slow\" devices. A \"slow\" device is one where the I/O call may block "
6781 "for an indefinite time, for example, a terminal, pipe, or socket. (A disk "
6782 "is not a slow device according to this definition.) A B<read>(2) on an "
6783 "B<eventfd>(2), B<signalfd>(2), B<timerfd>(2), B<fanotify>(7), or "
6784 "B<inotify>(7) file descriptor is also considered to be a \"slow\" "
6785 "operation. (Before Linux 3.8, reads from an B<inotify>(7) file descriptor "
6786 "were not restartable; when interrupted by a signal handler, B<read>(2) "
6787 "always failed with the error B<EINTR>.) If an I/O call on a slow device has "
6788 "already transferred some data by the time it is interrupted by a signal "
6789 "handler, then the call will return a success status (normally, the number of "
6790 "bytes transferred)."
6794 #: build/C/man7/signal.7:676
6795 msgid "B<open>(2), if it can block (e.g., when opening a FIFO; see B<fifo>(7))."
6799 #: build/C/man7/signal.7:683
6800 msgid "B<wait>(2), B<wait3>(2), B<wait4>(2), B<waitid>(2), and B<waitpid>(2)."
6803 #. If a timeout (setsockopt()) is in effect on the socket, then these
6804 #. system calls switch to using EINTR. Consequently, they and are not
6805 #. automatically restarted, and they show the stop/cont behavior
6806 #. described below. (Verified from 2.6.26 source, and by experiment; mtk)
6807 #. FIXME . What about sendmmsg()?
6809 #: build/C/man7/signal.7:701
6811 "Socket interfaces: B<accept>(2), B<connect>(2), B<recv>(2), B<recvfrom>(2), "
6812 "B<recvmmsg>(2), B<recvmsg>(2), B<send>(2), B<sendto>(2), and B<sendmsg>(2), "
6813 "unless a timeout has been set on the socket (see below)."
6817 #: build/C/man7/signal.7:711
6819 "File locking interfaces: B<flock>(2) and the B<F_SETLKW> and "
6820 "B<F_OFD_SETLKW> operations of B<fcntl>(2)"
6824 #: build/C/man7/signal.7:718
6826 "POSIX message queue interfaces: B<mq_receive>(3), B<mq_timedreceive>(3), "
6827 "B<mq_send>(3), and B<mq_timedsend>(3)."
6831 #: build/C/man7/signal.7:723
6833 "B<futex>(2) B<FUTEX_WAIT> (since Linux 2.6.22; beforehand, always failed "
6838 #: build/C/man7/signal.7:725
6839 msgid "B<getrandom>(2)."
6843 #: build/C/man7/signal.7:729
6844 msgid "B<pthread_mutex_lock>(3), B<pthread_cond_wait>(3), and related APIs."
6848 #: build/C/man7/signal.7:736
6850 "POSIX semaphore interfaces: B<sem_wait>(3) and B<sem_timedwait>(3) (since "
6851 "Linux 2.6.22; beforehand, always failed with B<EINTR>)."
6854 #. These are the system calls that give EINTR or ERESTARTNOHAND
6855 #. on interruption by a signal handler.
6857 #: build/C/man7/signal.7:747
6859 "The following interfaces are never restarted after being interrupted by a "
6860 "signal handler, regardless of the use of B<SA_RESTART>; they always fail "
6861 "with the error B<EINTR> when interrupted by a signal handler:"
6865 #: build/C/man7/signal.7:762 build/C/man7/signal.7:837
6867 "\"Input\" socket interfaces, when a timeout (B<SO_RCVTIMEO>) has been set "
6868 "on the socket using B<setsockopt>(2): B<accept>(2), B<recv>(2), "
6869 "B<recvfrom>(2), B<recvmmsg>(2) (also with a non-NULL I<timeout> argument), "
6870 "and B<recvmsg>(2)."
6873 #. FIXME . What about sendmmsg()?
6875 #: build/C/man7/signal.7:773 build/C/man7/signal.7:848
6877 "\"Output\" socket interfaces, when a timeout (B<SO_SNDTIMEO>) has been set "
6878 "on the socket using B<setsockopt>(2): B<connect>(2), B<send>(2), "
6879 "B<sendto>(2), and B<sendmsg>(2)."
6883 #: build/C/man7/signal.7:780
6885 "Interfaces used to wait for signals: B<pause>(2), B<sigsuspend>(2), "
6886 "B<sigtimedwait>(2), and B<sigwaitinfo>(2)."
6890 #: build/C/man7/signal.7:789
6892 "File descriptor multiplexing interfaces: B<epoll_wait>(2), "
6893 "B<epoll_pwait>(2), B<poll>(2), B<ppoll>(2), B<select>(2), and B<pselect>(2)."
6896 #. On some other systems, SA_RESTART does restart these system calls
6898 #: build/C/man7/signal.7:797
6900 "System V IPC interfaces: B<msgrcv>(2), B<msgsnd>(2), B<semop>(2), and "
6905 #: build/C/man7/signal.7:803
6906 msgid "Sleep interfaces: B<clock_nanosleep>(2), B<nanosleep>(2), and B<usleep>(3)."
6910 #: build/C/man7/signal.7:805
6911 msgid "B<io_getevents>(2)."
6915 #: build/C/man7/signal.7:811
6917 "The B<sleep>(3) function is also never restarted if interrupted by a "
6918 "handler, but gives a success return: the number of seconds remaining to "
6923 #: build/C/man7/signal.7:811
6925 msgid "Interruption of system calls and library functions by stop signals"
6929 #: build/C/man7/signal.7:820
6931 "On Linux, even in the absence of signal handlers, certain blocking "
6932 "interfaces can fail with the error B<EINTR> after the process is stopped by "
6933 "one of the stop signals and then resumed via B<SIGCONT>. This behavior is "
6934 "not sanctioned by POSIX.1, and doesn't occur on other systems."
6938 #: build/C/man7/signal.7:822
6939 msgid "The Linux interfaces that display this behavior are:"
6943 #: build/C/man7/signal.7:851
6944 msgid "B<epoll_wait>(2), B<epoll_pwait>(2)."
6948 #: build/C/man7/signal.7:854
6949 msgid "B<semop>(2), B<semtimedop>(2)."
6953 #: build/C/man7/signal.7:857
6954 msgid "B<sigtimedwait>(2), B<sigwaitinfo>(2)."
6957 #. commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
6959 #: build/C/man7/signal.7:864
6960 msgid "Linux 3.7 and earlier: B<read>(2) from an B<inotify>(7) file descriptor."
6964 #: build/C/man7/signal.7:870
6966 "Linux 2.6.21 and earlier: B<futex>(2) B<FUTEX_WAIT>, B<sem_timedwait>(3), "
6971 #: build/C/man7/signal.7:874
6972 msgid "Linux 2.6.8 and earlier: B<msgrcv>(2), B<msgsnd>(2)."
6976 #: build/C/man7/signal.7:877
6977 msgid "Linux 2.4 and earlier: B<nanosleep>(2)."
6980 #. It must be a *very* long time since this was true:
6985 #. have the same value.
6986 #. The latter is commented out in the kernel source, but
6987 #. the build process of some software still thinks that
6991 #: build/C/man7/signal.7:890
6992 msgid "POSIX.1, except as noted."
6996 #: build/C/man7/signal.7:925
6998 "B<kill>(1), B<getrlimit>(2), B<kill>(2), B<killpg>(2), "
6999 "B<restart_syscall>(2), B<rt_sigqueueinfo>(2), B<setitimer>(2), "
7000 "B<setrlimit>(2), B<sgetmask>(2), B<sigaction>(2), B<sigaltstack>(2), "
7001 "B<signal>(2), B<signalfd>(2), B<sigpending>(2), B<sigprocmask>(2), "
7002 "B<sigreturn>(2), B<sigsuspend>(2), B<sigwaitinfo>(2), B<abort>(3), "
7003 "B<bsd_signal>(3), B<longjmp>(3), B<raise>(3), B<pthread_sigqueue>(3), "
7004 "B<sigqueue>(3), B<sigset>(3), B<sigsetops>(3), B<sigvec>(3), B<sigwait>(3), "
7005 "B<strsignal>(3), B<sysv_signal>(3), B<core>(5), B<proc>(5), B<pthreads>(7), "
7010 #: build/C/man2/signalfd.2:20
7016 #: build/C/man2/signalfd.2:23
7017 msgid "signalfd - create a file descriptor for accepting signals"
7021 #: build/C/man2/signalfd.2:25
7022 msgid "B<#include E<lt>sys/signalfd.hE<gt>>"
7026 #: build/C/man2/signalfd.2:27
7027 msgid "B<int signalfd(int >I<fd>B<, const sigset_t *>I<mask>B<, int >I<flags>B<);>"
7031 #: build/C/man2/signalfd.2:38
7033 "B<signalfd>() creates a file descriptor that can be used to accept signals "
7034 "targeted at the caller. This provides an alternative to the use of a signal "
7035 "handler or B<sigwaitinfo>(2), and has the advantage that the file descriptor "
7036 "may be monitored by B<select>(2), B<poll>(2), and B<epoll>(7)."
7040 #: build/C/man2/signalfd.2:58
7042 "The I<mask> argument specifies the set of signals that the caller wishes to "
7043 "accept via the file descriptor. This argument is a signal set whose "
7044 "contents can be initialized using the macros described in B<sigsetops>(3). "
7045 "Normally, the set of signals to be received via the file descriptor should "
7046 "be blocked using B<sigprocmask>(2), to prevent the signals being handled "
7047 "according to their default dispositions. It is not possible to receive "
7048 "B<SIGKILL> or B<SIGSTOP> signals via a signalfd file descriptor; these "
7049 "signals are silently ignored if specified in I<mask>."
7053 #: build/C/man2/signalfd.2:72
7055 "If the I<fd> argument is -1, then the call creates a new file descriptor and "
7056 "associates the signal set specified in I<mask> with that descriptor. If "
7057 "I<fd> is not -1, then it must specify a valid existing signalfd file "
7058 "descriptor, and I<mask> is used to replace the signal set associated with "
7063 #: build/C/man2/signalfd.2:77
7065 "Starting with Linux 2.6.27, the following values may be bitwise ORed in "
7066 "I<flags> to change the behavior of B<signalfd>():"
7070 #: build/C/man2/signalfd.2:77
7072 msgid "B<SFD_NONBLOCK>"
7076 #: build/C/man2/signalfd.2:85
7078 msgid "B<SFD_CLOEXEC>"
7082 #: build/C/man2/signalfd.2:102
7084 "B<signalfd>() returns a file descriptor that supports the following "
7089 #: build/C/man2/signalfd.2:121
7091 "If one or more of the signals specified in I<mask> is pending for the "
7092 "process, then the buffer supplied to B<read>(2) is used to return one or "
7093 "more I<signalfd_siginfo> structures (see below) that describe the signals. "
7094 "The B<read>(2) returns information for as many signals as are pending and "
7095 "will fit in the supplied buffer. The buffer must be at least "
7096 "I<sizeof(struct signalfd_siginfo)> bytes. The return value of the "
7097 "B<read>(2) is the total number of bytes read."
7101 #: build/C/man2/signalfd.2:129
7103 "As a consequence of the B<read>(2), the signals are consumed, so that they "
7104 "are no longer pending for the process (i.e., will not be caught by signal "
7105 "handlers, and cannot be accepted using B<sigwaitinfo>(2))."
7109 #: build/C/man2/signalfd.2:140
7111 "If none of the signals in I<mask> is pending for the process, then the "
7112 "B<read>(2) either blocks until one of the signals in I<mask> is generated "
7113 "for the process, or fails with the error B<EAGAIN> if the file descriptor "
7114 "has been made nonblocking."
7118 #: build/C/man2/signalfd.2:153
7120 "The file descriptor is readable (the B<select>(2) I<readfds> argument; the "
7121 "B<poll>(2) B<POLLIN> flag) if one or more of the signals in I<mask> is "
7122 "pending for the process."
7126 #: build/C/man2/signalfd.2:160
7128 "The signalfd file descriptor also supports the other file-descriptor "
7129 "multiplexing APIs: B<pselect>(2), B<ppoll>(2), and B<epoll>(7)."
7133 #: build/C/man2/signalfd.2:165
7135 "When the file descriptor is no longer required it should be closed. When "
7136 "all file descriptors associated with the same signalfd object have been "
7137 "closed, the resources for object are freed by the kernel."
7141 #: build/C/man2/signalfd.2:165
7143 msgid "The signalfd_siginfo structure"
7147 #: build/C/man2/signalfd.2:171
7149 "The format of the I<signalfd_siginfo> structure(s) returned by B<read>(2)s "
7150 "from a signalfd file descriptor is as follows:"
7153 #. ssi_trapno is unused on most arches
7154 #. FIXME Since Linux 2.6.37 there is 'uint16_t ssi_addr_lsb'
7155 #. in the signalfd_siginfo structure. This needs to be documented.
7157 #: build/C/man2/signalfd.2:198
7160 "struct signalfd_siginfo {\n"
7161 " uint32_t ssi_signo; /* Signal number */\n"
7162 " int32_t ssi_errno; /* Error number (unused) */\n"
7163 " int32_t ssi_code; /* Signal code */\n"
7164 " uint32_t ssi_pid; /* PID of sender */\n"
7165 " uint32_t ssi_uid; /* Real UID of sender */\n"
7166 " int32_t ssi_fd; /* File descriptor (SIGIO) */\n"
7167 " uint32_t ssi_tid; /* Kernel timer ID (POSIX timers)\n"
7168 " uint32_t ssi_band; /* Band event (SIGIO) */\n"
7169 " uint32_t ssi_overrun; /* POSIX timer overrun count */\n"
7170 " uint32_t ssi_trapno; /* Trap number that caused signal */\n"
7171 " int32_t ssi_status; /* Exit status or signal (SIGCHLD) */\n"
7172 " int32_t ssi_int; /* Integer sent by sigqueue(3) */\n"
7173 " uint64_t ssi_ptr; /* Pointer sent by sigqueue(3) */\n"
7174 " uint64_t ssi_utime; /* User CPU time consumed (SIGCHLD) */\n"
7175 " uint64_t ssi_stime; /* System CPU time consumed (SIGCHLD) */\n"
7176 " uint64_t ssi_addr; /* Address that generated signal\n"
7177 " (for hardware-generated signals) */\n"
7178 " uint8_t pad[I<X>]; /* Pad size to 128 bytes (allow for\n"
7179 " additional fields in the future) */\n"
7184 #: build/C/man2/signalfd.2:221
7186 "Each of the fields in this structure is analogous to the similarly named "
7187 "field in the I<siginfo_t> structure. The I<siginfo_t> structure is "
7188 "described in B<sigaction>(2). Not all fields in the returned "
7189 "I<signalfd_siginfo> structure will be valid for a specific signal; the set "
7190 "of valid fields can be determined from the value returned in the I<ssi_code> "
7191 "field. This field is the analog of the I<siginfo_t> I<si_code> field; see "
7192 "B<sigaction>(2) for details."
7196 #: build/C/man2/signalfd.2:221 build/C/man2/timerfd_create.2:276
7198 msgid "fork(2) semantics"
7202 #: build/C/man2/signalfd.2:229
7204 "After a B<fork>(2), the child inherits a copy of the signalfd file "
7205 "descriptor. A B<read>(2) from the file descriptor in the child will return "
7206 "information about signals queued to the child."
7210 #: build/C/man2/signalfd.2:229 build/C/man2/timerfd_create.2:288
7212 msgid "execve(2) semantics"
7216 #: build/C/man2/signalfd.2:241
7218 "Just like any other file descriptor, a signalfd file descriptor remains open "
7219 "across an B<execve>(2), unless it has been marked for close-on-exec (see "
7220 "B<fcntl>(2)). Any signals that were available for reading before the "
7221 "B<execve>(2) remain available to the newly loaded program. (This is "
7222 "analogous to traditional signal semantics, where a blocked signal that is "
7223 "pending remains pending across an B<execve>(2).)"
7227 #: build/C/man2/signalfd.2:241
7229 msgid "Thread semantics"
7233 #: build/C/man2/signalfd.2:251
7235 "The semantics of signalfd file descriptors in a multithreaded program mirror "
7236 "the standard semantics for signals. In other words, when a thread reads "
7237 "from a signalfd file descriptor, it will read the signals that are directed "
7238 "to the thread itself and the signals that are directed to the process (i.e., "
7239 "the entire thread group). (A thread will not be able to read signals that "
7240 "are directed to other threads in the process.)"
7244 #: build/C/man2/signalfd.2:265
7246 "On success, B<signalfd>() returns a signalfd file descriptor; this is "
7247 "either a new file descriptor (if I<fd> was -1), or I<fd> if I<fd> was a "
7248 "valid signalfd file descriptor. On error, -1 is returned and I<errno> is "
7249 "set to indicate the error."
7253 #: build/C/man2/signalfd.2:271
7254 msgid "The I<fd> file descriptor is not a valid file descriptor."
7259 #. argument is not equal to
7260 #. .IR sizeof(sigset_t) ;
7262 #: build/C/man2/signalfd.2:279
7263 msgid "I<fd> is not a valid signalfd file descriptor."
7267 #: build/C/man2/signalfd.2:286 build/C/man2/timerfd_create.2:327
7268 msgid "I<flags> is invalid; or, in Linux 2.6.26 or earlier, I<flags> is nonzero."
7272 #: build/C/man2/signalfd.2:289 build/C/man2/timerfd_create.2:330
7273 msgid "The per-process limit of open file descriptors has been reached."
7277 #: build/C/man2/signalfd.2:299
7278 msgid "There was insufficient memory to create a new signalfd file descriptor."
7281 #. signalfd() is in glibc 2.7, but reportedly does not build
7283 #: build/C/man2/signalfd.2:307
7285 "B<signalfd>() is available on Linux since kernel 2.6.22. Working support "
7286 "is provided in glibc since version 2.8. The B<signalfd4>() system call "
7287 "(see NOTES) is available on Linux since kernel 2.6.27."
7291 #: build/C/man2/signalfd.2:312
7292 msgid "B<signalfd>() and B<signalfd4>() are Linux-specific."
7296 #: build/C/man2/signalfd.2:326
7298 "A process can create multiple signalfd file descriptors. This makes it "
7299 "possible to accept different signals on different file descriptors. (This "
7300 "may be useful if monitoring the file descriptors using B<select>(2), "
7301 "B<poll>(2), or B<epoll>(7): the arrival of different signals will make "
7302 "different descriptors ready.) If a signal appears in the I<mask> of more "
7303 "than one of the file descriptors, then occurrences of that signal can be "
7304 "read (once) from any one of the descriptors."
7308 #: build/C/man2/signalfd.2:336
7310 "The underlying Linux system call requires an additional argument, I<size_t "
7311 "sizemask>, which specifies the size of the I<mask> argument. The glibc "
7312 "B<signalfd>() wrapper function does not include this argument, since it "
7313 "provides the required value for the underlying system call."
7317 #: build/C/man2/signalfd.2:352
7319 "There are two underlying Linux system calls: B<signalfd>() and the more "
7320 "recent B<signalfd4>(). The former system call does not implement a I<flags> "
7321 "argument. The latter system call implements the I<flags> values described "
7322 "above. Starting with glibc 2.9, the B<signalfd>() wrapper function will "
7323 "use B<signalfd4>() where it is available."
7326 #. The fix also was put into 2.6.24.5
7328 #: build/C/man2/signalfd.2:360
7330 "In kernels before 2.6.25, the I<ssi_ptr> and I<ssi_int> fields are not "
7331 "filled in with the data accompanying a signal sent by B<sigqueue>(3)."
7335 #: build/C/man2/signalfd.2:370
7337 "The program below accepts the signals B<SIGINT> and B<SIGQUIT> via a "
7338 "signalfd file descriptor. The program terminates after accepting a "
7339 "B<SIGQUIT> signal. The following shell session demonstrates the use of the "
7344 #: build/C/man2/signalfd.2:381
7347 "$B< ./signalfd_demo>\n"
7348 "B<^C> # Control-C generates SIGINT\n"
7352 "B<^\\e> # Control-\\e generates SIGQUIT\n"
7358 #: build/C/man2/signalfd.2:391
7361 "#include E<lt>sys/signalfd.hE<gt>\n"
7362 "#include E<lt>signal.hE<gt>\n"
7363 "#include E<lt>unistd.hE<gt>\n"
7364 "#include E<lt>stdlib.hE<gt>\n"
7365 "#include E<lt>stdio.hE<gt>\n"
7369 #: build/C/man2/signalfd.2:402
7373 "main(int argc, char *argv[])\n"
7377 " struct signalfd_siginfo fdsi;\n"
7382 #: build/C/man2/signalfd.2:406
7385 " sigemptyset(&mask);\n"
7386 " sigaddset(&mask, SIGINT);\n"
7387 " sigaddset(&mask, SIGQUIT);\n"
7391 #: build/C/man2/signalfd.2:409
7394 " /* Block signals so that they aren\\(aqt handled\n"
7395 " according to their default dispositions */\n"
7399 #: build/C/man2/signalfd.2:412
7402 " if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)\n"
7403 " handle_error(\"sigprocmask\");\n"
7407 #: build/C/man2/signalfd.2:416
7410 " sfd = signalfd(-1, &mask, 0);\n"
7412 " handle_error(\"signalfd\");\n"
7416 #: build/C/man2/signalfd.2:421
7420 " s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));\n"
7421 " if (s != sizeof(struct signalfd_siginfo))\n"
7422 " handle_error(\"read\");\n"
7426 #: build/C/man2/signalfd.2:432
7429 " if (fdsi.ssi_signo == SIGINT) {\n"
7430 " printf(\"Got SIGINT\\en\");\n"
7431 " } else if (fdsi.ssi_signo == SIGQUIT) {\n"
7432 " printf(\"Got SIGQUIT\\en\");\n"
7433 " exit(EXIT_SUCCESS);\n"
7435 " printf(\"Read unexpected signal\\en\");\n"
7442 #: build/C/man2/signalfd.2:446
7444 "B<eventfd>(2), B<poll>(2), B<read>(2), B<select>(2), B<sigaction>(2), "
7445 "B<sigprocmask>(2), B<sigwaitinfo>(2), B<timerfd_create>(2), B<sigsetops>(3), "
7446 "B<sigwait>(3), B<epoll>(7), B<signal>(7)"
7450 #: build/C/man3/sigpause.3:25
7456 #: build/C/man3/sigpause.3:28
7457 msgid "sigpause - atomically release blocked signals and wait for interrupt"
7461 #: build/C/man3/sigpause.3:33
7463 msgid "B<int sigpause(int >I<sigmask>B<); /* BSD (but see NOTES) */>\n"
7467 #: build/C/man3/sigpause.3:35
7469 msgid "B<int sigpause(int >I<sig>B<); /* System V / UNIX 95 */>\n"
7473 #: build/C/man3/sigpause.3:41
7474 msgid "Don't use this function. Use B<sigsuspend>(2) instead."
7478 #: build/C/man3/sigpause.3:48
7480 "The function B<sigpause>() is designed to wait for some signal. It changes "
7481 "the process's signal mask (set of blocked signals), and then waits for a "
7482 "signal to arrive. Upon arrival of a signal, the original signal mask is "
7487 #: build/C/man3/sigpause.3:56
7489 "If B<sigpause>() returns, it was interrupted by a signal and the return "
7490 "value is -1 with I<errno> set to B<EINTR>."
7494 #: build/C/man3/sigpause.3:61
7495 msgid "The B<sigpause>() function is thread-safe."
7499 #: build/C/man3/sigpause.3:65
7500 msgid "The System V version of B<sigpause>() is standardized in POSIX.1-2001."
7503 #. __xpg_sigpause: UNIX 95, spec 1170, SVID, SVr4, XPG
7505 #: build/C/man3/sigpause.3:82
7507 "The classical BSD version of this function appeared in 4.2BSD. It sets the "
7508 "process's signal mask to I<sigmask>. UNIX 95 standardized the incompatible "
7509 "System V version of this function, which removes only the specified signal "
7510 "I<sig> from the process's signal mask. The unfortunate situation with two "
7511 "incompatible functions with the same name was solved by the "
7512 "B<\\%sigsuspend>(2) function, that takes a I<sigset_t\\ *> argument "
7513 "(instead of an I<int>)."
7517 #: build/C/man3/sigpause.3:85
7519 "On Linux, this routine is a system call only on the Sparc (sparc64) "
7523 #. Libc4 and libc5 know only about the BSD version.
7526 #. For the BSD version, one usually uses a zero
7528 #. to indicate that no signals are to be blocked.
7530 #: build/C/man3/sigpause.3:111
7532 "Glibc uses the BSD version if the B<_BSD_SOURCE> feature test macro is "
7533 "defined and none of B<_POSIX_SOURCE>, B<_POSIX_C_SOURCE>, B<_XOPEN_SOURCE>, "
7534 "B<_GNU_SOURCE>, or B<_SVID_SOURCE> is defined. Otherwise, the System V "
7535 "version is used (and B<_XOPEN_SOURCE> must be defined to obtain the "
7536 "declaration). Since glibc 2.19, only the System V version is exposed by "
7537 "I<E<lt>signal.hE<gt>>; applications that formerly used the BSD B<sigpause>() "
7538 "should be amended to use B<sigsuspend>(2)."
7542 #: build/C/man3/sigpause.3:119
7544 "B<kill>(2), B<sigaction>(2), B<sigprocmask>(2), B<sigsuspend>(2), "
7545 "B<sigblock>(3), B<sigvec>(3), B<feature_test_macros>(7)"
7549 #: build/C/man2/sigpending.2:29
7555 #: build/C/man2/sigpending.2:29
7561 #: build/C/man2/sigpending.2:32
7562 msgid "sigpending - examine pending signals"
7566 #: build/C/man2/sigpending.2:36
7567 msgid "B<int sigpending(sigset_t *>I<set>B<);>"
7571 #: build/C/man2/sigpending.2:45
7573 "B<sigpending>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || "
7578 #: build/C/man2/sigpending.2:53
7580 "B<sigpending>() returns the set of signals that are pending for delivery to "
7581 "the calling thread (i.e., the signals which have been raised while "
7582 "blocked). The mask of pending signals is returned in I<set>."
7586 #: build/C/man2/sigpending.2:59
7588 "B<sigpending>() returns 0 on success and -1 on error. In the event of an "
7589 "error, I<errno> is set to indicate the cause."
7593 #: build/C/man2/sigpending.2:64
7595 "I<set> points to memory which is not a valid part of the process address "
7600 #: build/C/man2/sigpending.2:74
7602 "If a signal is both blocked and has a disposition of \"ignored\", it is "
7603 "I<not> added to the mask of pending signals when generated."
7607 #: build/C/man2/sigpending.2:79
7609 "The set of signals that is pending for a thread is the union of the set of "
7610 "signals that is pending for that thread and the set of signals that is "
7611 "pending for the process as a whole; see B<signal>(7)."
7615 #: build/C/man2/sigpending.2:91
7617 "In versions of glibc up to and including 2.2.1, there is a bug in the "
7618 "wrapper function for B<sigpending>() which means that information about "
7619 "pending real-time signals is not correctly returned."
7623 #: build/C/man2/sigpending.2:99
7625 "B<kill>(2), B<sigaction>(2), B<signal>(2), B<sigprocmask>(2), "
7626 "B<sigsuspend>(2), B<sigsetops>(3), B<signal>(7)"
7630 #: build/C/man2/sigprocmask.2:29
7636 #: build/C/man2/sigprocmask.2:29 build/C/man2/sigsuspend.2:29
7642 #: build/C/man2/sigprocmask.2:32
7643 msgid "sigprocmask - examine and change blocked signals"
7647 #: build/C/man2/sigprocmask.2:37
7649 "B<int sigprocmask(int >I<how>B<, const sigset_t *>I<set>B<,> B<sigset_t "
7654 #: build/C/man2/sigprocmask.2:46
7656 "B<sigprocmask>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || "
7661 #: build/C/man2/sigprocmask.2:55
7663 "B<sigprocmask>() is used to fetch and/or change the signal mask of the "
7664 "calling thread. The signal mask is the set of signals whose delivery is "
7665 "currently blocked for the caller (see also B<signal>(7) for more details)."
7669 #: build/C/man2/sigprocmask.2:59
7670 msgid "The behavior of the call is dependent on the value of I<how>, as follows."
7674 #: build/C/man2/sigprocmask.2:59
7676 msgid "B<SIG_BLOCK>"
7680 #: build/C/man2/sigprocmask.2:64
7682 "The set of blocked signals is the union of the current set and the I<set> "
7687 #: build/C/man2/sigprocmask.2:64
7689 msgid "B<SIG_UNBLOCK>"
7693 #: build/C/man2/sigprocmask.2:70
7695 "The signals in I<set> are removed from the current set of blocked signals. "
7696 "It is permissible to attempt to unblock a signal which is not blocked."
7700 #: build/C/man2/sigprocmask.2:70
7702 msgid "B<SIG_SETMASK>"
7706 #: build/C/man2/sigprocmask.2:74
7707 msgid "The set of blocked signals is set to the argument I<set>."
7711 #: build/C/man2/sigprocmask.2:79
7713 "If I<oldset> is non-NULL, the previous value of the signal mask is stored in "
7718 #: build/C/man2/sigprocmask.2:88
7720 "If I<set> is NULL, then the signal mask is unchanged (i.e., I<how> is "
7721 "ignored), but the current value of the signal mask is nevertheless returned "
7722 "in I<oldset> (if it is not NULL)."
7726 #: build/C/man2/sigprocmask.2:93
7728 "The use of B<sigprocmask>() is unspecified in a multithreaded process; see "
7729 "B<pthread_sigmask>(3)."
7733 #: build/C/man2/sigprocmask.2:99
7735 "B<sigprocmask>() returns 0 on success and -1 on error. In the event of an "
7736 "error, I<errno> is set to indicate the cause."
7740 #: build/C/man2/sigprocmask.2:107
7742 "the I<set> or I<oldset> argument points outside the process's allocated "
7747 #: build/C/man2/sigprocmask.2:112
7748 msgid "The value specified in I<how> was invalid."
7752 #: build/C/man2/sigprocmask.2:118
7754 "It is not possible to block B<SIGKILL> or B<SIGSTOP>. Attempts to do so are "
7759 #: build/C/man2/sigprocmask.2:120
7760 msgid "Each of the threads in a process has its own signal mask."
7764 #: build/C/man2/sigprocmask.2:140
7766 "If B<SIGBUS>, B<SIGFPE>, B<SIGILL>, or B<SIGSEGV> are generated while they "
7767 "are blocked, the result is undefined, unless the signal was generated by "
7768 "B<kill>(2), B<sigqueue>(3), or B<raise>(3)."
7772 #: build/C/man2/sigprocmask.2:155
7774 "B<kill>(2), B<pause>(2), B<sigaction>(2), B<signal>(2), B<sigpending>(2), "
7775 "B<sigsuspend>(2), B<pthread_sigmask>(3), B<sigqueue>(3), B<sigsetops>(3), "
7780 #: build/C/man3/sigqueue.3:28
7786 #: build/C/man3/sigqueue.3:28 build/C/man3/sigwait.3:26
7792 #: build/C/man3/sigqueue.3:31
7793 msgid "sigqueue - queue a signal and data to a process"
7797 #: build/C/man3/sigqueue.3:35
7799 "B<int sigqueue(pid_t >I<pid>B<, int >I<sig>B<, const union sigval "
7804 #: build/C/man3/sigqueue.3:43
7805 msgid "B<sigqueue>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
7809 #: build/C/man3/sigqueue.3:55
7811 "B<sigqueue>() sends the signal specified in I<sig> to the process whose PID "
7812 "is given in I<pid>. The permissions required to send a signal are the same "
7813 "as for B<kill>(2). As with B<kill>(2), the null signal (0) can be used to "
7814 "check if a process with a given PID exists."
7818 #: build/C/man3/sigqueue.3:60
7820 "The I<value> argument is used to specify an accompanying item of data "
7821 "(either an integer or a pointer value) to be sent with the signal, and has "
7822 "the following type:"
7826 #: build/C/man3/sigqueue.3:67
7831 " void *sival_ptr;\n"
7836 #: build/C/man3/sigqueue.3:83
7838 "If the receiving process has installed a handler for this signal using the "
7839 "B<SA_SIGINFO> flag to B<sigaction>(2), then it can obtain this data via the "
7840 "I<si_value> field of the I<siginfo_t> structure passed as the second "
7841 "argument to the handler. Furthermore, the I<si_code> field of that "
7842 "structure will be set to B<SI_QUEUE>."
7846 #: build/C/man3/sigqueue.3:91
7848 "On success, B<sigqueue>() returns 0, indicating that the signal was "
7849 "successfully queued to the receiving process. Otherwise, -1 is returned and "
7850 "I<errno> is set to indicate the error."
7854 #: build/C/man3/sigqueue.3:102
7855 msgid "I<sig> was invalid."
7859 #: build/C/man3/sigqueue.3:108
7861 "The process does not have permission to send the signal to the receiving "
7862 "process. For the required permissions, see B<kill>(2)."
7866 #: build/C/man3/sigqueue.3:112
7867 msgid "No process has a PID matching I<pid>."
7871 #: build/C/man3/sigqueue.3:114
7872 msgid "This system call first appeared in Linux 2.2."
7876 #: build/C/man3/sigqueue.3:119
7877 msgid "The B<sigqueue>() function is thread-safe."
7881 #: build/C/man3/sigqueue.3:129
7883 "If this function results in the sending of a signal to the process that "
7884 "invoked it, and that signal was not blocked by the calling thread, and no "
7885 "other threads were willing to handle this signal (either by having it "
7886 "unblocked, or by waiting for it using B<sigwait>(3)), then at least some "
7887 "signal must be delivered to this thread before this function returns."
7891 #: build/C/man3/sigqueue.3:144
7893 "On Linux, this function is implemented using the B<rt_sigqueueinfo>(2) "
7894 "system call. The system call differs in its third argument, which is the "
7895 "I<siginfo_t> structure that will be supplied to the receiving process's "
7896 "signal handler or returned by the receiving process's B<sigtimedwait>(2) "
7897 "call. Inside the glibc B<sigqueue>() wrapper, this argument, I<uinfo>, is "
7898 "initialized as follows:"
7902 #: build/C/man3/sigqueue.3:152
7905 "uinfo.si_signo = sig; /* Argument supplied to sigqueue() */\n"
7906 "uinfo.si_code = SI_QUEUE;\n"
7907 "uinfo.si_pid = getpid(); /* Process ID of sender */\n"
7908 "uinfo.si_uid = getuid(); /* Real UID of sender */\n"
7909 "uinfo.si_value = val; /* Argument supplied to sigqueue() */\n"
7913 #: build/C/man3/sigqueue.3:162
7915 "B<kill>(2), B<rt_sigqueueinfo>(2), B<sigaction>(2), B<signal>(2), "
7916 "B<pthread_sigqueue>(3), B<sigwait>(3), B<signal>(7)"
7920 #: build/C/man2/sigreturn.2:30
7926 #: build/C/man2/sigreturn.2:33
7927 msgid "sigreturn - return from signal handler and cleanup stack frame"
7931 #: build/C/man2/sigreturn.2:35
7932 msgid "B<int sigreturn(...);>"
7935 #. See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code]
7937 #: build/C/man2/sigreturn.2:45
7939 "If the Linux kernel determines that an unblocked signal is pending for a "
7940 "process, then, at the next transition back to user mode in that process "
7941 "(e.g., upon return from a system call or when the process is rescheduled "
7942 "onto the CPU), it saves various pieces of process context (processor status "
7943 "word, registers, signal mask, and signal stack settings) into the "
7948 #: build/C/man2/sigreturn.2:52
7950 "The kernel also arranges that, during the transition back to user mode, the "
7951 "signal handler is called, and that, upon return from the handler, control "
7952 "passes to a piece of user-space code commonly called the \"signal "
7953 "trampoline\". The signal trampoline code in turn calls B<sigreturn>()."
7957 #: build/C/man2/sigreturn.2:65
7959 "This B<sigreturn>() call undoes everything that was done\\(emchanging the "
7960 "process's signal mask, switching signal stacks (see "
7961 "B<sigaltstack>(2))\\(emin order to invoke the signal handler. It restores "
7962 "the process's signal mask, switches stacks, and restores the process's "
7963 "context (processor flags and registers, including the stack pointer and "
7964 "instruction pointer), so that the process resumes execution at the point "
7965 "where it was interrupted by the signal."
7969 #: build/C/man2/sigreturn.2:68
7970 msgid "B<sigreturn>() never returns."
7974 #: build/C/man2/sigreturn.2:74
7976 "Many UNIX-type systems have a B<sigreturn>() system call or near "
7977 "equivalent. However, this call is not specified in POSIX, and details of "
7978 "its behavior vary across systems."
7982 #: build/C/man2/sigreturn.2:83
7984 "B<sigreturn>() exists only to allow the implementation of signal handlers. "
7985 "It should B<never> be called directly. Details of the arguments (if any) "
7986 "passed to B<sigreturn>() vary depending on the architecture."
7989 #. See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and
7990 #. sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source.
7992 #: build/C/man2/sigreturn.2:106
7994 "Once upon a time, UNIX systems placed the signal trampoline code onto the "
7995 "user stack. Nowadays, pages of the user stack are protected so as to "
7996 "disallow code execution. Thus, on contemporary Linux systems, depending on "
7997 "the architecture, the signal trampoline code lives either in the B<vdso>(7) "
7998 "or in the C library. In the latter case, the C library supplies the "
7999 "location of the trampoline code using the I<sa_restorer> field of the "
8000 "I<sigaction> structure that is passed to B<sigaction>(2), and sets the "
8001 "B<SA_RESTORER> flag in the I<sa_flags> field."
8005 #: build/C/man2/sigreturn.2:115
8007 "The saved process context information is placed in a I<ucontext_t> structure "
8008 "(see I<E<lt>sys/ucontext.hE<gt>>). That structure is visible within the "
8009 "signal handler as the third argument of a handler established with the "
8010 "B<SA_SIGINFO> flag."
8014 #: build/C/man2/sigreturn.2:123
8016 "On some other UNIX systems, the operation of the signal trampoline differs a "
8017 "little. In particular, on some systems, upon transitioning back to user "
8018 "mode, the kernel passes control to the trampoline (rather than the signal "
8019 "handler), and the trampoline code calls the signal handler (and then calls "
8020 "B<sigreturn>() once the handler returns)."
8024 #: build/C/man2/sigreturn.2:130
8026 "B<kill>(2), B<restart_syscall>(2), B<sigaltstack>(2), B<signal>(2), "
8027 "B<getcontext>(3), B<signal>(7)"
8031 #: build/C/man3/sigset.3:26
8037 #: build/C/man3/sigset.3:29
8038 msgid "sigset, sighold, sigrelse, sigignore - System V signal API"
8042 #: build/C/man3/sigset.3:35
8043 msgid "B<sighandler_t sigset(int >I<sig>B<, sighandler_t >I<disp>B<);>"
8047 #: build/C/man3/sigset.3:37
8048 msgid "B<int sighold(int >I<sig>B<);>"
8052 #: build/C/man3/sigset.3:39
8053 msgid "B<int sigrelse(int >I<sig>B<);>"
8057 #: build/C/man3/sigset.3:41
8058 msgid "B<int sigignore(int >I<sig>B<);>"
8062 #: build/C/man3/sigset.3:52
8063 msgid "B<sigset>(), B<sighold>(), B<sigrelse>(), B<sigignore>():"
8067 #: build/C/man3/sigset.3:56
8068 msgid "_XOPEN_SOURCE\\ E<gt>=\\ 500 || _XOPEN_SOURCE\\ &&\\ _XOPEN_SOURCE_EXTENDED"
8072 #: build/C/man3/sigset.3:65
8074 "These functions are provided in glibc as a compatibility interface for "
8075 "programs that make use of the historical System V signal API. This API is "
8076 "obsolete: new applications should use the POSIX signal API (B<sigaction>(2), "
8077 "B<sigprocmask>(2), etc.)"
8081 #: build/C/man3/sigset.3:74
8083 "The B<sigset>() function modifies the disposition of the signal I<sig>. "
8084 "The I<disp> argument can be the address of a signal handler function, or one "
8085 "of the following constants:"
8089 #: build/C/man3/sigset.3:74
8095 #: build/C/man3/sigset.3:79
8096 msgid "Reset the disposition of I<sig> to the default."
8100 #: build/C/man3/sigset.3:79
8106 #: build/C/man3/sigset.3:83
8107 msgid "Ignore I<sig>."
8111 #: build/C/man3/sigset.3:83
8117 #: build/C/man3/sigset.3:90
8119 "Add I<sig> to the process's signal mask, but leave the disposition of I<sig> "
8124 #: build/C/man3/sigset.3:96
8126 "If I<disp> specifies the address of a signal handler, then I<sig> is added "
8127 "to the process's signal mask during execution of the handler."
8131 #: build/C/man3/sigset.3:104
8133 "If I<disp> was specified as a value other than B<SIG_HOLD>, then I<sig> is "
8134 "removed from the process's signal mask."
8138 #: build/C/man3/sigset.3:110 build/C/man3/sigvec.3:87
8139 msgid "The dispositions for B<SIGKILL> and B<SIGSTOP> cannot be changed."
8143 #: build/C/man3/sigset.3:116
8144 msgid "The B<sighold>() function adds I<sig> to the calling process's signal mask."
8148 #: build/C/man3/sigset.3:122
8150 "The B<sigrelse>() function removes I<sig> from the calling process's signal "
8155 #: build/C/man3/sigset.3:129
8156 msgid "The B<sigignore>() function sets the disposition of I<sig> to B<SIG_IGN>."
8160 #: build/C/man3/sigset.3:145
8162 "On success, B<sigset>() returns B<SIG_HOLD> if I<sig> was blocked before "
8163 "the call, or the signal's previous disposition if it was not blocked before "
8164 "the call. On error, B<sigset>() returns -1, with I<errno> set to indicate "
8165 "the error. (But see BUGS below.)"
8169 #: build/C/man3/sigset.3:154
8171 "The B<sighold>(), B<sigrelse>(), and B<sigignore>() functions return 0 on "
8172 "success; on error, these functions return -1 and set I<errno> to indicate "
8177 #: build/C/man3/sigset.3:161
8179 "For B<sigset>() see the ERRORS under B<sigaction>(2) and "
8180 "B<sigprocmask>(2)."
8184 #: build/C/man3/sigset.3:168
8185 msgid "For B<sighold>() and B<sigrelse>() see the ERRORS under B<sigprocmask>(2)."
8189 #: build/C/man3/sigset.3:173
8190 msgid "For B<sigignore>(), see the errors under B<sigaction>(2)."
8194 #: build/C/man3/sigset.3:190
8196 "SVr4, POSIX.1-2001. These functions are obsolete: do not use them in new "
8197 "programs. POSIX.1-2008 marks B<sighold>(), B<sigignore>(), B<sigpause>(), "
8198 "B<sigrelse>(), and B<sigset>() as obsolete, recommending the use of "
8199 "B<sigaction>(2), B<sigprocmask>(2), B<pthread_sigmask>(3), and "
8200 "B<sigsuspend>(2) instead."
8204 #: build/C/man3/sigset.3:192
8205 msgid "These functions appeared in glibc version 2.1."
8209 #: build/C/man3/sigset.3:198
8211 "The I<sighandler_t> type is a GNU extension; it is used on this page only to "
8212 "make the B<sigset>() prototype more easily readable."
8216 #: build/C/man3/sigset.3:206
8218 "The B<sigset>() function provides reliable signal handling semantics (as "
8219 "when calling B<sigaction>(2) with I<sa_mask> equal to 0)."
8223 #: build/C/man3/sigset.3:224
8225 "On System V, the B<signal>() function provides unreliable semantics (as "
8226 "when calling B<sigaction>(2) with I<sa_mask> equal to I<SA_RESETHAND | "
8227 "SA_NODEFER>). On BSD, B<signal>() provides reliable semantics. "
8228 "POSIX.1-2001 leaves these aspects of B<signal>() unspecified. See "
8229 "B<signal>(2) for further details."
8233 #: build/C/man3/sigset.3:232 build/C/man3/sigvec.3:272
8235 "In order to wait for a signal, BSD and System V both provided a function "
8236 "named B<sigpause>(3), but this function has a different argument on the two "
8237 "systems. See B<sigpause>(3) for details."
8241 #: build/C/man3/sigset.3:241
8243 "In versions of glibc before 2.2, B<sigset>() did not unblock I<sig> if "
8244 "I<disp> was specified as a value other than B<SIG_HOLD>."
8247 #. See http://sourceware.org/bugzilla/show_bug.cgi?id=1951
8249 #: build/C/man3/sigset.3:266
8251 "In versions of glibc before 2.5, B<sigset>() does not correctly return the "
8252 "previous disposition of the signal in two cases. First, if I<disp> is "
8253 "specified as B<SIG_HOLD>, then a successful B<sigset>() always returns "
8254 "B<SIG_HOLD>. Instead, it should return the previous disposition of the "
8255 "signal (unless the signal was blocked, in which case B<SIG_HOLD> should be "
8256 "returned). Second, if the signal is currently blocked, then the return "
8257 "value of a successful B<sigset>() should be B<SIG_HOLD>. Instead, the "
8258 "previous disposition of the signal is returned. These problems have been "
8259 "fixed since glibc 2.5."
8263 #: build/C/man3/sigset.3:276
8265 "B<kill>(2), B<pause>(2), B<sigaction>(2), B<signal>(2), B<sigprocmask>(2), "
8266 "B<raise>(3), B<sigpause>(3), B<sigvec>(3), B<signal>(7)"
8270 #: build/C/man3/sigsetops.3:31
8276 #: build/C/man3/sigsetops.3:31
8282 #: build/C/man3/sigsetops.3:35
8284 "sigemptyset, sigfillset, sigaddset, sigdelset, sigismember - POSIX signal "
8289 #: build/C/man3/sigsetops.3:39
8290 msgid "B<int sigemptyset(sigset_t *>I<set>B<);>"
8294 #: build/C/man3/sigsetops.3:41
8295 msgid "B<int sigfillset(sigset_t *>I<set>B<);>"
8299 #: build/C/man3/sigsetops.3:43
8300 msgid "B<int sigaddset(sigset_t *>I<set>B<, int >I<signum>B<);>"
8304 #: build/C/man3/sigsetops.3:45
8305 msgid "B<int sigdelset(sigset_t *>I<set>B<, int >I<signum>B<);>"
8309 #: build/C/man3/sigsetops.3:47
8310 msgid "B<int sigismember(const sigset_t *>I<set>B<, int >I<signum>B<);>"
8314 #: build/C/man3/sigsetops.3:59
8316 "B<sigemptyset>(), B<sigfillset>(), B<sigaddset>(), B<sigdelset>(), "
8321 #: build/C/man3/sigsetops.3:61
8322 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
8326 #: build/C/man3/sigsetops.3:65
8327 msgid "These functions allow the manipulation of POSIX signal sets."
8331 #: build/C/man3/sigsetops.3:70
8333 "B<sigemptyset>() initializes the signal set given by I<set> to empty, with "
8334 "all signals excluded from the set."
8338 #: build/C/man3/sigsetops.3:75
8339 msgid "B<sigfillset>() initializes I<set> to full, including all signals."
8343 #: build/C/man3/sigsetops.3:83
8345 "B<sigaddset>() and B<sigdelset>() add and delete respectively signal "
8346 "I<signum> from I<set>."
8350 #: build/C/man3/sigsetops.3:89
8351 msgid "B<sigismember>() tests whether I<signum> is a member of I<set>."
8355 #: build/C/man3/sigsetops.3:107
8357 "Objects of type I<sigset_t> must be initialized by a call to either "
8358 "B<sigemptyset>() or B<sigfillset>() before being passed to the functions "
8359 "B<sigaddset>(), B<sigdelset>() and B<sigismember>() or the additional "
8360 "glibc functions described below (B<sigisemptyset>(), B<sigandset>(), and "
8361 "B<sigorset>()). The results are undefined if this is not done."
8365 #: build/C/man3/sigsetops.3:114
8367 "B<sigemptyset>(), B<sigfillset>(), B<sigaddset>(), and B<sigdelset>() "
8368 "return 0 on success and -1 on error."
8372 #: build/C/man3/sigsetops.3:123
8374 "B<sigismember>() returns 1 if I<signum> is a member of I<set>, 0 if "
8375 "I<signum> is not a member, and -1 on error."
8379 #: build/C/man3/sigsetops.3:127
8380 msgid "On error, these functions set I<errno> to indicate the cause of the error."
8384 #: build/C/man3/sigsetops.3:132
8385 msgid "I<sig> is not a valid signal."
8389 #: build/C/man3/sigsetops.3:145
8391 "The B<sigemptyset>(), B<sigfillset>(), B<sigaddset>(), B<sigdelset>(), "
8392 "B<sigismember>(), B<sigisemptyset>(), B<sigorset>(), and B<sigandset>() "
8393 "functions are thread-safe."
8397 #: build/C/man3/sigsetops.3:148
8403 #: build/C/man3/sigsetops.3:154
8405 "If the B<_GNU_SOURCE> feature test macro is defined, then "
8406 "I<E<lt>signal.hE<gt>> exposes three other functions for manipulating signal "
8411 #: build/C/man3/sigsetops.3:161
8414 "B<int sigisemptyset(const sigset_t *>I<set>B<);>\n"
8415 "B<int sigorset(sigset_t *>I<dest>B<, const sigset_t *>I<left>B<,>\n"
8416 "B< const sigset_t *>I<right>B<);>\n"
8417 "B<int sigandset(sigset_t *>I<dest>B<, const sigset_t *>I<left>B<,>\n"
8418 "B< const sigset_t *>I<right>B<);>\n"
8422 #: build/C/man3/sigsetops.3:167
8424 "B<sigisemptyset>() returns 1 if I<set> contains no signals, and 0 "
8429 #: build/C/man3/sigsetops.3:183
8431 "B<sigorset>() places the union of the sets I<left> and I<right> in "
8432 "I<dest>. B<sigandset>() places the intersection of the sets I<left> and "
8433 "I<right> in I<dest>. Both functions return 0 on success, and -1 on failure."
8437 #: build/C/man3/sigsetops.3:186
8439 "These functions are nonstandard (a few other systems provide similar "
8440 "functions) and their use should be avoided in portable applications."
8444 #: build/C/man3/sigsetops.3:191
8445 msgid "B<sigaction>(2), B<sigpending>(2), B<sigprocmask>(2), B<sigsuspend>(2)"
8449 #: build/C/man2/sigsuspend.2:29
8455 #: build/C/man2/sigsuspend.2:32
8456 msgid "sigsuspend - wait for a signal"
8460 #: build/C/man2/sigsuspend.2:36
8461 msgid "B<int sigsuspend(const sigset_t *>I<mask>B<);>"
8465 #: build/C/man2/sigsuspend.2:45
8467 "B<sigsuspend>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || "
8472 #: build/C/man2/sigsuspend.2:53
8474 "B<sigsuspend>() temporarily replaces the signal mask of the calling process "
8475 "with the mask given by I<mask> and then suspends the process until delivery "
8476 "of a signal whose action is to invoke a signal handler or to terminate a "
8481 #: build/C/man2/sigsuspend.2:62
8483 "If the signal terminates the process, then B<sigsuspend>() does not "
8484 "return. If the signal is caught, then B<sigsuspend>() returns after the "
8485 "signal handler returns, and the signal mask is restored to the state before "
8486 "the call to B<sigsuspend>()."
8490 #: build/C/man2/sigsuspend.2:70
8492 "It is not possible to block B<SIGKILL> or B<SIGSTOP>; specifying these "
8493 "signals in I<mask>, has no effect on the process's signal mask."
8497 #: build/C/man2/sigsuspend.2:76
8499 "B<sigsuspend>() always returns -1, with I<errno> set to indicate the error "
8500 "(normally, B<EINTR>)."
8504 #: build/C/man2/sigsuspend.2:81
8506 "I<mask> points to memory which is not a valid part of the process address "
8511 #: build/C/man2/sigsuspend.2:84
8512 msgid "The call was interrupted by a signal."
8516 #: build/C/man2/sigsuspend.2:104
8518 "Normally, B<sigsuspend>() is used in conjunction with B<sigprocmask>(2) in "
8519 "order to prevent delivery of a signal during the execution of a critical "
8520 "code section. The caller first blocks the signals with B<sigprocmask>(2). "
8521 "When the critical code has completed, the caller then waits for the signals "
8522 "by calling B<sigsuspend>() with the signal mask that was returned by "
8523 "B<sigprocmask>(2) (in the I<oldset> argument)."
8527 #: build/C/man2/sigsuspend.2:118
8529 "B<kill>(2), B<pause>(2), B<sigaction>(2), B<signal>(2), B<sigprocmask>(2), "
8530 "B<sigwaitinfo>(2), B<sigsetops>(3), B<sigwait>(3), B<signal>(7)"
8534 #: build/C/man3/sigvec.3:26
8540 #: build/C/man3/sigvec.3:29
8541 msgid "sigvec, sigblock, sigsetmask, siggetmask, sigmask - BSD signal API"
8545 #: build/C/man3/sigvec.3:33
8547 "B<int sigvec(int >I<sig>B<, const struct sigvec *>I<vec>B<, struct sigvec "
8552 #: build/C/man3/sigvec.3:35
8553 msgid "B<int sigmask(int >I<signum>B<);>"
8557 #: build/C/man3/sigvec.3:37
8558 msgid "B<int sigblock(int >I<mask>B<);>"
8562 #: build/C/man3/sigvec.3:39
8563 msgid "B<int sigsetmask(int >I<mask>B<);>"
8567 #: build/C/man3/sigvec.3:41
8568 msgid "B<int siggetmask(void);>"
8572 #: build/C/man3/sigvec.3:49
8573 msgid "All functions shown above: _BSD_SOURCE"
8577 #: build/C/man3/sigvec.3:56
8579 "These functions are provided in glibc as a compatibility interface for "
8580 "programs that make use of the historical BSD signal API. This API is "
8581 "obsolete: new applications should use the POSIX signal API (B<sigaction>(2), "
8582 "B<sigprocmask>(2), etc.)."
8586 #: build/C/man3/sigvec.3:81
8588 "The B<sigvec>() function sets and/or gets the disposition of the signal "
8589 "I<sig> (like the POSIX B<sigaction>(2)). If I<vec> is not NULL, it points "
8590 "to a I<sigvec> structure that defines the new disposition for I<sig>. If "
8591 "I<ovec> is not NULL, it points to a I<sigvec> structure that is used to "
8592 "return the previous disposition of I<sig>. To obtain the current "
8593 "disposition of I<sig> without changing it, specify NULL for I<vec>, and a "
8594 "non-null pointer for I<ovec>."
8598 #: build/C/man3/sigvec.3:91
8599 msgid "The I<sigvec> structure has the following form:"
8603 #: build/C/man3/sigvec.3:99
8607 " void (*sv_handler)(int); /* Signal disposition */\n"
8608 " int sv_mask; /* Signals to be blocked in handler */\n"
8609 " int sv_flags; /* Flags */\n"
8614 #: build/C/man3/sigvec.3:110
8616 "The I<sv_handler> field specifies the disposition of the signal, and is "
8617 "either: the address of a signal handler function; B<SIG_DFL>, meaning the "
8618 "default disposition applies for the signal; or B<SIG_IGN>, meaning that the "
8619 "signal is ignored."
8623 #: build/C/man3/sigvec.3:124
8625 "If I<sv_handler> specifies the address of a signal handler, then I<sv_mask> "
8626 "specifies a mask of signals that are to be blocked while the handler is "
8627 "executing. In addition, the signal for which the handler is invoked is also "
8628 "blocked. Attempts to block B<SIGKILL> or B<SIGSTOP> are silently ignored."
8632 #: build/C/man3/sigvec.3:131
8634 "If I<sv_handler> specifies the address of a signal handler, then the "
8635 "I<sv_flags> field specifies flags controlling what happens when the handler "
8636 "is called. This field may contain zero or more of the following flags:"
8640 #: build/C/man3/sigvec.3:131
8642 msgid "B<SV_INTERRUPT>"
8646 #: build/C/man3/sigvec.3:139
8648 "If the signal handler interrupts a blocking system call, then upon return "
8649 "from the handler the system call will not be restarted: instead it will fail "
8650 "with the error B<EINTR>. If this flag is not specified, then system calls "
8651 "are restarted by default."
8655 #: build/C/man3/sigvec.3:139
8657 msgid "B<SV_RESETHAND>"
8661 #: build/C/man3/sigvec.3:148
8663 "Reset the disposition of the signal to the default before calling the signal "
8664 "handler. If this flag is not specified, then the handler remains "
8665 "established until explicitly removed by a later call to B<sigvec>() or "
8666 "until the process performs an B<execve>(2)."
8670 #: build/C/man3/sigvec.3:148
8672 msgid "B<SV_ONSTACK>"
8676 #: build/C/man3/sigvec.3:155
8678 "Handle the signal on the alternate signal stack (historically established "
8679 "under BSD using the obsolete B<sigstack>() function; the POSIX replacement "
8680 "is B<sigaltstack>(2))."
8684 #: build/C/man3/sigvec.3:165
8686 "The B<sigmask>() macro constructs and returns a \"signal mask\" for "
8687 "I<signum>. For example, we can initialize the I<vec.sv_mask> field given to "
8688 "B<sigvec>() using code such as the following:"
8692 #: build/C/man3/sigvec.3:170
8695 " vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT);\n"
8696 " /* Block SIGQUIT and SIGABRT during\n"
8697 " handler execution */\n"
8701 #: build/C/man3/sigvec.3:185
8703 "The B<sigblock>() function adds the signals in I<mask> to the process's "
8704 "signal mask (like POSIX I<sigprocmask(SIG_BLOCK)>), and returns the "
8705 "process's previous signal mask. Attempts to block B<SIGKILL> or B<SIGSTOP> "
8706 "are silently ignored."
8710 #: build/C/man3/sigvec.3:193
8712 "The B<sigsetmask>() function sets the process's signal mask to the value "
8713 "given in I<mask> (like POSIX I<sigprocmask(SIG_SETMASK)>), and returns the "
8714 "process's previous signal mask."
8718 #: build/C/man3/sigvec.3:199
8720 "The B<siggetmask>() function returns the process's current signal mask. "
8721 "This call is equivalent to I<sigblock(0)>."
8725 #: build/C/man3/sigvec.3:205
8727 "The B<sigvec>() function returns 0 on success; on error, it returns -1 and "
8728 "sets I<errno> to indicate the error."
8732 #: build/C/man3/sigvec.3:211
8734 "The B<sigblock>() and B<sigsetmask>() functions return the previous signal "
8739 #: build/C/man3/sigvec.3:216
8740 msgid "The B<sigmask>() macro returns the signal mask for I<signum>."
8744 #: build/C/man3/sigvec.3:221
8745 msgid "See the ERRORS under B<sigaction>(2) and B<sigprocmask>(2)."
8749 #: build/C/man3/sigvec.3:230
8751 "The B<sigvec>(), B<sigblock>(), B<sigsetmask>(), and B<siggetmask>() "
8752 "functions are thread-safe."
8756 #: build/C/man3/sigvec.3:234
8757 msgid "The B<sigmask>() macro is thread-safe."
8761 #: build/C/man3/sigvec.3:241
8763 "Starting with version 2.21, the GNU C library no longer exports the "
8764 "B<sigvec>() function as part of the ABI. (To ensure backward "
8765 "compatibility, the glibc symbol versioning scheme continues to export the "
8766 "interface to binaries linked against older versions of the library.)"
8770 #: build/C/man3/sigvec.3:247
8772 "All of these functions were in 4.3BSD, except B<siggetmask>(), whose origin "
8773 "is unclear. These functions are obsolete: do not use them in new programs."
8777 #: build/C/man3/sigvec.3:264
8779 "On 4.3BSD, the B<signal>() function provided reliable semantics (as when "
8780 "calling B<sigvec>() with I<vec.sv_mask> equal to 0). On System V, "
8781 "B<signal>() provides unreliable semantics. POSIX.1-2001 leaves these "
8782 "aspects of B<signal>() unspecified. See B<signal>(2) for further details."
8786 #: build/C/man3/sigvec.3:282
8788 "B<kill>(2), B<pause>(2), B<sigaction>(2), B<signal>(2), B<sigprocmask>(2), "
8789 "B<raise>(3), B<sigpause>(3), B<sigset>(3), B<signal>(7)"
8793 #: build/C/man3/sigwait.3:26
8799 #: build/C/man3/sigwait.3:29
8800 msgid "sigwait - wait for a signal"
8804 #: build/C/man3/sigwait.3:34
8806 msgid "B< int sigwait(const sigset_t *>I<set>B<, int *>I<sig>B<);>\n"
8810 #: build/C/man3/sigwait.3:44
8811 msgid "B<sigwait>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
8815 #: build/C/man3/sigwait.3:56
8817 "The B<sigwait>() function suspends execution of the calling thread until "
8818 "one of the signals specified in the signal set I<set> becomes pending. The "
8819 "function accepts the signal (removes it from the pending list of signals), "
8820 "and returns the signal number in I<sig>."
8824 #: build/C/man3/sigwait.3:62
8826 "The operation of B<sigwait>() is the same as B<sigwaitinfo>(2), except "
8831 #: build/C/man3/sigwait.3:67
8833 "B<sigwait>() returns only the signal number, rather than a I<siginfo_t> "
8834 "structure describing the signal."
8838 #: build/C/man3/sigwait.3:69
8839 msgid "The return values of the two functions are different."
8843 #: build/C/man3/sigwait.3:74
8845 "On success, B<sigwait>() returns 0. On error, it returns a positive error "
8846 "number (listed in ERRORS)."
8849 #. Does not occur for glibc.
8851 #: build/C/man3/sigwait.3:80
8852 msgid "I<set> contains an invalid signal number."
8856 #: build/C/man3/sigwait.3:85
8857 msgid "The B<sigwait>() function is thread-safe."
8861 #: build/C/man3/sigwait.3:91
8862 msgid "B<sigwait>() is implemented using B<sigtimedwait>(2)."
8866 #: build/C/man3/sigwait.3:94
8867 msgid "See B<pthread_sigmask>(3)."
8871 #: build/C/man3/sigwait.3:102
8873 "B<sigaction>(2), B<signalfd>(2), B<sigpending>(2), B<sigsuspend>(2), "
8874 "B<sigwaitinfo>(2), B<sigsetops>(3), B<signal>(7)"
8878 #: build/C/man2/sigwaitinfo.2:25
8884 #: build/C/man2/sigwaitinfo.2:28
8885 msgid "sigwaitinfo, sigtimedwait - synchronously wait for queued signals"
8889 #: build/C/man2/sigwaitinfo.2:33
8891 msgid "B<int sigwaitinfo(const sigset_t *>I<set>B<, siginfo_t *>I<info>B<);>\n"
8895 #: build/C/man2/sigwaitinfo.2:36
8898 "B<int sigtimedwait(const sigset_t *>I<set>B<, siginfo_t *>I<info>B<, >\n"
8899 "B< const struct timespec *>I<timeout>B<);>\n"
8903 #: build/C/man2/sigwaitinfo.2:46
8904 msgid "B<sigwaitinfo>(), B<sigtimedwait>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
8908 #: build/C/man2/sigwaitinfo.2:56
8910 "B<sigwaitinfo>() suspends execution of the calling thread until one of the "
8911 "signals in I<set> is pending (If one of the signals in I<set> is already "
8912 "pending for the calling thread, B<sigwaitinfo>() will return immediately.)"
8916 #: build/C/man2/sigwaitinfo.2:68
8918 "B<sigwaitinfo>() removes the signal from the set of pending signals and "
8919 "returns the signal number as its function result. If the I<info> argument "
8920 "is not NULL, then the buffer that it points to is used to return a structure "
8921 "of type I<siginfo_t> (see B<sigaction>(2)) containing information about the "
8926 #: build/C/man2/sigwaitinfo.2:76
8928 "If multiple signals in I<set> are pending for the caller, the signal that is "
8929 "retrieved by B<sigwaitinfo>() is determined according to the usual ordering "
8930 "rules; see B<signal>(7) for further details."
8934 #: build/C/man2/sigwaitinfo.2:88
8936 "B<sigtimedwait>() operates in exactly the same way as B<sigwaitinfo>() "
8937 "except that it has an additional argument, I<timeout>, which specifies the "
8938 "interval for which the thread is suspended waiting for a signal. (This "
8939 "interval will be rounded up to the system clock granularity, and kernel "
8940 "scheduling delays mean that the interval may overrun by a small amount.) "
8941 "This argument is of the following type:"
8945 #: build/C/man2/sigwaitinfo.2:95
8948 "struct timespec {\n"
8949 " long tv_sec; /* seconds */\n"
8950 " long tv_nsec; /* nanoseconds */\n"
8955 #: build/C/man2/sigwaitinfo.2:105
8957 "If both fields of this structure are specified as 0, a poll is performed: "
8958 "B<sigtimedwait>() returns immediately, either with information about a "
8959 "signal that was pending for the caller, or with an error if none of the "
8960 "signals in I<set> was pending."
8964 #: build/C/man2/sigwaitinfo.2:114
8966 "On success, both B<sigwaitinfo>() and B<sigtimedwait>() return a signal "
8967 "number (i.e., a value greater than zero). On failure both calls return -1, "
8968 "with I<errno> set to indicate the error."
8972 #: build/C/man2/sigwaitinfo.2:123
8974 "No signal in I<set> was became pending within the I<timeout> period "
8975 "specified to B<sigtimedwait>()."
8979 #: build/C/man2/sigwaitinfo.2:129
8981 "The wait was interrupted by a signal handler; see B<signal>(7). (This "
8982 "handler was for a signal other than one of those in I<set>.)"
8986 #: build/C/man2/sigwaitinfo.2:133
8987 msgid "I<timeout> was invalid."
8991 #: build/C/man2/sigwaitinfo.2:153
8993 "In normal usage, the calling program blocks the signals in I<set> via a "
8994 "prior call to B<sigprocmask>(2) (so that the default disposition for these "
8995 "signals does not occur if they become pending between successive calls to "
8996 "B<sigwaitinfo>() or B<sigtimedwait>()) and does not establish handlers for "
8997 "these signals. In a multithreaded program, the signal should be blocked in "
8998 "all threads, in order to prevent the signal being treated according to its "
8999 "default disposition in a thread other than the one calling B<sigwaitinfo>() "
9000 "or B<sigtimedwait>())."
9004 #: build/C/man2/sigwaitinfo.2:158
9006 "The set of signals that is pending for a given thread is the union of the "
9007 "set of signals that is pending specifically for that thread and the set of "
9008 "signals that is pending for the process as a whole (see B<signal>(7))."
9012 #: build/C/man2/sigwaitinfo.2:164
9013 msgid "Attempts to wait for B<SIGKILL> and B<SIGSTOP> are silently ignored."
9017 #: build/C/man2/sigwaitinfo.2:173
9019 "If multiple threads of a process are blocked waiting for the same signal(s) "
9020 "in B<sigwaitinfo>() or B<sigtimedwait>(), then exactly one of the threads "
9021 "will actually receive the signal if it becomes pending for the process as a "
9022 "whole; which of the threads receives the signal is indeterminate."
9026 #: build/C/man2/sigwaitinfo.2:183
9028 "POSIX leaves the meaning of a NULL value for the I<timeout> argument of "
9029 "B<sigtimedwait>() unspecified, permitting the possibility that this has the "
9030 "same meaning as a call to B<sigwaitinfo>(), and indeed this is what is done "
9035 #: build/C/man2/sigwaitinfo.2:188
9037 "On Linux, B<sigwaitinfo>() is a library function implemented on top of "
9038 "B<sigtimedwait>()."
9042 #: build/C/man2/sigwaitinfo.2:201
9044 "The raw B<sigtimedwait>() system call has a fifth argument, I<size_t "
9045 "sigsetsize>, which specifies the size in bytes of the I<set> argument. The "
9046 "glibc B<sigtimedwait>() wrapper function specifies this argument as a fixed "
9047 "value (equal to I<sizeof(sigset_t)>)."
9051 #: build/C/man2/sigwaitinfo.2:213
9053 "B<kill>(2), B<sigaction>(2), B<signal>(2), B<signalfd>(2), B<sigpending>(2), "
9054 "B<sigprocmask>(2), B<sigqueue>(3), B<sigsetops>(3), B<sigwait>(3), "
9055 "B<signal>(7), B<time>(7)"
9059 #: build/C/man3/sysv_signal.3:25
9065 #: build/C/man3/sysv_signal.3:25
9071 #: build/C/man3/sysv_signal.3:28
9072 msgid "sysv_signal - signal handling with System V semantics"
9076 #: build/C/man3/sysv_signal.3:30
9077 msgid "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */"
9081 #: build/C/man3/sysv_signal.3:36
9082 msgid "B<sighandler_t sysv_signal(int >I<signum>B<, sighandler_t >I<handler>B<);>"
9086 #: build/C/man3/sysv_signal.3:41
9088 "The B<sysv_signal>() function takes the same arguments, and performs the "
9089 "same task, as B<signal>(2)."
9093 #: build/C/man3/sysv_signal.3:51
9095 "However B<sysv_signal>() provides the System V unreliable signal semantics, "
9096 "that is: a) the disposition of the signal is reset to the default when the "
9097 "handler is invoked; b) delivery of further instances of the signal is not "
9098 "blocked while the signal handler is executing; and c) if the handler "
9099 "interrupts (certain) blocking system calls, then the system call is not "
9100 "automatically restarted."
9104 #: build/C/man3/sysv_signal.3:57
9106 "The B<sysv_signal>() function returns the previous value of the signal "
9107 "handler, or B<SIG_ERR> on error."
9111 #: build/C/man3/sysv_signal.3:65
9112 msgid "The B<sysv_signal>() function is thread-safe."
9116 #: build/C/man3/sysv_signal.3:67
9117 msgid "This function is nonstandard."
9121 #: build/C/man3/sysv_signal.3:73
9122 msgid "Use of B<sysv_signal>() should be avoided; use B<sigaction>(2) instead."
9126 #: build/C/man3/sysv_signal.3:84
9128 "On older Linux systems, B<sysv_signal>() and B<signal>(2) were "
9129 "equivalent. But on newer systems, B<signal>(2) provides reliable signal "
9130 "semantics; see B<signal>(2) for details."
9134 #: build/C/man3/sysv_signal.3:97
9135 msgid "B<sigaction>(2), B<signal>(2), B<bsd_signal>(3), B<signal>(7)"
9139 #: build/C/man2/timer_create.2:33
9141 msgid "TIMER_CREATE"
9145 #: build/C/man2/timer_create.2:36
9146 msgid "timer_create - create a POSIX per-process timer"
9150 #: build/C/man2/timer_create.2:40
9153 "B<#include E<lt>signal.hE<gt>>\n"
9154 "B<#include E<lt>time.hE<gt>>\n"
9158 #: build/C/man2/timer_create.2:43
9161 "B<int timer_create(clockid_t >I<clockid>B<, struct sigevent *>I<sevp>B<,>\n"
9162 "B< timer_t *>I<timerid>B<);>\n"
9166 #: build/C/man2/timer_create.2:46 build/C/man2/timer_delete.2:37 build/C/man2/timer_getoverrun.2:37 build/C/man2/timer_settime.2:41
9167 msgid "Link with I<-lrt>."
9171 #: build/C/man2/timer_create.2:54
9172 msgid "B<timer_create>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
9176 #: build/C/man2/timer_create.2:62
9178 "B<timer_create>() creates a new per-process interval timer. The ID of the "
9179 "new timer is returned in the buffer pointed to by I<timerid>, which must be "
9180 "a non-null pointer. This ID is unique within the process, until the timer "
9181 "is deleted. The new timer is initially disarmed."
9185 #: build/C/man2/timer_create.2:67
9187 "The I<clockid> argument specifies the clock that the new timer uses to "
9188 "measure time. It can be specified as one of the following values:"
9192 #: build/C/man2/timer_create.2:67
9194 msgid "B<CLOCK_REALTIME>"
9198 #: build/C/man2/timer_create.2:70
9199 msgid "A settable system-wide real-time clock."
9203 #: build/C/man2/timer_create.2:70
9205 msgid "B<CLOCK_MONOTONIC>"
9208 #. Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime()
9209 #. in 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009
9211 #: build/C/man2/timer_create.2:77
9213 "A nonsettable monotonically increasing clock that measures time from some "
9214 "unspecified point in the past that does not change after system startup."
9218 #: build/C/man2/timer_create.2:77
9220 msgid "B<CLOCK_PROCESS_CPUTIME_ID> (since Linux 2.6.12)"
9224 #: build/C/man2/timer_create.2:81
9226 "A clock that measures (user and system) CPU time consumed by (all of the "
9227 "threads in) the calling process."
9231 #: build/C/man2/timer_create.2:81
9233 msgid "B<CLOCK_THREAD_CPUTIME_ID> (since Linux 2.6.12)"
9236 #. The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used
9237 #. to create a timer -- mtk, Feb 2009
9239 #: build/C/man2/timer_create.2:87
9241 "A clock that measures (user and system) CPU time consumed by the calling "
9246 #: build/C/man2/timer_create.2:96
9248 "As well as the above values, I<clockid> can be specified as the I<clockid> "
9249 "returned by a call to B<clock_getcpuclockid>(3) or "
9250 "B<pthread_getcpuclockid>(3)."
9254 #: build/C/man2/timer_create.2:105
9256 "The I<sevp> argument points to a I<sigevent> structure that specifies how "
9257 "the caller should be notified when the timer expires. For the definition "
9258 "and general details of this structure, see B<sigevent>(7)."
9262 #: build/C/man2/timer_create.2:109
9263 msgid "The I<sevp.sigev_notify> field can have the following values:"
9267 #: build/C/man2/timer_create.2:114
9269 "Don't asynchronously notify when the timer expires. Progress of the timer "
9270 "can be monitored using B<timer_gettime>(2)."
9274 #: build/C/man2/timer_create.2:132
9276 "Upon timer expiration, generate the signal I<sigev_signo> for the process. "
9277 "See B<sigevent>(7) for general details. The I<si_code> field of the "
9278 "I<siginfo_t> structure will be set to B<SI_TIMER>. At any point in time, at "
9279 "most one signal is queued to the process for a given timer; see "
9280 "B<timer_getoverrun>(2) for more details."
9284 #: build/C/man2/timer_create.2:140
9286 "Upon timer expiration, invoke I<sigev_notify_function> as if it were the "
9287 "start function of a new thread. See B<sigevent>(7) for details."
9291 #: build/C/man2/timer_create.2:154
9293 "As for B<SIGEV_SIGNAL>, but the signal is targeted at the thread whose ID is "
9294 "given in I<sigev_notify_thread_id>, which must be a thread in the same "
9295 "process as the caller. The I<sigev_notify_thread_id> field specifies a "
9296 "kernel thread ID, that is, the value returned by B<clone>(2) or "
9297 "B<gettid>(2). This flag is intended only for use by threading libraries."
9301 #: build/C/man2/timer_create.2:169
9303 "Specifying I<sevp> as NULL is equivalent to specifying a pointer to a "
9304 "I<sigevent> structure in which I<sigev_notify> is B<SIGEV_SIGNAL>, "
9305 "I<sigev_signo> is B<SIGALRM>, and I<sigev_value.sival_int> is the timer ID."
9309 #: build/C/man2/timer_create.2:177
9311 "On success, B<timer_create>() returns 0, and the ID of the new timer is "
9312 "placed in I<*timerid>. On failure, -1 is returned, and I<errno> is set to "
9313 "indicate the error."
9317 #: build/C/man2/timer_create.2:181
9318 msgid "Temporary error during kernel allocation of timer structures."
9322 #: build/C/man2/timer_create.2:189
9324 "Clock ID, I<sigev_notify>, I<sigev_signo>, or I<sigev_notify_thread_id> is "
9328 #. glibc layer: malloc()
9330 #: build/C/man2/timer_create.2:193
9331 msgid "Could not allocate memory."
9335 #: build/C/man2/timer_create.2:195 build/C/man2/timer_delete.2:67 build/C/man2/timer_getoverrun.2:97
9336 msgid "This system call is available since Linux 2.6."
9340 #: build/C/man2/timer_create.2:200
9341 msgid "A program may create multiple interval timers using B<timer_create>()."
9345 #: build/C/man2/timer_create.2:205
9347 "Timers are not inherited by the child of a B<fork>(2), and are disarmed and "
9348 "deleted during an B<execve>(2)."
9352 #: build/C/man2/timer_create.2:213
9354 "The kernel preallocates a \"queued real-time signal\" for each timer created "
9355 "using B<timer_create>(). Consequently, the number of timers is limited by "
9356 "the B<RLIMIT_SIGPENDING> resource limit (see B<setrlimit>(2))."
9360 #: build/C/man2/timer_create.2:218
9362 "The timers created by B<timer_create>() are commonly known as \"POSIX "
9363 "(interval) timers\". The POSIX timers API consists of the following "
9368 #: build/C/man2/timer_create.2:221
9369 msgid "B<timer_create>(): Create a timer."
9373 #: build/C/man2/timer_create.2:224
9374 msgid "B<timer_settime>(2): Arm (start) or disarm (stop) a timer."
9378 #: build/C/man2/timer_create.2:228
9380 "B<timer_gettime>(2): Fetch the time remaining until the next expiration of a "
9381 "timer, along with the interval setting of the timer."
9385 #: build/C/man2/timer_create.2:231
9387 "B<timer_getoverrun>(2): Return the overrun count for the last timer "
9392 #: build/C/man2/timer_create.2:234
9393 msgid "B<timer_delete>(2): Disarm and delete a timer."
9397 #: build/C/man2/timer_create.2:243
9399 "Since Linux 3.10, the I</proc/[pid]/timers> file can be used to list the "
9400 "POSIX timers for the process with PID I<pid>. See B<proc>(5) for further "
9405 #: build/C/man2/timer_create.2:246
9407 "Part of the implementation of the POSIX timers API is provided by glibc. In "
9412 #: build/C/man2/timer_create.2:250
9414 "The functionality for B<SIGEV_THREAD> is implemented within glibc, rather "
9418 #. See the glibc source file kernel-posix-timers.h for the structure
9419 #. that glibc uses to map user-space timer IDs to kernel timer IDs
9420 #. The kernel-level timer ID is exposed via siginfo.si_tid.
9422 #: build/C/man2/timer_create.2:256
9424 "The timer IDs presented at user level are maintained by glibc, which maps "
9425 "these IDs to the timer IDs employed by the kernel."
9429 #: build/C/man2/timer_create.2:264
9431 "The POSIX timers system calls first appeared in Linux 2.6. Prior to this, "
9432 "glibc provided an incomplete user-space implementation (B<CLOCK_REALTIME> "
9433 "timers only) using POSIX threads, and current glibc falls back to this "
9434 "implementation on systems running pre-2.6 Linux kernels."
9438 #: build/C/man2/timer_create.2:276
9440 "The program below takes two arguments: a sleep period in seconds, and a "
9441 "timer frequency in nanoseconds. The program establishes a handler for the "
9442 "signal it uses for the timer, blocks that signal, creates and arms a timer "
9443 "that expires with the given frequency, sleeps for the specified number of "
9444 "seconds, and then unblocks the timer signal. Assuming that the timer "
9445 "expired at least once while the program slept, the signal handler will be "
9446 "invoked, and the handler displays some information about the timer "
9447 "notification. The program terminates after one invocation of the signal "
9452 #: build/C/man2/timer_create.2:281
9454 "In the following example run, the program sleeps for 1 second, after "
9455 "creating a timer that has a frequency of 100 nanoseconds. By the time the "
9456 "signal is unblocked and delivered, there have been around ten million "
9461 #: build/C/man2/timer_create.2:293
9464 "$ B<./a.out 1 100>\n"
9465 "Establishing handler for signal 34\n"
9466 "Blocking signal 34\n"
9467 "timer ID is 0x804c008\n"
9468 "Sleeping for 1 seconds\n"
9469 "Unblocking signal 34\n"
9470 "Caught signal 34\n"
9471 " sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008\n"
9472 " overrun count = 10004886\n"
9476 #: build/C/man2/timer_create.2:303
9479 "#include E<lt>stdlib.hE<gt>\n"
9480 "#include E<lt>unistd.hE<gt>\n"
9481 "#include E<lt>stdio.hE<gt>\n"
9482 "#include E<lt>signal.hE<gt>\n"
9483 "#include E<lt>time.hE<gt>\n"
9487 #: build/C/man2/timer_create.2:306
9490 "#define CLOCKID CLOCK_REALTIME\n"
9491 "#define SIG SIGRTMIN\n"
9495 #: build/C/man2/timer_create.2:309
9498 "#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\e\n"
9503 #: build/C/man2/timer_create.2:315
9507 "print_siginfo(siginfo_t *si)\n"
9514 #: build/C/man2/timer_create.2:317
9516 msgid " tidp = si-E<gt>si_value.sival_ptr;\n"
9520 #: build/C/man2/timer_create.2:320
9523 " printf(\" sival_ptr = %p; \", si-E<gt>si_value.sival_ptr);\n"
9524 " printf(\" *sival_ptr = 0x%lx\\en\", (long) *tidp);\n"
9528 #: build/C/man2/timer_create.2:327
9531 " or = timer_getoverrun(*tidp);\n"
9533 " errExit(\"timer_getoverrun\");\n"
9535 " printf(\" overrun count = %d\\en\", or);\n"
9540 #: build/C/man2/timer_create.2:334
9544 "handler(int sig, siginfo_t *si, void *uc)\n"
9546 " /* Note: calling printf() from a signal handler is not\n"
9547 " strictly correct, since printf() is not async-signal-safe;\n"
9548 " see signal(7) */\n"
9552 #: build/C/man2/timer_create.2:339
9555 " printf(\"Caught signal %d\\en\", sig);\n"
9556 " print_siginfo(si);\n"
9557 " signal(sig, SIG_IGN);\n"
9562 #: build/C/man2/timer_create.2:349
9566 "main(int argc, char *argv[])\n"
9568 " timer_t timerid;\n"
9569 " struct sigevent sev;\n"
9570 " struct itimerspec its;\n"
9571 " long long freq_nanosecs;\n"
9573 " struct sigaction sa;\n"
9577 #: build/C/man2/timer_create.2:355
9580 " if (argc != 3) {\n"
9581 " fprintf(stderr, \"Usage: %s E<lt>sleep-secsE<gt> "
9582 "E<lt>freq-nanosecsE<gt>\\en\",\n"
9584 " exit(EXIT_FAILURE);\n"
9589 #: build/C/man2/timer_create.2:357
9591 msgid " /* Establish handler for timer signal */\n"
9595 #: build/C/man2/timer_create.2:364
9598 " printf(\"Establishing handler for signal %d\\en\", SIG);\n"
9599 " sa.sa_flags = SA_SIGINFO;\n"
9600 " sa.sa_sigaction = handler;\n"
9601 " sigemptyset(&sa.sa_mask);\n"
9602 " if (sigaction(SIG, &sa, NULL) == -1)\n"
9603 " errExit(\"sigaction\");\n"
9607 #: build/C/man2/timer_create.2:366
9609 msgid " /* Block timer signal temporarily */\n"
9613 #: build/C/man2/timer_create.2:372
9616 " printf(\"Blocking signal %d\\en\", SIG);\n"
9617 " sigemptyset(&mask);\n"
9618 " sigaddset(&mask, SIG);\n"
9619 " if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)\n"
9620 " errExit(\"sigprocmask\");\n"
9624 #: build/C/man2/timer_create.2:374
9626 msgid " /* Create the timer */\n"
9630 #: build/C/man2/timer_create.2:380
9633 " sev.sigev_notify = SIGEV_SIGNAL;\n"
9634 " sev.sigev_signo = SIG;\n"
9635 " sev.sigev_value.sival_ptr = &timerid;\n"
9636 " if (timer_create(CLOCKID, &sev, &timerid) == -1)\n"
9637 " errExit(\"timer_create\");\n"
9641 #: build/C/man2/timer_create.2:382
9643 msgid " printf(\"timer ID is 0x%lx\\en\", (long) timerid);\n"
9647 #: build/C/man2/timer_create.2:384
9649 msgid " /* Start the timer */\n"
9653 #: build/C/man2/timer_create.2:390
9656 " freq_nanosecs = atoll(argv[2]);\n"
9657 " its.it_value.tv_sec = freq_nanosecs / 1000000000;\n"
9658 " its.it_value.tv_nsec = freq_nanosecs % 1000000000;\n"
9659 " its.it_interval.tv_sec = its.it_value.tv_sec;\n"
9660 " its.it_interval.tv_nsec = its.it_value.tv_nsec;\n"
9664 #: build/C/man2/timer_create.2:393
9667 " if (timer_settime(timerid, 0, &its, NULL) == -1)\n"
9668 " errExit(\"timer_settime\");\n"
9672 #: build/C/man2/timer_create.2:396
9675 " /* Sleep for a while; meanwhile, the timer may expire\n"
9676 " multiple times */\n"
9680 #: build/C/man2/timer_create.2:399
9683 " printf(\"Sleeping for %d seconds\\en\", atoi(argv[1]));\n"
9684 " sleep(atoi(argv[1]));\n"
9688 #: build/C/man2/timer_create.2:402
9691 " /* Unlock the timer signal, so that timer notification\n"
9692 " can be delivered */\n"
9696 #: build/C/man2/timer_create.2:406
9699 " printf(\"Unblocking signal %d\\en\", SIG);\n"
9700 " if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)\n"
9701 " errExit(\"sigprocmask\");\n"
9705 #: build/C/man2/timer_create.2:409 build/C/man2/timerfd_create.2:547
9708 " exit(EXIT_SUCCESS);\n"
9713 #: build/C/man2/timer_create.2:425
9715 "B<clock_gettime>(2), B<setitimer>(2), B<timer_delete>(2), "
9716 "B<timer_getoverrun>(2), B<timer_settime>(2), B<timerfd_create>(2), "
9717 "B<clock_getcpuclockid>(3), B<pthread_getcpuclockid>(3), B<pthreads>(7), "
9718 "B<sigevent>(7), B<signal>(7), B<time>(7)"
9722 #: build/C/man2/timer_delete.2:26
9724 msgid "TIMER_DELETE"
9728 #: build/C/man2/timer_delete.2:26 build/C/man2/timer_getoverrun.2:26
9734 #: build/C/man2/timer_delete.2:29
9735 msgid "timer_delete - delete a POSIX per-process timer"
9739 #: build/C/man2/timer_delete.2:32 build/C/man2/timer_getoverrun.2:32 build/C/man2/timer_settime.2:33
9741 msgid "B<#include E<lt>time.hE<gt>>\n"
9745 #: build/C/man2/timer_delete.2:34
9747 msgid "B<int timer_delete(timer_t >I<timerid>B<);>\n"
9751 #: build/C/man2/timer_delete.2:45
9752 msgid "B<timer_delete>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
9756 #: build/C/man2/timer_delete.2:53
9758 "B<timer_delete>() deletes the timer whose ID is given in I<timerid>. If "
9759 "the timer was armed at the time of this call, it is disarmed before being "
9760 "deleted. The treatment of any pending signal generated by the deleted timer "
9765 #: build/C/man2/timer_delete.2:60
9767 "On success, B<timer_delete>() returns 0. On failure, -1 is returned, and "
9768 "I<errno> is set to indicate the error."
9772 #: build/C/man2/timer_delete.2:65 build/C/man2/timer_getoverrun.2:95
9773 msgid "I<timerid> is not a valid timer ID."
9777 #: build/C/man2/timer_delete.2:75
9779 "B<clock_gettime>(2), B<timer_create>(2), B<timer_getoverrun>(2), "
9780 "B<timer_settime>(2), B<time>(7)"
9784 #: build/C/man2/timer_getoverrun.2:26
9786 msgid "TIMER_GETOVERRUN"
9790 #: build/C/man2/timer_getoverrun.2:29
9791 msgid "timer_getoverrun - get overrun count for a POSIX per-process timer"
9795 #: build/C/man2/timer_getoverrun.2:34
9797 msgid "B<int timer_getoverrun(timer_t >I<timerid>B<);>\n"
9801 #: build/C/man2/timer_getoverrun.2:45
9802 msgid "B<timer_getoverrun>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
9806 #: build/C/man2/timer_getoverrun.2:56
9808 "B<timer_getoverrun>() returns the \"overrun count\" for the timer referred "
9809 "to by I<timerid>. An application can use the overrun count to accurately "
9810 "calculate the number of timer expirations that would have occurred over a "
9811 "given time interval. Timer overruns can occur both when receiving "
9812 "expiration notifications via signals (B<SIGEV_SIGNAL>), and via threads "
9813 "(B<SIGEV_THREAD>)."
9817 #: build/C/man2/timer_getoverrun.2:76
9819 "When expiration notifications are delivered via a signal, overruns can occur "
9820 "as follows. Regardless of whether or not a real-time signal is used for "
9821 "timer notifications, the system queues at most one signal per timer. (This "
9822 "is the behavior specified by POSIX.1-2001. The alternative, queuing one "
9823 "signal for each timer expiration, could easily result in overflowing the "
9824 "allowed limits for queued signals on the system.) Because of system "
9825 "scheduling delays, or because the signal may be temporarily blocked, there "
9826 "can be a delay between the time when the notification signal is generated "
9827 "and the time when it is delivered (e.g., caught by a signal handler) or "
9828 "accepted (e.g., using B<sigwaitinfo>(2)). In this interval, further timer "
9829 "expirations may occur. The timer overrun count is the number of additional "
9830 "timer expirations that occurred between the time when the signal was "
9831 "generated and when it was delivered or accepted."
9835 #: build/C/man2/timer_getoverrun.2:82
9837 "Timer overruns can also occur when expiration notifications are delivered "
9838 "via invocation of a thread, since there may be an arbitrary delay between an "
9839 "expiration of the timer and the invocation of the notification thread, and "
9840 "in that delay interval, additional timer expirations may occur."
9844 #: build/C/man2/timer_getoverrun.2:90
9846 "On success, B<timer_getoverrun>() returns the overrun count of the "
9847 "specified timer; this count may be 0 if no overruns have occurred. On "
9848 "failure, -1 is returned, and I<errno> is set to indicate the error."
9852 #: build/C/man2/timer_getoverrun.2:111
9854 "When timer notifications are delivered via signals (B<SIGEV_SIGNAL>), on "
9855 "Linux it is also possible to obtain the overrun count via the I<si_overrun> "
9856 "field of the I<siginfo_t> structure (see B<sigaction>(2)). This allows an "
9857 "application to avoid the overhead of making a system call to obtain the "
9858 "overrun count, but is a nonportable extension to POSIX.1-2001."
9861 #. FIXME . Austin bug filed, 11 Feb 09
9863 #: build/C/man2/timer_getoverrun.2:115
9865 "POSIX.1-2001 discusses timer overruns only in the context of timer "
9866 "notifications using signals."
9869 #. Bug filed: http://bugzilla.kernel.org/show_bug.cgi?id=12665
9870 #. http://thread.gmane.org/gmane.linux.kernel/113276/
9872 #: build/C/man2/timer_getoverrun.2:128
9874 "POSIX.1-2001 specifies that if the timer overrun count is equal to or "
9875 "greater than an implementation-defined maximum, B<DELAYTIMER_MAX>, then "
9876 "B<timer_getoverrun>() should return B<DELAYTIMER_MAX>. However, Linux does "
9877 "not implement this feature: instead, if the timer overrun value exceeds the "
9878 "maximum representable integer, the counter cycles, starting once more from "
9883 #: build/C/man2/timer_getoverrun.2:131 build/C/man2/timer_settime.2:212
9884 msgid "See B<timer_create>(2)."
9888 #: build/C/man2/timer_getoverrun.2:141
9890 "B<clock_gettime>(2), B<sigaction>(2), B<signalfd>(2), B<sigwaitinfo>(2), "
9891 "B<timer_create>(2), B<timer_delete>(2), B<timer_settime>(2), B<signal>(7), "
9896 #: build/C/man2/timer_settime.2:26
9898 msgid "TIMER_SETTIME"
9902 #: build/C/man2/timer_settime.2:26
9908 #: build/C/man2/timer_settime.2:30
9910 "timer_settime, timer_gettime - arm/disarm and fetch state of POSIX "
9915 #: build/C/man2/timer_settime.2:38
9918 "B<int timer_settime(timer_t >I<timerid>B<, int >I<flags>B<,>\n"
9919 "B< const struct itimerspec *>I<new_value>B<,>\n"
9920 "B< struct itimerspec *>I<old_value>B<);>\n"
9921 "B<int timer_gettime(timer_t >I<timerid>B<, struct itimerspec "
9922 "*>I<curr_value>B<);>\n"
9926 #: build/C/man2/timer_settime.2:50
9927 msgid "B<timer_settime>(), B<timer_gettime>(): _POSIX_C_SOURCE\\ E<gt>=\\ 199309L"
9931 #: build/C/man2/timer_settime.2:63
9933 "B<timer_settime>() arms or disarms the timer identified by I<timerid>. The "
9934 "I<new_value> argument is pointer to an I<itimerspec> structure that "
9935 "specifies the new initial value and the new interval for the timer. The "
9936 "I<itimerspec> structure is defined as follows:"
9940 #: build/C/man2/timer_settime.2:70 build/C/man2/timerfd_create.2:135
9943 "struct timespec {\n"
9944 " time_t tv_sec; /* Seconds */\n"
9945 " long tv_nsec; /* Nanoseconds */\n"
9950 #: build/C/man2/timer_settime.2:75
9953 "struct itimerspec {\n"
9954 " struct timespec it_interval; /* Timer interval */\n"
9955 " struct timespec it_value; /* Initial expiration */\n"
9960 #: build/C/man2/timer_settime.2:87
9962 "Each of the substructures of the I<itimerspec> structure is a I<timespec> "
9963 "structure that allows a time value to be specified in seconds and "
9964 "nanoseconds. These time values are measured according to the clock that was "
9965 "specified when the timer was created by B<timer_create>(2)."
9969 #: build/C/man2/timer_settime.2:101
9971 "If I<new_value-E<gt>it_value> specifies a nonzero value (i.e., either "
9972 "subfield is nonzero), then B<timer_settime>() arms (starts) the timer, "
9973 "setting it to initially expire at the given time. (If the timer was already "
9974 "armed, then the previous settings are overwritten.) If "
9975 "I<new_value-E<gt>it_value> specifies a zero value (i.e., both subfields are "
9976 "zero), then the timer is disarmed."
9980 #: build/C/man2/timer_settime.2:113
9982 "The I<new_value-E<gt>it_interval> field specifies the period of the timer, "
9983 "in seconds and nanoseconds. If this field is nonzero, then each time that "
9984 "an armed timer expires, the timer is reloaded from the value specified in "
9985 "I<new_value-E<gt>it_interval>. If I<new_value-E<gt>it_interval> specifies a "
9986 "zero value, then the timer expires just once, at the time specified by "
9990 #. By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
9992 #: build/C/man2/timer_settime.2:134
9994 "By default, the initial expiration time specified in "
9995 "I<new_value-E<gt>it_value> is interpreted relative to the current time on "
9996 "the timer's clock at the time of the call. This can be modified by "
9997 "specifying B<TIMER_ABSTIME> in I<flags>, in which case "
9998 "I<new_value-E<gt>it_value> is interpreted as an absolute value as measured "
9999 "on the timer's clock; that is, the timer will expire when the clock value "
10000 "reaches the value specified by I<new_value-E<gt>it_value>. If the specified "
10001 "absolute time has already passed, then the timer expires immediately, and "
10002 "the overrun count (see B<timer_getoverrun>(2)) will be set correctly."
10005 #. Similar remarks might apply with respect to process and thread CPU time
10006 #. clocks, but these clocks are not currently (2.6.28) settable on Linux.
10007 #. type: Plain text
10008 #: build/C/man2/timer_settime.2:144
10010 "If the value of the B<CLOCK_REALTIME> clock is adjusted while an absolute "
10011 "timer based on that clock is armed, then the expiration of the timer will be "
10012 "appropriately adjusted. Adjustments to the B<CLOCK_REALTIME> clock have no "
10013 "effect on relative timers based on that clock."
10016 #. type: Plain text
10017 #: build/C/man2/timer_settime.2:153
10019 "If I<old_value> is not NULL, then it points to a buffer that is used to "
10020 "return the previous interval of the timer (in I<old_value-E<gt>it_interval>) "
10021 "and the amount of time until the timer would previously have next expired "
10022 "(in I<old_value-E<gt>it_value>)."
10025 #. type: Plain text
10026 #: build/C/man2/timer_settime.2:173
10028 "B<timer_gettime>() returns the time until next expiration, and the "
10029 "interval, for the timer specified by I<timerid>, in the buffer pointed to by "
10030 "I<curr_value>. The time remaining until the next timer expiration is "
10031 "returned in I<curr_value-E<gt>it_value>; this is always a relative value, "
10032 "regardless of whether the B<TIMER_ABSTIME> flag was used when arming the "
10033 "timer. If the value returned in I<curr_value-E<gt>it_value> is zero, then "
10034 "the timer is currently disarmed. The timer interval is returned in "
10035 "I<curr_value-E<gt>it_interval>. If the value returned in "
10036 "I<curr_value-E<gt>it_interval> is zero, then this is a \"one-shot\" timer."
10039 #. type: Plain text
10040 #: build/C/man2/timer_settime.2:182
10042 "On success, B<timer_settime>() and B<timer_gettime>() return 0. On error, "
10043 "-1 is returned, and I<errno> is set to indicate the error."
10046 #. type: Plain text
10047 #: build/C/man2/timer_settime.2:184
10048 msgid "These functions may fail with the following errors:"
10051 #. type: Plain text
10052 #: build/C/man2/timer_settime.2:191
10053 msgid "I<new_value>, I<old_value>, or I<curr_value> is not a valid pointer."
10056 #. FIXME . eventually: invalid value in flags
10057 #. type: Plain text
10058 #: build/C/man2/timer_settime.2:196
10059 msgid "I<timerid> is invalid."
10062 #. type: Plain text
10063 #: build/C/man2/timer_settime.2:199
10064 msgid "B<timer_settime>() may fail with the following errors:"
10067 #. type: Plain text
10068 #: build/C/man2/timer_settime.2:205
10070 "I<new_value.it_value> is negative; or I<new_value.it_value.tv_nsec> is "
10071 "negative or greater than 999,999,999."
10074 #. type: Plain text
10075 #: build/C/man2/timer_settime.2:207
10076 msgid "These system calls are available since Linux 2.6."
10079 #. type: Plain text
10080 #: build/C/man2/timer_settime.2:216
10081 msgid "B<timer_create>(2), B<timer_getoverrun>(2), B<time>(7)"
10085 #: build/C/man2/timerfd_create.2:22
10087 msgid "TIMERFD_CREATE"
10091 #: build/C/man2/timerfd_create.2:22
10096 #. type: Plain text
10097 #: build/C/man2/timerfd_create.2:26
10099 "timerfd_create, timerfd_settime, timerfd_gettime - timers that notify via "
10103 #. type: Plain text
10104 #: build/C/man2/timerfd_create.2:29
10106 msgid "B<#include E<lt>sys/timerfd.hE<gt>>\n"
10109 #. type: Plain text
10110 #: build/C/man2/timerfd_create.2:31
10112 msgid "B<int timerfd_create(int >I<clockid>B<, int >I<flags>B<);>\n"
10115 #. type: Plain text
10116 #: build/C/man2/timerfd_create.2:35
10119 "B<int timerfd_settime(int >I<fd>B<, int >I<flags>B<,>\n"
10120 "B< const struct itimerspec *>I<new_value>B<,>\n"
10121 "B< struct itimerspec *>I<old_value>B<);>\n"
10124 #. type: Plain text
10125 #: build/C/man2/timerfd_create.2:37
10127 msgid "B<int timerfd_gettime(int >I<fd>B<, struct itimerspec *>I<curr_value>B<);>\n"
10130 #. type: Plain text
10131 #: build/C/man2/timerfd_create.2:50
10133 "These system calls create and operate on a timer that delivers timer "
10134 "expiration notifications via a file descriptor. They provide an alternative "
10135 "to the use of B<setitimer>(2) or B<timer_create>(2), with the advantage "
10136 "that the file descriptor may be monitored by B<select>(2), B<poll>(2), and "
10140 #. type: Plain text
10141 #: build/C/man2/timerfd_create.2:62
10143 "The use of these three system calls is analogous to the use of "
10144 "B<timer_create>(2), B<timer_settime>(2), and B<timer_gettime>(2). (There is "
10145 "no analog of B<timer_getoverrun>(2), since that functionality is provided by "
10146 "B<read>(2), as described below.)"
10150 #: build/C/man2/timerfd_create.2:62
10152 msgid "timerfd_create()"
10156 #. Additional clocks are now supported:
10157 #. CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM
10158 #. Since Linux 3.11, commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8
10160 #. Since Linux 3.15, commit 4a2378a943f09907fb1ae35c15de917f60289c14
10161 #. type: Plain text
10162 #: build/C/man2/timerfd_create.2:87
10164 "B<timerfd_create>() creates a new timer object, and returns a file "
10165 "descriptor that refers to that timer. The I<clockid> argument specifies the "
10166 "clock that is used to mark the progress of the timer, and must be either "
10167 "B<CLOCK_REALTIME> or B<CLOCK_MONOTONIC>. B<CLOCK_REALTIME> is a settable "
10168 "system-wide clock. B<CLOCK_MONOTONIC> is a nonsettable clock that is not "
10169 "affected by discontinuous changes in the system clock (e.g., manual changes "
10170 "to system time). The current value of each of these clocks can be retrieved "
10171 "using B<clock_gettime>(2)."
10174 #. type: Plain text
10175 #: build/C/man2/timerfd_create.2:92
10177 "Starting with Linux 2.6.27, the following values may be bitwise ORed in "
10178 "I<flags> to change the behavior of B<timerfd_create>():"
10182 #: build/C/man2/timerfd_create.2:92
10184 msgid "B<TFD_NONBLOCK>"
10188 #: build/C/man2/timerfd_create.2:100
10190 msgid "B<TFD_CLOEXEC>"
10193 #. type: Plain text
10194 #: build/C/man2/timerfd_create.2:114
10196 "In Linux versions up to and including 2.6.26, I<flags> must be specified as "
10201 #: build/C/man2/timerfd_create.2:114
10203 msgid "timerfd_settime()"
10206 #. type: Plain text
10207 #: build/C/man2/timerfd_create.2:119
10209 "B<timerfd_settime>() arms (starts) or disarms (stops) the timer referred "
10210 "to by the file descriptor I<fd>."
10213 #. type: Plain text
10214 #: build/C/man2/timerfd_create.2:128
10216 "The I<new_value> argument specifies the initial expiration and interval for "
10217 "the timer. The I<itimer> structure used for this argument contains two "
10218 "fields, each of which is in turn a structure of type I<timespec>:"
10221 #. type: Plain text
10222 #: build/C/man2/timerfd_create.2:140
10225 "struct itimerspec {\n"
10226 " struct timespec it_interval; /* Interval for periodic timer */\n"
10227 " struct timespec it_value; /* Initial expiration */\n"
10231 #. type: Plain text
10232 #: build/C/man2/timerfd_create.2:152
10234 "I<new_value.it_value> specifies the initial expiration of the timer, in "
10235 "seconds and nanoseconds. Setting either field of I<new_value.it_value> to a "
10236 "nonzero value arms the timer. Setting both fields of I<new_value.it_value> "
10237 "to zero disarms the timer."
10240 #. type: Plain text
10241 #: build/C/man2/timerfd_create.2:161
10243 "Setting one or both fields of I<new_value.it_interval> to nonzero values "
10244 "specifies the period, in seconds and nanoseconds, for repeated timer "
10245 "expirations after the initial expiration. If both fields of "
10246 "I<new_value.it_interval> are zero, the timer expires just once, at the time "
10247 "specified by I<new_value.it_value>."
10250 #. type: Plain text
10251 #: build/C/man2/timerfd_create.2:177
10253 "The I<flags> argument is either 0, to start a relative timer "
10254 "(I<new_value.it_value> specifies a time relative to the current value of the "
10255 "clock specified by I<clockid>), or B<TFD_TIMER_ABSTIME>, to start an "
10256 "absolute timer (I<new_value.it_value> specifies an absolute time for the "
10257 "clock specified by I<clockid>; that is, the timer will expire when the value "
10258 "of that clock reaches the value specified in I<new_value.it_value>)."
10261 #. type: Plain text
10262 #: build/C/man2/timerfd_create.2:188
10264 "If the I<old_value> argument is not NULL, then the I<itimerspec> structure "
10265 "that it points to is used to return the setting of the timer that was "
10266 "current at the time of the call; see the description of B<timerfd_gettime>() "
10271 #: build/C/man2/timerfd_create.2:188
10273 msgid "timerfd_gettime()"
10276 #. type: Plain text
10277 #: build/C/man2/timerfd_create.2:197
10279 "B<timerfd_gettime>() returns, in I<curr_value>, an I<itimerspec> structure "
10280 "that contains the current setting of the timer referred to by the file "
10281 "descriptor I<fd>."
10284 #. type: Plain text
10285 #: build/C/man2/timerfd_create.2:207
10287 "The I<it_value> field returns the amount of time until the timer will next "
10288 "expire. If both fields of this structure are zero, then the timer is "
10289 "currently disarmed. This field always contains a relative value, regardless "
10290 "of whether the B<TFD_TIMER_ABSTIME> flag was specified when setting the "
10294 #. type: Plain text
10295 #: build/C/man2/timerfd_create.2:214
10297 "The I<it_interval> field returns the interval of the timer. If both fields "
10298 "of this structure are zero, then the timer is set to expire just once, at "
10299 "the time specified by I<curr_value.it_value>."
10303 #: build/C/man2/timerfd_create.2:214
10305 msgid "Operating on a timer file descriptor"
10308 #. type: Plain text
10309 #: build/C/man2/timerfd_create.2:218
10311 "The file descriptor returned by B<timerfd_create>() supports the following "
10315 #. type: Plain text
10316 #: build/C/man2/timerfd_create.2:232
10318 "If the timer has already expired one or more times since its settings were "
10319 "last modified using B<timerfd_settime>(), or since the last successful "
10320 "B<read>(2), then the buffer given to B<read>(2) returns an unsigned 8-byte "
10321 "integer (I<uint64_t>) containing the number of expirations that have "
10322 "occurred. (The returned value is in host byte order\\(emthat is, the native "
10323 "byte order for integers on the host machine.)"
10326 #. type: Plain text
10327 #: build/C/man2/timerfd_create.2:245
10329 "If no timer expirations have occurred at the time of the B<read>(2), then "
10330 "the call either blocks until the next timer expiration, or fails with the "
10331 "error B<EAGAIN> if the file descriptor has been made nonblocking (via the "
10332 "use of the B<fcntl>(2) B<F_SETFL> operation to set the B<O_NONBLOCK> flag)."
10335 #. type: Plain text
10336 #: build/C/man2/timerfd_create.2:251
10338 "A B<read>(2) will fail with the error B<EINVAL> if the size of the supplied "
10339 "buffer is less than 8 bytes."
10342 #. type: Plain text
10343 #: build/C/man2/timerfd_create.2:262
10345 "The file descriptor is readable (the B<select>(2) I<readfds> argument; the "
10346 "B<poll>(2) B<POLLIN> flag) if one or more timer expirations have occurred."
10349 #. type: Plain text
10350 #: build/C/man2/timerfd_create.2:269
10352 "The file descriptor also supports the other file-descriptor multiplexing "
10353 "APIs: B<pselect>(2), B<ppoll>(2), and B<epoll>(7)."
10356 #. type: Plain text
10357 #: build/C/man2/timerfd_create.2:276
10359 "When the file descriptor is no longer required it should be closed. When "
10360 "all file descriptors associated with the same timer object have been closed, "
10361 "the timer is disarmed and its resources are freed by the kernel."
10364 #. type: Plain text
10365 #: build/C/man2/timerfd_create.2:288
10367 "After a B<fork>(2), the child inherits a copy of the file descriptor created "
10368 "by B<timerfd_create>(). The file descriptor refers to the same underlying "
10369 "timer object as the corresponding file descriptor in the parent, and "
10370 "B<read>(2)s in the child will return information about expirations of the "
10374 #. type: Plain text
10375 #: build/C/man2/timerfd_create.2:294
10377 "A file descriptor created by B<timerfd_create>() is preserved across "
10378 "B<execve>(2), and continues to generate timer expirations if the timer was "
10382 #. type: Plain text
10383 #: build/C/man2/timerfd_create.2:301
10385 "On success, B<timerfd_create>() returns a new file descriptor. On error, "
10386 "-1 is returned and I<errno> is set to indicate the error."
10389 #. type: Plain text
10390 #: build/C/man2/timerfd_create.2:309
10392 "B<timerfd_settime>() and B<timerfd_gettime>() return 0 on success; on "
10393 "error they return -1, and set I<errno> to indicate the error."
10396 #. type: Plain text
10397 #: build/C/man2/timerfd_create.2:312
10398 msgid "B<timerfd_create>() can fail with the following errors:"
10401 #. type: Plain text
10402 #: build/C/man2/timerfd_create.2:320
10403 msgid "The I<clockid> argument is neither B<CLOCK_MONOTONIC> nor B<CLOCK_REALTIME>;"
10406 #. type: Plain text
10407 #: build/C/man2/timerfd_create.2:340
10408 msgid "There was insufficient kernel memory to create the timer."
10411 #. type: Plain text
10412 #: build/C/man2/timerfd_create.2:345
10414 "B<timerfd_settime>() and B<timerfd_gettime>() can fail with the following "
10418 #. type: Plain text
10419 #: build/C/man2/timerfd_create.2:349
10420 msgid "I<fd> is not a valid file descriptor."
10423 #. type: Plain text
10424 #: build/C/man2/timerfd_create.2:360
10425 msgid "I<fd> is not a valid timerfd file descriptor."
10428 #. type: Plain text
10429 #: build/C/man2/timerfd_create.2:363
10430 msgid "B<timerfd_settime>() can also fail with the following errors:"
10433 #. type: Plain text
10434 #: build/C/man2/timerfd_create.2:369
10436 "I<new_value> is not properly initialized (one of the I<tv_nsec> falls "
10437 "outside the range zero to 999,999,999)."
10440 #. This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
10441 #. In older kernel versions, no check was made for invalid flags.
10442 #. type: Plain text
10443 #: build/C/man2/timerfd_create.2:375
10444 msgid "I<flags> is invalid."
10447 #. type: Plain text
10448 #: build/C/man2/timerfd_create.2:378
10450 "These system calls are available on Linux since kernel 2.6.25. Library "
10451 "support is provided by glibc since version 2.8."
10455 #. type: Plain text
10456 #: build/C/man2/timerfd_create.2:386
10458 "Currently, B<timerfd_create>() supports fewer types of clock IDs than "
10459 "B<timer_create>(2)."
10462 #. type: Plain text
10463 #: build/C/man2/timerfd_create.2:395
10465 "The following program creates a timer and then monitors its progress. The "
10466 "program accepts up to three command-line arguments. The first argument "
10467 "specifies the number of seconds for the initial expiration of the timer. "
10468 "The second argument specifies the interval for the timer, in seconds. The "
10469 "third argument specifies the number of times the program should allow the "
10470 "timer to expire before terminating. The second and third command-line "
10471 "arguments are optional."
10474 #. type: Plain text
10475 #: build/C/man2/timerfd_create.2:397 build/C/man2/wait.2:571
10476 msgid "The following shell session demonstrates the use of the program:"
10479 #. type: Plain text
10480 #: build/C/man2/timerfd_create.2:412
10483 "$B< a.out 3 1 100>\n"
10484 "0.000: timer started\n"
10485 "3.000: read: 1; total=1\n"
10486 "4.000: read: 1; total=2\n"
10487 "B<^Z > # type control-Z to suspend the program\n"
10488 "[1]+ Stopped ./timerfd3_demo 3 1 100\n"
10489 "$ B<fg> # Resume execution after a few seconds\n"
10491 "9.660: read: 5; total=7\n"
10492 "10.000: read: 1; total=8\n"
10493 "11.000: read: 1; total=9\n"
10494 "B<^C > # type control-C to suspend the program\n"
10497 #. The commented out code here is what we currently need until
10498 #. the required stuff is in glibc
10501 #. /* Link with -lrt */
10502 #. #define _GNU_SOURCE
10503 #. #include <sys/syscall.h>
10504 #. #include <unistd.h>
10505 #. #include <time.h>
10506 #. #if defined(__i386__)
10507 #. #define __NR_timerfd_create 322
10508 #. #define __NR_timerfd_settime 325
10509 #. #define __NR_timerfd_gettime 326
10513 #. timerfd_create(int clockid, int flags)
10515 #. return syscall(__NR_timerfd_create, clockid, flags);
10519 #. timerfd_settime(int fd, int flags, struct itimerspec *new_value,
10520 #. struct itimerspec *curr_value)
10522 #. return syscall(__NR_timerfd_settime, fd, flags, new_value,
10527 #. timerfd_gettime(int fd, struct itimerspec *curr_value)
10529 #. return syscall(__NR_timerfd_gettime, fd, curr_value);
10532 #. #define TFD_TIMER_ABSTIME (1 << 0)
10534 #. ////////////////////////////////////////////////////////////
10535 #. type: Plain text
10536 #: build/C/man2/timerfd_create.2:461
10539 "#include E<lt>sys/timerfd.hE<gt>\n"
10540 "#include E<lt>time.hE<gt>\n"
10541 "#include E<lt>unistd.hE<gt>\n"
10542 "#include E<lt>stdlib.hE<gt>\n"
10543 "#include E<lt>stdio.hE<gt>\n"
10544 "#include E<lt>stdint.hE<gt> /* Definition of uint64_t */\n"
10547 #. type: Plain text
10548 #: build/C/man2/timerfd_create.2:464
10551 "#define handle_error(msg) \\e\n"
10552 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
10555 #. type: Plain text
10556 #: build/C/man2/timerfd_create.2:472
10560 "print_elapsed_time(void)\n"
10562 " static struct timespec start;\n"
10563 " struct timespec curr;\n"
10564 " static int first_call = 1;\n"
10565 " int secs, nsecs;\n"
10568 #. type: Plain text
10569 #: build/C/man2/timerfd_create.2:478
10572 " if (first_call) {\n"
10573 " first_call = 0;\n"
10574 " if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)\n"
10575 " handle_error(\"clock_gettime\");\n"
10579 #. type: Plain text
10580 #: build/C/man2/timerfd_create.2:481
10583 " if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)\n"
10584 " handle_error(\"clock_gettime\");\n"
10587 #. type: Plain text
10588 #: build/C/man2/timerfd_create.2:490
10591 " secs = curr.tv_sec - start.tv_sec;\n"
10592 " nsecs = curr.tv_nsec - start.tv_nsec;\n"
10593 " if (nsecs E<lt> 0) {\n"
10595 " nsecs += 1000000000;\n"
10597 " printf(\"%d.%03d: \", secs, (nsecs + 500000) / 1000000);\n"
10601 #. type: Plain text
10602 #: build/C/man2/timerfd_create.2:499
10606 "main(int argc, char *argv[])\n"
10608 " struct itimerspec new_value;\n"
10609 " int max_exp, fd;\n"
10610 " struct timespec now;\n"
10611 " uint64_t exp, tot_exp;\n"
10615 #. type: Plain text
10616 #: build/C/man2/timerfd_create.2:505
10619 " if ((argc != 2) && (argc != 4)) {\n"
10620 " fprintf(stderr, \"%s init-secs [interval-secs max-exp]\\en\",\n"
10622 " exit(EXIT_FAILURE);\n"
10626 #. type: Plain text
10627 #: build/C/man2/timerfd_create.2:508
10630 " if (clock_gettime(CLOCK_REALTIME, &now) == -1)\n"
10631 " handle_error(\"clock_gettime\");\n"
10634 #. type: Plain text
10635 #: build/C/man2/timerfd_create.2:511
10638 " /* Create a CLOCK_REALTIME absolute timer with initial\n"
10639 " expiration and interval as specified in command line */\n"
10642 #. type: Plain text
10643 #: build/C/man2/timerfd_create.2:522
10646 " new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);\n"
10647 " new_value.it_value.tv_nsec = now.tv_nsec;\n"
10648 " if (argc == 2) {\n"
10649 " new_value.it_interval.tv_sec = 0;\n"
10652 " new_value.it_interval.tv_sec = atoi(argv[2]);\n"
10653 " max_exp = atoi(argv[3]);\n"
10655 " new_value.it_interval.tv_nsec = 0;\n"
10658 #. type: Plain text
10659 #: build/C/man2/timerfd_create.2:526
10662 " fd = timerfd_create(CLOCK_REALTIME, 0);\n"
10664 " handle_error(\"timerfd_create\");\n"
10667 #. type: Plain text
10668 #: build/C/man2/timerfd_create.2:529
10671 " if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)\n"
10672 " handle_error(\"timerfd_settime\");\n"
10675 #. type: Plain text
10676 #: build/C/man2/timerfd_create.2:532
10679 " print_elapsed_time();\n"
10680 " printf(\"timer started\\en\");\n"
10683 #. type: Plain text
10684 #: build/C/man2/timerfd_create.2:537
10687 " for (tot_exp = 0; tot_exp E<lt> max_exp;) {\n"
10688 " s = read(fd, &exp, sizeof(uint64_t));\n"
10689 " if (s != sizeof(uint64_t))\n"
10690 " handle_error(\"read\");\n"
10693 #. type: Plain text
10694 #: build/C/man2/timerfd_create.2:544
10697 " tot_exp += exp;\n"
10698 " print_elapsed_time();\n"
10699 " printf(\"read: %llu; total=%llu\\en\",\n"
10700 " (unsigned long long) exp,\n"
10701 " (unsigned long long) tot_exp);\n"
10705 #. type: Plain text
10706 #: build/C/man2/timerfd_create.2:560
10708 "B<eventfd>(2), B<poll>(2), B<read>(2), B<select>(2), B<setitimer>(2), "
10709 "B<signalfd>(2), B<timer_create>(2), B<timer_gettime>(2), "
10710 "B<timer_settime>(2), B<epoll>(7), B<time>(7)"
10714 #: build/C/man2/tkill.2:29
10719 #. type: Plain text
10720 #: build/C/man2/tkill.2:32
10721 msgid "tkill, tgkill - send a signal to a thread"
10724 #. type: Plain text
10725 #: build/C/man2/tkill.2:35
10727 msgid "B<int tkill(int >I<tid>B<, int >I<sig>B<);>\n"
10730 #. type: Plain text
10731 #: build/C/man2/tkill.2:37
10733 msgid "B<int tgkill(int >I<tgid>B<, int >I<tid>B<, int >I<sig>B<);>\n"
10736 #. type: Plain text
10737 #: build/C/man2/tkill.2:54
10739 "B<tgkill>() sends the signal I<sig> to the thread with the thread ID I<tid> "
10740 "in the thread group I<tgid>. (By contrast, B<kill>(2) can be used to send "
10741 "a signal only to a process (i.e., thread group) as a whole, and the signal "
10742 "will be delivered to an arbitrary thread within that process.)"
10745 #. FIXME Maybe say something about the following:
10746 #. http://sourceware.org/bugzilla/show_bug.cgi?id=12889
10747 #. Rich Felker <bugdal@aerifal.cx>
10748 #. There is a race condition in pthread_kill: it is possible that,
10749 #. between the time pthread_kill reads the pid/tid from the target
10750 #. thread descriptor and the time it makes the tgkill syscall,
10751 #. the target thread terminates and the same tid gets assigned
10752 #. to a new thread in the same process.
10754 #. (The tgkill syscall was designed to eliminate a similar race
10755 #. condition in tkill, but it only succeeded in eliminating races
10756 #. where the tid gets reused in a different process, and does not
10757 #. help if the same tid gets assigned to a new thread in the
10760 #. The only solution I can see is to introduce a mutex that ensures
10761 #. that a thread cannot exit while pthread_kill is being called on it.
10763 #. Note that in most real-world situations, like almost all race
10764 #. conditions, this one will be extremely rare. To make it
10765 #. measurable, one could exhaust all but 1-2 available pid values,
10766 #. possibly by lowering the max pid parameter in /proc, forcing
10767 #. the same tid to be reused rapidly.
10768 #. type: Plain text
10769 #: build/C/man2/tkill.2:85
10771 "B<tkill>() is an obsolete predecessor to B<tgkill>(). It allows only the "
10772 "target thread ID to be specified, which may result in the wrong thread being "
10773 "signaled if a thread terminates and its thread ID is recycled. Avoid using "
10774 "this system call."
10777 #. type: Plain text
10778 #: build/C/man2/tkill.2:88
10780 "These are the raw system call interfaces, meant for internal thread library "
10784 #. type: Plain text
10785 #: build/C/man2/tkill.2:96
10786 msgid "An invalid thread ID, thread group ID, or signal was specified."
10789 #. type: Plain text
10790 #: build/C/man2/tkill.2:101
10791 msgid "Permission denied. For the required permissions, see B<kill>(2)."
10794 #. type: Plain text
10795 #: build/C/man2/tkill.2:104
10796 msgid "No process with the specified thread ID (and thread group ID) exists."
10799 #. type: Plain text
10800 #: build/C/man2/tkill.2:109
10802 "B<tkill>() is supported since Linux 2.4.19 / 2.5.4. B<tgkill>() was added "
10806 #. type: Plain text
10807 #: build/C/man2/tkill.2:115
10809 "B<tkill>() and B<tgkill>() are Linux-specific and should not be used in "
10810 "programs that are intended to be portable."
10813 #. type: Plain text
10814 #: build/C/man2/tkill.2:121
10816 "See the description of B<CLONE_THREAD> in B<clone>(2) for an explanation of "
10820 #. type: Plain text
10821 #: build/C/man2/tkill.2:124
10823 "Glibc does not provide wrappers for these system calls; call them using "
10827 #. type: Plain text
10828 #: build/C/man2/tkill.2:129
10829 msgid "B<clone>(2), B<gettid>(2), B<kill>(2), B<rt_sigqueueinfo>(2)"
10833 #: build/C/man2/wait.2:49
10838 #. type: Plain text
10839 #: build/C/man2/wait.2:52
10840 msgid "wait, waitpid, waitid - wait for process to change state"
10843 #. type: Plain text
10844 #: build/C/man2/wait.2:54
10845 msgid "B<#include E<lt>sys/types.hE<gt>>"
10848 #. type: Plain text
10849 #: build/C/man2/wait.2:56
10850 msgid "B<#include E<lt>sys/wait.hE<gt>>"
10853 #. type: Plain text
10854 #: build/C/man2/wait.2:58
10855 msgid "B<pid_t wait(int *>I<status>B<);>"
10858 #. type: Plain text
10859 #: build/C/man2/wait.2:60
10860 msgid "B<pid_t waitpid(pid_t >I<pid>B<, int *>I<status>B<, int >I<options>B<);>"
10863 #. type: Plain text
10864 #: build/C/man2/wait.2:65
10867 "B<int waitid(idtype_t >I<idtype>B<, id_t >I<id>B<, siginfo_t *>I<infop>B<, "
10868 "int >I<options>B<);>\n"
10869 " /* This is the glibc and POSIX interface; see\n"
10870 " NOTES for information on the raw system call. */\n"
10873 #. type: Plain text
10874 #: build/C/man2/wait.2:74
10875 msgid "B<waitid>():"
10878 #. type: Plain text
10879 #: build/C/man2/wait.2:78
10881 "_SVID_SOURCE || _XOPEN_SOURCE\\ E<gt>=\\ 500 || _XOPEN_SOURCE\\ &&\\ "
10882 "_XOPEN_SOURCE_EXTENDED"
10885 #. type: Plain text
10886 #: build/C/man2/wait.2:93
10888 "All of these system calls are used to wait for state changes in a child of "
10889 "the calling process, and obtain information about the child whose state has "
10890 "changed. A state change is considered to be: the child terminated; the "
10891 "child was stopped by a signal; or the child was resumed by a signal. In the "
10892 "case of a terminated child, performing a wait allows the system to release "
10893 "the resources associated with the child; if a wait is not performed, then "
10894 "the terminated child remains in a \"zombie\" state (see NOTES below)."
10897 #. type: Plain text
10898 #: build/C/man2/wait.2:105
10900 "If a child has already changed state, then these calls return immediately. "
10901 "Otherwise, they block until either a child changes state or a signal handler "
10902 "interrupts the call (assuming that system calls are not automatically "
10903 "restarted using the B<SA_RESTART> flag of B<sigaction>(2)). In the "
10904 "remainder of this page, a child whose state has changed and which has not "
10905 "yet been waited upon by one of these system calls is termed I<waitable>."
10909 #: build/C/man2/wait.2:105
10911 msgid "wait() and waitpid()"
10914 #. type: Plain text
10915 #: build/C/man2/wait.2:113
10917 "The B<wait>() system call suspends execution of the calling process until "
10918 "one of its children terminates. The call I<wait(&status)> is equivalent to:"
10921 #. type: Plain text
10922 #: build/C/man2/wait.2:116
10924 msgid " waitpid(-1, &status, 0);\n"
10927 #. type: Plain text
10928 #: build/C/man2/wait.2:130
10930 "The B<waitpid>() system call suspends execution of the calling process "
10931 "until a child specified by I<pid> argument has changed state. By default, "
10932 "B<waitpid>() waits only for terminated children, but this behavior is "
10933 "modifiable via the I<options> argument, as described below."
10936 #. type: Plain text
10937 #: build/C/man2/wait.2:134
10938 msgid "The value of I<pid> can be:"
10942 #: build/C/man2/wait.2:134
10947 #. type: Plain text
10948 #: build/C/man2/wait.2:138
10950 "meaning wait for any child process whose process group ID is equal to the "
10951 "absolute value of I<pid>."
10955 #: build/C/man2/wait.2:138
10960 #. type: Plain text
10961 #: build/C/man2/wait.2:140
10962 msgid "meaning wait for any child process."
10966 #: build/C/man2/wait.2:140
10971 #. type: Plain text
10972 #: build/C/man2/wait.2:143
10974 "meaning wait for any child process whose process group ID is equal to that "
10975 "of the calling process."
10979 #: build/C/man2/wait.2:143
10984 #. type: Plain text
10985 #: build/C/man2/wait.2:147
10986 msgid "meaning wait for the child whose process ID is equal to the value of I<pid>."
10989 #. type: Plain text
10990 #: build/C/man2/wait.2:151
10991 msgid "The value of I<options> is an OR of zero or more of the following constants:"
10995 #: build/C/man2/wait.2:151 build/C/man2/wait.2:280
11000 #. type: Plain text
11001 #: build/C/man2/wait.2:154
11002 msgid "return immediately if no child has exited."
11006 #: build/C/man2/wait.2:154
11008 msgid "B<WUNTRACED>"
11011 #. type: Plain text
11012 #: build/C/man2/wait.2:163
11014 "also return if a child has stopped (but not traced via B<ptrace>(2)). "
11015 "Status for I<traced> children which have stopped is provided even if this "
11016 "option is not specified."
11020 #: build/C/man2/wait.2:163
11022 msgid "B<WCONTINUED> (since Linux 2.6.10)"
11025 #. type: Plain text
11026 #: build/C/man2/wait.2:167
11027 msgid "also return if a stopped child has been resumed by delivery of B<SIGCONT>."
11030 #. type: Plain text
11031 #: build/C/man2/wait.2:169
11032 msgid "(For Linux-only options, see below.)"
11035 #. type: Plain text
11036 #: build/C/man2/wait.2:183
11038 "If I<status> is not NULL, B<wait>() and B<waitpid>() store status "
11039 "information in the I<int> to which it points. This integer can be inspected "
11040 "with the following macros (which take the integer itself as an argument, not "
11041 "a pointer to it, as is done in B<wait>() and B<waitpid>()!):"
11045 #: build/C/man2/wait.2:183
11047 msgid "B<WIFEXITED(>I<status>B<)>"
11050 #. type: Plain text
11051 #: build/C/man2/wait.2:191
11053 "returns true if the child terminated normally, that is, by calling "
11054 "B<exit>(3) or B<_exit>(2), or by returning from main()."
11058 #: build/C/man2/wait.2:191
11060 msgid "B<WEXITSTATUS(>I<status>B<)>"
11063 #. type: Plain text
11064 #: build/C/man2/wait.2:204
11066 "returns the exit status of the child. This consists of the least "
11067 "significant 8 bits of the I<status> argument that the child specified in a "
11068 "call to B<exit>(3) or B<_exit>(2) or as the argument for a return "
11069 "statement in main(). This macro should be employed only if B<WIFEXITED> "
11074 #: build/C/man2/wait.2:204
11076 msgid "B<WIFSIGNALED(>I<status>B<)>"
11079 #. type: Plain text
11080 #: build/C/man2/wait.2:207
11081 msgid "returns true if the child process was terminated by a signal."
11085 #: build/C/man2/wait.2:207
11087 msgid "B<WTERMSIG(>I<status>B<)>"
11090 #. type: Plain text
11091 #: build/C/man2/wait.2:214
11093 "returns the number of the signal that caused the child process to "
11094 "terminate. This macro should be employed only if B<WIFSIGNALED> returned "
11099 #: build/C/man2/wait.2:214
11101 msgid "B<WCOREDUMP(>I<status>B<)>"
11104 #. type: Plain text
11105 #: build/C/man2/wait.2:223
11107 "returns true if the child produced a core dump. This macro should be "
11108 "employed only if B<WIFSIGNALED> returned true. This macro is not specified "
11109 "in POSIX.1-2001 and is not available on some UNIX implementations (e.g., "
11110 "AIX, SunOS). Only use this enclosed in #ifdef WCOREDUMP ... #endif."
11114 #: build/C/man2/wait.2:223
11116 msgid "B<WIFSTOPPED(>I<status>B<)>"
11119 #. type: Plain text
11120 #: build/C/man2/wait.2:230
11122 "returns true if the child process was stopped by delivery of a signal; this "
11123 "is possible only if the call was done using B<WUNTRACED> or when the child "
11124 "is being traced (see B<ptrace>(2))."
11128 #: build/C/man2/wait.2:230
11130 msgid "B<WSTOPSIG(>I<status>B<)>"
11133 #. type: Plain text
11134 #: build/C/man2/wait.2:236
11136 "returns the number of the signal which caused the child to stop. This macro "
11137 "should be employed only if B<WIFSTOPPED> returned true."
11141 #: build/C/man2/wait.2:236
11143 msgid "B<WIFCONTINUED(>I<status>B<)>"
11146 #. type: Plain text
11147 #: build/C/man2/wait.2:241
11149 "(since Linux 2.6.10) returns true if the child process was resumed by "
11150 "delivery of B<SIGCONT>."
11154 #: build/C/man2/wait.2:241
11159 #. type: Plain text
11160 #: build/C/man2/wait.2:246
11162 "The B<waitid>() system call (available since Linux 2.6.9) provides more "
11163 "precise control over which child state changes to wait for."
11166 #. type: Plain text
11167 #: build/C/man2/wait.2:252
11169 "The I<idtype> and I<id> arguments select the child(ren) to wait for, as "
11174 #: build/C/man2/wait.2:252
11176 msgid "I<idtype> == B<P_PID>"
11179 #. type: Plain text
11180 #: build/C/man2/wait.2:255
11181 msgid "Wait for the child whose process ID matches I<id>."
11185 #: build/C/man2/wait.2:255
11187 msgid "I<idtype> == B<P_PGID>"
11190 #. type: Plain text
11191 #: build/C/man2/wait.2:258
11192 msgid "Wait for any child whose process group ID matches I<id>."
11196 #: build/C/man2/wait.2:258
11198 msgid "I<idtype> == B<P_ALL>"
11201 #. type: Plain text
11202 #: build/C/man2/wait.2:262
11203 msgid "Wait for any child; I<id> is ignored."
11206 #. type: Plain text
11207 #: build/C/man2/wait.2:266
11209 "The child state changes to wait for are specified by ORing one or more of "
11210 "the following flags in I<options>:"
11214 #: build/C/man2/wait.2:266
11219 #. type: Plain text
11220 #: build/C/man2/wait.2:269
11221 msgid "Wait for children that have terminated."
11225 #: build/C/man2/wait.2:269
11227 msgid "B<WSTOPPED>"
11230 #. type: Plain text
11231 #: build/C/man2/wait.2:272
11232 msgid "Wait for children that have been stopped by delivery of a signal."
11236 #: build/C/man2/wait.2:272
11238 msgid "B<WCONTINUED>"
11241 #. type: Plain text
11242 #: build/C/man2/wait.2:277
11244 "Wait for (previously stopped) children that have been resumed by delivery of "
11248 #. type: Plain text
11249 #: build/C/man2/wait.2:280
11250 msgid "The following flags may additionally be ORed in I<options>:"
11253 #. type: Plain text
11254 #: build/C/man2/wait.2:284
11255 msgid "As for B<waitpid>()."
11259 #: build/C/man2/wait.2:284
11264 #. type: Plain text
11265 #: build/C/man2/wait.2:288
11267 "Leave the child in a waitable state; a later wait call can be used to again "
11268 "retrieve the child status information."
11271 #. type: Plain text
11272 #: build/C/man2/wait.2:295
11274 "Upon successful return, B<waitid>() fills in the following fields of the "
11275 "I<siginfo_t> structure pointed to by I<infop>:"
11278 #. type: Plain text
11279 #: build/C/man2/wait.2:298
11280 msgid "The process ID of the child."
11283 #. type: Plain text
11284 #: build/C/man2/wait.2:302
11286 "The real user ID of the child. (This field is not set on most other "
11287 "implementations.)"
11290 #. type: Plain text
11291 #: build/C/man2/wait.2:306
11292 msgid "Always set to B<SIGCHLD>."
11296 #: build/C/man2/wait.2:306
11298 msgid "I<si_status>"
11301 #. type: Plain text
11302 #: build/C/man2/wait.2:316
11304 "Either the exit status of the child, as given to B<_exit>(2) (or "
11305 "B<exit>(3)), or the signal that caused the child to terminate, stop, or "
11306 "continue. The I<si_code> field can be used to determine how to interpret "
11310 #. type: Plain text
11311 #: build/C/man2/wait.2:333
11313 "Set to one of: B<CLD_EXITED> (child called B<_exit>(2)); B<CLD_KILLED> "
11314 "(child killed by signal); B<CLD_DUMPED> (child killed by signal, and dumped "
11315 "core); B<CLD_STOPPED> (child stopped by signal); B<CLD_TRAPPED> (traced "
11316 "child has trapped); or B<CLD_CONTINUED> (child continued by B<SIGCONT>)."
11319 #. POSIX.1-2001 leaves this possibility unspecified; most
11320 #. implementations (including Linux) zero out the structure
11321 #. in this case, but at least one implementation (AIX 5.1)
11322 #. does not -- MTK Nov 04
11323 #. type: Plain text
11324 #: build/C/man2/wait.2:355
11326 "If B<WNOHANG> was specified in I<options> and there were no children in a "
11327 "waitable state, then B<waitid>() returns 0 immediately and the state of the "
11328 "I<siginfo_t> structure pointed to by I<infop> is unspecified. To "
11329 "distinguish this case from that where a child was in a waitable state, zero "
11330 "out the I<si_pid> field before the call and check for a nonzero value in "
11331 "this field after the call returns."
11334 #. type: Plain text
11335 #: build/C/man2/wait.2:359
11337 "B<wait>(): on success, returns the process ID of the terminated child; on "
11338 "error, -1 is returned."
11341 #. type: Plain text
11342 #: build/C/man2/wait.2:368
11344 "B<waitpid>(): on success, returns the process ID of the child whose state "
11345 "has changed; if B<WNOHANG> was specified and one or more child(ren) "
11346 "specified by I<pid> exist, but have not yet changed state, then 0 is "
11347 "returned. On error, -1 is returned."
11350 #. FIXME As reported by Vegard Nossum, if infop is NULL, then waitid()
11351 #. returns the PID of the child. Either this is a bug, or it is intended
11352 #. behavior that needs to be documented. See my Jan 2009 LKML mail
11353 #. "waitid() return value strangeness when infop is NULL".
11354 #. type: Plain text
11355 #: build/C/man2/wait.2:381
11357 "B<waitid>(): returns 0 on success or if B<WNOHANG> was specified and no "
11358 "child(ren) specified by I<id> has yet changed state; on error, -1 is "
11362 #. type: Plain text
11363 #: build/C/man2/wait.2:385
11365 "Each of these calls sets I<errno> to an appropriate value in the case of an "
11370 #: build/C/man2/wait.2:386 build/C/man2/wait.2:391
11375 #. type: Plain text
11376 #: build/C/man2/wait.2:391
11378 "(for B<wait>()) The calling process does not have any unwaited-for "
11382 #. type: Plain text
11383 #: build/C/man2/wait.2:411
11385 "(for B<waitpid>() or B<waitid>()) The process specified by I<pid> "
11386 "(B<waitpid>()) or I<idtype> and I<id> (B<waitid>()) does not exist or is "
11387 "not a child of the calling process. (This can happen for one's own child if "
11388 "the action for B<SIGCHLD> is set to B<SIG_IGN>. See also the I<Linux Notes> "
11389 "section about threads.)"
11392 #. type: Plain text
11393 #: build/C/man2/wait.2:418
11395 "B<WNOHANG> was not set and an unblocked signal or a B<SIGCHLD> was caught; "
11396 "see B<signal>(7)."
11399 #. type: Plain text
11400 #: build/C/man2/wait.2:423
11401 msgid "The I<options> argument was invalid."
11404 #. type: Plain text
11405 #: build/C/man2/wait.2:438
11407 "A child that terminates, but has not been waited for becomes a \"zombie\". "
11408 "The kernel maintains a minimal set of information about the zombie process "
11409 "(PID, termination status, resource usage information) in order to allow the "
11410 "parent to later perform a wait to obtain information about the child. As "
11411 "long as a zombie is not removed from the system via a wait, it will consume "
11412 "a slot in the kernel process table, and if this table fills, it will not be "
11413 "possible to create further processes. If a parent process terminates, then "
11414 "its \"zombie\" children (if any) are adopted by B<init>(1), which "
11415 "automatically performs a wait to remove the zombies."
11418 #. type: Plain text
11419 #: build/C/man2/wait.2:467
11421 "POSIX.1-2001 specifies that if the disposition of B<SIGCHLD> is set to "
11422 "B<SIG_IGN> or the B<SA_NOCLDWAIT> flag is set for B<SIGCHLD> (see "
11423 "B<sigaction>(2)), then children that terminate do not become zombies and a "
11424 "call to B<wait>() or B<waitpid>() will block until all children have "
11425 "terminated, and then fail with I<errno> set to B<ECHILD>. (The original "
11426 "POSIX standard left the behavior of setting B<SIGCHLD> to B<SIG_IGN> "
11427 "unspecified. Note that even though the default disposition of B<SIGCHLD> is "
11428 "\"ignore\", explicitly setting the disposition to B<SIG_IGN> results in "
11429 "different treatment of zombie process children.)"
11432 #. type: Plain text
11433 #: build/C/man2/wait.2:480
11435 "Linux 2.6 conforms to the POSIX requirements. However, Linux 2.4 (and "
11436 "earlier) does not: if a B<wait>() or B<waitpid>() call is made while "
11437 "B<SIGCHLD> is being ignored, the call behaves just as though B<SIGCHLD> were "
11438 "not being ignored, that is, the call blocks until the next child terminates "
11439 "and then returns the process ID and status of that child."
11442 #. type: Plain text
11443 #: build/C/man2/wait.2:496
11445 "In the Linux kernel, a kernel-scheduled thread is not a distinct construct "
11446 "from a process. Instead, a thread is simply a process that is created using "
11447 "the Linux-unique B<clone>(2) system call; other routines such as the "
11448 "portable B<pthread_create>(3) call are implemented using B<clone>(2). "
11449 "Before Linux 2.4, a thread was just a special case of a process, and as a "
11450 "consequence one thread could not wait on the children of another thread, "
11451 "even when the latter belongs to the same thread group. However, POSIX "
11452 "prescribes such functionality, and since Linux 2.4 a thread can, and by "
11453 "default will, wait on children of other threads in the same thread group."
11456 #. type: Plain text
11457 #: build/C/man2/wait.2:503
11459 "The following Linux-specific I<options> are for use with children created "
11460 "using B<clone>(2); they cannot be used with B<waitid>():"
11464 #: build/C/man2/wait.2:503
11466 msgid "B<__WCLONE>"
11470 #. type: Plain text
11471 #: build/C/man2/wait.2:514
11473 "Wait for \"clone\" children only. If omitted, then wait for \"non-clone\" "
11474 "children only. (A \"clone\" child is one which delivers no signal, or a "
11475 "signal other than B<SIGCHLD> to its parent upon termination.) This option "
11476 "is ignored if B<__WALL> is also specified."
11480 #: build/C/man2/wait.2:514
11482 msgid "B<__WALL> (since Linux 2.4)"
11485 #. since patch-2.3.48
11486 #. type: Plain text
11487 #: build/C/man2/wait.2:519
11488 msgid "Wait for all children, regardless of type (\"clone\" or \"non-clone\")."
11492 #: build/C/man2/wait.2:519
11494 msgid "B<__WNOTHREAD> (since Linux 2.4)"
11497 #. since patch-2.4.0-test8
11498 #. type: Plain text
11499 #: build/C/man2/wait.2:525
11501 "Do not wait for children of other threads in the same thread group. This "
11502 "was the default before Linux 2.4."
11505 #. type: Plain text
11506 #: build/C/man2/wait.2:537
11508 "The raw B<waitid>() system call takes a fifth argument, of type I<struct "
11509 "rusage\\ *>. If this argument is non-NULL, then it is used to return "
11510 "resource usage information about the child, in the same manner as "
11511 "B<wait4>(2). See B<getrusage>(2) for details."
11514 #. type: Plain text
11515 #: build/C/man2/wait.2:552
11517 "According to POSIX.1-2008, an application calling B<waitid>() must ensure "
11518 "that I<infop> points to a I<siginfo_t> structure (i.e., that it is a "
11519 "non-null pointer). On Linux, if I<infop> is NULL, B<waitid>() succeeds, "
11520 "and returns the process ID of the waited-for child. Applications should "
11521 "avoid relying on this inconsistent, nonstandard, and unnecessary feature."
11524 #. fork.2 refers to this example program.
11525 #. type: Plain text
11526 #: build/C/man2/wait.2:569
11528 "The following program demonstrates the use of B<fork>(2) and B<waitpid>(). "
11529 "The program creates a child process. If no command-line argument is "
11530 "supplied to the program, then the child suspends its execution using "
11531 "B<pause>(2), to allow the user to send signals to the child. Otherwise, if "
11532 "a command-line argument is supplied, then the child exits immediately, using "
11533 "the integer supplied on the command line as the exit status. The parent "
11534 "process executes a loop that monitors the child using B<waitpid>(), and uses "
11535 "the W*() macros described above to analyze the wait status value."
11538 #. type: Plain text
11539 #: build/C/man2/wait.2:585
11543 "Child PID is 32360\n"
11545 "$B< kill -STOP 32360>\n"
11546 "stopped by signal 19\n"
11547 "$B< kill -CONT 32360>\n"
11549 "$B< kill -TERM 32360>\n"
11550 "killed by signal 15\n"
11551 "[1]+ Done ./a.out\n"
11555 #. type: Plain text
11556 #: build/C/man2/wait.2:594
11559 "#include E<lt>sys/wait.hE<gt>\n"
11560 "#include E<lt>stdlib.hE<gt>\n"
11561 "#include E<lt>unistd.hE<gt>\n"
11562 "#include E<lt>stdio.hE<gt>\n"
11565 #. type: Plain text
11566 #: build/C/man2/wait.2:600
11570 "main(int argc, char *argv[])\n"
11572 " pid_t cpid, w;\n"
11576 #. type: Plain text
11577 #: build/C/man2/wait.2:606
11580 " cpid = fork();\n"
11581 " if (cpid == -1) {\n"
11582 " perror(\"fork\");\n"
11583 " exit(EXIT_FAILURE);\n"
11587 #. type: Plain text
11588 #: build/C/man2/wait.2:612
11591 " if (cpid == 0) { /* Code executed by child */\n"
11592 " printf(\"Child PID is %ld\\en\", (long) getpid());\n"
11593 " if (argc == 1)\n"
11594 " pause(); /* Wait for signals */\n"
11595 " _exit(atoi(argv[1]));\n"
11598 #. type: Plain text
11599 #: build/C/man2/wait.2:620
11602 " } else { /* Code executed by parent */\n"
11604 " w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);\n"
11605 " if (w == -1) {\n"
11606 " perror(\"waitpid\");\n"
11607 " exit(EXIT_FAILURE);\n"
11611 #. type: Plain text
11612 #: build/C/man2/wait.2:634
11615 " if (WIFEXITED(status)) {\n"
11616 " printf(\"exited, status=%d\\en\", WEXITSTATUS(status));\n"
11617 " } else if (WIFSIGNALED(status)) {\n"
11618 " printf(\"killed by signal %d\\en\", WTERMSIG(status));\n"
11619 " } else if (WIFSTOPPED(status)) {\n"
11620 " printf(\"stopped by signal %d\\en\", WSTOPSIG(status));\n"
11621 " } else if (WIFCONTINUED(status)) {\n"
11622 " printf(\"continued\\en\");\n"
11624 " } while (!WIFEXITED(status) && !WIFSIGNALED(status));\n"
11625 " exit(EXIT_SUCCESS);\n"
11630 #. type: Plain text
11631 #: build/C/man2/wait.2:647
11633 "B<_exit>(2), B<clone>(2), B<fork>(2), B<kill>(2), B<ptrace>(2), "
11634 "B<sigaction>(2), B<signal>(2), B<wait4>(2), B<pthread_create>(3), "
11635 "B<credentials>(7), B<signal>(7)"
11639 #: build/C/man2/wait4.2:33
11645 #: build/C/man2/wait4.2:33
11650 #. type: Plain text
11651 #: build/C/man2/wait4.2:36
11652 msgid "wait3, wait4 - wait for process to change state, BSD style"
11655 #. type: Plain text
11656 #: build/C/man2/wait4.2:42
11659 "B<#include E<lt>sys/types.hE<gt>>\n"
11660 "B<#include E<lt>sys/time.hE<gt>>\n"
11661 "B<#include E<lt>sys/resource.hE<gt>>\n"
11662 "B<#include E<lt>sys/wait.hE<gt>>\n"
11665 #. type: Plain text
11666 #: build/C/man2/wait4.2:45
11669 "B<pid_t wait3(int *>I<status>B<, int >I<options>B<,>\n"
11670 "B< struct rusage *>I<rusage>B<);>\n"
11673 #. type: Plain text
11674 #: build/C/man2/wait4.2:48
11677 "B<pid_t wait4(pid_t >I<pid>B<, int *>I<status>B<, int >I<options>B<,>\n"
11678 "B< struct rusage *>I<rusage>B<);>\n"
11681 #. type: Plain text
11682 #: build/C/man2/wait4.2:57
11683 msgid "B<wait3>():"
11686 #. type: Plain text
11687 #: build/C/man2/wait4.2:63
11688 msgid "B<wait4>():"
11691 #. type: Plain text
11692 #: build/C/man2/wait4.2:65
11693 msgid "_BSD_SOURCE"
11696 #. type: Plain text
11697 #: build/C/man2/wait4.2:73
11699 "These functions are obsolete; use B<waitpid>(2) or B<waitid>(2) in new "
11703 #. type: Plain text
11704 #: build/C/man2/wait4.2:83
11706 "The B<wait3>() and B<wait4>() system calls are similar to B<waitpid>(2), "
11707 "but additionally return resource usage information about the child in the "
11708 "structure pointed to by I<rusage>."
11711 #. type: Plain text
11712 #: build/C/man2/wait4.2:89
11714 "Other than the use of the I<rusage> argument, the following B<wait3>() "
11718 #. type: Plain text
11719 #: build/C/man2/wait4.2:92
11721 msgid " wait3(status, options, rusage);\n"
11724 #. type: Plain text
11725 #: build/C/man2/wait4.2:95 build/C/man2/wait4.2:109
11726 msgid "is equivalent to:"
11729 #. type: Plain text
11730 #: build/C/man2/wait4.2:98
11732 msgid " waitpid(-1, status, options);\n"
11735 #. type: Plain text
11736 #: build/C/man2/wait4.2:103
11737 msgid "Similarly, the following B<wait4>() call:"
11740 #. type: Plain text
11741 #: build/C/man2/wait4.2:106
11743 msgid " wait4(pid, status, options, rusage);\n"
11746 #. type: Plain text
11747 #: build/C/man2/wait4.2:112
11749 msgid " waitpid(pid, status, options);\n"
11752 #. type: Plain text
11753 #: build/C/man2/wait4.2:122
11755 "In other words, B<wait3>() waits of any child, while B<wait4>() can be "
11756 "used to select a specific child, or children, on which to wait. See "
11757 "B<wait>(2) for further details."
11760 #. type: Plain text
11761 #: build/C/man2/wait4.2:132
11763 "If I<rusage> is not NULL, the I<struct rusage> to which it points will be "
11764 "filled with accounting information about the child. See B<getrusage>(2) "
11768 #. type: Plain text
11769 #: build/C/man2/wait4.2:135 build/C/man2/wait4.2:138
11770 msgid "As for B<waitpid>(2)."
11773 #. type: Plain text
11774 #: build/C/man2/wait4.2:140
11778 #. type: Plain text
11779 #: build/C/man2/wait4.2:147
11781 "SUSv1 included a specification of B<wait3>(); SUSv2 included B<wait3>(), but "
11782 "marked it LEGACY; SUSv3 removed it."
11785 #. type: Plain text
11786 #: build/C/man2/wait4.2:159
11788 "Including I<E<lt>sys/time.hE<gt>> is not required these days, but increases "
11789 "portability. (Indeed, I<E<lt>sys/resource.hE<gt>> defines the I<rusage> "
11790 "structure with fields of type I<struct timeval> defined in "
11791 "I<E<lt>sys/time.hE<gt>>.)"
11794 #. type: Plain text
11795 #: build/C/man2/wait4.2:165
11797 "On Linux, B<wait3>() is a library function implemented on top of the "
11798 "B<wait4>() system call."
11801 #. type: Plain text
11802 #: build/C/man2/wait4.2:172
11804 "B<fork>(2), B<getrusage>(2), B<sigaction>(2), B<signal>(2), B<wait>(2), "