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-01-23 22:25+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/getcontext.3:25
26 #: build/C/man3/getcontext.3:25
32 #: build/C/man3/getcontext.3:25 build/C/man3/pthread_attr_init.3:26 build/C/man3/pthread_attr_setaffinity_np.3:26 build/C/man3/pthread_attr_setdetachstate.3:26 build/C/man3/pthread_attr_setguardsize.3:26 build/C/man3/pthread_attr_setinheritsched.3:26 build/C/man3/pthread_attr_setschedparam.3:26 build/C/man3/pthread_attr_setschedpolicy.3:26 build/C/man3/pthread_attr_setscope.3:26 build/C/man3/pthread_attr_setstack.3:26 build/C/man3/pthread_attr_setstackaddr.3:26 build/C/man3/pthread_attr_setstacksize.3:26 build/C/man3/pthread_cancel.3:26 build/C/man3/pthread_cleanup_push.3:26 build/C/man3/pthread_cleanup_push_defer_np.3:26 build/C/man3/pthread_create.3:26 build/C/man3/pthread_detach.3:26 build/C/man3/pthread_equal.3:26 build/C/man3/pthread_exit.3:26 build/C/man3/pthread_getattr_np.3:26 build/C/man3/pthread_getcpuclockid.3:26 build/C/man3/pthread_join.3:26 build/C/man3/pthread_kill.3:26 build/C/man3/pthread_kill_other_threads_np.3:26 build/C/man3/pthread_self.3:26 build/C/man3/pthread_setaffinity_np.3:26 build/C/man3/pthread_setcancelstate.3:26 build/C/man3/pthread_setconcurrency.3:25 build/C/man3/pthread_setname_np.3:26 build/C/man3/pthread_setschedparam.3:26 build/C/man3/pthread_setschedprio.3:26 build/C/man3/pthread_sigmask.3:26 build/C/man3/pthread_sigqueue.3:25 build/C/man3/pthread_testcancel.3:26 build/C/man3/pthread_tryjoin_np.3:26 build/C/man3/pthread_yield.3:25 build/C/man7/pthreads.7:26
38 #: build/C/man3/getcontext.3:25 build/C/man3/makecontext.3:28 build/C/man3/pthread_attr_init.3:26 build/C/man3/pthread_attr_setaffinity_np.3:26 build/C/man3/pthread_attr_setdetachstate.3:26 build/C/man3/pthread_attr_setguardsize.3:26 build/C/man3/pthread_attr_setinheritsched.3:26 build/C/man3/pthread_attr_setschedparam.3:26 build/C/man3/pthread_attr_setschedpolicy.3:26 build/C/man3/pthread_attr_setscope.3:26 build/C/man3/pthread_attr_setstack.3:26 build/C/man3/pthread_attr_setstackaddr.3:26 build/C/man3/pthread_attr_setstacksize.3:26 build/C/man3/pthread_cancel.3:26 build/C/man3/pthread_cleanup_push.3:26 build/C/man3/pthread_cleanup_push_defer_np.3:26 build/C/man3/pthread_create.3:26 build/C/man3/pthread_detach.3:26 build/C/man3/pthread_equal.3:26 build/C/man3/pthread_exit.3:26 build/C/man3/pthread_getattr_np.3:26 build/C/man3/pthread_getcpuclockid.3:26 build/C/man3/pthread_join.3:26 build/C/man3/pthread_kill.3:26 build/C/man3/pthread_kill_other_threads_np.3:26 build/C/man3/pthread_rwlockattr_setkind_np.3:25 build/C/man3/pthread_self.3:26 build/C/man3/pthread_setaffinity_np.3:26 build/C/man3/pthread_setcancelstate.3:26 build/C/man3/pthread_setconcurrency.3:25 build/C/man3/pthread_setname_np.3:26 build/C/man3/pthread_setschedparam.3:26 build/C/man3/pthread_setschedprio.3:26 build/C/man3/pthread_sigmask.3:26 build/C/man3/pthread_sigqueue.3:25 build/C/man3/pthread_testcancel.3:26 build/C/man3/pthread_tryjoin_np.3:26 build/C/man3/pthread_yield.3:25 build/C/man7/pthreads.7:26
40 msgid "Linux Programmer's Manual"
44 #: build/C/man3/getcontext.3:26 build/C/man3/makecontext.3:29 build/C/man3/pthread_attr_init.3:27 build/C/man3/pthread_attr_setaffinity_np.3:27 build/C/man3/pthread_attr_setdetachstate.3:27 build/C/man3/pthread_attr_setguardsize.3:27 build/C/man3/pthread_attr_setinheritsched.3:27 build/C/man3/pthread_attr_setschedparam.3:27 build/C/man3/pthread_attr_setschedpolicy.3:27 build/C/man3/pthread_attr_setscope.3:27 build/C/man3/pthread_attr_setstack.3:27 build/C/man3/pthread_attr_setstackaddr.3:27 build/C/man3/pthread_attr_setstacksize.3:27 build/C/man3/pthread_cancel.3:27 build/C/man3/pthread_cleanup_push.3:27 build/C/man3/pthread_cleanup_push_defer_np.3:27 build/C/man3/pthread_create.3:27 build/C/man3/pthread_detach.3:27 build/C/man3/pthread_equal.3:27 build/C/man3/pthread_exit.3:27 build/C/man3/pthread_getattr_np.3:27 build/C/man3/pthread_getcpuclockid.3:27 build/C/man3/pthread_join.3:27 build/C/man3/pthread_kill.3:27 build/C/man3/pthread_kill_other_threads_np.3:27 build/C/man3/pthread_rwlockattr_setkind_np.3:26 build/C/man3/pthread_self.3:27 build/C/man3/pthread_setaffinity_np.3:27 build/C/man3/pthread_setcancelstate.3:27 build/C/man3/pthread_setconcurrency.3:26 build/C/man3/pthread_setname_np.3:27 build/C/man3/pthread_setschedparam.3:27 build/C/man3/pthread_setschedprio.3:27 build/C/man3/pthread_sigmask.3:27 build/C/man3/pthread_sigqueue.3:26 build/C/man3/pthread_testcancel.3:27 build/C/man3/pthread_tryjoin_np.3:27 build/C/man3/pthread_yield.3:26 build/C/man7/pthreads.7:27
50 #: build/C/man3/getcontext.3:28
51 msgid "getcontext, setcontext - get or set the user context"
55 #: build/C/man3/getcontext.3:28 build/C/man3/makecontext.3:31 build/C/man3/pthread_attr_init.3:30 build/C/man3/pthread_attr_setaffinity_np.3:30 build/C/man3/pthread_attr_setdetachstate.3:30 build/C/man3/pthread_attr_setguardsize.3:30 build/C/man3/pthread_attr_setinheritsched.3:30 build/C/man3/pthread_attr_setschedparam.3:30 build/C/man3/pthread_attr_setschedpolicy.3:30 build/C/man3/pthread_attr_setscope.3:30 build/C/man3/pthread_attr_setstack.3:30 build/C/man3/pthread_attr_setstackaddr.3:30 build/C/man3/pthread_attr_setstacksize.3:30 build/C/man3/pthread_cancel.3:29 build/C/man3/pthread_cleanup_push.3:30 build/C/man3/pthread_cleanup_push_defer_np.3:30 build/C/man3/pthread_create.3:29 build/C/man3/pthread_detach.3:29 build/C/man3/pthread_equal.3:29 build/C/man3/pthread_exit.3:29 build/C/man3/pthread_getattr_np.3:29 build/C/man3/pthread_getcpuclockid.3:29 build/C/man3/pthread_join.3:29 build/C/man3/pthread_kill.3:29 build/C/man3/pthread_kill_other_threads_np.3:29 build/C/man3/pthread_rwlockattr_setkind_np.3:29 build/C/man3/pthread_self.3:29 build/C/man3/pthread_setaffinity_np.3:30 build/C/man3/pthread_setcancelstate.3:30 build/C/man3/pthread_setconcurrency.3:29 build/C/man3/pthread_setname_np.3:29 build/C/man3/pthread_setschedparam.3:30 build/C/man3/pthread_setschedprio.3:29 build/C/man3/pthread_sigmask.3:29 build/C/man3/pthread_sigqueue.3:28 build/C/man3/pthread_testcancel.3:29 build/C/man3/pthread_tryjoin_np.3:30 build/C/man3/pthread_yield.3:28
61 #: build/C/man3/getcontext.3:30 build/C/man3/makecontext.3:33
62 msgid "B<#include E<lt>ucontext.hE<gt>>"
66 #: build/C/man3/getcontext.3:32
67 msgid "B<int getcontext(ucontext_t *>I<ucp>B<);>"
71 #: build/C/man3/getcontext.3:34
72 msgid "B<int setcontext(const ucontext_t *>I<ucp>B<);>"
76 #: build/C/man3/getcontext.3:34 build/C/man3/makecontext.3:38 build/C/man3/pthread_attr_init.3:39 build/C/man3/pthread_attr_setaffinity_np.3:42 build/C/man3/pthread_attr_setdetachstate.3:41 build/C/man3/pthread_attr_setguardsize.3:41 build/C/man3/pthread_attr_setinheritsched.3:41 build/C/man3/pthread_attr_setschedparam.3:41 build/C/man3/pthread_attr_setschedpolicy.3:41 build/C/man3/pthread_attr_setscope.3:41 build/C/man3/pthread_attr_setstack.3:54 build/C/man3/pthread_attr_setstackaddr.3:41 build/C/man3/pthread_attr_setstacksize.3:41 build/C/man3/pthread_cancel.3:37 build/C/man3/pthread_cleanup_push.3:40 build/C/man3/pthread_cleanup_push_defer_np.3:53 build/C/man3/pthread_create.3:38 build/C/man3/pthread_detach.3:37 build/C/man3/pthread_equal.3:37 build/C/man3/pthread_exit.3:37 build/C/man3/pthread_getattr_np.3:38 build/C/man3/pthread_getcpuclockid.3:38 build/C/man3/pthread_join.3:37 build/C/man3/pthread_kill.3:49 build/C/man3/pthread_kill_other_threads_np.3:35 build/C/man3/pthread_rwlockattr_setkind_np.3:54 build/C/man3/pthread_self.3:37 build/C/man3/pthread_setaffinity_np.3:42 build/C/man3/pthread_setcancelstate.3:39 build/C/man3/pthread_setconcurrency.3:38 build/C/man3/pthread_setname_np.3:39 build/C/man3/pthread_setschedparam.3:41 build/C/man3/pthread_setschedprio.3:37 build/C/man3/pthread_sigmask.3:50 build/C/man3/pthread_sigqueue.3:46 build/C/man3/pthread_testcancel.3:37 build/C/man3/pthread_tryjoin_np.3:42 build/C/man3/pthread_yield.3:37 build/C/man7/pthreads.7:29
82 #: build/C/man3/getcontext.3:49
84 "In a System V-like environment, one has the two types I<mcontext_t> and "
85 "I<ucontext_t> defined in I<E<lt>ucontext.hE<gt>> and the four functions "
86 "B<getcontext>(), B<setcontext>(), B<makecontext>(3), and B<swapcontext>(3) "
87 "that allow user-level context switching between multiple threads of control "
92 #: build/C/man3/getcontext.3:57
94 "The I<mcontext_t> type is machine-dependent and opaque. The I<ucontext_t> "
95 "type is a structure that has at least the following fields:"
99 #: build/C/man3/getcontext.3:67
102 "typedef struct ucontext {\n"
103 " struct ucontext *uc_link;\n"
104 " sigset_t uc_sigmask;\n"
105 " stack_t uc_stack;\n"
106 " mcontext_t uc_mcontext;\n"
112 #: build/C/man3/getcontext.3:94
114 "with I<sigset_t> and I<stack_t> defined in I<E<lt>signal.hE<gt>>. Here "
115 "I<uc_link> points to the context that will be resumed when the current "
116 "context terminates (in case the current context was created using "
117 "B<makecontext>(3)), I<uc_sigmask> is the set of signals blocked in this "
118 "context (see B<sigprocmask>(2)), I<uc_stack> is the stack used by this "
119 "context (see B<sigaltstack>(2)), and I<uc_mcontext> is the machine-specific "
120 "representation of the saved context, that includes the calling thread's "
125 #: build/C/man3/getcontext.3:101
127 "The function B<getcontext>() initializes the structure pointed at by I<ucp> "
128 "to the currently active context."
132 #: build/C/man3/getcontext.3:114
134 "The function B<setcontext>() restores the user context pointed at by "
135 "I<ucp>. A successful call does not return. The context should have been "
136 "obtained by a call of B<getcontext>(), or B<makecontext>(3), or passed as "
137 "third argument to a signal handler."
141 #: build/C/man3/getcontext.3:118
143 "If the context was obtained by a call of B<getcontext>(), program execution "
144 "continues as if this call just returned."
148 #: build/C/man3/getcontext.3:135
150 "If the context was obtained by a call of B<makecontext>(3), program "
151 "execution continues by a call to the function I<func> specified as the "
152 "second argument of that call to B<makecontext>(3). When the function "
153 "I<func> returns, we continue with the I<uc_link> member of the structure "
154 "I<ucp> specified as the first argument of that call to B<makecontext>(3). "
155 "When this member is NULL, the thread exits."
159 #: build/C/man3/getcontext.3:142
161 "If the context was obtained by a call to a signal handler, then old standard "
162 "text says that \"program execution continues with the program instruction "
163 "following the instruction interrupted by the signal\". However, this "
164 "sentence was removed in SUSv2, and the present verdict is \"the result is "
169 #: build/C/man3/getcontext.3:142 build/C/man3/makecontext.3:84 build/C/man3/pthread_attr_init.3:68 build/C/man3/pthread_attr_setaffinity_np.3:76 build/C/man3/pthread_attr_setdetachstate.3:77 build/C/man3/pthread_attr_setguardsize.3:90 build/C/man3/pthread_attr_setinheritsched.3:93 build/C/man3/pthread_attr_setschedparam.3:85 build/C/man3/pthread_attr_setschedpolicy.3:83 build/C/man3/pthread_attr_setscope.3:103 build/C/man3/pthread_attr_setstack.3:85 build/C/man3/pthread_attr_setstackaddr.3:74 build/C/man3/pthread_attr_setstacksize.3:61 build/C/man3/pthread_cancel.3:112 build/C/man3/pthread_cleanup_push.3:121 build/C/man3/pthread_create.3:115 build/C/man3/pthread_detach.3:49 build/C/man3/pthread_equal.3:41 build/C/man3/pthread_exit.3:71 build/C/man3/pthread_getattr_np.3:73 build/C/man3/pthread_getcpuclockid.3:46 build/C/man3/pthread_join.3:70 build/C/man3/pthread_kill.3:63 build/C/man3/pthread_rwlockattr_setkind_np.3:96 build/C/man3/pthread_self.3:46 build/C/man3/pthread_setaffinity_np.3:77 build/C/man3/pthread_setcancelstate.3:92 build/C/man3/pthread_setconcurrency.3:56 build/C/man3/pthread_setname_np.3:72 build/C/man3/pthread_setschedparam.3:104 build/C/man3/pthread_setschedprio.3:53 build/C/man3/pthread_sigmask.3:61 build/C/man3/pthread_sigqueue.3:66 build/C/man3/pthread_testcancel.3:50 build/C/man3/pthread_tryjoin_np.3:85 build/C/man3/pthread_yield.3:44
175 #: build/C/man3/getcontext.3:151
177 "When successful, B<getcontext>() returns 0 and B<setcontext>() does not "
178 "return. On error, both return -1 and set I<errno> appropriately."
182 #: build/C/man3/getcontext.3:151 build/C/man3/makecontext.3:96 build/C/man3/pthread_attr_init.3:71 build/C/man3/pthread_attr_setaffinity_np.3:79 build/C/man3/pthread_attr_setdetachstate.3:80 build/C/man3/pthread_attr_setguardsize.3:93 build/C/man3/pthread_attr_setinheritsched.3:96 build/C/man3/pthread_attr_setschedparam.3:88 build/C/man3/pthread_attr_setschedpolicy.3:86 build/C/man3/pthread_attr_setscope.3:106 build/C/man3/pthread_attr_setstack.3:88 build/C/man3/pthread_attr_setstackaddr.3:77 build/C/man3/pthread_attr_setstacksize.3:64 build/C/man3/pthread_cancel.3:117 build/C/man3/pthread_cleanup_push.3:123 build/C/man3/pthread_create.3:122 build/C/man3/pthread_detach.3:54 build/C/man3/pthread_equal.3:45 build/C/man3/pthread_exit.3:73 build/C/man3/pthread_getattr_np.3:76 build/C/man3/pthread_getcpuclockid.3:49 build/C/man3/pthread_join.3:75 build/C/man3/pthread_kill.3:68 build/C/man3/pthread_rwlockattr_setkind_np.3:104 build/C/man3/pthread_self.3:48 build/C/man3/pthread_setaffinity_np.3:80 build/C/man3/pthread_setcancelstate.3:95 build/C/man3/pthread_setconcurrency.3:68 build/C/man3/pthread_setname_np.3:75 build/C/man3/pthread_setschedparam.3:112 build/C/man3/pthread_setschedprio.3:61 build/C/man3/pthread_sigmask.3:66 build/C/man3/pthread_sigqueue.3:71 build/C/man3/pthread_testcancel.3:54 build/C/man3/pthread_tryjoin_np.3:89 build/C/man3/pthread_yield.3:49
188 #: build/C/man3/getcontext.3:153
189 msgid "None defined."
193 #: build/C/man3/getcontext.3:153 build/C/man3/makecontext.3:105 build/C/man3/pthread_attr_setdetachstate.3:87 build/C/man3/pthread_attr_setguardsize.3:106 build/C/man3/pthread_attr_setinheritsched.3:110 build/C/man3/pthread_attr_setschedparam.3:100 build/C/man3/pthread_attr_setschedpolicy.3:100 build/C/man3/pthread_attr_setscope.3:119 build/C/man3/pthread_attr_setstack.3:112 build/C/man3/pthread_attr_setstackaddr.3:83 build/C/man3/pthread_attr_setstacksize.3:83 build/C/man3/pthread_equal.3:47 build/C/man3/pthread_exit.3:75 build/C/man3/pthread_getcpuclockid.3:65 build/C/man3/pthread_kill.3:72 build/C/man3/pthread_kill_other_threads_np.3:47 build/C/man3/pthread_self.3:50 build/C/man3/pthread_setaffinity_np.3:121 build/C/man3/pthread_setcancelstate.3:113 build/C/man3/pthread_setconcurrency.3:83 build/C/man3/pthread_setschedparam.3:141 build/C/man3/pthread_setschedprio.3:83 build/C/man3/pthread_sigmask.3:69 build/C/man3/pthread_sigqueue.3:94 build/C/man3/pthread_testcancel.3:58 build/C/man3/pthread_yield.3:53
199 #: build/C/man3/getcontext.3:154 build/C/man3/makecontext.3:106 build/C/man3/pthread_attr_setdetachstate.3:88 build/C/man3/pthread_attr_setguardsize.3:107 build/C/man3/pthread_attr_setinheritsched.3:111 build/C/man3/pthread_attr_setschedparam.3:101 build/C/man3/pthread_attr_setschedpolicy.3:101 build/C/man3/pthread_attr_setscope.3:120 build/C/man3/pthread_attr_setstack.3:113 build/C/man3/pthread_attr_setstackaddr.3:84 build/C/man3/pthread_attr_setstacksize.3:84 build/C/man3/pthread_equal.3:48 build/C/man3/pthread_exit.3:76 build/C/man3/pthread_getcpuclockid.3:66 build/C/man3/pthread_kill.3:73 build/C/man3/pthread_kill_other_threads_np.3:48 build/C/man3/pthread_self.3:51 build/C/man3/pthread_setaffinity_np.3:122 build/C/man3/pthread_setcancelstate.3:114 build/C/man3/pthread_setconcurrency.3:84 build/C/man3/pthread_setschedparam.3:142 build/C/man3/pthread_setschedprio.3:84 build/C/man3/pthread_sigmask.3:70 build/C/man3/pthread_sigqueue.3:95 build/C/man3/pthread_testcancel.3:59 build/C/man3/pthread_yield.3:54
201 msgid "Multithreading (see pthreads(7))"
205 #: build/C/man3/getcontext.3:160
206 msgid "The B<getcontext>() and B<setcontext>() functions are thread-safe."
210 #: build/C/man3/getcontext.3:160 build/C/man3/makecontext.3:112 build/C/man3/pthread_attr_init.3:79 build/C/man3/pthread_attr_setaffinity_np.3:108 build/C/man3/pthread_attr_setdetachstate.3:94 build/C/man3/pthread_attr_setguardsize.3:113 build/C/man3/pthread_attr_setinheritsched.3:117 build/C/man3/pthread_attr_setschedparam.3:107 build/C/man3/pthread_attr_setschedpolicy.3:107 build/C/man3/pthread_attr_setscope.3:126 build/C/man3/pthread_attr_setstack.3:119 build/C/man3/pthread_attr_setstackaddr.3:90 build/C/man3/pthread_attr_setstacksize.3:90 build/C/man3/pthread_cancel.3:125 build/C/man3/pthread_cleanup_push.3:127 build/C/man3/pthread_cleanup_push_defer_np.3:114 build/C/man3/pthread_create.3:153 build/C/man3/pthread_detach.3:64 build/C/man3/pthread_equal.3:52 build/C/man3/pthread_exit.3:80 build/C/man3/pthread_getattr_np.3:98 build/C/man3/pthread_getcpuclockid.3:70 build/C/man3/pthread_join.3:98 build/C/man3/pthread_kill.3:77 build/C/man3/pthread_kill_other_threads_np.3:52 build/C/man3/pthread_rwlockattr_setkind_np.3:127 build/C/man3/pthread_self.3:55 build/C/man3/pthread_setaffinity_np.3:128 build/C/man3/pthread_setcancelstate.3:120 build/C/man3/pthread_setconcurrency.3:90 build/C/man3/pthread_setname_np.3:102 build/C/man3/pthread_setschedparam.3:148 build/C/man3/pthread_setschedprio.3:88 build/C/man3/pthread_sigmask.3:74 build/C/man3/pthread_sigqueue.3:99 build/C/man3/pthread_testcancel.3:63 build/C/man3/pthread_tryjoin_np.3:120 build/C/man3/pthread_yield.3:58
212 msgid "CONFORMING TO"
216 #: build/C/man3/getcontext.3:166
218 "SUSv2, POSIX.1-2001. POSIX.1-2008 removes the specification of "
219 "B<getcontext>(), citing portability issues, and recommending that "
220 "applications be rewritten to use POSIX threads instead."
224 #: build/C/man3/getcontext.3:166 build/C/man3/makecontext.3:120 build/C/man3/pthread_attr_init.3:81 build/C/man3/pthread_attr_setaffinity_np.3:111 build/C/man3/pthread_attr_setdetachstate.3:96 build/C/man3/pthread_attr_setguardsize.3:115 build/C/man3/pthread_attr_setschedparam.3:109 build/C/man3/pthread_attr_setscope.3:128 build/C/man3/pthread_attr_setstack.3:121 build/C/man3/pthread_attr_setstackaddr.3:93 build/C/man3/pthread_attr_setstacksize.3:92 build/C/man3/pthread_cancel.3:127 build/C/man3/pthread_cleanup_push.3:129 build/C/man3/pthread_create.3:155 build/C/man3/pthread_detach.3:66 build/C/man3/pthread_equal.3:54 build/C/man3/pthread_exit.3:82 build/C/man3/pthread_getcpuclockid.3:72 build/C/man3/pthread_join.3:100 build/C/man3/pthread_kill.3:79 build/C/man3/pthread_kill_other_threads_np.3:55 build/C/man3/pthread_self.3:57 build/C/man3/pthread_setaffinity_np.3:131 build/C/man3/pthread_setcancelstate.3:122 build/C/man3/pthread_setconcurrency.3:92 build/C/man3/pthread_setname_np.3:104 build/C/man3/pthread_setschedparam.3:150 build/C/man3/pthread_setschedprio.3:90 build/C/man3/pthread_sigmask.3:76 build/C/man3/pthread_yield.3:64
230 #: build/C/man3/getcontext.3:183
232 "The earliest incarnation of this mechanism was the "
233 "B<setjmp>(3)/B<longjmp>(3) mechanism. Since that does not define the "
234 "handling of the signal context, the next stage was the "
235 "B<sigsetjmp>(3)/B<siglongjmp>(3) pair. The present mechanism gives much "
236 "more control. On the other hand, there is no easy way to detect whether a "
237 "return from B<getcontext>() is from the first call, or via a "
238 "B<setcontext>() call. The user has to invent her own bookkeeping device, "
239 "and a register variable won't do since registers are restored."
243 #: build/C/man3/getcontext.3:194
245 "When a signal occurs, the current user context is saved and a new context is "
246 "created by the kernel for the signal handler. Do not leave the handler "
247 "using B<longjmp>(3): it is undefined what would happen with contexts. Use "
248 "B<siglongjmp>(3) or B<setcontext>() instead."
252 #: build/C/man3/getcontext.3:194 build/C/man3/makecontext.3:227 build/C/man3/pthread_attr_init.3:297 build/C/man3/pthread_attr_setaffinity_np.3:118 build/C/man3/pthread_attr_setdetachstate.3:118 build/C/man3/pthread_attr_setguardsize.3:165 build/C/man3/pthread_attr_setinheritsched.3:138 build/C/man3/pthread_attr_setschedparam.3:116 build/C/man3/pthread_attr_setschedpolicy.3:112 build/C/man3/pthread_attr_setscope.3:139 build/C/man3/pthread_attr_setstack.3:162 build/C/man3/pthread_attr_setstackaddr.3:117 build/C/man3/pthread_attr_setstacksize.3:118 build/C/man3/pthread_cancel.3:226 build/C/man3/pthread_cleanup_push.3:315 build/C/man3/pthread_cleanup_push_defer_np.3:117 build/C/man3/pthread_create.3:376 build/C/man3/pthread_detach.3:97 build/C/man3/pthread_equal.3:61 build/C/man3/pthread_exit.3:110 build/C/man3/pthread_getattr_np.3:345 build/C/man3/pthread_getcpuclockid.3:175 build/C/man3/pthread_join.3:127 build/C/man3/pthread_kill.3:99 build/C/man3/pthread_kill_other_threads_np.3:71 build/C/man3/pthread_rwlockattr_setkind_np.3:130 build/C/man3/pthread_self.3:81 build/C/man3/pthread_setaffinity_np.3:213 build/C/man3/pthread_setcancelstate.3:186 build/C/man3/pthread_setconcurrency.3:107 build/C/man3/pthread_setname_np.3:200 build/C/man3/pthread_setschedparam.3:440 build/C/man3/pthread_setschedprio.3:96 build/C/man3/pthread_sigmask.3:152 build/C/man3/pthread_sigqueue.3:101 build/C/man3/pthread_testcancel.3:68 build/C/man3/pthread_tryjoin_np.3:143 build/C/man3/pthread_yield.3:67 build/C/man7/pthreads.7:893
258 #: build/C/man3/getcontext.3:201
260 "B<sigaction>(2), B<sigaltstack>(2), B<sigprocmask>(2), B<longjmp>(3), "
261 "B<makecontext>(3), B<sigsetjmp>(3)"
265 #: build/C/man3/getcontext.3:201 build/C/man3/makecontext.3:233 build/C/man3/pthread_attr_init.3:313 build/C/man3/pthread_attr_setaffinity_np.3:124 build/C/man3/pthread_attr_setdetachstate.3:124 build/C/man3/pthread_attr_setguardsize.3:173 build/C/man3/pthread_attr_setinheritsched.3:150 build/C/man3/pthread_attr_setschedparam.3:128 build/C/man3/pthread_attr_setschedpolicy.3:123 build/C/man3/pthread_attr_setscope.3:149 build/C/man3/pthread_attr_setstack.3:174 build/C/man3/pthread_attr_setstackaddr.3:123 build/C/man3/pthread_attr_setstacksize.3:125 build/C/man3/pthread_cancel.3:238 build/C/man3/pthread_cleanup_push.3:321 build/C/man3/pthread_cleanup_push_defer_np.3:123 build/C/man3/pthread_create.3:389 build/C/man3/pthread_detach.3:104 build/C/man3/pthread_equal.3:65 build/C/man3/pthread_exit.3:114 build/C/man3/pthread_getattr_np.3:361 build/C/man3/pthread_getcpuclockid.3:183 build/C/man3/pthread_join.3:134 build/C/man3/pthread_kill.3:108 build/C/man3/pthread_kill_other_threads_np.3:77 build/C/man3/pthread_rwlockattr_setkind_np.3:132 build/C/man3/pthread_self.3:85 build/C/man3/pthread_setaffinity_np.3:221 build/C/man3/pthread_setcancelstate.3:191 build/C/man3/pthread_setconcurrency.3:110 build/C/man3/pthread_setname_np.3:206 build/C/man3/pthread_setschedparam.3:454 build/C/man3/pthread_setschedprio.3:110 build/C/man3/pthread_sigmask.3:161 build/C/man3/pthread_sigqueue.3:109 build/C/man3/pthread_testcancel.3:73 build/C/man3/pthread_tryjoin_np.3:148 build/C/man3/pthread_yield.3:71 build/C/man7/pthreads.7:927
271 #: build/C/man3/getcontext.3:209 build/C/man3/makecontext.3:241 build/C/man3/pthread_attr_init.3:321 build/C/man3/pthread_attr_setaffinity_np.3:132 build/C/man3/pthread_attr_setdetachstate.3:132 build/C/man3/pthread_attr_setguardsize.3:181 build/C/man3/pthread_attr_setinheritsched.3:158 build/C/man3/pthread_attr_setschedparam.3:136 build/C/man3/pthread_attr_setschedpolicy.3:131 build/C/man3/pthread_attr_setscope.3:157 build/C/man3/pthread_attr_setstack.3:182 build/C/man3/pthread_attr_setstackaddr.3:131 build/C/man3/pthread_attr_setstacksize.3:133 build/C/man3/pthread_cancel.3:246 build/C/man3/pthread_cleanup_push.3:329 build/C/man3/pthread_cleanup_push_defer_np.3:131 build/C/man3/pthread_create.3:397 build/C/man3/pthread_detach.3:112 build/C/man3/pthread_equal.3:73 build/C/man3/pthread_exit.3:122 build/C/man3/pthread_getattr_np.3:369 build/C/man3/pthread_getcpuclockid.3:191 build/C/man3/pthread_join.3:142 build/C/man3/pthread_kill.3:116 build/C/man3/pthread_kill_other_threads_np.3:85 build/C/man3/pthread_rwlockattr_setkind_np.3:140 build/C/man3/pthread_self.3:93 build/C/man3/pthread_setaffinity_np.3:229 build/C/man3/pthread_setcancelstate.3:199 build/C/man3/pthread_setconcurrency.3:118 build/C/man3/pthread_setname_np.3:214 build/C/man3/pthread_setschedparam.3:462 build/C/man3/pthread_setschedprio.3:118 build/C/man3/pthread_sigmask.3:169 build/C/man3/pthread_sigqueue.3:117 build/C/man3/pthread_testcancel.3:81 build/C/man3/pthread_tryjoin_np.3:156 build/C/man3/pthread_yield.3:79 build/C/man7/pthreads.7:935
273 "This page is part of release 3.78 of the Linux I<man-pages> project. A "
274 "description of the project, information about reporting bugs, and the latest "
275 "version of this page, can be found at "
276 "\\%http://www.kernel.org/doc/man-pages/."
280 #: build/C/man3/makecontext.3:28
286 #: build/C/man3/makecontext.3:28 build/C/man3/pthread_attr_setaffinity_np.3:26 build/C/man3/pthread_attr_setdetachstate.3:26 build/C/man3/pthread_attr_setguardsize.3:26 build/C/man3/pthread_attr_setscope.3:26 build/C/man3/pthread_attr_setstack.3:26 build/C/man3/pthread_attr_setstackaddr.3:26 build/C/man3/pthread_attr_setstacksize.3:26 build/C/man3/pthread_cleanup_push_defer_np.3:26 build/C/man3/pthread_create.3:26 build/C/man3/pthread_setname_np.3:26 build/C/man3/pthread_setschedprio.3:26 build/C/man3/pthread_sigqueue.3:25
292 #: build/C/man3/makecontext.3:28
298 #: build/C/man3/makecontext.3:31
299 msgid "makecontext, swapcontext - manipulate user context"
303 #: build/C/man3/makecontext.3:36
305 "B<void makecontext(ucontext_t *>I<ucp>B<, void (*>I<func>B<)(),> B<int "
310 #: build/C/man3/makecontext.3:38
311 msgid "B<int swapcontext(ucontext_t *>I<oucp>B<, const ucontext_t *>I<ucp>B<);>"
315 #: build/C/man3/makecontext.3:49
317 "In a System V-like environment, one has the type I<ucontext_t> defined in "
318 "I<E<lt>ucontext.hE<gt>> and the four functions B<getcontext>(3), "
319 "B<setcontext>(3), B<makecontext>() and B<swapcontext>() that allow "
320 "user-level context switching between multiple threads of control within a "
325 #: build/C/man3/makecontext.3:52
326 msgid "For the type and the first two functions, see B<getcontext>(3)."
330 #: build/C/man3/makecontext.3:64
332 "The B<makecontext>() function modifies the context pointed to by I<ucp> "
333 "(which was obtained from a call to B<getcontext>(3)). Before invoking "
334 "B<makecontext>(), the caller must allocate a new stack for this context and "
335 "assign its address to I<ucp-E<gt>uc_stack>, and define a successor context "
336 "and assign its address to I<ucp-E<gt>uc_link>."
340 #: build/C/man3/makecontext.3:78
342 "When this context is later activated (using B<setcontext>(3) or "
343 "B<swapcontext>()) the function I<func> is called, and passed the series of "
344 "integer (I<int>) arguments that follow I<argc>; the caller must specify the "
345 "number of these arguments in I<argc>. When this function returns, the "
346 "successor context is activated. If the successor context pointer is NULL, "
351 #: build/C/man3/makecontext.3:84
353 "The B<swapcontext>() function saves the current context in the structure "
354 "pointed to by I<oucp>, and then activates the context pointed to by I<ucp>."
358 #: build/C/man3/makecontext.3:96
360 "When successful, B<swapcontext>() does not return. (But we may return "
361 "later, in case I<oucp> is activated, in which case it looks like "
362 "B<swapcontext>() returns 0.) On error, B<swapcontext>() returns -1 and "
363 "sets I<errno> appropriately."
367 #: build/C/man3/makecontext.3:97 build/C/man3/pthread_attr_setaffinity_np.3:102 build/C/man3/pthread_getattr_np.3:77
373 #: build/C/man3/makecontext.3:100
374 msgid "Insufficient stack space left."
378 #: build/C/man3/makecontext.3:100 build/C/man3/pthread_attr_setaffinity_np.3:106 build/C/man3/pthread_attr_setguardsize.3:104 build/C/man3/pthread_attr_setstack.3:110 build/C/man3/pthread_attr_setstackaddr.3:81 build/C/man3/pthread_attr_setstacksize.3:81 build/C/man3/pthread_getattr_np.3:96 build/C/man3/pthread_getcpuclockid.3:63 build/C/man3/pthread_rwlockattr_setkind_np.3:121 build/C/man3/pthread_setaffinity_np.3:119 build/C/man3/pthread_setconcurrency.3:81 build/C/man3/pthread_setname_np.3:100 build/C/man3/pthread_setschedprio.3:81 build/C/man3/pthread_sigqueue.3:90 build/C/man3/pthread_tryjoin_np.3:118
384 #: build/C/man3/makecontext.3:105
386 "B<makecontext>() and B<swapcontext>() are provided in glibc since version "
391 #: build/C/man3/makecontext.3:112
392 msgid "The B<makecontext>() and B<swapcontext>() functions are thread-safe."
396 #: build/C/man3/makecontext.3:120
398 "SUSv2, POSIX.1-2001. POSIX.1-2008 removes the specifications of "
399 "B<makecontext>() and B<swapcontext>(), citing portability issues, and "
400 "recommending that applications be rewritten to use POSIX threads instead."
404 #: build/C/man3/makecontext.3:128
406 "The interpretation of I<ucp-E<gt>uc_stack> is just as in B<sigaltstack>(2), "
407 "namely, this struct contains the start and length of a memory area to be "
408 "used as the stack, regardless of the direction of growth of the stack. "
409 "Thus, it is not necessary for the user program to worry about this "
414 #: build/C/man3/makecontext.3:144
416 "On architectures where I<int> and pointer types are the same size (e.g., "
417 "x86-32, where both types are 32 bits), you may be able to get away with "
418 "passing pointers as arguments to B<makecontext>() following I<argc>. "
419 "However, doing this is not guaranteed to be portable, is undefined according "
420 "to the standards, and won't work on architectures where pointers are larger "
421 "than I<int>s. Nevertheless, starting with version 2.8, glibc makes some "
422 "changes to B<makecontext>(), to permit this on some 64-bit architectures "
427 #: build/C/man3/makecontext.3:144 build/C/man3/pthread_attr_init.3:87 build/C/man3/pthread_attr_setdetachstate.3:115 build/C/man3/pthread_attr_setguardsize.3:162 build/C/man3/pthread_attr_setinheritsched.3:135 build/C/man3/pthread_attr_setschedparam.3:113 build/C/man3/pthread_attr_setschedpolicy.3:109 build/C/man3/pthread_attr_setstack.3:159 build/C/man3/pthread_attr_setstacksize.3:115 build/C/man3/pthread_cancel.3:135 build/C/man3/pthread_cleanup_push.3:155 build/C/man3/pthread_create.3:209 build/C/man3/pthread_detach.3:93 build/C/man3/pthread_getattr_np.3:101 build/C/man3/pthread_getcpuclockid.3:83 build/C/man3/pthread_join.3:124 build/C/man3/pthread_setaffinity_np.3:161 build/C/man3/pthread_setcancelstate.3:183 build/C/man3/pthread_setname_np.3:114 build/C/man3/pthread_setschedparam.3:156 build/C/man3/pthread_sigmask.3:78 build/C/man3/pthread_testcancel.3:65 build/C/man3/pthread_tryjoin_np.3:123
433 #: build/C/man3/makecontext.3:152
435 "The example program below demonstrates the use of B<getcontext>(3), "
436 "B<makecontext>(), and B<swapcontext>(). Running the program produces the "
441 #: build/C/man3/makecontext.3:164
445 "main: swapcontext(&uctx_main, &uctx_func2)\n"
447 "func2: swapcontext(&uctx_func2, &uctx_func1)\n"
449 "func1: swapcontext(&uctx_func1, &uctx_func2)\n"
456 #: build/C/man3/makecontext.3:166 build/C/man3/pthread_attr_init.3:148 build/C/man3/pthread_cancel.3:151 build/C/man3/pthread_cleanup_push.3:231 build/C/man3/pthread_create.3:248 build/C/man3/pthread_getattr_np.3:179 build/C/man3/pthread_getcpuclockid.3:101 build/C/man3/pthread_setname_np.3:140 build/C/man3/pthread_setschedparam.3:231 build/C/man3/pthread_sigmask.3:96
458 msgid "Program source"
462 #: build/C/man3/makecontext.3:172
465 "#include E<lt>ucontext.hE<gt>\n"
466 "#include E<lt>stdio.hE<gt>\n"
467 "#include E<lt>stdlib.hE<gt>\n"
471 #: build/C/man3/makecontext.3:174
473 msgid "static ucontext_t uctx_main, uctx_func1, uctx_func2;\n"
477 #: build/C/man3/makecontext.3:177
480 "#define handle_error(msg) \\e\n"
481 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
485 #: build/C/man3/makecontext.3:187
491 " printf(\"func1: started\\en\");\n"
492 " printf(\"func1: swapcontext(&uctx_func1, &uctx_func2)\\en\");\n"
493 " if (swapcontext(&uctx_func1, &uctx_func2) == -1)\n"
494 " handle_error(\"swapcontext\");\n"
495 " printf(\"func1: returning\\en\");\n"
500 #: build/C/man3/makecontext.3:197
506 " printf(\"func2: started\\en\");\n"
507 " printf(\"func2: swapcontext(&uctx_func2, &uctx_func1)\\en\");\n"
508 " if (swapcontext(&uctx_func2, &uctx_func1) == -1)\n"
509 " handle_error(\"swapcontext\");\n"
510 " printf(\"func2: returning\\en\");\n"
515 #: build/C/man3/makecontext.3:203
519 "main(int argc, char *argv[])\n"
521 " char func1_stack[16384];\n"
522 " char func2_stack[16384];\n"
526 #: build/C/man3/makecontext.3:210
529 " if (getcontext(&uctx_func1) == -1)\n"
530 " handle_error(\"getcontext\");\n"
531 " uctx_func1.uc_stack.ss_sp = func1_stack;\n"
532 " uctx_func1.uc_stack.ss_size = sizeof(func1_stack);\n"
533 " uctx_func1.uc_link = &uctx_main;\n"
534 " makecontext(&uctx_func1, func1, 0);\n"
538 #: build/C/man3/makecontext.3:218
541 " if (getcontext(&uctx_func2) == -1)\n"
542 " handle_error(\"getcontext\");\n"
543 " uctx_func2.uc_stack.ss_sp = func2_stack;\n"
544 " uctx_func2.uc_stack.ss_size = sizeof(func2_stack);\n"
545 " /* Successor context is f1(), unless argc E<gt> 1 */\n"
546 " uctx_func2.uc_link = (argc E<gt> 1) ? NULL : &uctx_func1;\n"
547 " makecontext(&uctx_func2, func2, 0);\n"
551 #: build/C/man3/makecontext.3:222
554 " printf(\"main: swapcontext(&uctx_main, &uctx_func2)\\en\");\n"
555 " if (swapcontext(&uctx_main, &uctx_func2) == -1)\n"
556 " handle_error(\"swapcontext\");\n"
560 #: build/C/man3/makecontext.3:226
563 " printf(\"main: exiting\\en\");\n"
564 " exit(EXIT_SUCCESS);\n"
569 #: build/C/man3/makecontext.3:233
571 "B<sigaction>(2), B<sigaltstack>(2), B<sigprocmask>(2), B<getcontext>(3), "
576 #: build/C/man3/pthread_attr_init.3:26
578 msgid "PTHREAD_ATTR_INIT"
582 #: build/C/man3/pthread_attr_init.3:26
588 #: build/C/man3/pthread_attr_init.3:30
590 "pthread_attr_init, pthread_attr_destroy - initialize and destroy thread "
595 #: build/C/man3/pthread_attr_init.3:33 build/C/man3/pthread_attr_setdetachstate.3:33 build/C/man3/pthread_attr_setguardsize.3:33 build/C/man3/pthread_attr_setinheritsched.3:33 build/C/man3/pthread_attr_setschedparam.3:33 build/C/man3/pthread_attr_setschedpolicy.3:33 build/C/man3/pthread_attr_setscope.3:33 build/C/man3/pthread_attr_setstack.3:33 build/C/man3/pthread_attr_setstackaddr.3:33 build/C/man3/pthread_attr_setstacksize.3:33 build/C/man3/pthread_cancel.3:32 build/C/man3/pthread_cleanup_push.3:33 build/C/man3/pthread_cleanup_push_defer_np.3:33 build/C/man3/pthread_create.3:32 build/C/man3/pthread_detach.3:32 build/C/man3/pthread_equal.3:32 build/C/man3/pthread_exit.3:32 build/C/man3/pthread_join.3:32 build/C/man3/pthread_kill_other_threads_np.3:32 build/C/man3/pthread_rwlockattr_setkind_np.3:32 build/C/man3/pthread_self.3:32 build/C/man3/pthread_setcancelstate.3:33 build/C/man3/pthread_setconcurrency.3:32 build/C/man3/pthread_setschedparam.3:33 build/C/man3/pthread_setschedprio.3:32 build/C/man3/pthread_testcancel.3:32
597 msgid "B<#include E<lt>pthread.hE<gt>>\n"
601 #: build/C/man3/pthread_attr_init.3:36
604 "B<int pthread_attr_init(pthread_attr_t *>I<attr>B<);>\n"
605 "B<int pthread_attr_destroy(pthread_attr_t *>I<attr>B<);>\n"
609 #: build/C/man3/pthread_attr_init.3:38 build/C/man3/pthread_attr_setaffinity_np.3:41 build/C/man3/pthread_attr_setdetachstate.3:40 build/C/man3/pthread_attr_setguardsize.3:40 build/C/man3/pthread_attr_setinheritsched.3:40 build/C/man3/pthread_attr_setschedparam.3:40 build/C/man3/pthread_attr_setschedpolicy.3:40 build/C/man3/pthread_attr_setscope.3:40 build/C/man3/pthread_attr_setstack.3:40 build/C/man3/pthread_attr_setstackaddr.3:40 build/C/man3/pthread_attr_setstacksize.3:40 build/C/man3/pthread_cancel.3:36 build/C/man3/pthread_cleanup_push.3:39 build/C/man3/pthread_equal.3:36 build/C/man3/pthread_exit.3:36 build/C/man3/pthread_getattr_np.3:37 build/C/man3/pthread_getcpuclockid.3:37 build/C/man3/pthread_rwlockattr_setkind_np.3:39 build/C/man3/pthread_self.3:36 build/C/man3/pthread_setaffinity_np.3:41 build/C/man3/pthread_setcancelstate.3:38 build/C/man3/pthread_setconcurrency.3:37 build/C/man3/pthread_setschedparam.3:40 build/C/man3/pthread_setschedprio.3:36 build/C/man3/pthread_testcancel.3:36
611 msgid "Compile and link with I<-pthread>.\n"
615 #: build/C/man3/pthread_attr_init.3:50
617 "The B<pthread_attr_init>() function initializes the thread attributes "
618 "object pointed to by I<attr> with default attribute values. After this "
619 "call, individual attributes of the object can be set using various related "
620 "functions (listed under SEE ALSO), and then the object can be used in one or "
621 "more B<pthread_create>(3) calls that create threads."
625 #: build/C/man3/pthread_attr_init.3:55
627 "Calling B<pthread_attr_init>() on a thread attributes object that has "
628 "already been initialized results in undefined behavior."
632 #: build/C/man3/pthread_attr_init.3:62
634 "When a thread attributes object is no longer required, it should be "
635 "destroyed using the B<pthread_attr_destroy>() function. Destroying a "
636 "thread attributes object has no effect on threads that were created using "
641 #: build/C/man3/pthread_attr_init.3:68
643 "Once a thread attributes object has been destroyed, it can be reinitialized "
644 "using B<pthread_attr_init>(). Any other use of a destroyed thread "
645 "attributes object has undefined results."
649 #: build/C/man3/pthread_attr_init.3:71 build/C/man3/pthread_attr_setaffinity_np.3:79 build/C/man3/pthread_attr_setdetachstate.3:80 build/C/man3/pthread_attr_setguardsize.3:93 build/C/man3/pthread_attr_setinheritsched.3:96 build/C/man3/pthread_attr_setschedparam.3:88 build/C/man3/pthread_attr_setschedpolicy.3:86 build/C/man3/pthread_attr_setscope.3:106 build/C/man3/pthread_attr_setstack.3:88 build/C/man3/pthread_attr_setstackaddr.3:77 build/C/man3/pthread_attr_setstacksize.3:64 build/C/man3/pthread_setaffinity_np.3:80 build/C/man3/pthread_setcancelstate.3:95 build/C/man3/pthread_setname_np.3:75
651 "On success, these functions return 0; on error, they return a nonzero error "
656 #: build/C/man3/pthread_attr_init.3:79
658 "POSIX.1-2001 documents an B<ENOMEM> error for B<pthread_attr_init>(); on "
659 "Linux these functions always succeed (but portable and future-proof "
660 "applications should nevertheless handle a possible error return)."
664 #: build/C/man3/pthread_attr_init.3:81 build/C/man3/pthread_attr_setdetachstate.3:96 build/C/man3/pthread_attr_setguardsize.3:115 build/C/man3/pthread_attr_setinheritsched.3:119 build/C/man3/pthread_attr_setschedparam.3:109 build/C/man3/pthread_attr_setschedpolicy.3:109 build/C/man3/pthread_attr_setscope.3:128 build/C/man3/pthread_attr_setstack.3:121 build/C/man3/pthread_attr_setstacksize.3:92 build/C/man3/pthread_cancel.3:127 build/C/man3/pthread_cleanup_push.3:129 build/C/man3/pthread_create.3:155 build/C/man3/pthread_detach.3:66 build/C/man3/pthread_equal.3:54 build/C/man3/pthread_exit.3:82 build/C/man3/pthread_getcpuclockid.3:72 build/C/man3/pthread_join.3:100 build/C/man3/pthread_self.3:57 build/C/man3/pthread_setcancelstate.3:122 build/C/man3/pthread_setconcurrency.3:92 build/C/man3/pthread_setschedparam.3:150 build/C/man3/pthread_setschedprio.3:90 build/C/man3/pthread_sigmask.3:76 build/C/man3/pthread_testcancel.3:65
665 msgid "POSIX.1-2001."
669 #: build/C/man3/pthread_attr_init.3:87
671 "The I<pthread_attr_t> type should be treated as opaque: any access to the "
672 "object other than via pthreads functions is nonportable and produces "
677 #: build/C/man3/pthread_attr_init.3:96
679 "The program below optionally makes use of B<pthread_attr_init>() and "
680 "various related functions to initialize a thread attributes object that is "
681 "used to create a single thread. Once created, the thread uses the "
682 "B<pthread_getattr_np>(3) function (a nonstandard GNU extension) to retrieve "
683 "the thread's attributes, and then displays those attributes."
687 #: build/C/man3/pthread_attr_init.3:105
689 "If the program is run with no command-line argument, then it passes NULL as "
690 "the I<attr> argument of B<pthread_create>(3), so that the thread is created "
691 "with default attributes. Running the program on Linux/x86-32 with the NPTL "
692 "threading implementation, we see the following:"
695 #. Results from glibc 2.8, SUSE 11.0; Oct 2008
697 #: build/C/man3/pthread_attr_init.3:121
700 "$B< ulimit -s> # No stack limit ==E<gt> default stack size is 2MB\n"
703 "Thread attributes:\n"
704 " Detach state = PTHREAD_CREATE_JOINABLE\n"
705 " Scope = PTHREAD_SCOPE_SYSTEM\n"
706 " Inherit scheduler = PTHREAD_INHERIT_SCHED\n"
707 " Scheduling policy = SCHED_OTHER\n"
708 " Scheduling priority = 0\n"
709 " Guard size = 4096 bytes\n"
710 " Stack address = 0x40196000\n"
711 " Stack size = 0x201000 bytes\n"
715 #: build/C/man3/pthread_attr_init.3:131
717 "When we supply a stack size as a command-line argument, the program "
718 "initializes a thread attributes object, sets various attributes in that "
719 "object, and passes a pointer to the object in the call to "
720 "B<pthread_create>(3). Running the program on Linux/x86-32 with the NPTL "
721 "threading implementation, we see the following:"
724 #. Results from glibc 2.8, SUSE 11.0; Oct 2008
726 #: build/C/man3/pthread_attr_init.3:146
729 "$B< ./a.out 0x3000000>\n"
730 "posix_memalign() allocated at 0x40197000\n"
731 "Thread attributes:\n"
732 " Detach state = PTHREAD_CREATE_DETACHED\n"
733 " Scope = PTHREAD_SCOPE_SYSTEM\n"
734 " Inherit scheduler = PTHREAD_EXPLICIT_SCHED\n"
735 " Scheduling policy = SCHED_OTHER\n"
736 " Scheduling priority = 0\n"
737 " Guard size = 0 bytes\n"
738 " Stack address = 0x40197000\n"
739 " Stack size = 0x3000000 bytes\n"
743 #: build/C/man3/pthread_attr_init.3:157 build/C/man3/pthread_getattr_np.3:188
746 "#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */\n"
747 "#include E<lt>pthread.hE<gt>\n"
748 "#include E<lt>stdio.hE<gt>\n"
749 "#include E<lt>stdlib.hE<gt>\n"
750 "#include E<lt>unistd.hE<gt>\n"
751 "#include E<lt>errno.hE<gt>\n"
755 #: build/C/man3/pthread_attr_init.3:160 build/C/man3/pthread_cancel.3:162 build/C/man3/pthread_cleanup_push.3:243 build/C/man3/pthread_create.3:261 build/C/man3/pthread_getattr_np.3:191 build/C/man3/pthread_getcpuclockid.3:119 build/C/man3/pthread_setaffinity_np.3:179 build/C/man3/pthread_setschedparam.3:244 build/C/man3/pthread_sigmask.3:110
758 "#define handle_error_en(en, msg) \\e\n"
759 " do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)\n"
763 #: build/C/man3/pthread_attr_init.3:168
767 "display_pthread_attr(pthread_attr_t *attr, char *prefix)\n"
772 " struct sched_param sp;\n"
776 #: build/C/man3/pthread_attr_init.3:176
779 " s = pthread_attr_getdetachstate(attr, &i);\n"
781 " handle_error_en(s, \"pthread_attr_getdetachstate\");\n"
782 " printf(\"%sDetach state = %s\\en\", prefix,\n"
783 " (i == PTHREAD_CREATE_DETACHED) ? \"PTHREAD_CREATE_DETACHED\" :\n"
784 " (i == PTHREAD_CREATE_JOINABLE) ? \"PTHREAD_CREATE_JOINABLE\" :\n"
789 #: build/C/man3/pthread_attr_init.3:184
792 " s = pthread_attr_getscope(attr, &i);\n"
794 " handle_error_en(s, \"pthread_attr_getscope\");\n"
795 " printf(\"%sScope = %s\\en\", prefix,\n"
796 " (i == PTHREAD_SCOPE_SYSTEM) ? \"PTHREAD_SCOPE_SYSTEM\" :\n"
797 " (i == PTHREAD_SCOPE_PROCESS) ? \"PTHREAD_SCOPE_PROCESS\" :\n"
802 #: build/C/man3/pthread_attr_init.3:192
805 " s = pthread_attr_getinheritsched(attr, &i);\n"
807 " handle_error_en(s, \"pthread_attr_getinheritsched\");\n"
808 " printf(\"%sInherit scheduler = %s\\en\", prefix,\n"
809 " (i == PTHREAD_INHERIT_SCHED) ? \"PTHREAD_INHERIT_SCHED\" :\n"
810 " (i == PTHREAD_EXPLICIT_SCHED) ? \"PTHREAD_EXPLICIT_SCHED\" :\n"
815 #: build/C/man3/pthread_attr_init.3:201
818 " s = pthread_attr_getschedpolicy(attr, &i);\n"
820 " handle_error_en(s, \"pthread_attr_getschedpolicy\");\n"
821 " printf(\"%sScheduling policy = %s\\en\", prefix,\n"
822 " (i == SCHED_OTHER) ? \"SCHED_OTHER\" :\n"
823 " (i == SCHED_FIFO) ? \"SCHED_FIFO\" :\n"
824 " (i == SCHED_RR) ? \"SCHED_RR\" :\n"
829 #: build/C/man3/pthread_attr_init.3:206
832 " s = pthread_attr_getschedparam(attr, &sp);\n"
834 " handle_error_en(s, \"pthread_attr_getschedparam\");\n"
835 " printf(\"%sScheduling priority = %d\\en\", prefix, sp.sched_priority);\n"
839 #: build/C/man3/pthread_attr_init.3:211
842 " s = pthread_attr_getguardsize(attr, &v);\n"
844 " handle_error_en(s, \"pthread_attr_getguardsize\");\n"
845 " printf(\"%sGuard size = %d bytes\\en\", prefix, v);\n"
849 #: build/C/man3/pthread_attr_init.3:218
852 " s = pthread_attr_getstack(attr, &stkaddr, &v);\n"
854 " handle_error_en(s, \"pthread_attr_getstack\");\n"
855 " printf(\"%sStack address = %p\\en\", prefix, stkaddr);\n"
856 " printf(\"%sStack size = 0x%x bytes\\en\", prefix, v);\n"
861 #: build/C/man3/pthread_attr_init.3:224
865 "thread_start(void *arg)\n"
868 " pthread_attr_t gattr;\n"
872 #: build/C/man3/pthread_attr_init.3:228
875 " /* pthread_getattr_np() is a non-standard GNU extension that\n"
876 " retrieves the attributes of the thread specified in its\n"
877 " first argument */\n"
881 #: build/C/man3/pthread_attr_init.3:232
884 " s = pthread_getattr_np(pthread_self(), &gattr);\n"
886 " handle_error_en(s, \"pthread_getattr_np\");\n"
890 #: build/C/man3/pthread_attr_init.3:235
893 " printf(\"Thread attributes:\\en\");\n"
894 " display_pthread_attr(&gattr, \"\\et\");\n"
898 #: build/C/man3/pthread_attr_init.3:238 build/C/man3/pthread_getattr_np.3:240
901 " exit(EXIT_SUCCESS); /* Terminate all threads */\n"
906 #: build/C/man3/pthread_attr_init.3:246
910 "main(int argc, char *argv[])\n"
913 " pthread_attr_t attr;\n"
914 " pthread_attr_t *attrp; /* NULL or &attr */\n"
919 #: build/C/man3/pthread_attr_init.3:248 build/C/man3/pthread_setschedparam.3:362
921 msgid " attrp = NULL;\n"
925 #: build/C/man3/pthread_attr_init.3:252
928 " /* If a command-line argument was supplied, use it to set the\n"
929 " stack-size attribute and set a few other thread attributes,\n"
930 " and set attrp pointing to thread attributes object */\n"
934 #: build/C/man3/pthread_attr_init.3:256
937 " if (argc E<gt> 1) {\n"
943 #: build/C/man3/pthread_attr_init.3:258
945 msgid " attrp = &attr;\n"
949 #: build/C/man3/pthread_attr_init.3:262
952 " s = pthread_attr_init(&attr);\n"
954 " handle_error_en(s, \"pthread_attr_init\");\n"
958 #: build/C/man3/pthread_attr_init.3:266
961 " s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);\n"
963 " handle_error_en(s, \"pthread_attr_setdetachstate\");\n"
967 #: build/C/man3/pthread_attr_init.3:270
970 " s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);\n"
972 " handle_error_en(s, \"pthread_attr_setinheritsched\");\n"
976 #: build/C/man3/pthread_attr_init.3:272
978 msgid " stack_size = strtoul(argv[1], NULL, 0);\n"
982 #: build/C/man3/pthread_attr_init.3:276
985 " s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);\n"
987 " handle_error_en(s, \"posix_memalign\");\n"
991 #: build/C/man3/pthread_attr_init.3:278
993 msgid " printf(\"posix_memalign() allocated at %p\\en\", sp);\n"
997 #: build/C/man3/pthread_attr_init.3:283
1000 " s = pthread_attr_setstack(&attr, sp, stack_size);\n"
1002 " handle_error_en(s, \"pthread_attr_setstack\");\n"
1007 #: build/C/man3/pthread_attr_init.3:287 build/C/man3/pthread_getattr_np.3:335
1010 " s = pthread_create(&thr, attrp, &thread_start, NULL);\n"
1012 " handle_error_en(s, \"pthread_create\");\n"
1016 #: build/C/man3/pthread_attr_init.3:293 build/C/man3/pthread_getattr_np.3:341
1019 " if (attrp != NULL) {\n"
1020 " s = pthread_attr_destroy(attrp);\n"
1022 " handle_error_en(s, \"pthread_attr_destroy\");\n"
1027 #: build/C/man3/pthread_attr_init.3:296 build/C/man3/pthread_getattr_np.3:344
1030 " pause(); /* Terminates when other thread calls exit() */\n"
1035 #: build/C/man3/pthread_attr_init.3:313
1037 "B<pthread_attr_setaffinity_np>(3), B<pthread_attr_setdetachstate>(3), "
1038 "B<pthread_attr_setguardsize>(3), B<pthread_attr_setinheritsched>(3), "
1039 "B<pthread_attr_setschedparam>(3), B<pthread_attr_setschedpolicy>(3), "
1040 "B<pthread_attr_setscope>(3), B<pthread_attr_setstack>(3), "
1041 "B<pthread_attr_setstackaddr>(3), B<pthread_attr_setstacksize>(3), "
1042 "B<pthread_create>(3), B<pthread_getattr_np>(3), B<pthreads>(7)"
1046 #: build/C/man3/pthread_attr_setaffinity_np.3:26
1048 msgid "PTHREAD_ATTR_SETAFFINITY_NP"
1052 #: build/C/man3/pthread_attr_setaffinity_np.3:30
1054 "pthread_attr_setaffinity_np, pthread_attr_getaffinity_np - set/get CPU "
1055 "affinity attribute in thread attributes object"
1059 #: build/C/man3/pthread_attr_setaffinity_np.3:34 build/C/man3/pthread_getattr_np.3:33 build/C/man3/pthread_setaffinity_np.3:34 build/C/man3/pthread_tryjoin_np.3:34 build/C/man3/pthread_yield.3:32
1062 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
1063 "B<#include E<lt>pthread.hE<gt>>\n"
1067 #: build/C/man3/pthread_attr_setaffinity_np.3:39
1070 "B<int pthread_attr_setaffinity_np(pthread_attr_t *>I<attr>B<,>\n"
1071 "B< size_t >I<cpusetsize>B<, const cpu_set_t "
1072 "*>I<cpuset>B<);>\n"
1073 "B<int pthread_attr_getaffinity_np(const pthread_attr_t *>I<attr>B<,>\n"
1074 "B< size_t >I<cpusetsize>B<, cpu_set_t *>I<cpuset>B<);>\n"
1078 #: build/C/man3/pthread_attr_setaffinity_np.3:54
1080 "The B<pthread_attr_setaffinity_np>() function sets the CPU affinity mask "
1081 "attribute of the thread attributes object referred to by I<attr> to the "
1082 "value specified in I<cpuset>. This attribute determines the CPU affinity "
1083 "mask of a thread created using the thread attributes object I<attr>."
1087 #: build/C/man3/pthread_attr_setaffinity_np.3:63
1089 "The B<pthread_attr_getaffinity_np>() function returns the CPU affinity mask "
1090 "attribute of the thread attributes object referred to by I<attr> in the "
1091 "buffer pointed to by I<cpuset>."
1095 #: build/C/man3/pthread_attr_setaffinity_np.3:70
1097 "The argument I<cpusetsize> is the length (in bytes) of the buffer pointed to "
1098 "by I<cpuset>. Typically, this argument would be specified as "
1099 "I<sizeof(cpu_set_t)>."
1103 #: build/C/man3/pthread_attr_setaffinity_np.3:76 build/C/man3/pthread_setaffinity_np.3:67
1105 "For more details on CPU affinity masks, see B<sched_setaffinity>(2). For a "
1106 "description of a set of macros that can be used to manipulate and inspect "
1107 "CPU sets, see B<CPU_SET>(3)."
1111 #: build/C/man3/pthread_attr_setaffinity_np.3:80 build/C/man3/pthread_attr_setaffinity_np.3:92 build/C/man3/pthread_attr_setdetachstate.3:83 build/C/man3/pthread_attr_setinheritsched.3:99 build/C/man3/pthread_attr_setschedpolicy.3:89 build/C/man3/pthread_attr_setscope.3:109 build/C/man3/pthread_attr_setstack.3:91 build/C/man3/pthread_attr_setstacksize.3:67 build/C/man3/pthread_create.3:144 build/C/man3/pthread_detach.3:55 build/C/man3/pthread_join.3:85 build/C/man3/pthread_join.3:89 build/C/man3/pthread_kill.3:69 build/C/man3/pthread_rwlockattr_setkind_np.3:105 build/C/man3/pthread_setaffinity_np.3:84 build/C/man3/pthread_setaffinity_np.3:93 build/C/man3/pthread_setaffinity_np.3:109 build/C/man3/pthread_setcancelstate.3:99 build/C/man3/pthread_setcancelstate.3:107 build/C/man3/pthread_setconcurrency.3:71 build/C/man3/pthread_setschedparam.3:122 build/C/man3/pthread_setschedprio.3:62 build/C/man3/pthread_sigqueue.3:78 build/C/man3/pthread_tryjoin_np.3:106
1117 #. The raw sched_getaffinity() system call returns the size (in bytes)
1118 #. of the cpumask_t type.
1120 #: build/C/man3/pthread_attr_setaffinity_np.3:92
1122 "(B<pthread_attr_setaffinity_np>()) I<cpuset> specified a CPU that was "
1123 "outside the set supported by the kernel. (The kernel configuration option "
1124 "B<CONFIG_NR_CPUS> defines the range of the set supported by the kernel data "
1125 "type used to represent CPU sets.)"
1129 #: build/C/man3/pthread_attr_setaffinity_np.3:102
1131 "(B<pthread_attr_getaffinity_np>()) A CPU in the affinity mask of the thread "
1132 "attributes object referred to by I<attr> lies outside the range specified by "
1133 "I<cpusetsize> (i.e., I<cpuset>/I<cpusetsize> is too small)."
1137 #: build/C/man3/pthread_attr_setaffinity_np.3:106
1138 msgid "(B<pthread_attr_setaffinity_np>()) Could not allocate memory."
1142 #: build/C/man3/pthread_attr_setaffinity_np.3:108 build/C/man3/pthread_setaffinity_np.3:121
1143 msgid "These functions are provided by glibc since version 2.3.4."
1147 #: build/C/man3/pthread_attr_setaffinity_np.3:111 build/C/man3/pthread_cleanup_push_defer_np.3:117 build/C/man3/pthread_setaffinity_np.3:131 build/C/man3/pthread_tryjoin_np.3:123
1149 "These functions are nonstandard GNU extensions; hence the suffix \"_np\" "
1150 "(nonportable) in the names."
1154 #: build/C/man3/pthread_attr_setaffinity_np.3:118 build/C/man3/pthread_setaffinity_np.3:157
1156 "In glibc 2.3.3 only, versions of these functions were provided that did not "
1157 "have a I<cpusetsize> argument. Instead the CPU set size given to the "
1158 "underlying system calls was always I<sizeof(cpu_set_t)>."
1162 #: build/C/man3/pthread_attr_setaffinity_np.3:124
1164 "B<sched_setaffinity>(2), B<pthread_attr_init>(3), "
1165 "B<pthread_setaffinity_np>(3), B<cpuset>(7), B<pthreads>(7)"
1169 #: build/C/man3/pthread_attr_setdetachstate.3:26
1171 msgid "PTHREAD_ATTR_SETDETACHSTATE"
1175 #: build/C/man3/pthread_attr_setdetachstate.3:30
1177 "pthread_attr_setdetachstate, pthread_attr_getdetachstate - set/get detach "
1178 "state attribute in thread attributes object"
1182 #: build/C/man3/pthread_attr_setdetachstate.3:38
1185 "B<int pthread_attr_setdetachstate(pthread_attr_t *>I<attr>B<, int "
1186 ">I<detachstate>B<);>\n"
1187 "B<int pthread_attr_getdetachstate(const pthread_attr_t *>I<attr>B<, int "
1188 "*>I<detachstate>B<);>\n"
1192 #: build/C/man3/pthread_attr_setdetachstate.3:53
1194 "The B<pthread_attr_setdetachstate>() function sets the detach state "
1195 "attribute of the thread attributes object referred to by I<attr> to the "
1196 "value specified in I<detachstate>. The detach state attribute determines "
1197 "whether a thread created using the thread attributes object I<attr> will be "
1198 "created in a joinable or a detached state."
1202 #: build/C/man3/pthread_attr_setdetachstate.3:56
1203 msgid "The following values may be specified in I<detachstate>:"
1207 #: build/C/man3/pthread_attr_setdetachstate.3:56
1209 msgid "B<PTHREAD_CREATE_DETACHED>"
1213 #: build/C/man3/pthread_attr_setdetachstate.3:61
1214 msgid "Threads that are created using I<attr> will be created in a detached state."
1218 #: build/C/man3/pthread_attr_setdetachstate.3:61
1220 msgid "B<PTHREAD_CREATE_JOINABLE>"
1224 #: build/C/man3/pthread_attr_setdetachstate.3:66
1225 msgid "Threads that are created using I<attr> will be created in a joinable state."
1229 #: build/C/man3/pthread_attr_setdetachstate.3:70
1231 "The default setting of the detach state attribute in a newly initialized "
1232 "thread attributes object is B<PTHREAD_CREATE_JOINABLE>."
1236 #: build/C/man3/pthread_attr_setdetachstate.3:77
1238 "The B<pthread_attr_getdetachstate>() returns the detach state attribute of "
1239 "the thread attributes object I<attr> in the buffer pointed to by "
1244 #: build/C/man3/pthread_attr_setdetachstate.3:83
1245 msgid "B<pthread_attr_setdetachstate>() can fail with the following error:"
1249 #: build/C/man3/pthread_attr_setdetachstate.3:87
1250 msgid "An invalid value was specified in I<detachstate>."
1254 #: build/C/man3/pthread_attr_setdetachstate.3:94
1256 "The B<pthread_attr_setdetachstate>() and B<pthread_attr_getdetachstate>() "
1257 "functions are thread-safe."
1261 #: build/C/man3/pthread_attr_setdetachstate.3:100
1262 msgid "See B<pthread_create>(3) for more details on detached and joinable threads."
1266 #: build/C/man3/pthread_attr_setdetachstate.3:108
1268 "A thread that is created in a joinable state should eventually either be "
1269 "joined using B<pthread_join>(3) or detached using B<pthread_detach>(3); see "
1270 "B<pthread_create>(3)."
1274 #: build/C/man3/pthread_attr_setdetachstate.3:115
1276 "It is an error to specify the thread ID of a thread that was created in a "
1277 "detached state in a later call to B<pthread_detach>(3) or "
1278 "B<pthread_join>(3)."
1282 #: build/C/man3/pthread_attr_setdetachstate.3:118 build/C/man3/pthread_attr_setstack.3:162
1283 msgid "See B<pthread_attr_init>(3)."
1287 #: build/C/man3/pthread_attr_setdetachstate.3:124
1289 "B<pthread_attr_init>(3), B<pthread_create>(3), B<pthread_detach>(3), "
1290 "B<pthread_join>(3), B<pthreads>(7)"
1294 #: build/C/man3/pthread_attr_setguardsize.3:26
1296 msgid "PTHREAD_ATTR_SETGUARDSIZE"
1300 #: build/C/man3/pthread_attr_setguardsize.3:30
1302 "pthread_attr_setguardsize, pthread_attr_getguardsize - set/get guard size "
1303 "attribute in thread attributes object"
1307 #: build/C/man3/pthread_attr_setguardsize.3:38
1310 "B<int pthread_attr_setguardsize(pthread_attr_t *>I<attr>B<, size_t "
1311 ">I<guardsize>B<);>\n"
1312 "B<int pthread_attr_getguardsize(const pthread_attr_t *>I<attr>B<, size_t "
1313 "*>I<guardsize>B<);>\n"
1317 #: build/C/man3/pthread_attr_setguardsize.3:49
1319 "The B<pthread_attr_setguardsize>() function sets the guard size attribute "
1320 "of the thread attributes object referred to by I<attr> to the value "
1321 "specified in I<guardsize>."
1325 #: build/C/man3/pthread_attr_setguardsize.3:59
1327 "If I<guardsize> is greater than 0, then for each new thread created using "
1328 "I<attr> the system allocates an additional region of at least I<guardsize> "
1329 "bytes at the end of the thread's stack to act as the guard area for the "
1330 "stack (but see BUGS)."
1334 #: build/C/man3/pthread_attr_setguardsize.3:65
1336 "If I<guardsize> is 0, then new threads created with I<attr> will not have a "
1341 #: build/C/man3/pthread_attr_setguardsize.3:67
1342 msgid "The default guard size is the same as the system page size."
1346 #: build/C/man3/pthread_attr_setguardsize.3:82
1348 "If the stack address attribute has been set in I<attr> (using "
1349 "B<pthread_attr_setstack>(3) or B<pthread_attr_setstackaddr>(3)), meaning "
1350 "that the caller is allocating the thread's stack, then the guard size "
1351 "attribute is ignored (i.e., no guard area is created by the system): it is "
1352 "the application's responsibility to handle stack overflow (perhaps by using "
1353 "B<mprotect>(2) to manually define a guard area at the end of the stack that "
1354 "it has allocated)."
1358 #: build/C/man3/pthread_attr_setguardsize.3:90
1360 "The B<pthread_attr_getguardsize>() function returns the guard size "
1361 "attribute of the thread attributes object referred to by I<attr> in the "
1362 "buffer pointed to by I<guardsize>."
1366 #: build/C/man3/pthread_attr_setguardsize.3:104
1368 "POSIX.1-2001 documents an B<EINVAL> error if I<attr> or I<guardsize> is "
1369 "invalid. On Linux these functions always succeed (but portable and "
1370 "future-proof applications should nevertheless handle a possible error "
1375 #: build/C/man3/pthread_attr_setguardsize.3:106 build/C/man3/pthread_attr_setstackaddr.3:83 build/C/man3/pthread_attr_setstacksize.3:83
1376 msgid "These functions are provided by glibc since version 2.1."
1380 #: build/C/man3/pthread_attr_setguardsize.3:113
1382 "The B<pthread_attr_setguardsize>() and B<pthread_attr_getguardsize>() "
1383 "functions are thread-safe."
1387 #: build/C/man3/pthread_attr_setguardsize.3:129
1389 "A guard area consists of virtual memory pages that are protected to prevent "
1390 "read and write access. If a thread overflows its stack into the guard area, "
1391 "then, on most hard architectures, it receives a B<SIGSEGV> signal, thus "
1392 "notifying it of the overflow. Guard areas start on page boundaries, and the "
1393 "guard size is internally rounded up to the system page size when creating a "
1394 "thread. (Nevertheless, B<pthread_attr_getguardsize>() returns the guard "
1395 "size that was set by B<pthread_attr_setguardsize>().)"
1399 #: build/C/man3/pthread_attr_setguardsize.3:133
1401 "Setting a guard size of 0 may be useful to save memory in an application "
1402 "that creates many threads and knows that stack overflow can never occur."
1406 #: build/C/man3/pthread_attr_setguardsize.3:137
1408 "Choosing a guard size larger than the default size may be necessary for "
1409 "detecting stack overflows if a thread allocates large data structures on the "
1414 #: build/C/man3/pthread_attr_setguardsize.3:137 build/C/man3/pthread_attr_setinheritsched.3:119 build/C/man3/pthread_attr_setstacksize.3:103 build/C/man3/pthread_create.3:203 build/C/man3/pthread_exit.3:98 build/C/man3/pthread_rwlockattr_setkind_np.3:109
1420 #: build/C/man3/pthread_attr_setguardsize.3:148
1422 "As at glibc 2.8, the NPTL threading implementation includes the guard area "
1423 "within the stack size allocation, rather than allocating extra space at the "
1424 "end of the stack, as POSIX.1 requires. (This can result in an B<EINVAL> "
1425 "error from B<pthread_create>(3) if the guard size value is too large, "
1426 "leaving no space for the actual stack.)"
1429 #. glibc includes the guardsize within the allocated stack size,
1430 #. which looks pretty clearly to be in violation of POSIX.
1432 #. Filed bug, 22 Oct 2008:
1433 #. http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973
1436 #. https//bugzilla.redhat.com/show_bug.cgi?id=435337
1437 #. Reportedly, LinuxThreads did the right thing, allocating
1438 #. extra space at the end of the stack:
1439 #. http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html
1441 #: build/C/man3/pthread_attr_setguardsize.3:162
1443 "The obsolete LinuxThreads implementation did the right thing, allocating "
1444 "extra space at the end of the stack for the guard area."
1448 #: build/C/man3/pthread_attr_setguardsize.3:165
1449 msgid "See B<pthread_getattr_np>(3)."
1453 #: build/C/man3/pthread_attr_setguardsize.3:173
1455 "B<mmap>(2), B<mprotect>(2), B<pthread_attr_init>(3), "
1456 "B<pthread_attr_setstack>(3), B<pthread_attr_setstacksize>(3), "
1457 "B<pthread_create>(3), B<pthreads>(7)"
1461 #: build/C/man3/pthread_attr_setinheritsched.3:26
1463 msgid "PTHREAD_ATTR_SETINHERITSCHED"
1467 #: build/C/man3/pthread_attr_setinheritsched.3:26 build/C/man3/pthread_attr_setschedparam.3:26 build/C/man3/pthread_attr_setschedpolicy.3:26 build/C/man7/pthreads.7:26
1473 #: build/C/man3/pthread_attr_setinheritsched.3:30
1475 "pthread_attr_setinheritsched, pthread_attr_getinheritsched - set/get "
1476 "inherit-scheduler attribute in thread attributes object"
1480 #: build/C/man3/pthread_attr_setinheritsched.3:38
1483 "B<int pthread_attr_setinheritsched(pthread_attr_t *>I<attr>B<,>\n"
1484 "B< int >I<inheritsched>B<);>\n"
1485 "B<int pthread_attr_getinheritsched(const pthread_attr_t *>I<attr>B<,>\n"
1486 "B< int *>I<inheritsched>B<);>\n"
1490 #: build/C/man3/pthread_attr_setinheritsched.3:55
1492 "The B<pthread_attr_setinheritsched>() function sets the inherit-scheduler "
1493 "attribute of the thread attributes object referred to by I<attr> to the "
1494 "value specified in I<inheritsched>. The inherit-scheduler attribute "
1495 "determines whether a thread created using the thread attributes object "
1496 "I<attr> will inherit its scheduling attributes from the calling thread or "
1497 "whether it will take them from I<attr>."
1501 #: build/C/man3/pthread_attr_setinheritsched.3:64
1503 "The following scheduling attributes are affected by the inherit-scheduler "
1504 "attribute: scheduling policy (B<pthread_attr_setschedpolicy>(3)), scheduling "
1505 "priority (B<pthread_attr_setschedparam>(3)), and contention scope "
1506 "(B<pthread_attr_setscope>(3))."
1510 #: build/C/man3/pthread_attr_setinheritsched.3:67
1511 msgid "The following values may be specified in I<inheritsched>:"
1515 #: build/C/man3/pthread_attr_setinheritsched.3:67
1517 msgid "B<PTHREAD_INHERIT_SCHED>"
1521 #: build/C/man3/pthread_attr_setinheritsched.3:75
1523 "Threads that are created using I<attr> inherit scheduling attributes from "
1524 "the creating thread; the scheduling attributes in I<attr> are ignored."
1528 #: build/C/man3/pthread_attr_setinheritsched.3:75
1530 msgid "B<PTHREAD_EXPLICIT_SCHED>"
1533 #. FIXME Document the defaults for scheduler settings
1535 #: build/C/man3/pthread_attr_setinheritsched.3:82
1537 "Threads that are created using I<attr> take their scheduling attributes from "
1538 "the values specified by the attributes object."
1542 #: build/C/man3/pthread_attr_setinheritsched.3:86
1544 "The default setting of the inherit-scheduler attribute in a newly "
1545 "initialized thread attributes object is B<PTHREAD_INHERIT_SCHED>."
1549 #: build/C/man3/pthread_attr_setinheritsched.3:93
1551 "The B<pthread_attr_getinheritsched>() returns the inherit-scheduler "
1552 "attribute of the thread attributes object I<attr> in the buffer pointed to "
1553 "by I<inheritsched>."
1557 #: build/C/man3/pthread_attr_setinheritsched.3:99
1558 msgid "B<pthread_attr_setinheritsched>() can fail with the following error:"
1562 #: build/C/man3/pthread_attr_setinheritsched.3:103
1563 msgid "Invalid value in I<inheritsched>."
1567 #. Available since glibc 2.0.
1569 #: build/C/man3/pthread_attr_setinheritsched.3:110
1571 "POSIX.1-2001 also documents an optional B<ENOTSUP> error (\"attempt was made "
1572 "to set the attribute to an unsupported value\") for "
1573 "B<pthread_attr_setinheritsched>()."
1577 #: build/C/man3/pthread_attr_setinheritsched.3:117
1579 "The B<pthread_attr_setinheritsched>() and B<pthread_attr_getinheritsched>() "
1580 "functions are thread-safe."
1583 #. FIXME . Track status of the following bug:
1584 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7007
1586 #: build/C/man3/pthread_attr_setinheritsched.3:135
1588 "As at glibc 2.8, if a thread attributes object is initialized using "
1589 "B<pthread_attr_init>(3), then the scheduling policy of the attributes object "
1590 "is set to B<SCHED_OTHER> and the scheduling priority is set to 0. However, "
1591 "if the inherit-scheduler attribute is then set to B<PTHREAD_EXPLICIT_SCHED>, "
1592 "then a thread created using the attribute object wrongly inherits its "
1593 "scheduling attributes from the creating thread. This bug does not occur if "
1594 "either the scheduling policy or scheduling priority attribute is explicitly "
1595 "set in the thread attributes object before calling B<pthread_create>(3)."
1599 #: build/C/man3/pthread_attr_setinheritsched.3:138 build/C/man3/pthread_attr_setschedparam.3:116 build/C/man3/pthread_attr_setschedpolicy.3:112
1600 msgid "See B<pthread_setschedparam>(3)."
1604 #: build/C/man3/pthread_attr_setinheritsched.3:150
1606 "B<pthread_attr_init>(3), B<pthread_attr_setschedparam>(3), "
1607 "B<pthread_attr_setschedpolicy>(3), B<pthread_attr_setscope>(3), "
1608 "B<pthread_create>(3), B<pthread_setschedparam>(3), "
1609 "B<pthread_setschedprio>(3), B<pthreads>(7), B<sched>(7)"
1613 #: build/C/man3/pthread_attr_setschedparam.3:26
1615 msgid "PTHREAD_ATTR_SETSCHEDPARAM"
1619 #: build/C/man3/pthread_attr_setschedparam.3:30
1621 "pthread_attr_setschedparam, pthread_attr_getschedparam - set/get scheduling "
1622 "parameter attributes in thread attributes object"
1626 #: build/C/man3/pthread_attr_setschedparam.3:38
1629 "B<int pthread_attr_setschedparam(pthread_attr_t *>I<attr>B<,>\n"
1630 "B< const struct sched_param *>I<param>B<);>\n"
1631 "B<int pthread_attr_getschedparam(const pthread_attr_t *>I<attr>B<,>\n"
1632 "B< struct sched_param *>I<param>B<);>\n"
1636 #: build/C/man3/pthread_attr_setschedparam.3:52
1638 "The B<pthread_attr_setschedparam>() function sets the scheduling parameter "
1639 "attributes of the thread attributes object referred to by I<attr> to the "
1640 "values specified in the buffer pointed to by I<param>. These attributes "
1641 "determine the scheduling parameters of a thread created using the thread "
1642 "attributes object I<attr>."
1646 #: build/C/man3/pthread_attr_setschedparam.3:59
1648 "The B<pthread_attr_getschedparam>() returns the scheduling parameter "
1649 "attributes of the thread attributes object I<attr> in the buffer pointed to "
1654 #: build/C/man3/pthread_attr_setschedparam.3:61
1655 msgid "Scheduling parameters are maintained in the following structure:"
1659 #: build/C/man3/pthread_attr_setschedparam.3:67 build/C/man3/pthread_setschedparam.3:69
1662 "struct sched_param {\n"
1663 " int sched_priority; /* Scheduling priority */\n"
1668 #: build/C/man3/pthread_attr_setschedparam.3:74 build/C/man3/pthread_setschedparam.3:76
1670 "As can be seen, only one scheduling parameter is supported. For details of "
1671 "the permitted ranges for scheduling priorities in each scheduling policy, "
1676 #: build/C/man3/pthread_attr_setschedparam.3:85
1678 "In order for the parameter setting made by B<pthread_attr_setschedparam>() "
1679 "to have effect when calling B<pthread_create>(3), the caller must use "
1680 "B<pthread_attr_setinheritsched>(3) to set the inherit-scheduler attribute "
1681 "of the attributes object I<attr> to B<PTHREAD_EXPLICIT_SCHED>."
1685 #. Available since glibc 2.0.
1687 #: build/C/man3/pthread_attr_setschedparam.3:100
1689 "POSIX.1 documents B<EINVAL> and B<ENOTSUP> errors for "
1690 "B<pthread_attr_setschedparam>(). On Linux these functions always succeed "
1691 "(but portable and future-proof applications should nevertheless handle a "
1692 "possible error return)."
1696 #: build/C/man3/pthread_attr_setschedparam.3:107
1698 "The B<pthread_attr_setschedparam>() and B<pthread_attr_getschedparam>() "
1699 "functions are thread-safe."
1703 #: build/C/man3/pthread_attr_setschedparam.3:113
1705 "See B<pthread_attr_setschedpolicy>(3) for a list of the thread scheduling "
1706 "policies supported on Linux."
1710 #: build/C/man3/pthread_attr_setschedparam.3:128
1712 "B<sched_get_priority_min>(2), B<pthread_attr_init>(3), "
1713 "B<pthread_attr_setinheritsched>(3), B<pthread_attr_setschedpolicy>(3), "
1714 "B<pthread_create>(3), B<pthread_setschedparam>(3), "
1715 "B<pthread_setschedprio>(3), B<pthreads>(7), B<sched>(7)"
1719 #: build/C/man3/pthread_attr_setschedpolicy.3:26
1721 msgid "PTHREAD_ATTR_SETSCHEDPOLICY"
1725 #: build/C/man3/pthread_attr_setschedpolicy.3:30
1727 "pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set/get "
1728 "scheduling policy attribute in thread attributes object"
1732 #: build/C/man3/pthread_attr_setschedpolicy.3:38
1735 "B<int pthread_attr_setschedpolicy(pthread_attr_t *>I<attr>B<, int "
1737 "B<int pthread_attr_getschedpolicy(const pthread_attr_t *>I<attr>B<, int "
1738 ">I<*policy>B<);>\n"
1742 #: build/C/man3/pthread_attr_setschedpolicy.3:52
1744 "The B<pthread_attr_setschedpolicy>() function sets the scheduling policy "
1745 "attribute of the thread attributes object referred to by I<attr> to the "
1746 "value specified in I<policy>. This attribute determines the scheduling "
1747 "policy of a thread created using the thread attributes object I<attr>."
1750 #. FIXME . pthread_setschedparam() places no restriction on the policy,
1751 #. but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
1752 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7013
1754 #: build/C/man3/pthread_attr_setschedpolicy.3:65
1756 "The supported values for I<policy> are B<SCHED_FIFO>, B<SCHED_RR>, and "
1757 "B<SCHED_OTHER>, with the semantics described in B<sched>(7)."
1761 #: build/C/man3/pthread_attr_setschedpolicy.3:72
1763 "The B<pthread_attr_getschedpolicy>() returns the scheduling policy "
1764 "attribute of the thread attributes object I<attr> in the buffer pointed to "
1769 #: build/C/man3/pthread_attr_setschedpolicy.3:83
1771 "In order for the policy setting made by B<pthread_attr_setschedpolicy>() to "
1772 "have effect when calling B<pthread_create>(3), the caller must use "
1773 "B<pthread_attr_setinheritsched>(3) to set the inherit-scheduler attribute "
1774 "of the attributes object I<attr> to B<PTHREAD_EXPLICIT_SCHED>."
1778 #: build/C/man3/pthread_attr_setschedpolicy.3:89
1779 msgid "B<pthread_attr_setschedpolicy>() can fail with the following error:"
1783 #: build/C/man3/pthread_attr_setschedpolicy.3:93
1784 msgid "Invalid value in I<policy>."
1788 #. Available since glibc 2.0.
1790 #: build/C/man3/pthread_attr_setschedpolicy.3:100
1792 "POSIX.1-2001 also documents an optional B<ENOTSUP> error (\"attempt was made "
1793 "to set the attribute to an unsupported value\") for "
1794 "B<pthread_attr_setschedpolicy>()."
1798 #: build/C/man3/pthread_attr_setschedpolicy.3:107
1800 "The B<pthread_attr_setschedpolicy>() and B<pthread_attr_getschedpolicy>() "
1801 "functions are thread-safe."
1805 #: build/C/man3/pthread_attr_setschedpolicy.3:123
1807 "B<pthread_attr_init>(3), B<pthread_attr_setinheritsched>(3), "
1808 "B<pthread_attr_setschedparam>(3), B<pthread_create>(3), "
1809 "B<pthread_setschedparam>(3), B<pthread_setschedprio>(3), B<pthreads>(7), "
1814 #: build/C/man3/pthread_attr_setscope.3:26
1816 msgid "PTHREAD_ATTR_SETSCOPE"
1820 #: build/C/man3/pthread_attr_setscope.3:30
1822 "pthread_attr_setscope, pthread_attr_getscope - set/get contention scope "
1823 "attribute in thread attributes object"
1827 #: build/C/man3/pthread_attr_setscope.3:38
1830 "B<int pthread_attr_setscope(pthread_attr_t *>I<attr>B<, int >I<scope>B<);>\n"
1831 "B<int pthread_attr_getscope(const pthread_attr_t *>I<attr>B<, int "
1836 #: build/C/man3/pthread_attr_setscope.3:53
1838 "The B<pthread_attr_setscope>() function sets the contention scope attribute "
1839 "of the thread attributes object referred to by I<attr> to the value "
1840 "specified in I<scope>. The contention scope attribute defines the set of "
1841 "threads against which a thread competes for resources such as the CPU. "
1842 "POSIX.1-2001 specifies two possible values for I<scope>:"
1846 #: build/C/man3/pthread_attr_setscope.3:53
1848 msgid "B<PTHREAD_SCOPE_SYSTEM>"
1852 #: build/C/man3/pthread_attr_setscope.3:61
1854 "The thread competes for resources with all other threads in all processes on "
1855 "the system that are in the same scheduling allocation domain (a group of one "
1856 "or more processors). B<PTHREAD_SCOPE_SYSTEM> threads are scheduled relative "
1857 "to one another according to their scheduling policy and priority."
1861 #: build/C/man3/pthread_attr_setscope.3:61
1863 msgid "B<PTHREAD_SCOPE_PROCESS>"
1867 #: build/C/man3/pthread_attr_setscope.3:76
1869 "The thread competes for resources with all other threads in the same process "
1870 "that were also created with the B<PTHREAD_SCOPE_PROCESS> contention scope. "
1871 "B<PTHREAD_SCOPE_PROCESS> threads are scheduled relative to other threads in "
1872 "the process according to their scheduling policy and priority. POSIX.1-2001 "
1873 "leaves it unspecified how these threads contend with other threads in other "
1874 "process on the system or with other threads in the same process that were "
1875 "created with the B<PTHREAD_SCOPE_SYSTEM> contention scope."
1879 #: build/C/man3/pthread_attr_setscope.3:83
1881 "POSIX.1-2001 requires that an implementation support at least one of these "
1882 "contention scopes. Linux supports B<PTHREAD_SCOPE_SYSTEM>, but not "
1883 "B<PTHREAD_SCOPE_PROCESS>."
1887 #: build/C/man3/pthread_attr_setscope.3:95
1889 "On systems that support multiple contention scopes, then, in order for the "
1890 "parameter setting made by B<pthread_attr_setscope>() to have effect when "
1891 "calling B<pthread_create>(3), the caller must use "
1892 "B<pthread_attr_setinheritsched>(3) to set the inherit-scheduler attribute "
1893 "of the attributes object I<attr> to B<PTHREAD_EXPLICIT_SCHED>."
1897 #: build/C/man3/pthread_attr_setscope.3:103
1899 "The B<pthread_attr_getscope>() function returns the contention scope "
1900 "attribute of the thread attributes object referred to by I<attr> in the "
1901 "buffer pointed to by I<scope>."
1905 #: build/C/man3/pthread_attr_setscope.3:109
1906 msgid "B<pthread_attr_setscope>() can fail with the following errors:"
1910 #: build/C/man3/pthread_attr_setscope.3:113
1911 msgid "An invalid value was specified in I<scope>."
1915 #: build/C/man3/pthread_attr_setscope.3:113
1921 #: build/C/man3/pthread_attr_setscope.3:119
1923 "I<scope> specified the value B<PTHREAD_SCOPE_PROCESS>, which is not "
1924 "supported on Linux."
1928 #: build/C/man3/pthread_attr_setscope.3:126
1930 "The B<pthread_attr_setscope>() and B<pthread_attr_getscope>() functions "
1935 #: build/C/man3/pthread_attr_setscope.3:136
1937 "The B<PTHREAD_SCOPE_SYSTEM> contention scope typically indicates that a "
1938 "user-space thread is bound directly to a single kernel-scheduling entity. "
1939 "This is the case on Linux for the obsolete LinuxThreads implementation and "
1940 "the modern NPTL implementation, which are both 1:1 threading "
1945 #: build/C/man3/pthread_attr_setscope.3:139
1947 "POSIX.1-2001 specifies that the default contention scope is "
1948 "implementation-defined."
1952 #: build/C/man3/pthread_attr_setscope.3:149
1954 "B<pthread_attr_init>(3), B<pthread_attr_setaffinity_np>(3), "
1955 "B<pthread_attr_setinheritsched>(3), B<pthread_attr_setschedparam>(3), "
1956 "B<pthread_attr_setschedpolicy>(3), B<pthread_create>(3), B<pthreads>(7)"
1960 #: build/C/man3/pthread_attr_setstack.3:26
1962 msgid "PTHREAD_ATTR_SETSTACK"
1966 #: build/C/man3/pthread_attr_setstack.3:30
1968 "pthread_attr_setstack, pthread_attr_getstack - set/get stack attributes in "
1969 "thread attributes object"
1973 #: build/C/man3/pthread_attr_setstack.3:38
1976 "B<int pthread_attr_setstack(pthread_attr_t *>I<attr>B<,>\n"
1977 "B< void *>I<stackaddr>B<, size_t "
1978 ">I<stacksize>B<);>\n"
1979 "B<int pthread_attr_getstack(const pthread_attr_t *>I<attr>B<,>\n"
1980 "B< void **>I<stackaddr>B<, size_t "
1981 "*>I<stacksize>B<);>\n"
1985 #: build/C/man3/pthread_attr_setstack.3:45 build/C/man3/pthread_cleanup_push_defer_np.3:44 build/C/man3/pthread_kill.3:41 build/C/man3/pthread_rwlockattr_setkind_np.3:44 build/C/man3/pthread_sigmask.3:42 build/C/man3/pthread_sigqueue.3:42
1986 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
1990 #: build/C/man3/pthread_attr_setstack.3:50
1991 msgid "B<pthread_attr_getstack>(), B<pthread_attr_setstack>():"
1995 #: build/C/man3/pthread_attr_setstack.3:52
1996 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ E<gt>=\\ 600"
2000 #: build/C/man3/pthread_attr_setstack.3:68
2002 "The B<pthread_attr_setstack>() function sets the stack address and stack "
2003 "size attributes of the thread attributes object referred to by I<attr> to "
2004 "the values specified in I<stackaddr> and I<stacksize>, respectively. These "
2005 "attributes specify the location and size of the stack that should be used by "
2006 "a thread that is created using the thread attributes object I<attr>."
2010 #: build/C/man3/pthread_attr_setstack.3:74
2012 "I<stackaddr> should point to the lowest addressable byte of a buffer of "
2013 "I<stacksize> bytes that was allocated by the caller. The pages of the "
2014 "allocated buffer should be both readable and writable."
2018 #: build/C/man3/pthread_attr_setstack.3:85
2020 "The B<pthread_attr_getstack>() function returns the stack address and stack "
2021 "size attributes of the thread attributes object referred to by I<attr> in "
2022 "the buffers pointed to by I<stackaddr> and I<stacksize>, respectively."
2026 #: build/C/man3/pthread_attr_setstack.3:91
2027 msgid "B<pthread_attr_setstack>() can fail with the following error:"
2031 #: build/C/man3/pthread_attr_setstack.3:102
2033 "I<stacksize> is less than B<PTHREAD_STACK_MIN> (16384) bytes. On some "
2034 "systems, this error may also occur if I<stackaddr> or I<stackaddr\\ +\\ "
2035 "stacksize> is not suitably aligned."
2039 #: build/C/man3/pthread_attr_setstack.3:110
2041 "POSIX.1-2001 also documents an B<EACCES> error if the stack area described "
2042 "by I<stackaddr> and I<stacksize> is not both readable and writable by the "
2047 #: build/C/man3/pthread_attr_setstack.3:112
2048 msgid "These functions are provided by glibc since version 2.2."
2052 #: build/C/man3/pthread_attr_setstack.3:119
2054 "The B<pthread_attr_setstack>() and B<pthread_attr_getstack>() functions "
2059 #: build/C/man3/pthread_attr_setstack.3:129
2061 "These functions are provided for applications that must ensure that a "
2062 "thread's stack is placed in a particular location. For most applications, "
2063 "this is not necessary, and the use of these functions should be avoided. "
2064 "(Use B<pthread_attr_setstacksize>(3) if an application simply requires a "
2065 "stack size other than the default.)"
2069 #: build/C/man3/pthread_attr_setstack.3:140
2071 "When an application employs B<pthread_attr_setstack>(), it takes over the "
2072 "responsibility of allocating the stack. Any guard size value that was set "
2073 "using B<pthread_attr_setguardsize>(3) is ignored. If deemed necessary, it "
2074 "is the application's responsibility to allocate a guard area (one or more "
2075 "pages protected against reading and writing) to handle the possibility of "
2080 #: build/C/man3/pthread_attr_setstack.3:151
2082 "The address specified in I<stackaddr> should be suitably aligned: for full "
2083 "portability, align it on a page boundary (I<sysconf(_SC_PAGESIZE)>). "
2084 "B<posix_memalign>(3) may be useful for allocation. Probably, I<stacksize> "
2085 "should also be a multiple of the system page size."
2089 #: build/C/man3/pthread_attr_setstack.3:159
2091 "If I<attr> is used to create multiple threads, then the caller must change "
2092 "the stack address attribute between calls to B<pthread_create>(3); "
2093 "otherwise, the threads will attempt to use the same memory area for their "
2094 "stacks, and chaos will ensue."
2098 #: build/C/man3/pthread_attr_setstack.3:174
2100 "B<mmap>(2), B<mprotect>(2), B<posix_memalign>(3), B<pthread_attr_init>(3), "
2101 "B<pthread_attr_setguardsize>(3), B<pthread_attr_setstackaddr>(3), "
2102 "B<pthread_attr_setstacksize>(3), B<pthread_create>(3), B<pthreads>(7)"
2106 #: build/C/man3/pthread_attr_setstackaddr.3:26
2108 msgid "PTHREAD_ATTR_SETSTACKADDR"
2112 #: build/C/man3/pthread_attr_setstackaddr.3:30
2114 "pthread_attr_setstackaddr, pthread_attr_getstackaddr - set/get stack address "
2115 "attribute in thread attributes object"
2119 #: build/C/man3/pthread_attr_setstackaddr.3:38
2122 "B<int pthread_attr_setstackaddr(pthread_attr_t *>I<attr>B<, void "
2123 "*>I<stackaddr>B<);>\n"
2124 "B<int pthread_attr_getstackaddr(const pthread_attr_t *>I<attr>B<, void "
2125 "**>I<stackaddr>B<);>\n"
2129 #: build/C/man3/pthread_attr_setstackaddr.3:49
2131 "These functions are obsolete: B<do not use them.> Use "
2132 "B<pthread_attr_setstack>(3) and B<pthread_attr_getstack>(3) instead."
2136 #: build/C/man3/pthread_attr_setstackaddr.3:60
2138 "The B<pthread_attr_setstackaddr>() function sets the stack address "
2139 "attribute of the thread attributes object referred to by I<attr> to the "
2140 "value specified in I<stackaddr>. This attribute specifies the location of "
2141 "the stack that should be used by a thread that is created using the thread "
2142 "attributes object I<attr>."
2146 #: build/C/man3/pthread_attr_setstackaddr.3:66
2148 "I<stackaddr> should point to a buffer of at least B<PTHREAD_STACK_MIN> bytes "
2149 "that was allocated by the caller. The pages of the allocated buffer should "
2150 "be both readable and writable."
2154 #: build/C/man3/pthread_attr_setstackaddr.3:74
2156 "The B<pthread_attr_getstackaddr>() function returns the stack address "
2157 "attribute of the thread attributes object referred to by I<attr> in the "
2158 "buffer pointed to by I<stackaddr>."
2162 #: build/C/man3/pthread_attr_setstackaddr.3:81
2164 "No errors are defined (but applications should nevertheless handle a "
2165 "possible error return)."
2169 #: build/C/man3/pthread_attr_setstackaddr.3:90
2171 "The B<pthread_attr_setstackaddr>() and B<pthread_attr_getstackaddr>() "
2172 "functions are thread-safe."
2176 #: build/C/man3/pthread_attr_setstackaddr.3:93
2178 "POSIX.1-2001 specifies these functions but marks them as obsolete. "
2179 "POSIX.1-2008 removes the specification of these functions."
2183 #: build/C/man3/pthread_attr_setstackaddr.3:117
2185 "I<Do not use these functions!> They cannot be portably used, since they "
2186 "provide no way of specifying the direction of growth or the range of the "
2187 "stack. For example, on architectures with a stack that grows downward, "
2188 "I<stackaddr> specifies the next address past the I<highest> address of the "
2189 "allocated stack area. However, on architectures with a stack that grows "
2190 "upward, I<stackaddr> specifies the I<lowest> address in the allocated stack "
2191 "area. By contrast, the I<stackaddr> used by B<pthread_attr_setstack>(3) "
2192 "and B<pthread_attr_getstack>(3), is always a pointer to the lowest address "
2193 "in the allocated stack area (and the I<stacksize> argument specifies the "
2194 "range of the stack)."
2198 #: build/C/man3/pthread_attr_setstackaddr.3:123
2200 "B<pthread_attr_init>(3), B<pthread_attr_setstack>(3), "
2201 "B<pthread_attr_setstacksize>(3), B<pthread_create>(3), B<pthreads>(7)"
2205 #: build/C/man3/pthread_attr_setstacksize.3:26
2207 msgid "PTHREAD_ATTR_SETSTACKSIZE"
2211 #: build/C/man3/pthread_attr_setstacksize.3:30
2213 "pthread_attr_setstacksize, pthread_attr_getstacksize - set/get stack size "
2214 "attribute in thread attributes object"
2218 #: build/C/man3/pthread_attr_setstacksize.3:38
2221 "B<int pthread_attr_setstacksize(pthread_attr_t *>I<attr>B<, size_t "
2222 ">I<stacksize>B<);>\n"
2223 "B<int pthread_attr_getstacksize(const pthread_attr_t *>I<attr>B<, size_t "
2224 "*>I<stacksize>B<);>\n"
2228 #: build/C/man3/pthread_attr_setstacksize.3:49
2230 "The B<pthread_attr_setstacksize>() function sets the stack size attribute "
2231 "of the thread attributes object referred to by I<attr> to the value "
2232 "specified in I<stacksize>."
2236 #: build/C/man3/pthread_attr_setstacksize.3:53
2238 "The stack size attribute determines the minimum size (in bytes) that will be "
2239 "allocated for threads created using the thread attributes object I<attr>."
2243 #: build/C/man3/pthread_attr_setstacksize.3:61
2245 "The B<pthread_attr_getstacksize>() function returns the stack size "
2246 "attribute of the thread attributes object referred to by I<attr> in the "
2247 "buffer pointed to by I<stacksize>."
2251 #: build/C/man3/pthread_attr_setstacksize.3:67
2252 msgid "B<pthread_attr_setstacksize>() can fail with the following error:"
2256 #: build/C/man3/pthread_attr_setstacksize.3:72
2257 msgid "The stack size is less than B<PTHREAD_STACK_MIN> (16384) bytes."
2262 #: build/C/man3/pthread_attr_setstacksize.3:81
2264 "On some systems, B<pthread_attr_setstacksize>() can fail with the error "
2265 "B<EINVAL> if I<stacksize> is not a multiple of the system page size."
2269 #: build/C/man3/pthread_attr_setstacksize.3:90
2271 "The B<pthread_attr_setstacksize>() and B<pthread_attr_getstacksize>() "
2272 "functions are thread-safe."
2276 #: build/C/man3/pthread_attr_setstacksize.3:95
2278 "For details on the default stack size of new threads, see "
2279 "B<pthread_create>(3)."
2283 #: build/C/man3/pthread_attr_setstacksize.3:98
2285 "A thread's stack size is fixed at the time of thread creation. Only the "
2286 "main thread can dynamically grow its stack."
2290 #: build/C/man3/pthread_attr_setstacksize.3:103
2292 "The B<pthread_attr_setstack>(3) function allows an application to set both "
2293 "the size and location of a caller-allocated stack that is to be used by a "
2298 #: build/C/man3/pthread_attr_setstacksize.3:115
2300 "As at glibc 2.8, if the specified I<stacksize> is not a multiple of "
2301 "B<STACK_ALIGN> (16 bytes on most architectures), it may be rounded "
2302 "I<downward>, in violation of POSIX.1-2001, which says that the allocated "
2303 "stack will be at least I<stacksize> bytes."
2307 #: build/C/man3/pthread_attr_setstacksize.3:118 build/C/man3/pthread_join.3:127
2308 msgid "See B<pthread_create>(3)."
2312 #: build/C/man3/pthread_attr_setstacksize.3:125
2314 "B<getrlimit>(2), B<pthread_attr_init>(3), B<pthread_attr_setguardsize>(3), "
2315 "B<pthread_attr_setstack>(3), B<pthread_create>(3), B<pthreads>(7)"
2319 #: build/C/man3/pthread_cancel.3:26
2321 msgid "PTHREAD_CANCEL"
2325 #: build/C/man3/pthread_cancel.3:26
2331 #: build/C/man3/pthread_cancel.3:29
2332 msgid "pthread_cancel - send a cancellation request to a thread"
2336 #: build/C/man3/pthread_cancel.3:34
2338 msgid "B<int pthread_cancel(pthread_t >I<thread>B<);>\n"
2342 #: build/C/man3/pthread_cancel.3:49
2344 "The B<pthread_cancel>() function sends a cancellation request to the thread "
2345 "I<thread>. Whether and when the target thread reacts to the cancellation "
2346 "request depends on two attributes that are under the control of that thread: "
2347 "its cancelability I<state> and I<type>."
2351 #: build/C/man3/pthread_cancel.3:61
2353 "A thread's cancelability state, determined by B<pthread_setcancelstate>(3), "
2354 "can be I<enabled> (the default for new threads) or I<disabled>. If a thread "
2355 "has disabled cancellation, then a cancellation request remains queued until "
2356 "the thread enables cancellation. If a thread has enabled cancellation, then "
2357 "its cancelability type determines when cancellation occurs."
2361 #: build/C/man3/pthread_cancel.3:77
2363 "A thread's cancellation type, determined by B<pthread_setcanceltype>(3), may "
2364 "be either I<asynchronous> or I<deferred> (the default for new threads). "
2365 "Asynchronous cancelability means that the thread can be canceled at any time "
2366 "(usually immediately, but the system does not guarantee this). Deferred "
2367 "cancelability means that cancellation will be delayed until the thread next "
2368 "calls a function that is a I<cancellation point>. A list of functions that "
2369 "are or may be cancellation points is provided in B<pthreads>(7)."
2373 #: build/C/man3/pthread_cancel.3:81
2375 "When a cancellation requested is acted on, the following steps occur for "
2376 "I<thread> (in this order):"
2380 #: build/C/man3/pthread_cancel.3:81 build/C/man3/pthread_cleanup_push.3:69
2386 #: build/C/man3/pthread_cancel.3:86
2388 "Cancellation clean-up handlers are popped (in the reverse of the order in "
2389 "which they were pushed) and called. (See B<pthread_cleanup_push>(3).)"
2393 #: build/C/man3/pthread_cancel.3:86 build/C/man3/pthread_cleanup_push.3:73
2399 #: build/C/man3/pthread_cancel.3:91
2401 "Thread-specific data destructors are called, in an unspecified order. (See "
2402 "B<pthread_key_create>(3).)"
2406 #: build/C/man3/pthread_cancel.3:91 build/C/man3/pthread_cleanup_push.3:83
2412 #: build/C/man3/pthread_cancel.3:95
2413 msgid "The thread is terminated. (See B<pthread_exit>(3).)"
2417 #: build/C/man3/pthread_cancel.3:103
2419 "The above steps happen asynchronously with respect to the "
2420 "B<pthread_cancel>() call; the return status of B<pthread_cancel>() merely "
2421 "informs the caller whether the cancellation request was successfully queued."
2425 #: build/C/man3/pthread_cancel.3:112
2427 "After a canceled thread has terminated, a join with that thread using "
2428 "B<pthread_join>(3) obtains B<PTHREAD_CANCELED> as the thread's exit "
2429 "status. (Joining with a thread is the only way to know that cancellation "
2434 #: build/C/man3/pthread_cancel.3:117
2436 "On success, B<pthread_cancel>() returns 0; on error, it returns a nonzero "
2441 #: build/C/man3/pthread_cancel.3:118 build/C/man3/pthread_detach.3:59 build/C/man3/pthread_getcpuclockid.3:58 build/C/man3/pthread_join.3:93 build/C/man3/pthread_setaffinity_np.3:114 build/C/man3/pthread_setschedparam.3:114 build/C/man3/pthread_setschedprio.3:70 build/C/man3/pthread_sigqueue.3:86
2447 #: build/C/man3/pthread_cancel.3:125 build/C/man3/pthread_detach.3:64 build/C/man3/pthread_getcpuclockid.3:63 build/C/man3/pthread_join.3:98 build/C/man3/pthread_setaffinity_np.3:119 build/C/man3/pthread_setschedparam.3:119 build/C/man3/pthread_setschedprio.3:75
2448 msgid "No thread with the ID I<thread> could be found."
2452 #: build/C/man3/pthread_cancel.3:135
2454 "On Linux, cancellation is implemented using signals. Under the NPTL "
2455 "threading implementation, the first real-time signal (i.e., signal 32) is "
2456 "used for this purpose. On LinuxThreads, the second real-time signal is "
2457 "used, if real-time signals are available, otherwise B<SIGUSR2> is used."
2461 #: build/C/man3/pthread_cancel.3:141
2463 "The program below creates a thread and then cancels it. The main thread "
2464 "joins with the canceled thread to check that its exit status was "
2465 "B<PTHREAD_CANCELED>. The following shell session shows what happens when we "
2470 #: build/C/man3/pthread_cancel.3:149
2474 "thread_func(): started; cancellation disabled\n"
2475 "main(): sending cancellation request\n"
2476 "thread_func(): about to enable cancellation\n"
2477 "main(): thread was canceled\n"
2481 #: build/C/man3/pthread_cancel.3:159
2484 "#include E<lt>pthread.hE<gt>\n"
2485 "#include E<lt>stdio.hE<gt>\n"
2486 "#include E<lt>errno.hE<gt>\n"
2487 "#include E<lt>stdlib.hE<gt>\n"
2488 "#include E<lt>unistd.hE<gt>\n"
2492 #: build/C/man3/pthread_cancel.3:167
2496 "thread_func(void *ignored_argument)\n"
2502 #: build/C/man3/pthread_cancel.3:170
2505 " /* Disable cancellation for a while, so that we don\\(aqt\n"
2506 " immediately react to a cancellation request */\n"
2510 #: build/C/man3/pthread_cancel.3:174
2513 " s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);\n"
2515 " handle_error_en(s, \"pthread_setcancelstate\");\n"
2519 #: build/C/man3/pthread_cancel.3:178
2522 " printf(\"thread_func(): started; cancellation disabled\\en\");\n"
2524 " printf(\"thread_func(): about to enable cancellation\\en\");\n"
2528 #: build/C/man3/pthread_cancel.3:182
2531 " s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);\n"
2533 " handle_error_en(s, \"pthread_setcancelstate\");\n"
2537 #: build/C/man3/pthread_cancel.3:184
2539 msgid " /* sleep() is a cancellation point */\n"
2543 #: build/C/man3/pthread_cancel.3:186
2545 msgid " sleep(1000); /* Should get canceled while we sleep */\n"
2549 #: build/C/man3/pthread_cancel.3:188
2551 msgid " /* Should never get here */\n"
2555 #: build/C/man3/pthread_cancel.3:192
2558 " printf(\"thread_func(): not canceled!\\en\");\n"
2564 #: build/C/man3/pthread_cancel.3:199
2576 #: build/C/man3/pthread_cancel.3:201
2578 msgid " /* Start a thread and then send it a cancellation request */\n"
2582 #: build/C/man3/pthread_cancel.3:205
2585 " s = pthread_create(&thr, NULL, &thread_func, NULL);\n"
2587 " handle_error_en(s, \"pthread_create\");\n"
2591 #: build/C/man3/pthread_cancel.3:207
2593 msgid " sleep(2); /* Give thread a chance to get started */\n"
2597 #: build/C/man3/pthread_cancel.3:212
2600 " printf(\"main(): sending cancellation request\\en\");\n"
2601 " s = pthread_cancel(thr);\n"
2603 " handle_error_en(s, \"pthread_cancel\");\n"
2607 #: build/C/man3/pthread_cancel.3:214
2609 msgid " /* Join with thread to see what its exit status was */\n"
2613 #: build/C/man3/pthread_cancel.3:218 build/C/man3/pthread_cleanup_push.3:307
2616 " s = pthread_join(thr, &res);\n"
2618 " handle_error_en(s, \"pthread_join\");\n"
2622 #: build/C/man3/pthread_cancel.3:225
2625 " if (res == PTHREAD_CANCELED)\n"
2626 " printf(\"main(): thread was canceled\\en\");\n"
2628 " printf(\"main(): thread wasn\\(aqt canceled (shouldn\\(aqt "
2629 "happen!)\\en\");\n"
2630 " exit(EXIT_SUCCESS);\n"
2635 #: build/C/man3/pthread_cancel.3:238
2637 "B<pthread_cleanup_push>(3), B<pthread_create>(3), B<pthread_exit>(3), "
2638 "B<pthread_join>(3), B<pthread_key_create>(3), B<pthread_setcancelstate>(3), "
2639 "B<pthread_setcanceltype>(3), B<pthread_testcancel>(3), B<pthreads>(7)"
2643 #: build/C/man3/pthread_cleanup_push.3:26
2645 msgid "PTHREAD_CLEANUP_PUSH"
2649 #: build/C/man3/pthread_cleanup_push.3:26
2655 #: build/C/man3/pthread_cleanup_push.3:30
2657 "pthread_cleanup_push, pthread_cleanup_pop - push and pop thread cancellation "
2662 #: build/C/man3/pthread_cleanup_push.3:37
2665 "B<void pthread_cleanup_push(void (*>I<routine>B<)(void *),>\n"
2666 "B< void *>I<arg>B<);>\n"
2667 "B<void pthread_cleanup_pop(int >I<execute>B<);>\n"
2671 #: build/C/man3/pthread_cleanup_push.3:48
2673 "These functions manipulate the calling thread's stack of thread-cancellation "
2674 "clean-up handlers. A clean-up handler is a function that is automatically "
2675 "executed when a thread is canceled (or in various other circumstances "
2676 "described below); it might, for example, unlock a mutex so that it becomes "
2677 "available to other threads in the process."
2681 #: build/C/man3/pthread_cleanup_push.3:59
2683 "The B<pthread_cleanup_push>() function pushes I<routine> onto the top of "
2684 "the stack of clean-up handlers. When I<routine> is later invoked, it will "
2685 "be given I<arg> as its argument."
2689 #: build/C/man3/pthread_cleanup_push.3:66
2691 "The B<pthread_cleanup_pop>() function removes the routine at the top of the "
2692 "stack of clean-up handlers, and optionally executes it if I<execute> is "
2697 #: build/C/man3/pthread_cleanup_push.3:69
2699 "A cancellation clean-up handler is popped from the stack and executed in the "
2700 "following circumstances:"
2704 #: build/C/man3/pthread_cleanup_push.3:73
2706 "When a thread is canceled, all of the stacked clean-up handlers are popped "
2707 "and executed in the reverse of the order in which they were pushed onto the "
2712 #: build/C/man3/pthread_cleanup_push.3:83
2714 "When a thread terminates by calling B<pthread_exit>(3), all clean-up "
2715 "handlers are executed as described in the preceding point. (Clean-up "
2716 "handlers are I<not> called if the thread terminates by performing a "
2717 "I<return> from the thread start function.)"
2721 #: build/C/man3/pthread_cleanup_push.3:89
2723 "When a thread calls B<pthread_cleanup_pop>() with a nonzero I<execute> "
2724 "argument, the top-most clean-up handler is popped and executed."
2728 #: build/C/man3/pthread_cleanup_push.3:101
2730 "POSIX.1 permits B<pthread_cleanup_push>() and B<pthread_cleanup_pop>() to "
2731 "be implemented as macros that expand to text containing \\(aqB<{>\\(aq and "
2732 "\\(aqB<}>\\(aq, respectively. For this reason, the caller must ensure that "
2733 "calls to these functions are paired within the same function, and at the "
2734 "same lexical nesting level. (In other words, a clean-up handler is "
2735 "established only during the execution of a specified section of code.)"
2739 #: build/C/man3/pthread_cleanup_push.3:121
2741 "Calling B<longjmp>(3) (B<siglongjmp>(3)) produces undefined results if any "
2742 "call has been made to B<pthread_cleanup_push>() or B<pthread_cleanup_pop>() "
2743 "without the matching call of the pair since the jump buffer was filled by "
2744 "B<setjmp>(3) (B<sigsetjmp>(3)). Likewise, calling B<longjmp>(3) "
2745 "(B<siglongjmp>(3)) from inside a clean-up handler produces undefined "
2746 "results unless the jump buffer was also filled by B<setjmp>(3) "
2747 "(B<sigsetjmp>(3)) inside the handler."
2751 #: build/C/man3/pthread_cleanup_push.3:123
2752 msgid "These functions do not return a value."
2756 #. Available since glibc 2.0
2758 #: build/C/man3/pthread_cleanup_push.3:127
2759 msgid "There are no errors."
2763 #: build/C/man3/pthread_cleanup_push.3:140
2765 "On Linux, the B<pthread_cleanup_push>() and B<pthread_cleanup_pop>() "
2766 "functions I<are> implemented as macros that expand to text containing "
2767 "\\(aqB<{>\\(aq and \\(aqB<}>\\(aq, respectively. This means that variables "
2768 "declared within the scope of paired calls to these functions will be visible "
2769 "within only that scope."
2772 #. The text was actually added in the 2004 TC2
2774 #: build/C/man3/pthread_cleanup_push.3:155
2776 "POSIX.1 says that the effect of using I<return>, I<break>, I<continue>, or "
2777 "I<goto> to prematurely leave a block bracketed B<pthread_cleanup_push>() "
2778 "and B<pthread_cleanup_pop>() is undefined. Portable applications should "
2783 #: build/C/man3/pthread_cleanup_push.3:170
2785 "The program below provides a simple example of the use of the functions "
2786 "described in this page. The program creates a thread that executes a loop "
2787 "bracketed by B<pthread_cleanup_push>() and B<pthread_cleanup_pop>(). This "
2788 "loop increments a global variable, I<cnt>, once each second. Depending on "
2789 "what command-line arguments are supplied, the main thread sends the other "
2790 "thread a cancellation request, or sets a global variable that causes the "
2791 "other thread to exit its loop and terminate normally (by doing a I<return>)."
2795 #: build/C/man3/pthread_cleanup_push.3:173
2797 "In the following shell session, the main thread sends a cancellation request "
2798 "to the other thread:"
2802 #: build/C/man3/pthread_cleanup_push.3:183
2806 "New thread started\n"
2809 "Canceling thread\n"
2810 "Called clean-up handler\n"
2811 "Thread was canceled; cnt = 0\n"
2815 #: build/C/man3/pthread_cleanup_push.3:191
2817 "From the above, we see that the thread was canceled, and that the "
2818 "cancellation clean-up handler was called and it reset the value of the "
2819 "global variable I<cnt> to 0."
2823 #: build/C/man3/pthread_cleanup_push.3:194
2825 "In the next run, the main program sets a global variable that causes other "
2826 "thread to terminate normally:"
2830 #: build/C/man3/pthread_cleanup_push.3:202
2834 "New thread started\n"
2837 "Thread terminated normally; cnt = 2\n"
2841 #: build/C/man3/pthread_cleanup_push.3:210
2843 "From the above, we see that the clean-up handler was not executed (because "
2844 "I<cleanup_pop_arg> was 0), and therefore the value of I<cnt> was not reset."
2848 #: build/C/man3/pthread_cleanup_push.3:215
2850 "In the next run, the main program sets a global variable that causes the "
2851 "other thread to terminate normally, and supplies a nonzero value for "
2852 "I<cleanup_pop_arg>:"
2856 #: build/C/man3/pthread_cleanup_push.3:224
2859 "$ B<./a.out x 1>\n"
2860 "New thread started\n"
2863 "Called clean-up handler\n"
2864 "Thread terminated normally; cnt = 0\n"
2868 #: build/C/man3/pthread_cleanup_push.3:231
2870 "In the above, we see that although the thread was not canceled, the clean-up "
2871 "handler was executed, because the argument given to B<pthread_cleanup_pop>() "
2876 #: build/C/man3/pthread_cleanup_push.3:240
2879 "#include E<lt>pthread.hE<gt>\n"
2880 "#include E<lt>sys/types.hE<gt>\n"
2881 "#include E<lt>stdio.hE<gt>\n"
2882 "#include E<lt>stdlib.hE<gt>\n"
2883 "#include E<lt>unistd.hE<gt>\n"
2884 "#include E<lt>errno.hE<gt>\n"
2888 #: build/C/man3/pthread_cleanup_push.3:247
2891 "static int done = 0;\n"
2892 "static int cleanup_pop_arg = 0;\n"
2893 "static int cnt = 0;\n"
2897 #: build/C/man3/pthread_cleanup_push.3:254
2901 "cleanup_handler(void *arg)\n"
2903 " printf(\"Called clean-up handler\\en\");\n"
2909 #: build/C/man3/pthread_cleanup_push.3:259
2913 "thread_start(void *arg)\n"
2915 " time_t start, curr;\n"
2919 #: build/C/man3/pthread_cleanup_push.3:261
2921 msgid " printf(\"New thread started\\en\");\n"
2925 #: build/C/man3/pthread_cleanup_push.3:263
2927 msgid " pthread_cleanup_push(cleanup_handler, NULL);\n"
2931 #: build/C/man3/pthread_cleanup_push.3:265
2933 msgid " curr = start = time(NULL);\n"
2937 #: build/C/man3/pthread_cleanup_push.3:274
2940 " while (!done) {\n"
2941 " pthread_testcancel(); /* A cancellation point */\n"
2942 " if (curr E<lt> time(NULL)) {\n"
2943 " curr = time(NULL);\n"
2944 " printf(\"cnt = %d\\en\", cnt); /* A cancellation point */\n"
2951 #: build/C/man3/pthread_cleanup_push.3:278
2954 " pthread_cleanup_pop(cleanup_pop_arg);\n"
2960 #: build/C/man3/pthread_cleanup_push.3:285
2964 "main(int argc, char *argv[])\n"
2972 #: build/C/man3/pthread_cleanup_push.3:289
2975 " s = pthread_create(&thr, NULL, thread_start, NULL);\n"
2977 " handle_error_en(s, \"pthread_create\");\n"
2981 #: build/C/man3/pthread_cleanup_push.3:291
2983 msgid " sleep(2); /* Allow new thread to run a while */\n"
2987 #: build/C/man3/pthread_cleanup_push.3:296
2990 " if (argc E<gt> 1) {\n"
2991 " if (argc E<gt> 2)\n"
2992 " cleanup_pop_arg = atoi(argv[2]);\n"
2997 #: build/C/man3/pthread_cleanup_push.3:303
3001 " printf(\"Canceling thread\\en\");\n"
3002 " s = pthread_cancel(thr);\n"
3004 " handle_error_en(s, \"pthread_cancel\");\n"
3009 #: build/C/man3/pthread_cleanup_push.3:314
3012 " if (res == PTHREAD_CANCELED)\n"
3013 " printf(\"Thread was canceled; cnt = %d\\en\", cnt);\n"
3015 " printf(\"Thread terminated normally; cnt = %d\\en\", cnt);\n"
3016 " exit(EXIT_SUCCESS);\n"
3021 #: build/C/man3/pthread_cleanup_push.3:321
3023 "B<pthread_cancel>(3), B<pthread_cleanup_push_defer_np>(3), "
3024 "B<pthread_setcancelstate>(3), B<pthread_testcancel>(3), B<pthreads>(7)"
3028 #: build/C/man3/pthread_cleanup_push_defer_np.3:26
3030 msgid "PTHREAD_CLEANUP_PUSH_DEFER_NP"
3034 #: build/C/man3/pthread_cleanup_push_defer_np.3:30
3036 "pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np - push and pop "
3037 "thread cancellation clean-up handlers while saving cancelability type"
3041 #: build/C/man3/pthread_cleanup_push_defer_np.3:37
3044 "B<void pthread_cleanup_push_defer_np(void (*>I<routine>B<)(void *),>\n"
3045 "B< void *>I<arg>B<);>\n"
3046 "B<void pthread_cleanup_pop_restore_np(int >I<execute>B<);>\n"
3050 #: build/C/man3/pthread_cleanup_push_defer_np.3:40 build/C/man3/pthread_create.3:38 build/C/man3/pthread_detach.3:37 build/C/man3/pthread_join.3:37 build/C/man3/pthread_kill.3:37 build/C/man3/pthread_setname_np.3:39 build/C/man3/pthread_sigmask.3:38 build/C/man3/pthread_sigqueue.3:38 build/C/man3/pthread_tryjoin_np.3:42 build/C/man3/pthread_yield.3:37
3051 msgid "Compile and link with I<-pthread>."
3055 #: build/C/man3/pthread_cleanup_push_defer_np.3:49
3056 msgid "B<pthread_cleanup_push_defer_np>(), B<pthread_cleanup_pop_defer_np>():"
3060 #: build/C/man3/pthread_cleanup_push_defer_np.3:51
3065 #: build/C/man3/pthread_cleanup_push_defer_np.3:59
3067 "These functions are the same as B<pthread_cleanup_push>(3) and "
3068 "B<pthread_cleanup_pop>(3), except for the differences noted on this page."
3072 #: build/C/man3/pthread_cleanup_push_defer_np.3:72
3074 "Like B<pthread_cleanup_push>(3), B<pthread_cleanup_push_defer_np>() pushes "
3075 "I<routine> onto the thread's stack of cancellation clean-up handlers. In "
3076 "addition, it also saves the thread's current cancelability type, and sets "
3077 "the cancelability type to \"deferred\" (see B<pthread_setcanceltype>(3)); "
3078 "this ensures that cancellation clean-up will occur even if the thread's "
3079 "cancelability type was \"asynchronous\" before the call."
3083 #: build/C/man3/pthread_cleanup_push_defer_np.3:81
3085 "Like B<pthread_cleanup_pop>(3), B<pthread_cleanup_pop_restore_np>() pops "
3086 "the top-most clean-up handler from the thread's stack of cancellation "
3087 "clean-up handlers. In addition, it restores the thread's cancelability type "
3088 "to its value at the time of the matching B<pthread_cleanup_push_defer_np>()."
3092 #: build/C/man3/pthread_cleanup_push_defer_np.3:87
3094 "The caller must ensure that calls to these functions are paired within the "
3095 "same function, and at the same lexical nesting level. Other restrictions "
3096 "apply, as described in B<pthread_cleanup_push>(3)."
3100 #: build/C/man3/pthread_cleanup_push_defer_np.3:89
3101 msgid "This sequence of calls:"
3105 #: build/C/man3/pthread_cleanup_push_defer_np.3:94
3108 "pthread_cleanup_push_defer_np(routine, arg);\n"
3109 "pthread_cleanup_pop_restore_np(execute);\n"
3113 #: build/C/man3/pthread_cleanup_push_defer_np.3:98
3114 msgid "is equivalent to (but shorter and more efficient than):"
3118 #: build/C/man3/pthread_cleanup_push_defer_np.3:104
3120 msgid "int oldtype;\n"
3124 #: build/C/man3/pthread_cleanup_push_defer_np.3:110
3127 "pthread_cleanup_push(routine, arg);\n"
3128 "pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);\n"
3130 "pthread_setcanceltype(oldtype, NULL);\n"
3131 "pthread_cleanup_pop(execute);\n"
3135 #: build/C/man3/pthread_cleanup_push_defer_np.3:123
3137 "B<pthread_cancel>(3), B<pthread_cleanup_push>(3), "
3138 "B<pthread_setcancelstate>(3), B<pthread_testcancel>(3), B<pthreads>(7)"
3142 #: build/C/man3/pthread_create.3:26
3144 msgid "PTHREAD_CREATE"
3148 #: build/C/man3/pthread_create.3:29
3149 msgid "pthread_create - create a new thread"
3153 #: build/C/man3/pthread_create.3:35
3156 "B<int pthread_create(pthread_t *>I<thread>B<, const pthread_attr_t "
3158 "B< void *(*>I<start_routine>B<) (void *), void "
3163 #: build/C/man3/pthread_create.3:47
3165 "The B<pthread_create>() function starts a new thread in the calling "
3166 "process. The new thread starts execution by invoking I<start_routine>(); "
3167 "I<arg> is passed as the sole argument of I<start_routine>()."
3171 #: build/C/man3/pthread_create.3:49
3172 msgid "The new thread terminates in one of the following ways:"
3176 #: build/C/man3/pthread_create.3:49 build/C/man3/pthread_create.3:55 build/C/man3/pthread_create.3:63 build/C/man3/pthread_create.3:66 build/C/man3/pthread_getattr_np.3:52 build/C/man3/pthread_getattr_np.3:55 build/C/man3/pthread_getattr_np.3:58
3182 #: build/C/man3/pthread_create.3:55
3184 "It calls B<pthread_exit>(3), specifying an exit status value that is "
3185 "available to another thread in the same process that calls "
3186 "B<pthread_join>(3)."
3190 #: build/C/man3/pthread_create.3:63
3192 "It returns from I<start_routine>(). This is equivalent to calling "
3193 "B<pthread_exit>(3) with the value supplied in the I<return> statement."
3197 #: build/C/man3/pthread_create.3:66
3198 msgid "It is canceled (see B<pthread_cancel>(3))."
3202 #: build/C/man3/pthread_create.3:72
3204 "Any of the threads in the process calls B<exit>(3), or the main thread "
3205 "performs a return from I<main>(). This causes the termination of all "
3206 "threads in the process."
3210 #: build/C/man3/pthread_create.3:86
3212 "The I<attr> argument points to a I<pthread_attr_t> structure whose contents "
3213 "are used at thread creation time to determine attributes for the new thread; "
3214 "this structure is initialized using B<pthread_attr_init>(3) and related "
3215 "functions. If I<attr> is NULL, then the thread is created with default "
3220 #: build/C/man3/pthread_create.3:93
3222 "Before returning, a successful call to B<pthread_create>() stores the ID of "
3223 "the new thread in the buffer pointed to by I<thread>; this identifier is "
3224 "used to refer to the thread in subsequent calls to other pthreads functions."
3228 #: build/C/man3/pthread_create.3:101
3230 "The new thread inherits a copy of the creating thread's signal mask "
3231 "(B<pthread_sigmask>(3)). The set of pending signals for the new thread is "
3232 "empty (B<sigpending>(2)). The new thread does not inherit the creating "
3233 "thread's alternate signal stack (B<sigaltstack>(2))."
3237 #: build/C/man3/pthread_create.3:104
3239 "The new thread inherits the calling thread's floating-point environment "
3243 #. CLOCK_THREAD_CPUTIME_ID in clock_gettime(2)
3245 #: build/C/man3/pthread_create.3:109
3247 "The initial value of the new thread's CPU-time clock is 0 (see "
3248 "B<pthread_getcpuclockid>(3))."
3252 #: build/C/man3/pthread_create.3:109
3254 msgid "Linux-specific details"
3258 #: build/C/man3/pthread_create.3:115
3260 "The new thread inherits copies of the calling thread's capability sets (see "
3261 "B<capabilities>(7)) and CPU affinity mask (see B<sched_setaffinity>(2))."
3265 #: build/C/man3/pthread_create.3:122
3267 "On success, B<pthread_create>() returns 0; on error, it returns an error "
3268 "number, and the contents of I<*thread> are undefined."
3272 #: build/C/man3/pthread_create.3:123 build/C/man3/pthread_create.3:126 build/C/man3/pthread_sigqueue.3:72
3278 #: build/C/man3/pthread_create.3:126
3279 msgid "Insufficient resources to create another thread."
3282 #. NOTE! The following should match the description in fork(2)
3284 #: build/C/man3/pthread_create.3:144
3286 "A system-imposed limit on the number of threads was encountered. There are "
3287 "a number of limits that may trigger this error: the B<RLIMIT_NPROC> soft "
3288 "resource limit (set via B<setrlimit>(2)), which limits the number of "
3289 "processes and threads for a real user ID, was reached; the kernel's "
3290 "system-wide limit on the number of processes and threads, "
3291 "I</proc/sys/kernel/threads-max>, was reached (see B<proc>(5)); or the "
3292 "maximum number of PIDs, I</proc/sys/kernel/pid_max>, was reached (see "
3297 #: build/C/man3/pthread_create.3:148
3298 msgid "Invalid settings in I<attr>."
3302 #: build/C/man3/pthread_create.3:148 build/C/man3/pthread_setschedparam.3:129 build/C/man3/pthread_setschedprio.3:66
3308 #: build/C/man3/pthread_create.3:153
3310 "No permission to set the scheduling policy and parameters specified in "
3315 #: build/C/man3/pthread_create.3:167
3317 "See B<pthread_self>(3) for further information on the thread ID returned in "
3318 "I<*thread> by B<pthread_create>(). Unless real-time scheduling policies are "
3319 "being employed, after a call to B<pthread_create>(), it is indeterminate "
3320 "which thread\\(emthe caller or the new thread\\(emwill next execute."
3324 #: build/C/man3/pthread_create.3:187
3326 "A thread may either be I<joinable> or I<detached>. If a thread is joinable, "
3327 "then another thread can call B<pthread_join>(3) to wait for the thread to "
3328 "terminate and fetch its exit status. Only when a terminated joinable thread "
3329 "has been joined are the last of its resources released back to the system. "
3330 "When a detached thread terminates, its resources are automatically released "
3331 "back to the system: it is not possible to join with the thread in order to "
3332 "obtain its exit status. Making a thread detached is useful for some types "
3333 "of daemon threads whose exit status the application does not need to care "
3334 "about. By default, a new thread is created in a joinable state, unless "
3335 "I<attr> was set to create the thread in a detached state (using "
3336 "B<pthread_attr_setdetachstate>(3))."
3339 #. FIXME . Perhaps some of the following detail should be in
3340 #. a future pthread_attr_setstacksize(3) page.
3342 #: build/C/man3/pthread_create.3:203
3344 "On Linux/x86-32, the default stack size for a new thread is 2 megabytes. "
3345 "Under the NPTL threading implementation, if the B<RLIMIT_STACK> soft "
3346 "resource limit I<at the time the program started> has any value other than "
3347 "\"unlimited\", then it determines the default stack size of new threads. "
3348 "Using B<pthread_attr_setstacksize>(3), the stack size attribute can be "
3349 "explicitly set in the I<attr> argument used to create a thread, in order to "
3350 "obtain a stack size other than the default."
3354 #: build/C/man3/pthread_create.3:209
3356 "In the obsolete LinuxThreads implementation, each of the threads in a "
3357 "process has a different process ID. This is in violation of the POSIX "
3358 "threads specification, and is the source of many other nonconformances to "
3359 "the standard; see B<pthreads>(7)."
3363 #: build/C/man3/pthread_create.3:213
3365 "The program below demonstrates the use of B<pthread_create>(), as well as a "
3366 "number of other functions in the pthreads API."
3370 #: build/C/man3/pthread_create.3:218
3372 "In the following run, on a system providing the NPTL threading "
3373 "implementation, the stack size defaults to the value given by the \"stack "
3374 "size\" resource limit:"
3378 #: build/C/man3/pthread_create.3:230
3382 "8192 # The stack size limit is 8 MB (0x800000 bytes)\n"
3383 "$B< ./a.out hola salut servus>\n"
3384 "Thread 1: top of stack near 0xb7dd03b8; argv_string=hola\n"
3385 "Thread 2: top of stack near 0xb75cf3b8; argv_string=salut\n"
3386 "Thread 3: top of stack near 0xb6dce3b8; argv_string=servus\n"
3387 "Joined with thread 1; returned value was HOLA\n"
3388 "Joined with thread 2; returned value was SALUT\n"
3389 "Joined with thread 3; returned value was SERVUS\n"
3393 #: build/C/man3/pthread_create.3:236
3395 "In the next run, the program explicitly sets a stack size of 1MB (using "
3396 "B<pthread_attr_setstacksize>(3)) for the created threads:"
3400 #: build/C/man3/pthread_create.3:246
3403 "$B< ./a.out -s 0x100000 hola salut servus>\n"
3404 "Thread 1: top of stack near 0xb7d723b8; argv_string=hola\n"
3405 "Thread 2: top of stack near 0xb7c713b8; argv_string=salut\n"
3406 "Thread 3: top of stack near 0xb7b703b8; argv_string=servus\n"
3407 "Joined with thread 1; returned value was HOLA\n"
3408 "Joined with thread 2; returned value was SALUT\n"
3409 "Joined with thread 3; returned value was SERVUS\n"
3413 #: build/C/man3/pthread_create.3:258
3416 "#include E<lt>pthread.hE<gt>\n"
3417 "#include E<lt>string.hE<gt>\n"
3418 "#include E<lt>stdio.hE<gt>\n"
3419 "#include E<lt>stdlib.hE<gt>\n"
3420 "#include E<lt>unistd.hE<gt>\n"
3421 "#include E<lt>errno.hE<gt>\n"
3422 "#include E<lt>ctype.hE<gt>\n"
3426 #: build/C/man3/pthread_create.3:264 build/C/man3/pthread_getcpuclockid.3:116
3429 "#define handle_error(msg) \\e\n"
3430 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
3434 #: build/C/man3/pthread_create.3:270
3437 "struct thread_info { /* Used as argument to thread_start() */\n"
3438 " pthread_t thread_id; /* ID returned by pthread_create() */\n"
3439 " int thread_num; /* Application-defined thread # */\n"
3440 " char *argv_string; /* From command-line argument */\n"
3445 #: build/C/man3/pthread_create.3:273
3448 "/* Thread start function: display address near top of our stack,\n"
3449 " and return upper-cased copy of argv_string */\n"
3453 #: build/C/man3/pthread_create.3:279
3457 "thread_start(void *arg)\n"
3459 " struct thread_info *tinfo = arg;\n"
3460 " char *uargv, *p;\n"
3464 #: build/C/man3/pthread_create.3:282
3467 " printf(\"Thread %d: top of stack near %p; argv_string=%s\\en\",\n"
3468 " tinfo-E<gt>thread_num, &p, tinfo-E<gt>argv_string);\n"
3472 #: build/C/man3/pthread_create.3:286
3475 " uargv = strdup(tinfo-E<gt>argv_string);\n"
3476 " if (uargv == NULL)\n"
3477 " handle_error(\"strdup\");\n"
3481 #: build/C/man3/pthread_create.3:289
3484 " for (p = uargv; *p != \\(aq\\e0\\(aq; p++)\n"
3485 " *p = toupper(*p);\n"
3489 #: build/C/man3/pthread_create.3:292
3497 #: build/C/man3/pthread_create.3:301
3501 "main(int argc, char *argv[])\n"
3503 " int s, tnum, opt, num_threads;\n"
3504 " struct thread_info *tinfo;\n"
3505 " pthread_attr_t attr;\n"
3506 " int stack_size;\n"
3511 #: build/C/man3/pthread_create.3:303
3513 msgid " /* The \"-s\" option specifies a stack size for our threads */\n"
3517 #: build/C/man3/pthread_create.3:310
3520 " stack_size = -1;\n"
3521 " while ((opt = getopt(argc, argv, \"s:\")) != -1) {\n"
3523 " case \\(aqs\\(aq:\n"
3524 " stack_size = strtoul(optarg, NULL, 0);\n"
3529 #: build/C/man3/pthread_create.3:317
3533 " fprintf(stderr, \"Usage: %s [-s stack-size] arg...\\en\",\n"
3535 " exit(EXIT_FAILURE);\n"
3541 #: build/C/man3/pthread_create.3:319
3543 msgid " num_threads = argc - optind;\n"
3547 #: build/C/man3/pthread_create.3:321
3549 msgid " /* Initialize thread creation attributes */\n"
3553 #: build/C/man3/pthread_create.3:325
3556 " s = pthread_attr_init(&attr);\n"
3558 " handle_error_en(s, \"pthread_attr_init\");\n"
3562 #: build/C/man3/pthread_create.3:331
3565 " if (stack_size E<gt> 0) {\n"
3566 " s = pthread_attr_setstacksize(&attr, stack_size);\n"
3568 " handle_error_en(s, \"pthread_attr_setstacksize\");\n"
3573 #: build/C/man3/pthread_create.3:333
3575 msgid " /* Allocate memory for pthread_create() arguments */\n"
3579 #: build/C/man3/pthread_create.3:337
3582 " tinfo = calloc(num_threads, sizeof(struct thread_info));\n"
3583 " if (tinfo == NULL)\n"
3584 " handle_error(\"calloc\");\n"
3588 #: build/C/man3/pthread_create.3:339
3590 msgid " /* Create one thread for each command-line argument */\n"
3594 #: build/C/man3/pthread_create.3:343
3597 " for (tnum = 0; tnum E<lt> num_threads; tnum++) {\n"
3598 " tinfo[tnum].thread_num = tnum + 1;\n"
3599 " tinfo[tnum].argv_string = argv[optind + tnum];\n"
3603 #: build/C/man3/pthread_create.3:346
3606 " /* The pthread_create() call stores the thread ID into\n"
3607 " corresponding element of tinfo[] */\n"
3611 #: build/C/man3/pthread_create.3:352
3614 " s = pthread_create(&tinfo[tnum].thread_id, &attr,\n"
3615 " &thread_start, &tinfo[tnum]);\n"
3617 " handle_error_en(s, \"pthread_create\");\n"
3622 #: build/C/man3/pthread_create.3:355
3625 " /* Destroy the thread attributes object, since it is no\n"
3626 " longer needed */\n"
3630 #: build/C/man3/pthread_create.3:359
3633 " s = pthread_attr_destroy(&attr);\n"
3635 " handle_error_en(s, \"pthread_attr_destroy\");\n"
3639 #: build/C/man3/pthread_create.3:361
3641 msgid " /* Now join with each thread, and display its returned value */\n"
3645 #: build/C/man3/pthread_create.3:366
3648 " for (tnum = 0; tnum E<lt> num_threads; tnum++) {\n"
3649 " s = pthread_join(tinfo[tnum].thread_id, &res);\n"
3651 " handle_error_en(s, \"pthread_join\");\n"
3655 #: build/C/man3/pthread_create.3:371
3658 " printf(\"Joined with thread %d; returned value was %s\\en\",\n"
3659 " tinfo[tnum].thread_num, (char *) res);\n"
3660 " free(res); /* Free memory allocated by thread */\n"
3665 #: build/C/man3/pthread_create.3:375
3669 " exit(EXIT_SUCCESS);\n"
3674 #: build/C/man3/pthread_create.3:389
3676 "B<getrlimit>(2), B<pthread_attr_init>(3), B<pthread_cancel>(3), "
3677 "B<pthread_detach>(3), B<pthread_equal>(3), B<pthread_exit>(3), "
3678 "B<pthread_getattr_np>(3), B<pthread_join>(3), B<pthread_self>(3), "
3683 #: build/C/man3/pthread_detach.3:26
3685 msgid "PTHREAD_DETACH"
3689 #: build/C/man3/pthread_detach.3:26 build/C/man3/pthread_join.3:26
3695 #: build/C/man3/pthread_detach.3:29
3696 msgid "pthread_detach - detach a thread"
3700 #: build/C/man3/pthread_detach.3:34
3702 msgid "B<int pthread_detach(pthread_t >I<thread>B<);>\n"
3706 #: build/C/man3/pthread_detach.3:46
3708 "The B<pthread_detach>() function marks the thread identified by I<thread> "
3709 "as detached. When a detached thread terminates, its resources are "
3710 "automatically released back to the system without the need for another "
3711 "thread to join with the terminated thread."
3715 #: build/C/man3/pthread_detach.3:49
3717 "Attempting to detach an already detached thread results in unspecified "
3722 #: build/C/man3/pthread_detach.3:54
3724 "On success, B<pthread_detach>() returns 0; on error, it returns an error "
3729 #: build/C/man3/pthread_detach.3:59 build/C/man3/pthread_join.3:89
3730 msgid "I<thread> is not a joinable thread."
3734 #: build/C/man3/pthread_detach.3:70
3736 "Once a thread has been detached, it can't be joined with B<pthread_join>(3) "
3737 "or be made joinable again."
3741 #: build/C/man3/pthread_detach.3:77
3743 "A new thread can be created in a detached state using "
3744 "B<pthread_attr_setdetachstate>(3) to set the detached attribute of the "
3745 "I<attr> argument of B<pthread_create>(3)."
3749 #: build/C/man3/pthread_detach.3:84
3751 "The detached attribute merely determines the behavior of the system when the "
3752 "thread terminates; it does not prevent the thread from being terminated if "
3753 "the process terminates using B<exit>(3) (or equivalently, if the main "
3758 #: build/C/man3/pthread_detach.3:93
3760 "Either B<pthread_join>(3) or B<pthread_detach>() should be called for each "
3761 "thread that an application creates, so that system resources for the thread "
3762 "can be released. (But note that the resources of all threads are freed when "
3763 "the process terminates.)"
3767 #: build/C/man3/pthread_detach.3:95
3768 msgid "The following statement detaches the calling thread:"
3772 #: build/C/man3/pthread_detach.3:97
3774 msgid " pthread_detach(pthread_self());\n"
3778 #: build/C/man3/pthread_detach.3:104
3780 "B<pthread_attr_setdetachstate>(3), B<pthread_cancel>(3), "
3781 "B<pthread_create>(3), B<pthread_exit>(3), B<pthread_join>(3), B<pthreads>(7)"
3785 #: build/C/man3/pthread_equal.3:26
3787 msgid "PTHREAD_EQUAL"
3791 #: build/C/man3/pthread_equal.3:26 build/C/man3/pthread_exit.3:26 build/C/man3/pthread_getcpuclockid.3:26 build/C/man3/pthread_setaffinity_np.3:26 build/C/man3/pthread_setconcurrency.3:25
3797 #: build/C/man3/pthread_equal.3:29
3798 msgid "pthread_equal - compare thread IDs"
3802 #: build/C/man3/pthread_equal.3:34
3804 msgid "B<int pthread_equal(pthread_t >I<t1>B<, pthread_t >I<t2>B<);>\n"
3808 #: build/C/man3/pthread_equal.3:41
3809 msgid "The B<pthread_equal>() function compares two thread identifiers."
3813 #: build/C/man3/pthread_equal.3:45
3815 "If the two thread IDs are equal, B<pthread_equal>() returns a nonzero "
3816 "value; otherwise, it returns 0."
3820 #. Available since glibc 2.0
3822 #: build/C/man3/pthread_equal.3:47 build/C/man3/pthread_exit.3:75 build/C/man3/pthread_self.3:50 build/C/man3/pthread_testcancel.3:58
3823 msgid "This function always succeeds."
3827 #: build/C/man3/pthread_equal.3:52
3828 msgid "The B<pthread_equal>() function is thread-safe."
3832 #: build/C/man3/pthread_equal.3:61
3834 "The B<pthread_equal>() function is necessary because thread IDs should be "
3835 "considered opaque: there is no portable way for applications to directly "
3836 "compare two I<pthread_t> values."
3840 #: build/C/man3/pthread_equal.3:65
3841 msgid "B<pthread_create>(3), B<pthread_self>(3), B<pthreads>(7)"
3845 #: build/C/man3/pthread_exit.3:26
3847 msgid "PTHREAD_EXIT"
3851 #: build/C/man3/pthread_exit.3:29
3852 msgid "pthread_exit - terminate calling thread"
3856 #: build/C/man3/pthread_exit.3:34
3858 msgid "B<void pthread_exit(void *>I<retval>B<);>\n"
3862 #: build/C/man3/pthread_exit.3:45
3864 "The B<pthread_exit>() function terminates the calling thread and returns a "
3865 "value via I<retval> that (if the thread is joinable) is available to "
3866 "another thread in the same process that calls B<pthread_join>(3)."
3870 #: build/C/man3/pthread_exit.3:55
3872 "Any clean-up handlers established by B<pthread_cleanup_push>(3) that have "
3873 "not yet been popped, are popped (in the reverse of the order in which they "
3874 "were pushed) and executed. If the thread has any thread-specific data, "
3875 "then, after the clean-up handlers have been executed, the corresponding "
3876 "destructor functions are called, in an unspecified order."
3880 #: build/C/man3/pthread_exit.3:62
3882 "When a thread terminates, process-shared resources (e.g., mutexes, condition "
3883 "variables, semaphores, and file descriptors) are not released, and functions "
3884 "registered using B<atexit>(3) are not called."
3888 #: build/C/man3/pthread_exit.3:71
3890 "After the last thread in a process terminates, the process terminates as by "
3891 "calling B<exit>(3) with an exit status of zero; thus, process-shared "
3892 "resources are released and functions registered using B<atexit>(3) are "
3897 #: build/C/man3/pthread_exit.3:73
3898 msgid "This function does not return to the caller."
3902 #: build/C/man3/pthread_exit.3:80
3903 msgid "The B<pthread_exit>() function is thread-safe."
3907 #: build/C/man3/pthread_exit.3:87
3909 "Performing a return from the start function of any thread other than the "
3910 "main thread results in an implicit call to B<pthread_exit>(), using the "
3911 "function's return value as the thread's exit status."
3915 #: build/C/man3/pthread_exit.3:93
3917 "To allow other threads to continue execution, the main thread should "
3918 "terminate by calling B<pthread_exit>() rather than B<exit>(3)."
3922 #: build/C/man3/pthread_exit.3:98
3924 "The value pointed to by I<retval> should not be located on the calling "
3925 "thread's stack, since the contents of that stack are undefined after the "
3926 "thread terminates."
3930 #. FIXME . review a later kernel to see if this gets fixed
3931 #. http://thread.gmane.org/gmane.linux.kernel/611611
3932 #. http://marc.info/?l=linux-kernel&m=122525468300823&w=2
3934 #: build/C/man3/pthread_exit.3:110
3936 "Currently, there are limitations in the kernel implementation logic for "
3937 "B<wait>(2)ing on a stopped thread group with a dead thread group leader. "
3938 "This can manifest in problems such as a locked terminal if a stop signal is "
3939 "sent to a foreground process whose thread group leader has already called "
3940 "B<pthread_exit>()."
3944 #: build/C/man3/pthread_exit.3:114
3945 msgid "B<pthread_create>(3), B<pthread_join>(3), B<pthreads>(7)"
3949 #: build/C/man3/pthread_getattr_np.3:26
3951 msgid "PTHREAD_GETATTR_NP"
3955 #: build/C/man3/pthread_getattr_np.3:26
3961 #: build/C/man3/pthread_getattr_np.3:29
3962 msgid "pthread_getattr_np - get attributes of created thread"
3966 #: build/C/man3/pthread_getattr_np.3:35
3969 "B<int pthread_getattr_np(pthread_t >I<thread>B<, pthread_attr_t "
3974 #: build/C/man3/pthread_getattr_np.3:45
3976 "The B<pthread_getattr_np>() function initializes the thread attributes "
3977 "object referred to by I<attr> so that it contains actual attribute values "
3978 "describing the running thread I<thread>."
3982 #: build/C/man3/pthread_getattr_np.3:52
3984 "The returned attribute values may differ from the corresponding attribute "
3985 "values passed in the I<attr> object that was used to create the thread using "
3986 "B<pthread_create>(3). In particular, the following attributes may differ:"
3990 #: build/C/man3/pthread_getattr_np.3:55
3992 "the detach state, since a joinable thread may have detached itself after "
3997 #: build/C/man3/pthread_getattr_np.3:58
3998 msgid "the stack size, which the implementation may align to a suitable boundary."
4002 #: build/C/man3/pthread_getattr_np.3:63
4004 "and the guard size, which the implementation may round upward to a multiple "
4005 "of the page size, or ignore (i.e., treat as 0), if the application is "
4006 "allocating its own stack."
4010 #: build/C/man3/pthread_getattr_np.3:68
4012 "Furthermore, if the stack address attribute was not set in the thread "
4013 "attributes object used to create the thread, then the returned thread "
4014 "attributes object will report the actual stack address that the "
4015 "implementation selected for the thread."
4019 #: build/C/man3/pthread_getattr_np.3:73
4021 "When the thread attributes object returned by B<pthread_getattr_np>() is no "
4022 "longer required, it should be destroyed using B<pthread_attr_destroy>(3)."
4026 #: build/C/man3/pthread_getattr_np.3:76 build/C/man3/pthread_getcpuclockid.3:49
4028 "On success, this function returns 0; on error, it returns a nonzero error "
4032 #. Can happen (but unlikely) while trying to allocate memory for cpuset
4034 #: build/C/man3/pthread_getattr_np.3:81
4035 msgid "Insufficient memory."
4039 #: build/C/man3/pthread_getattr_np.3:96
4041 "In addition, if I<thread> refers to the main thread, then "
4042 "B<pthread_getattr_np>() can fail because of errors from various underlying "
4043 "calls: B<fopen>(3), if I</proc/self/maps> can't be opened; and "
4044 "B<getrlimit>(2), if the B<RLIMIT_STACK> resource limit is not supported."
4048 #: build/C/man3/pthread_getattr_np.3:98
4049 msgid "This function is available in glibc since version 2.2.3."
4053 #: build/C/man3/pthread_getattr_np.3:101 build/C/man3/pthread_kill_other_threads_np.3:55
4055 "This function is a nonstandard GNU extension; hence the suffix \"_np\" "
4056 "(nonportable) in the name."
4060 #: build/C/man3/pthread_getattr_np.3:111
4062 "The program below demonstrates the use of B<pthread_getattr_np>(). The "
4063 "program creates a thread that then uses B<pthread_getattr_np>() to retrieve "
4064 "and display its guard size, stack address, and stack size attributes. "
4065 "Command-line arguments can be used to set these attributes to values other "
4066 "than the default when creating the thread. The shell sessions below "
4067 "demonstrate the use of the program."
4071 #: build/C/man3/pthread_getattr_np.3:114
4073 "In the first run, on an x86-32 system, a thread is created using default "
4078 #: build/C/man3/pthread_getattr_np.3:124
4081 "$B< ulimit -s> # No stack limit ==E<gt> default stack size is 2MB\n"
4084 "Attributes of created thread:\n"
4085 " Guard size = 4096 bytes\n"
4086 " Stack address = 0x40196000 (EOS = 0x40397000)\n"
4087 " Stack size = 0x201000 (2101248) bytes\n"
4091 #: build/C/man3/pthread_getattr_np.3:130
4093 "In the following run, we see that if a guard size is specified, it is "
4094 "rounded up to the next multiple of the system page size (4096 bytes on "
4099 #: build/C/man3/pthread_getattr_np.3:138
4102 "$B< ./a.out -g 4097>\n"
4103 "Thread attributes object after initializations:\n"
4104 " Guard size = 4097 bytes\n"
4105 " Stack address = (nil)\n"
4106 " Stack size = 0x0 (0) bytes\n"
4110 #: build/C/man3/pthread_getattr_np.3:143
4113 "Attributes of created thread:\n"
4114 " Guard size = 8192 bytes\n"
4115 " Stack address = 0x40196000 (EOS = 0x40397000)\n"
4116 " Stack size = 0x201000 (2101248) bytes\n"
4121 #. $ ./a.out \-s 0x8000
4122 #. Thread attributes object after initializations:
4123 #. Guard size = 4096 bytes
4124 #. Stack address = 0xffff8000 (EOS = (nil))
4125 #. Stack size = 0x8000 (32768) bytes
4127 #. Attributes of created thread:
4128 #. Guard size = 4096 bytes
4129 #. Stack address = 0x4001e000 (EOS = 0x40026000)
4130 #. Stack size = 0x8000 (32768) bytes
4134 #: build/C/man3/pthread_getattr_np.3:162
4136 "In the last run, the program manually allocates a stack for the thread. In "
4137 "this case, the guard size attribute is ignored."
4141 #: build/C/man3/pthread_getattr_np.3:167
4144 "$B< ./a.out -g 4096 -s 0x8000 -a>\n"
4145 "Allocated thread stack at 0x804d000\n"
4149 #: build/C/man3/pthread_getattr_np.3:172
4152 "Thread attributes object after initializations:\n"
4153 " Guard size = 4096 bytes\n"
4154 " Stack address = 0x804d000 (EOS = 0x8055000)\n"
4155 " Stack size = 0x8000 (32768) bytes\n"
4159 #: build/C/man3/pthread_getattr_np.3:177
4162 "Attributes of created thread:\n"
4163 " Guard size = 0 bytes\n"
4164 " Stack address = 0x804d000 (EOS = 0x8055000)\n"
4165 " Stack size = 0x8000 (32768) bytes\n"
4169 #: build/C/man3/pthread_getattr_np.3:198
4173 "display_stack_related_attributes(pthread_attr_t *attr, char *prefix)\n"
4176 " size_t stack_size, guard_size;\n"
4177 " void *stack_addr;\n"
4181 #: build/C/man3/pthread_getattr_np.3:203
4184 " s = pthread_attr_getguardsize(attr, &guard_size);\n"
4186 " handle_error_en(s, \"pthread_attr_getguardsize\");\n"
4187 " printf(\"%sGuard size = %d bytes\\en\", prefix, guard_size);\n"
4191 #: build/C/man3/pthread_getattr_np.3:214
4194 " s = pthread_attr_getstack(attr, &stack_addr, &stack_size);\n"
4196 " handle_error_en(s, \"pthread_attr_getstack\");\n"
4197 " printf(\"%sStack address = %p\", prefix, stack_addr);\n"
4198 " if (stack_size E<gt> 0)\n"
4199 " printf(\" (EOS = %p)\", (char *) stack_addr + stack_size);\n"
4200 " printf(\"\\en\");\n"
4201 " printf(\"%sStack size = 0x%x (%d) bytes\\en\",\n"
4202 " prefix, stack_size, stack_size);\n"
4207 #: build/C/man3/pthread_getattr_np.3:220
4211 "display_thread_attributes(pthread_t thread, char *prefix)\n"
4214 " pthread_attr_t attr;\n"
4218 #: build/C/man3/pthread_getattr_np.3:224
4221 " s = pthread_getattr_np(thread, &attr);\n"
4223 " handle_error_en(s, \"pthread_getattr_np\");\n"
4227 #: build/C/man3/pthread_getattr_np.3:226
4229 msgid " display_stack_related_attributes(&attr, prefix);\n"
4233 #: build/C/man3/pthread_getattr_np.3:231
4236 " s = pthread_attr_destroy(&attr);\n"
4238 " handle_error_en(s, \"pthread_attr_destroy\");\n"
4243 #: build/C/man3/pthread_getattr_np.3:237
4246 "static void * /* Start function for thread we create */\n"
4247 "thread_start(void *arg)\n"
4249 " printf(\"Attributes of created thread:\\en\");\n"
4250 " display_thread_attributes(pthread_self(), \"\\et\");\n"
4254 #: build/C/man3/pthread_getattr_np.3:251
4258 "usage(char *pname, char *msg)\n"
4260 " if (msg != NULL)\n"
4261 " fputs(msg, stderr);\n"
4262 " fprintf(stderr, \"Usage: %s [-s stack-size [-a]]\"\n"
4263 " \" [-g guard-size]\\en\", pname);\n"
4264 " fprintf(stderr, \"\\et\\et-a means program should allocate "
4266 " exit(EXIT_FAILURE);\n"
4271 #: build/C/man3/pthread_getattr_np.3:264
4274 "static pthread_attr_t * /* Get thread attributes from command line */\n"
4275 "get_thread_attributes_from_cl(int argc, char *argv[],\n"
4276 " pthread_attr_t *attrp)\n"
4278 " int s, opt, allocate_stack;\n"
4279 " long stack_size, guard_size;\n"
4280 " void *stack_addr;\n"
4281 " pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize\n"
4282 " a thread attributes object */\n"
4283 " allocate_stack = 0;\n"
4284 " stack_size = -1;\n"
4285 " guard_size = -1;\n"
4289 #: build/C/man3/pthread_getattr_np.3:273
4292 " while ((opt = getopt(argc, argv, \"ag:s:\")) != -1) {\n"
4294 " case \\(aqa\\(aq: allocate_stack = 1; break;\n"
4295 " case \\(aqg\\(aq: guard_size = strtoul(optarg, NULL, 0); break;\n"
4296 " case \\(aqs\\(aq: stack_size = strtoul(optarg, NULL, 0); break;\n"
4297 " default: usage(argv[0], NULL);\n"
4303 #: build/C/man3/pthread_getattr_np.3:276
4306 " if (allocate_stack && stack_size == -1)\n"
4307 " usage(argv[0], \"Specifying -a without -s makes no sense\\en\");\n"
4311 #: build/C/man3/pthread_getattr_np.3:279
4314 " if (argc E<gt> optind)\n"
4315 " usage(argv[0], \"Extraneous command-line arguments\\en\");\n"
4319 #: build/C/man3/pthread_getattr_np.3:282
4322 " if (stack_size E<gt>= 0 || guard_size E<gt> 0) {\n"
4323 " ret_attrp = attrp;\n"
4327 #: build/C/man3/pthread_getattr_np.3:287
4330 " s = pthread_attr_init(attrp);\n"
4332 " handle_error_en(s, \"pthread_attr_init\");\n"
4337 #: build/C/man3/pthread_getattr_np.3:299
4340 " if (stack_size E<gt>= 0) {\n"
4341 " if (!allocate_stack) {\n"
4342 " s = pthread_attr_setstacksize(attrp, stack_size);\n"
4344 " handle_error_en(s, \"pthread_attr_setstacksize\");\n"
4346 " s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),\n"
4349 " handle_error_en(s, \"posix_memalign\");\n"
4350 " printf(\"Allocated thread stack at %p\\en\\en\", stack_addr);\n"
4354 #: build/C/man3/pthread_getattr_np.3:305
4357 " s = pthread_attr_setstack(attrp, stack_addr, stack_size);\n"
4359 " handle_error_en(s, \"pthread_attr_setstacksize\");\n"
4365 #: build/C/man3/pthread_getattr_np.3:311
4368 " if (guard_size E<gt>= 0) {\n"
4369 " s = pthread_attr_setguardsize(attrp, guard_size);\n"
4371 " handle_error_en(s, \"pthread_attr_setstacksize\");\n"
4376 #: build/C/man3/pthread_getattr_np.3:314
4379 " return ret_attrp;\n"
4384 #: build/C/man3/pthread_getattr_np.3:323
4388 "main(int argc, char *argv[])\n"
4392 " pthread_attr_t attr;\n"
4393 " pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize\n"
4394 " a thread attributes object */\n"
4398 #: build/C/man3/pthread_getattr_np.3:325
4400 msgid " attrp = get_thread_attributes_from_cl(argc, argv, &attr);\n"
4404 #: build/C/man3/pthread_getattr_np.3:331
4407 " if (attrp != NULL) {\n"
4408 " printf(\"Thread attributes object after initializations:\\en\");\n"
4409 " display_stack_related_attributes(attrp, \"\\et\");\n"
4410 " printf(\"\\en\");\n"
4415 #: build/C/man3/pthread_getattr_np.3:361
4417 "B<pthread_attr_getaffinity_np>(3), B<pthread_attr_getdetachstate>(3), "
4418 "B<pthread_attr_getguardsize>(3), B<pthread_attr_getinheritsched>(3), "
4419 "B<pthread_attr_getschedparam>(3), B<pthread_attr_getschedpolicy>(3), "
4420 "B<pthread_attr_getscope>(3), B<pthread_attr_getstack>(3), "
4421 "B<pthread_attr_getstackaddr>(3), B<pthread_attr_getstacksize>(3), "
4422 "B<pthread_attr_init>(3), B<pthread_create>(3), B<pthreads>(7)"
4426 #: build/C/man3/pthread_getcpuclockid.3:26
4428 msgid "PTHREAD_GETCPUCLOCKID"
4432 #: build/C/man3/pthread_getcpuclockid.3:29
4433 msgid "pthread_getcpuclockid - retrieve ID of a thread's CPU time clock"
4437 #: build/C/man3/pthread_getcpuclockid.3:33
4440 "B<#include E<lt>pthread.hE<gt>>\n"
4441 "B<#include E<lt>time.hE<gt>>\n"
4445 #: build/C/man3/pthread_getcpuclockid.3:35
4448 "B<int pthread_getcpuclockid(pthread_t >I<thread>B<, clockid_t "
4449 "*>I<clock_id>B<);>\n"
4452 #. The clockid is constructed as follows:
4453 #. *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
4454 #. where CLOCK_IDFIELD_SIZE is 3.
4456 #: build/C/man3/pthread_getcpuclockid.3:46
4458 "The B<pthread_getcpuclockid>() function returns the clock ID for the CPU "
4459 "time clock of the thread I<thread>."
4463 #: build/C/man3/pthread_getcpuclockid.3:50
4468 #. CLOCK_THREAD_CPUTIME_ID not defined
4470 #. Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
4471 #. be possible if kernel thread IDs took more than 29 bits (which
4472 #. they currently cannot).
4474 #: build/C/man3/pthread_getcpuclockid.3:58
4475 msgid "Per-thread CPU time clocks are not supported by the system."
4479 #: build/C/man3/pthread_getcpuclockid.3:65
4480 msgid "This function is available in glibc since version 2.2."
4484 #: build/C/man3/pthread_getcpuclockid.3:70
4485 msgid "The B<pthread_getcpuclockid>() function is thread-safe."
4489 #: build/C/man3/pthread_getcpuclockid.3:83
4491 "When I<thread> refers to the calling thread, this function returns an "
4492 "identifier that refers to the same clock manipulated by B<clock_gettime>(2) "
4493 "and B<clock_settime>(2) when given the clock ID B<CLOCK_THREAD_CPUTIME_ID>."
4497 #: build/C/man3/pthread_getcpuclockid.3:89
4499 "The program below creates a thread and then uses B<clock_gettime>(2) to "
4500 "retrieve the total process CPU time, and the per-thread CPU time consumed by "
4501 "the two threads. The following shell session shows an example run:"
4505 #: build/C/man3/pthread_getcpuclockid.3:99
4509 "Main thread sleeping\n"
4510 "Subthread starting infinite loop\n"
4511 "Main thread consuming some CPU time...\n"
4512 "Process total CPU time: 1.368\n"
4513 "Main thread CPU time: 0.376\n"
4514 "Subthread CPU time: 0.992\n"
4518 #: build/C/man3/pthread_getcpuclockid.3:105
4520 msgid "/* Link with \"-lrt\" */\n"
4524 #: build/C/man3/pthread_getcpuclockid.3:113
4527 "#include E<lt>time.hE<gt>\n"
4528 "#include E<lt>stdio.hE<gt>\n"
4529 "#include E<lt>stdlib.hE<gt>\n"
4530 "#include E<lt>unistd.hE<gt>\n"
4531 "#include E<lt>pthread.hE<gt>\n"
4532 "#include E<lt>string.hE<gt>\n"
4533 "#include E<lt>errno.hE<gt>\n"
4537 #: build/C/man3/pthread_getcpuclockid.3:127
4541 "thread_start(void *arg)\n"
4543 " printf(\"Subthread starting infinite loop\\en\");\n"
4550 #: build/C/man3/pthread_getcpuclockid.3:132
4554 "pclock(char *msg, clockid_t cid)\n"
4556 " struct timespec ts;\n"
4560 #: build/C/man3/pthread_getcpuclockid.3:138
4563 " printf(\"%s\", msg);\n"
4564 " if (clock_gettime(cid, &ts) == -1)\n"
4565 " handle_error(\"clock_gettime\");\n"
4566 " printf(\"%4ld.%03ld\\en\", ts.tv_sec, ts.tv_nsec / 1000000);\n"
4571 #: build/C/man3/pthread_getcpuclockid.3:145
4575 "main(int argc, char *argv[])\n"
4577 " pthread_t thread;\n"
4583 #: build/C/man3/pthread_getcpuclockid.3:149
4586 " s = pthread_create(&thread, NULL, thread_start, NULL);\n"
4588 " handle_error_en(s, \"pthread_create\");\n"
4592 #: build/C/man3/pthread_getcpuclockid.3:152
4595 " printf(\"Main thread sleeping\\en\");\n"
4600 #: build/C/man3/pthread_getcpuclockid.3:156
4603 " printf(\"Main thread consuming some CPU time...\\en\");\n"
4604 " for (j = 0; j E<lt> 2000000; j++)\n"
4609 #: build/C/man3/pthread_getcpuclockid.3:158
4611 msgid " pclock(\"Process total CPU time: \", CLOCK_PROCESS_CPUTIME_ID);\n"
4615 #: build/C/man3/pthread_getcpuclockid.3:163
4618 " s = pthread_getcpuclockid(pthread_self(), &cid);\n"
4620 " handle_error_en(s, \"pthread_getcpuclockid\");\n"
4621 " pclock(\"Main thread CPU time: \", cid);\n"
4625 #: build/C/man3/pthread_getcpuclockid.3:166
4628 " /* The preceding 4 lines of code could have been replaced by:\n"
4629 " pclock(\"Main thread CPU time: \", CLOCK_THREAD_CPUTIME_ID); */\n"
4633 #: build/C/man3/pthread_getcpuclockid.3:171
4636 " s = pthread_getcpuclockid(thread, &cid);\n"
4638 " handle_error_en(s, \"pthread_getcpuclockid\");\n"
4639 " pclock(\"Subthread CPU time: 1 \", cid);\n"
4643 #: build/C/man3/pthread_getcpuclockid.3:174
4646 " exit(EXIT_SUCCESS); /* Terminates both threads */\n"
4651 #: build/C/man3/pthread_getcpuclockid.3:183
4653 "B<clock_gettime>(2), B<clock_settime>(2), B<timer_create>(2), "
4654 "B<clock_getcpuclockid>(3), B<pthread_self>(3), B<pthreads>(7), B<time>(7)"
4658 #: build/C/man3/pthread_join.3:26
4660 msgid "PTHREAD_JOIN"
4664 #: build/C/man3/pthread_join.3:29
4665 msgid "pthread_join - join with a terminated thread"
4669 #: build/C/man3/pthread_join.3:34
4671 msgid "B<int pthread_join(pthread_t >I<thread>B<, void **>I<retval>B<);>\n"
4675 #: build/C/man3/pthread_join.3:49
4677 "The B<pthread_join>() function waits for the thread specified by I<thread> "
4678 "to terminate. If that thread has already terminated, then B<pthread_join>() "
4679 "returns immediately. The thread specified by I<thread> must be joinable."
4683 #: build/C/man3/pthread_join.3:63
4685 "If I<retval> is not NULL, then B<pthread_join>() copies the exit status of "
4686 "the target thread (i.e., the value that the target thread supplied to "
4687 "B<pthread_exit>(3)) into the location pointed to by I<*retval>. If the "
4688 "target thread was canceled, then B<PTHREAD_CANCELED> is placed in "
4693 #: build/C/man3/pthread_join.3:70
4695 "If multiple threads simultaneously try to join with the same thread, the "
4696 "results are undefined. If the thread calling B<pthread_join>() is "
4697 "canceled, then the target thread will remain joinable (i.e., it will not be "
4702 #: build/C/man3/pthread_join.3:75
4704 "On success, B<pthread_join>() returns 0; on error, it returns an error "
4709 #: build/C/man3/pthread_join.3:76
4714 #. The following verified by testing on glibc 2.8/NPTL:
4715 #. The following verified by testing on glibc 2.8/NPTL:
4717 #: build/C/man3/pthread_join.3:85
4719 "A deadlock was detected (e.g., two threads tried to join with each other); "
4720 "or I<thread> specifies the calling thread."
4723 #. POSIX.1-2001 does not specify this error case.
4725 #: build/C/man3/pthread_join.3:93
4726 msgid "Another thread is already waiting to join with this thread."
4730 #: build/C/man3/pthread_join.3:104
4732 "After a successful call to B<pthread_join>(), the caller is guaranteed that "
4733 "the target thread has terminated."
4737 #: build/C/man3/pthread_join.3:107
4739 "Joining with a thread that has previously been joined results in undefined "
4744 #: build/C/man3/pthread_join.3:115
4746 "Failure to join with a thread that is joinable (i.e., one that is not "
4747 "detached), produces a \"zombie thread\". Avoid doing this, since each "
4748 "zombie thread consumes some system resources, and when enough zombie threads "
4749 "have accumulated, it will no longer be possible to create new threads (or "
4754 #: build/C/man3/pthread_join.3:121
4756 "There is no pthreads analog of I<waitpid(-1,\\ &status,\\ 0)>, that is, "
4757 "\"join with any terminated thread\". If you believe you need this "
4758 "functionality, you probably need to rethink your application design."
4762 #: build/C/man3/pthread_join.3:124
4764 "All of the threads in a process are peers: any thread can join with any "
4765 "other thread in the process."
4769 #: build/C/man3/pthread_join.3:134
4771 "B<pthread_cancel>(3), B<pthread_create>(3), B<pthread_detach>(3), "
4772 "B<pthread_exit>(3), B<pthread_tryjoin_np>(3), B<pthreads>(7)"
4776 #: build/C/man3/pthread_kill.3:26
4778 msgid "PTHREAD_KILL"
4782 #: build/C/man3/pthread_kill.3:26 build/C/man3/pthread_kill_other_threads_np.3:26 build/C/man3/pthread_self.3:26 build/C/man3/pthread_setcancelstate.3:26 build/C/man3/pthread_yield.3:25
4788 #: build/C/man3/pthread_kill.3:29
4789 msgid "pthread_kill - send a signal to a thread"
4793 #: build/C/man3/pthread_kill.3:32 build/C/man3/pthread_sigmask.3:32
4795 msgid "B<#include E<lt>signal.hE<gt>>\n"
4799 #: build/C/man3/pthread_kill.3:34
4801 msgid "B<int pthread_kill(pthread_t >I<thread>B<, int >I<sig>B<);>\n"
4805 #: build/C/man3/pthread_kill.3:45
4806 msgid "B<pthread_kill>():"
4810 #: build/C/man3/pthread_kill.3:47 build/C/man3/pthread_sigmask.3:48
4811 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 199506L || _XOPEN_SOURCE\\ E<gt>=\\ 500"
4815 #: build/C/man3/pthread_kill.3:59
4817 "The B<pthread_kill>() function sends the signal I<sig> to I<thread>, a "
4818 "thread in the same process as the caller. The signal is asynchronously "
4819 "directed to I<thread>."
4823 #: build/C/man3/pthread_kill.3:63
4825 "If I<sig> is 0, then no signal is sent, but error checking is still "
4830 #: build/C/man3/pthread_kill.3:68
4832 "On success, B<pthread_kill>() returns 0; on error, it returns an error "
4833 "number, and no signal is sent."
4837 #: build/C/man3/pthread_kill.3:72
4838 msgid "An invalid signal was specified."
4842 #: build/C/man3/pthread_kill.3:77
4843 msgid "The B<pthread_kill>() function is thread-safe."
4847 #: build/C/man3/pthread_kill.3:79
4848 msgid "POSIX.1-2008."
4852 #: build/C/man3/pthread_kill.3:86
4854 "Signal dispositions are process-wide: if a signal handler is installed, the "
4855 "handler will be invoked in the thread I<thread>, but if the disposition of "
4856 "the signal is \"stop\", \"continue\", or \"terminate\", this action will "
4857 "affect the whole process."
4861 #: build/C/man3/pthread_kill.3:99
4863 "POSIX.1-2008 recommends that if an implementation detects the use of a "
4864 "thread ID after the end of its lifetime, B<pthread_kill>() should return "
4865 "the error B<ESRCH>. The glibc implementation returns this error in the "
4866 "cases where an invalid thread ID can be detected. But note also that POSIX "
4867 "says that an attempt to use a thread ID whose lifetime has ended produces "
4868 "undefined behavior, and an attempt to use an invalid thread ID in a call to "
4869 "B<pthread_kill>() can, for example, cause a segmentation fault."
4873 #: build/C/man3/pthread_kill.3:108
4875 "B<kill>(2), B<sigaction>(2), B<sigpending>(2), B<pthread_self>(3), "
4876 "B<pthread_sigmask>(3), B<raise>(3), B<pthreads>(7), B<signal>(7)"
4880 #: build/C/man3/pthread_kill_other_threads_np.3:26
4882 msgid "PTHREAD_KILL_OTHER_THREADS_NP"
4886 #: build/C/man3/pthread_kill_other_threads_np.3:29
4887 msgid "pthread_kill_other_threads_np - terminate all other threads in process"
4891 #: build/C/man3/pthread_kill_other_threads_np.3:34
4893 msgid "B<void pthread_kill_other_threads_np(void);>\n"
4897 #. Available since glibc 2.0
4899 #: build/C/man3/pthread_kill_other_threads_np.3:47
4901 "B<pthread_kill_other_threads_np>() has an effect only in the LinuxThreads "
4902 "threading implementation. On that implementation, calling this function "
4903 "causes the immediate termination of all threads in the application, except "
4904 "the calling thread. The cancellation state and cancellation type of the "
4905 "to-be-terminated threads are ignored, and the cleanup handlers are not "
4906 "called in those threads."
4910 #: build/C/man3/pthread_kill_other_threads_np.3:52
4911 msgid "The B<pthread_kill_other_threads_np>() function is thread-safe."
4915 #: build/C/man3/pthread_kill_other_threads_np.3:64
4917 "B<pthread_kill_other_threads_np>() is intended to be called just before a "
4918 "thread calls B<execve>(2) or a similar function. This function is designed "
4919 "to address a limitation in the obsolete LinuxThreads implementation whereby "
4920 "the other threads of an application are not automatically terminated (as "
4921 "POSIX.1-2001 requires) during B<execve>(2)."
4925 #: build/C/man3/pthread_kill_other_threads_np.3:71
4927 "In the NPTL threading implementation, B<pthread_kill_other_threads_np>() "
4928 "exists, but does nothing. (Nothing needs to be done, because the "
4929 "implementation does the right thing during an B<execve>(2).)"
4933 #: build/C/man3/pthread_kill_other_threads_np.3:77
4935 "B<execve>(2), B<pthread_cancel>(3), B<pthread_setcancelstate>(3), "
4936 "B<pthread_setcanceltype>(3), B<pthreads>(7)"
4940 #: build/C/man3/pthread_rwlockattr_setkind_np.3:25
4942 msgid "PTHREAD_RWLOCKATTR_SETKIND_NP"
4946 #: build/C/man3/pthread_rwlockattr_setkind_np.3:25
4952 #: build/C/man3/pthread_rwlockattr_setkind_np.3:29
4954 "pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np - set/get the "
4955 "read-write lock kind of the thread read-write lock attribute object"
4959 #: build/C/man3/pthread_rwlockattr_setkind_np.3:37
4962 "B<int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *>I<attr>B<,>\n"
4963 "B< int >I<pref>B<);>\n"
4964 "B<int pthread_rwlockattr_getkind_np(const pthread_rwlockattr_t "
4966 "B< int *>I<pref>B<);>\n"
4970 #: build/C/man3/pthread_rwlockattr_setkind_np.3:48
4971 msgid "B<pthread_rwlockattr_setkind_np>(), B<pthread_rwlockattr_getkind_np>():"
4975 #: build/C/man3/pthread_rwlockattr_setkind_np.3:52
4976 msgid "_XOPEN_SOURCE\\ E<gt>=\\ 500 || _POSIX_C_SOURCE E<gt>= 200809L"
4980 #: build/C/man3/pthread_rwlockattr_setkind_np.3:65
4982 "The B<pthread_rwlockattr_setkind_np>() function sets the \"lock kind\" "
4983 "attribute of the read-write lock attribute object referred to by I<attr> to "
4984 "the value specified in I<pref>. The argument I<pref> may be set to one of "
4989 #: build/C/man3/pthread_rwlockattr_setkind_np.3:65
4991 msgid "B<PTHREAD_RWLOCK_PREFER_READER_NP>"
4995 #: build/C/man3/pthread_rwlockattr_setkind_np.3:78
4997 "This is the default. A thread may hold multiple read locks; that is, read "
4998 "locks are recursive. According to The Single Unix Specification, the "
4999 "behavior is unspecified when a reader tries to place a lock, and there is no "
5000 "write lock but writers are waiting. Giving preference to the reader, as is "
5001 "set by B<PTHREAD_RWLOCK_PREFER_READER_NP>, implies that the reader will "
5002 "receive the requested lock, even if a writer is waiting. As long as there "
5003 "are readers, the writer will be starved."
5007 #: build/C/man3/pthread_rwlockattr_setkind_np.3:78
5009 msgid "B<PTHREAD_RWLOCK_PREFER_WRITER_NP>"
5013 #: build/C/man3/pthread_rwlockattr_setkind_np.3:83
5015 "This is intended as the write lock analog of "
5016 "B<PTHREAD_RWLOCK_PREFER_READER_NP>. But see BUGS."
5020 #: build/C/man3/pthread_rwlockattr_setkind_np.3:83
5022 msgid "B<PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP>"
5026 #: build/C/man3/pthread_rwlockattr_setkind_np.3:88
5028 "Setting the lock kind to this avoids writer starvation as long as any read "
5029 "locking is not done in a recursive fashion."
5033 #: build/C/man3/pthread_rwlockattr_setkind_np.3:96
5035 "The B<pthread_rwlockattr_getkind_np>() function returns the value of the "
5036 "lock kind attribute of the read-write lock attribute object referred to by "
5037 "I<attr> in the pointer I<pref>."
5041 #: build/C/man3/pthread_rwlockattr_setkind_np.3:104
5043 "On success, these functions return 0. Given valid pointer arguments, "
5044 "B<pthread_rwlockattr_getkind_np>() always succeeds. On error, "
5045 "B<pthread_rwlockattr_setkind_np>() returns a non-zero error number."
5049 #: build/C/man3/pthread_rwlockattr_setkind_np.3:109
5050 msgid "I<pref> specifies an unsupported value."
5053 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7057
5055 #: build/C/man3/pthread_rwlockattr_setkind_np.3:121
5057 "Setting the value read-write lock kind to B<PTHREAD_RWLOCK_PREFER_WRITER_NP> "
5058 "results in the same behavior as setting the value to "
5059 "B<PTHREAD_RWLOCK_PREFER_READER_NP>. As long as a reader thread holds the "
5060 "lock, the thread holding a write lock will be starved. Setting the lock "
5061 "kind to B<PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP> allows writers to "
5062 "run, but, as the name implies a writer may not lock recursively."
5066 #: build/C/man3/pthread_rwlockattr_setkind_np.3:127
5068 "The B<pthread_rwlockattr_getkind_np>() and "
5069 "B<pthread_rwlockattr_setkind_np>() functions first appeared in glibc 2.1."
5073 #: build/C/man3/pthread_rwlockattr_setkind_np.3:130
5075 "These functions are non-standard GNU extensions; hence the suffix \"_np\" "
5076 "(non-portable) in the names."
5080 #: build/C/man3/pthread_rwlockattr_setkind_np.3:132
5081 msgid "B<pthreads>(7)"
5085 #: build/C/man3/pthread_self.3:26
5087 msgid "PTHREAD_SELF"
5091 #: build/C/man3/pthread_self.3:29
5092 msgid "pthread_self - obtain ID of the calling thread"
5096 #: build/C/man3/pthread_self.3:34
5098 msgid "B<pthread_t pthread_self(void);>\n"
5102 #: build/C/man3/pthread_self.3:46
5104 "The B<pthread_self>() function returns the ID of the calling thread. This "
5105 "is the same value that is returned in I<*thread> in the B<pthread_create>(3) "
5106 "call that created this thread."
5110 #: build/C/man3/pthread_self.3:48
5111 msgid "This function always succeeds, returning the calling thread's ID."
5115 #: build/C/man3/pthread_self.3:55
5116 msgid "The B<pthread_self>() function is thread-safe."
5120 #: build/C/man3/pthread_self.3:68
5122 "POSIX.1 allows an implementation wide freedom in choosing the type used to "
5123 "represent a thread ID; for example, representation using either an "
5124 "arithmetic type or a structure is permitted. Therefore, variables of type "
5125 "I<pthread_t> can't portably be compared using the C equality operator "
5126 "(B<==>); use B<pthread_equal>(3) instead."
5130 #: build/C/man3/pthread_self.3:72
5132 "Thread identifiers should be considered opaque: any attempt to use a thread "
5133 "ID other than in pthreads calls is nonportable and can lead to unspecified "
5138 #: build/C/man3/pthread_self.3:76
5140 "Thread IDs are guaranteed to be unique only within a process. A thread ID "
5141 "may be reused after a terminated thread has been joined, or a detached "
5142 "thread has terminated."
5146 #: build/C/man3/pthread_self.3:81
5148 "The thread ID returned by B<pthread_self>() is not the same thing as the "
5149 "kernel thread ID returned by a call to B<gettid>(2)."
5153 #: build/C/man3/pthread_self.3:85
5154 msgid "B<pthread_create>(3), B<pthread_equal>(3), B<pthreads>(7)"
5158 #: build/C/man3/pthread_setaffinity_np.3:26
5160 msgid "PTHREAD_SETAFFINITY_NP"
5164 #: build/C/man3/pthread_setaffinity_np.3:30
5166 "pthread_setaffinity_np, pthread_getaffinity_np - set/get CPU affinity of a "
5171 #: build/C/man3/pthread_setaffinity_np.3:39
5174 "B<int pthread_setaffinity_np(pthread_t >I<thread>B<, size_t "
5175 ">I<cpusetsize>B<,>\n"
5176 "B< const cpu_set_t *>I<cpuset>B<);>\n"
5177 "B<int pthread_getaffinity_np(pthread_t >I<thread>B<, size_t "
5178 ">I<cpusetsize>B<,>\n"
5179 "B< cpu_set_t *>I<cpuset>B<);>\n"
5183 #: build/C/man3/pthread_setaffinity_np.3:54
5185 "The B<pthread_setaffinity_np>() function sets the CPU affinity mask of the "
5186 "thread I<thread> to the CPU set pointed to by I<cpuset>. If the call is "
5187 "successful, and the thread is not currently running on one of the CPUs in "
5188 "I<cpuset>, then it is migrated to one of those CPUs."
5192 #: build/C/man3/pthread_setaffinity_np.3:61
5194 "The B<pthread_getaffinity_np>() function returns the CPU affinity mask of "
5195 "the thread I<thread> in the buffer pointed to by I<cpuset>."
5199 #: build/C/man3/pthread_setaffinity_np.3:77
5201 "The argument I<cpusetsize> is the length (in bytes) of the buffer pointed to "
5202 "by I<cpuset>. Typically, this argument would be specified as "
5203 "I<sizeof(cpu_set_t)>. (It may be some other value, if using the macros "
5204 "described in B<CPU_SET>(3) for dynamically allocating a CPU set.)"
5208 #: build/C/man3/pthread_setaffinity_np.3:81
5214 #: build/C/man3/pthread_setaffinity_np.3:84
5215 msgid "A supplied memory address was invalid."
5219 #: build/C/man3/pthread_setaffinity_np.3:93
5221 "(B<pthread_setaffinity_np>()) The affinity bit mask I<mask> contains no "
5222 "processors that are currently physically on the system and permitted to the "
5223 "thread according to any restrictions that may be imposed by the \"cpuset\" "
5224 "mechanism described in B<cpuset>(7)."
5228 #. Loic Domaigne commented: it seems that in the future the
5229 #. kernel developers want to make cpumask_t dynamic, so
5230 #. CONFIG_NR_CPUS might become obsolete in the future.
5232 #. The raw sched_getaffinity() system call returns the size (in bytes)
5233 #. of the cpumask_t type.
5235 #: build/C/man3/pthread_setaffinity_np.3:109
5237 "(B<pthread_setaffinity_np>()) I<cpuset> specified a CPU that was outside "
5238 "the set supported by the kernel. (The kernel configuration option "
5239 "B<CONFIG_NR_CPUS> defines the range of the set supported by the kernel data "
5240 "type used to represent CPU sets.)"
5244 #: build/C/man3/pthread_setaffinity_np.3:114
5246 "(B<pthread_getaffinity_np>()) I<cpusetsize> is smaller than the size of the "
5247 "affinity mask used by the kernel."
5251 #: build/C/man3/pthread_setaffinity_np.3:128
5253 "The B<pthread_setaffinity_np>() and B<pthread_getaffinity_np>() functions "
5258 #: build/C/man3/pthread_setaffinity_np.3:144
5260 "After a call to B<pthread_setaffinity_np>(), the set of CPUs on which the "
5261 "thread will actually run is the intersection of the set specified in the "
5262 "I<cpuset> argument and the set of CPUs actually present on the system. The "
5263 "system may further restrict the set of CPUs on which the thread runs if the "
5264 "\"cpuset\" mechanism described in B<cpuset>(7) is being used. These "
5265 "restrictions on the actual set of CPUs on which the thread will run are "
5266 "silently imposed by the kernel."
5270 #: build/C/man3/pthread_setaffinity_np.3:150
5272 "These functions are implemented on top of the B<sched_setaffinity>(2) and "
5273 "B<sched_getaffinity>(2) system calls."
5277 #: build/C/man3/pthread_setaffinity_np.3:161
5279 "A new thread created by B<pthread_create>(3) inherits a copy of its "
5280 "creator's CPU affinity mask."
5284 #: build/C/man3/pthread_setaffinity_np.3:169
5286 "In the following program, the main thread uses B<pthread_setaffinity_np>() "
5287 "to set its CPU affinity mask to include CPUs 0 to 7 (which may not all be "
5288 "available on the system), and then calls B<pthread_getaffinity_np>() to "
5289 "check the resulting CPU affinity mask of the thread."
5293 #: build/C/man3/pthread_setaffinity_np.3:176
5296 "#define _GNU_SOURCE\n"
5297 "#include E<lt>pthread.hE<gt>\n"
5298 "#include E<lt>stdio.hE<gt>\n"
5299 "#include E<lt>stdlib.hE<gt>\n"
5300 "#include E<lt>errno.hE<gt>\n"
5304 #: build/C/man3/pthread_setaffinity_np.3:186
5308 "main(int argc, char *argv[])\n"
5311 " cpu_set_t cpuset;\n"
5312 " pthread_t thread;\n"
5316 #: build/C/man3/pthread_setaffinity_np.3:188
5318 msgid " thread = pthread_self();\n"
5322 #: build/C/man3/pthread_setaffinity_np.3:190
5324 msgid " /* Set affinity mask to include CPUs 0 to 7 */\n"
5328 #: build/C/man3/pthread_setaffinity_np.3:194
5331 " CPU_ZERO(&cpuset);\n"
5332 " for (j = 0; j E<lt> 8; j++)\n"
5333 " CPU_SET(j, &cpuset);\n"
5337 #: build/C/man3/pthread_setaffinity_np.3:198
5340 " s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset);\n"
5342 " handle_error_en(s, \"pthread_setaffinity_np\");\n"
5346 #: build/C/man3/pthread_setaffinity_np.3:200
5348 msgid " /* Check the actual affinity mask assigned to the thread */\n"
5352 #: build/C/man3/pthread_setaffinity_np.3:204
5355 " s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset);\n"
5357 " handle_error_en(s, \"pthread_getaffinity_np\");\n"
5361 #: build/C/man3/pthread_setaffinity_np.3:209
5364 " printf(\"Set returned by pthread_getaffinity_np() contained:\\en\");\n"
5365 " for (j = 0; j E<lt> CPU_SETSIZE; j++)\n"
5366 " if (CPU_ISSET(j, &cpuset))\n"
5367 " printf(\" CPU %d\\en\", j);\n"
5371 #: build/C/man3/pthread_setaffinity_np.3:212 build/C/man3/pthread_setschedparam.3:439
5374 " exit(EXIT_SUCCESS);\n"
5379 #: build/C/man3/pthread_setaffinity_np.3:221
5381 "B<sched_setaffinity>(2), B<pthread_attr_setaffinity_np>(3), "
5382 "B<pthread_self>(3), B<sched_getcpu>(3), B<cpuset>(7), B<pthreads>(7), "
5387 #: build/C/man3/pthread_setcancelstate.3:26
5389 msgid "PTHREAD_SETCANCELSTATE"
5393 #: build/C/man3/pthread_setcancelstate.3:30
5395 "pthread_setcancelstate, pthread_setcanceltype - set cancelability state and "
5400 #: build/C/man3/pthread_setcancelstate.3:36
5403 "B<int pthread_setcancelstate(int >I<state>B<, int *>I<oldstate>B<);>\n"
5404 "B<int pthread_setcanceltype(int >I<type>B<, int *>I<oldtype>B<);>\n"
5408 #: build/C/man3/pthread_setcancelstate.3:51
5410 "The B<pthread_setcancelstate>() sets the cancelability state of the calling "
5411 "thread to the value given in I<state>. The previous cancelability state of "
5412 "the thread is returned in the buffer pointed to by I<oldstate>. The "
5413 "I<state> argument must have one of the following values:"
5417 #: build/C/man3/pthread_setcancelstate.3:51
5419 msgid "B<PTHREAD_CANCEL_ENABLE>"
5423 #: build/C/man3/pthread_setcancelstate.3:58
5425 "The thread is cancelable. This is the default cancelability state in all "
5426 "new threads, including the initial thread. The thread's cancelability type "
5427 "determines when a cancelable thread will respond to a cancellation request."
5431 #: build/C/man3/pthread_setcancelstate.3:58
5433 msgid "B<PTHREAD_CANCEL_DISABLE>"
5437 #: build/C/man3/pthread_setcancelstate.3:63
5439 "The thread is not cancelable. If a cancellation request is received, it is "
5440 "blocked until cancelability is enabled."
5444 #: build/C/man3/pthread_setcancelstate.3:75
5446 "The B<pthread_setcanceltype>() sets the cancelability type of the calling "
5447 "thread to the value given in I<type>. The previous cancelability type of "
5448 "the thread is returned in the buffer pointed to by I<oldtype>. The I<type> "
5449 "argument must have one of the following values:"
5453 #: build/C/man3/pthread_setcancelstate.3:75
5455 msgid "B<PTHREAD_CANCEL_DEFERRED>"
5459 #: build/C/man3/pthread_setcancelstate.3:82
5461 "A cancellation request is deferred until the thread next calls a function "
5462 "that is a cancellation point (see B<pthreads>(7)). This is the default "
5463 "cancelability type in all new threads, including the initial thread."
5467 #: build/C/man3/pthread_setcancelstate.3:82
5469 msgid "B<PTHREAD_CANCEL_ASYNCHRONOUS>"
5473 #: build/C/man3/pthread_setcancelstate.3:88
5475 "The thread can be canceled at any time. (Typically, it will be canceled "
5476 "immediately upon receiving a cancellation request, but the system doesn't "
5481 #: build/C/man3/pthread_setcancelstate.3:92
5483 "The set-and-get operation performed by each of these functions is atomic "
5484 "with respect to other threads in the process calling the same function."
5488 #: build/C/man3/pthread_setcancelstate.3:99
5489 msgid "The B<pthread_setcancelstate>() can fail with the following error:"
5493 #: build/C/man3/pthread_setcancelstate.3:103
5494 msgid "Invalid value for I<state>."
5498 #: build/C/man3/pthread_setcancelstate.3:107
5499 msgid "The B<pthread_setcanceltype>() can fail with the following error:"
5503 #. Available since glibc 2.0
5505 #: build/C/man3/pthread_setcancelstate.3:113
5506 msgid "Invalid value for I<type>."
5510 #: build/C/man3/pthread_setcancelstate.3:120
5512 "The B<pthread_setcancelstate>() and B<pthread_setcanceltype>() functions "
5517 #: build/C/man3/pthread_setcancelstate.3:125
5519 "For details of what happens when a thread is canceled, see "
5520 "B<pthread_cancel>(3)."
5524 #: build/C/man3/pthread_setcancelstate.3:132
5526 "Briefly disabling cancelability is useful if a thread performs some critical "
5527 "action that must not be interrupted by a cancellation request. Beware of "
5528 "disabling cancelability for long periods, or around operations that may "
5529 "block for long periods, since that will render the thread unresponsive to "
5530 "cancellation requests."
5534 #: build/C/man3/pthread_setcancelstate.3:132
5536 msgid "Asynchronous cancelability"
5540 #: build/C/man3/pthread_setcancelstate.3:151
5542 "Setting the cancelability type to B<PTHREAD_CANCEL_ASYNCHRONOUS> is rarely "
5543 "useful. Since the thread could be canceled at I<any> time, it cannot safely "
5544 "reserve resources (e.g., allocating memory with B<malloc>(3)), acquire "
5545 "mutexes, semaphores, or locks, and so on. Reserving resources is unsafe "
5546 "because the application has no way of knowing what the state of these "
5547 "resources is when the thread is canceled; that is, did cancellation occur "
5548 "before the resources were reserved, while they were reserved, or after they "
5549 "were released? Furthermore, some internal data structures (e.g., the linked "
5550 "list of free blocks managed by the B<malloc>(3) family of functions) may be "
5551 "left in an inconsistent state if cancellation occurs in the middle of the "
5552 "function call. Consequently, clean-up handlers cease to be useful."
5556 #: build/C/man3/pthread_setcancelstate.3:162
5558 "Functions that can be safely asynchronously canceled are called "
5559 "I<async-cancel-safe functions>. POSIX.1-2001 requires only that "
5560 "B<pthread_cancel>(3), B<pthread_setcancelstate>(), and "
5561 "B<pthread_setcanceltype>() be async-cancel-safe. In general, other library "
5562 "functions can't be safely called from an asynchronously cancelable thread."
5566 #: build/C/man3/pthread_setcancelstate.3:165
5568 "One of the few circumstances in which asynchronous cancelability is useful "
5569 "is for cancellation of a thread that is in a pure compute-bound loop."
5573 #: build/C/man3/pthread_setcancelstate.3:165
5575 msgid "Portability notes"
5578 #. It looks like at least Solaris, FreeBSD and Tru64 support this.
5580 #: build/C/man3/pthread_setcancelstate.3:183
5582 "The Linux threading implementations permit the I<oldstate> argument of "
5583 "B<pthread_setcancelstate>() to be NULL, in which case the information about "
5584 "the previous cancelability state is not returned to the caller. Many other "
5585 "implementations also permit a NULL I<oldstat> argument, but POSIX.1-2001 "
5586 "does not specify this point, so portable applications should always specify "
5587 "a non-NULL value in I<oldstate>. A precisely analogous set of statements "
5588 "applies for the I<oldtype> argument of B<pthread_setcanceltype>()."
5592 #: build/C/man3/pthread_setcancelstate.3:186
5593 msgid "See B<pthread_cancel>(3)."
5597 #: build/C/man3/pthread_setcancelstate.3:191
5599 "B<pthread_cancel>(3), B<pthread_cleanup_push>(3), B<pthread_testcancel>(3), "
5604 #: build/C/man3/pthread_setconcurrency.3:25
5606 msgid "PTHREAD_SETCONCURRENCY"
5610 #: build/C/man3/pthread_setconcurrency.3:29
5612 "pthread_setconcurrency, pthread_getconcurrency - set/get the concurrency "
5617 #: build/C/man3/pthread_setconcurrency.3:35
5620 "B<int pthread_setconcurrency(int >I<new_level>B<);>\n"
5621 "B<int pthread_getconcurrency(void);>\n"
5625 #: build/C/man3/pthread_setconcurrency.3:48
5627 "The B<pthread_setconcurrency>() function informs the implementation of the "
5628 "application's desired concurrency level, specified in I<new_level>. The "
5629 "implementation takes this only as a hint: POSIX.1 does not specify the level "
5630 "of concurrency that should be provided as a result of calling "
5631 "B<pthread_setconcurrency>()."
5635 #: build/C/man3/pthread_setconcurrency.3:53
5637 "Specifying I<new_level> as 0 instructs the implementation to manage the "
5638 "concurrency level as it deems appropriate."
5642 #: build/C/man3/pthread_setconcurrency.3:56
5644 "B<pthread_getconcurrency>() returns the current value of the concurrency "
5645 "level for this process."
5649 #: build/C/man3/pthread_setconcurrency.3:61
5651 "On success, B<pthread_setconcurrency>() returns 0; on error, it returns a "
5652 "nonzero error number."
5656 #: build/C/man3/pthread_setconcurrency.3:68
5658 "B<pthread_getconcurrency>() always succeeds, returning the concurrency "
5659 "level set by a previous call to B<pthread_setconcurrency>(), or 0, if "
5660 "B<pthread_setconcurrency>() has not previously been called."
5664 #: build/C/man3/pthread_setconcurrency.3:71
5665 msgid "B<pthread_setconcurrency>() can fail with the following error:"
5669 #: build/C/man3/pthread_setconcurrency.3:75
5670 msgid "I<new_level> is negative."
5674 #: build/C/man3/pthread_setconcurrency.3:81
5676 "POSIX.1-2001 also documents an B<EAGAIN> error (\"the value specified by "
5677 "I<new_level> would cause a system resource to be exceeded\")."
5681 #: build/C/man3/pthread_setconcurrency.3:83
5682 msgid "These functions are available in glibc since version 2.1."
5686 #: build/C/man3/pthread_setconcurrency.3:90
5688 "The B<pthread_setconcurrency>() and B<pthread_getconcurrency>() functions "
5693 #: build/C/man3/pthread_setconcurrency.3:94
5694 msgid "The default concurrency level is 0."
5698 #: build/C/man3/pthread_setconcurrency.3:101
5700 "Concurrency levels are meaningful only for M:N threading implementations, "
5701 "where at any moment a subset of a process's set of user-level threads may be "
5702 "bound to a smaller number of kernel-scheduling entities. Setting the "
5703 "concurrency level allows the application to give the system a hint as to the "
5704 "number of kernel-scheduling entities that should be provided for efficient "
5705 "execution of the application."
5709 #: build/C/man3/pthread_setconcurrency.3:107
5711 "Both LinuxThreads and NPTL are 1:1 threading implementations, so setting the "
5712 "concurrency level has no meaning. In other words, on Linux these functions "
5713 "merely exist for compatibility with other systems, and they have no effect "
5714 "on the execution of a program."
5718 #: build/C/man3/pthread_setconcurrency.3:110
5719 msgid "B<pthread_attr_setscope>(3), B<pthreads>(7)"
5723 #: build/C/man3/pthread_setname_np.3:26
5725 msgid "PTHREAD_SETNAME_NP"
5729 #: build/C/man3/pthread_setname_np.3:29
5730 msgid "pthread_setname_np, pthread_getname_np - set/get the name of a thread"
5734 #: build/C/man3/pthread_setname_np.3:36
5737 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
5738 "B<#include E<lt>pthread.hE<gt>>\n"
5739 "B<int pthread_setname_np(pthread_t >I<thread>B<, const char *>I<name>B<);>\n"
5740 "B<int pthread_getname_np(pthread_t >I<thread>B<,>\n"
5741 "B< char *>I<name>B<, size_t >I<len>B<);>\n"
5745 #: build/C/man3/pthread_setname_np.3:55
5747 "By default, all the threads created using B<pthread_create>() inherit the "
5748 "program name. The B<pthread_setname_np>() function can be used to set a "
5749 "unique name for a thread, which can be useful for debugging multithreaded "
5750 "applications. The thread name is a meaningful C language string, whose "
5751 "length is restricted to 16 characters, including the terminating null byte "
5752 "(\\(aq\\e0\\(aq). The I<thread> argument specifies the thread whose name is "
5753 "to be changed; I<name> specifies the new name."
5757 #: build/C/man3/pthread_setname_np.3:72
5759 "The B<pthread_getname_np>() function can be used to retrieve the name of "
5760 "the thread. The I<thread> argument specifies the thread whose name is to be "
5761 "retrieved. The buffer I<name> is used to return the thread name; I<len> "
5762 "specifies the number of bytes available in I<name>. The buffer specified by "
5763 "I<name> should be at least 16 characters in length. The returned thread "
5764 "name in the output buffer will be null terminated."
5768 #: build/C/man3/pthread_setname_np.3:79
5769 msgid "The B<pthread_setname_np>() function can fail with the following error:"
5773 #: build/C/man3/pthread_setname_np.3:79 build/C/man3/pthread_setname_np.3:88
5779 #: build/C/man3/pthread_setname_np.3:84
5781 "The length of the string specified pointed to by I<name> exceeds the allowed "
5786 #: build/C/man3/pthread_setname_np.3:88
5787 msgid "The B<pthread_getname_np>() function can fail with the following error:"
5791 #: build/C/man3/pthread_setname_np.3:95
5793 "The buffer specified by I<name> and I<len> is too small to hold the thread "
5798 #: build/C/man3/pthread_setname_np.3:100
5800 "If either of these functions fails to open I</proc/self/task/[tid]/comm>, "
5801 "then the call may fail with one of the errors described in B<open>(2)."
5805 #: build/C/man3/pthread_setname_np.3:102
5806 msgid "These functions first appeared in glibc in version 2.12."
5810 #: build/C/man3/pthread_setname_np.3:104
5811 msgid "These functions are nonstandard GNU extensions."
5815 #: build/C/man3/pthread_setname_np.3:114
5817 "B<pthread_setname_np>() internally writes to the thread-specific I<comm> "
5818 "file under the I</proc> filesystem: I</proc/self/task/[tid]/comm>. "
5819 "B<pthread_getname_np>() retrieves it from the same location."
5823 #: build/C/man3/pthread_setname_np.3:120
5825 "The program below demonstrates the use of B<pthread_setname_np>() and "
5826 "B<pthread_getname_np>()."
5830 #: build/C/man3/pthread_setname_np.3:122
5831 msgid "The following shell session shows a sample run of the program:"
5835 #: build/C/man3/pthread_setname_np.3:138
5839 "Created a thread. Default name is: a.out\n"
5840 "The thread name after setting it is THREADFOO.\n"
5841 "B<^Z> # Suspend the program\n"
5842 "[1]+ Stopped ./a.out\n"
5843 "$ B<ps H -C a.out -o 'pid tid cmd comm'>\n"
5844 " PID TID CMD COMMAND\n"
5845 " 5990 5990 ./a.out a.out\n"
5846 " 5990 5991 ./a.out THREADFOO\n"
5847 "$ B<cat /proc/5990/task/5990/comm>\n"
5849 "$ B<cat /proc/5990/task/5991/comm>\n"
5854 #: build/C/man3/pthread_setname_np.3:150
5857 "#define _GNU_SOURCE\n"
5858 "#include E<lt>pthread.hE<gt>\n"
5859 "#include E<lt>stdio.hE<gt>\n"
5860 "#include E<lt>string.hE<gt>\n"
5861 "#include E<lt>unistd.hE<gt>\n"
5862 "#include E<lt>errno.hE<gt>\n"
5863 "#include E<lt>stdlib.hE<gt>\n"
5867 #: build/C/man3/pthread_setname_np.3:152
5869 msgid "#define NAMELEN 16\n"
5873 #: build/C/man3/pthread_setname_np.3:156
5876 "#define errExitEN(en, msg) \\e\n"
5877 " do { errno = en; perror(msg); exit(EXIT_FAILURE); \\e\n"
5882 #: build/C/man3/pthread_setname_np.3:163
5886 "threadfunc(void *parm)\n"
5888 " sleep(5); // allow main program to set the thread name\n"
5894 #: build/C/man3/pthread_setname_np.3:170
5898 "main(int argc, char **argv)\n"
5900 " pthread_t thread;\n"
5902 " char thread_name[NAMELEN];\n"
5906 #: build/C/man3/pthread_setname_np.3:174
5909 " rc = pthread_create(&thread, NULL, threadfunc, NULL);\n"
5911 " errExitEN(rc, \"pthread_create\");\n"
5915 #: build/C/man3/pthread_setname_np.3:178
5918 " rc = pthread_getname_np(thread, thread_name, NAMELEN);\n"
5920 " errExitEN(rc, \"pthread_getname_np\");\n"
5924 #: build/C/man3/pthread_setname_np.3:183
5927 " printf(\"Created a thread. Default name is: %s\\en\", thread_name);\n"
5928 " rc = pthread_setname_np(thread, (argc E<gt> 1) ? argv[1] : "
5931 " errExitEN(rc, \"pthread_setname_np\");\n"
5935 #: build/C/man3/pthread_setname_np.3:185
5937 msgid " sleep(2);\n"
5941 #: build/C/man3/pthread_setname_np.3:191
5944 " rc = pthread_getname_np(thread, thread_name,\n"
5945 " (argc E<gt> 2) ? atoi(argv[1]) : NAMELEN);\n"
5947 " errExitEN(rc, \"pthread_getname_np\");\n"
5948 " printf(\"The thread name after setting it is %s.\\en\", thread_name);\n"
5952 #: build/C/man3/pthread_setname_np.3:195
5955 " rc = pthread_join(thread, NULL);\n"
5957 " errExitEN(rc, \"pthread_join\");\n"
5961 #: build/C/man3/pthread_setname_np.3:199
5964 " printf(\"Done\\en\");\n"
5965 " exit(EXIT_SUCCESS);\n"
5970 #: build/C/man3/pthread_setname_np.3:206
5971 msgid "B<prctl>(2), B<pthread_create>(3), B<pthreads>(7)"
5975 #: build/C/man3/pthread_setschedparam.3:26
5977 msgid "PTHREAD_SETSCHEDPARAM"
5981 #: build/C/man3/pthread_setschedparam.3:26
5987 #: build/C/man3/pthread_setschedparam.3:30
5989 "pthread_setschedparam, pthread_getschedparam - set/get scheduling policy and "
5990 "parameters of a thread"
5994 #: build/C/man3/pthread_setschedparam.3:38
5997 "B<int pthread_setschedparam(pthread_t >I<thread>B<, int >I<policy>B<,>\n"
5998 "B< const struct sched_param *>I<param>B<);>\n"
5999 "B<int pthread_getschedparam(pthread_t >I<thread>B<, int *>I<policy>B<,>\n"
6000 "B< struct sched_param *>I<param>B<);>\n"
6004 #: build/C/man3/pthread_setschedparam.3:46
6006 "The B<pthread_setschedparam>() function sets the scheduling policy and "
6007 "parameters of the thread I<thread>."
6010 #. FIXME . pthread_setschedparam() places no restriction on the policy,
6011 #. but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
6012 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7013
6014 #: build/C/man3/pthread_setschedparam.3:57
6016 "I<policy> specifies the new scheduling policy for I<thread>. The supported "
6017 "values for I<policy>, and their semantics, are described in B<sched>(7)."
6021 #: build/C/man3/pthread_setschedparam.3:63
6023 "The structure pointed to by I<param> specifies the new scheduling parameters "
6024 "for I<thread>. Scheduling parameters are maintained in the following "
6028 #. FIXME . nptl/pthread_setschedparam.c has the following
6029 #. /* If the thread should have higher priority because of some
6030 #. PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
6031 #. Eventually (perhaps after writing the mutexattr pages), we
6032 #. may want to add something on the topic to this page.
6034 #: build/C/man3/pthread_setschedparam.3:104
6036 "The B<pthread_getschedparam>() function returns the scheduling policy and "
6037 "parameters of the thread I<thread>, in the buffers pointed to by I<policy> "
6038 "and I<param>, respectively. The returned priority value is that set by the "
6039 "most recent B<pthread_setschedparam>(), B<pthread_setschedprio>(3), or "
6040 "B<pthread_create>(3) call that affected I<thread>. The returned priority "
6041 "does not reflect any temporary priority adjustments as a result of calls to "
6042 "any priority inheritance or priority ceiling functions (see, for example, "
6043 "B<pthread_mutexattr_setprioceiling>(3) and "
6044 "B<pthread_mutexattr_setprotocol>(3))."
6048 #: build/C/man3/pthread_setschedparam.3:112
6050 "On success, these functions return 0; on error, they return a nonzero error "
6051 "number. If B<pthread_setschedparam>() fails, the scheduling policy and "
6052 "parameters of I<thread> are not changed."
6056 #: build/C/man3/pthread_setschedparam.3:114
6057 msgid "Both of these functions can fail with the following error:"
6061 #: build/C/man3/pthread_setschedparam.3:122
6062 msgid "B<pthread_setschedparam>() may additionally fail with the following errors:"
6066 #: build/C/man3/pthread_setschedparam.3:129
6068 "I<policy> is not a recognized policy, or I<param> does not make sense for "
6073 #: build/C/man3/pthread_setschedparam.3:133
6075 "The caller does not have appropriate privileges to set the specified "
6076 "scheduling policy and parameters."
6080 #. Available since glibc 2.0
6082 #: build/C/man3/pthread_setschedparam.3:141
6084 "POSIX.1-2001 also documents an B<ENOTSUP> (\"attempt was made to set the "
6085 "policy or scheduling parameters to an unsupported value\") error for "
6086 "B<pthread_setschedparam>()."
6090 #: build/C/man3/pthread_setschedparam.3:148
6092 "The B<pthread_setschedparam>() and B<pthread_getschedparam>() functions "
6097 #: build/C/man3/pthread_setschedparam.3:156
6099 "For a description of the permissions required to, and the effect of, "
6100 "changing a thread's scheduling policy and priority, and details of the "
6101 "permitted ranges for priorities in each scheduling policy, see B<sched>(7)."
6105 #: build/C/man3/pthread_setschedparam.3:163
6107 "The program below demonstrates the use of B<pthread_setschedparam>() and "
6108 "B<pthread_getschedparam>(), as well as the use of a number of other "
6109 "scheduling-related pthreads functions."
6113 #: build/C/man3/pthread_setschedparam.3:179
6115 "In the following run, the main thread sets its scheduling policy to "
6116 "B<SCHED_FIFO> with a priority of 10, and initializes a thread attributes "
6117 "object with a scheduling policy attribute of B<SCHED_RR> and a scheduling "
6118 "priority attribute of 20. The program then sets (using "
6119 "B<pthread_attr_setinheritsched>(3)) the inherit scheduler attribute of the "
6120 "thread attributes object to B<PTHREAD_EXPLICIT_SCHED>, meaning that threads "
6121 "created using this attributes object should take their scheduling attributes "
6122 "from the thread attributes object. The program then creates a thread using "
6123 "the thread attributes object, and that thread displays its scheduling policy "
6128 #: build/C/man3/pthread_setschedparam.3:187
6131 "$ B<su> # Need privilege to set real-time scheduling policies\n"
6133 "# B<./a.out -mf10 -ar20 -i e>\n"
6134 "Scheduler settings of main thread\n"
6135 " policy=SCHED_FIFO, priority=10\n"
6139 #: build/C/man3/pthread_setschedparam.3:191
6142 "Scheduler settings in \\(aqattr\\(aq\n"
6143 " policy=SCHED_RR, priority=20\n"
6144 " inheritsched is EXPLICIT\n"
6148 #: build/C/man3/pthread_setschedparam.3:194
6151 "Scheduler attributes of new thread\n"
6152 " policy=SCHED_RR, priority=20\n"
6156 #: build/C/man3/pthread_setschedparam.3:199
6158 "In the above output, one can see that the scheduling policy and priority "
6159 "were taken from the values specified in the thread attributes object."
6163 #: build/C/man3/pthread_setschedparam.3:206
6165 "The next run is the same as the previous, except that the inherit scheduler "
6166 "attribute is set to B<PTHREAD_INHERIT_SCHED>, meaning that threads created "
6167 "using the thread attributes object should ignore the scheduling attributes "
6168 "specified in the attributes object and instead take their scheduling "
6169 "attributes from the creating thread."
6173 #: build/C/man3/pthread_setschedparam.3:212
6176 "# B<./a.out -mf10 -ar20 -i i>\n"
6177 "Scheduler settings of main thread\n"
6178 " policy=SCHED_FIFO, priority=10\n"
6182 #: build/C/man3/pthread_setschedparam.3:216
6185 "Scheduler settings in \\(aqattr\\(aq\n"
6186 " policy=SCHED_RR, priority=20\n"
6187 " inheritsched is INHERIT\n"
6191 #: build/C/man3/pthread_setschedparam.3:219
6194 "Scheduler attributes of new thread\n"
6195 " policy=SCHED_FIFO, priority=10\n"
6199 #: build/C/man3/pthread_setschedparam.3:225
6201 "In the above output, one can see that the scheduling policy and priority "
6202 "were taken from the creating thread, rather than the thread attributes "
6207 #: build/C/man3/pthread_setschedparam.3:231
6209 "Note that if we had omitted the I<-i\\ i> option, the output would have been "
6210 "the same, since B<PTHREAD_INHERIT_SCHED> is the default for the inherit "
6211 "scheduler attribute."
6215 #: build/C/man3/pthread_setschedparam.3:235
6217 msgid "/* pthreads_sched_test.c */\n"
6221 #: build/C/man3/pthread_setschedparam.3:241
6224 "#include E<lt>pthread.hE<gt>\n"
6225 "#include E<lt>stdio.hE<gt>\n"
6226 "#include E<lt>stdlib.hE<gt>\n"
6227 "#include E<lt>unistd.hE<gt>\n"
6228 "#include E<lt>errno.hE<gt>\n"
6232 #: build/C/man3/pthread_setschedparam.3:250
6236 "usage(char *prog_name, char *msg)\n"
6238 " if (msg != NULL)\n"
6239 " fputs(msg, stderr);\n"
6243 #: build/C/man3/pthread_setschedparam.3:267
6246 " fprintf(stderr, \"Usage: %s [options]\\en\", prog_name);\n"
6247 " fprintf(stderr, \"Options are:\\en\");\n"
6248 "#define fpe(msg) fprintf(stderr, \"\\et%s\", msg); /* Shorter */\n"
6249 " fpe(\"-aE<lt>policyE<gt>E<lt>prioE<gt> Set scheduling policy and "
6250 "priority in\\en\");\n"
6251 " fpe(\" thread attributes object\\en\");\n"
6252 " fpe(\" E<lt>policyE<gt> can be\\en\");\n"
6253 " fpe(\" f SCHED_FIFO\\en\");\n"
6254 " fpe(\" r SCHED_RR\\en\");\n"
6255 " fpe(\" o SCHED_OTHER\\en\");\n"
6256 " fpe(\"-A Use default thread attributes object\\en\");\n"
6257 " fpe(\"-i {e|i} Set inherit scheduler attribute to\\en\");\n"
6258 " fpe(\" \\(aqexplicit\\(aq or \\(aqinherit\\(aq\\en\");\n"
6259 " fpe(\"-mE<lt>policyE<gt>E<lt>prioE<gt> Set scheduling policy and "
6260 "priority on\\en\");\n"
6261 " fpe(\" main thread before pthread_create() "
6263 " exit(EXIT_FAILURE);\n"
6268 #: build/C/man3/pthread_setschedparam.3:278
6272 "get_policy(char p, int *policy)\n"
6275 " case \\(aqf\\(aq: *policy = SCHED_FIFO; return 1;\n"
6276 " case \\(aqr\\(aq: *policy = SCHED_RR; return 1;\n"
6277 " case \\(aqo\\(aq: *policy = SCHED_OTHER; return 1;\n"
6278 " default: return 0;\n"
6284 #: build/C/man3/pthread_setschedparam.3:289
6288 "display_sched_attr(int policy, struct sched_param *param)\n"
6290 " printf(\" policy=%s, priority=%d\\en\",\n"
6291 " (policy == SCHED_FIFO) ? \"SCHED_FIFO\" :\n"
6292 " (policy == SCHED_RR) ? \"SCHED_RR\" :\n"
6293 " (policy == SCHED_OTHER) ? \"SCHED_OTHER\" :\n"
6295 " param-E<gt>sched_priority);\n"
6300 #: build/C/man3/pthread_setschedparam.3:295
6304 "display_thread_sched_attr(char *msg)\n"
6307 " struct sched_param param;\n"
6311 #: build/C/man3/pthread_setschedparam.3:299
6314 " s = pthread_getschedparam(pthread_self(), &policy, ¶m);\n"
6316 " handle_error_en(s, \"pthread_getschedparam\");\n"
6320 #: build/C/man3/pthread_setschedparam.3:303
6323 " printf(\"%s\\en\", msg);\n"
6324 " display_sched_attr(policy, ¶m);\n"
6329 #: build/C/man3/pthread_setschedparam.3:308
6333 "thread_start(void *arg)\n"
6335 " display_thread_sched_attr(\"Scheduler attributes of new thread\");\n"
6339 #: build/C/man3/pthread_setschedparam.3:311
6347 #: build/C/man3/pthread_setschedparam.3:321
6351 "main(int argc, char *argv[])\n"
6353 " int s, opt, inheritsched, use_null_attrib, policy;\n"
6354 " pthread_t thread;\n"
6355 " pthread_attr_t attr;\n"
6356 " pthread_attr_t *attrp;\n"
6357 " char *attr_sched_str, *main_sched_str, *inheritsched_str;\n"
6358 " struct sched_param param;\n"
6362 #: build/C/man3/pthread_setschedparam.3:323
6364 msgid " /* Process command-line options */\n"
6368 #: build/C/man3/pthread_setschedparam.3:328
6371 " use_null_attrib = 0;\n"
6372 " attr_sched_str = NULL;\n"
6373 " main_sched_str = NULL;\n"
6374 " inheritsched_str = NULL;\n"
6378 #: build/C/man3/pthread_setschedparam.3:338
6381 " while ((opt = getopt(argc, argv, \"a:Ai:m:\")) != -1) {\n"
6383 " case \\(aqa\\(aq: attr_sched_str = optarg; break;\n"
6384 " case \\(aqA\\(aq: use_null_attrib = 1; break;\n"
6385 " case \\(aqi\\(aq: inheritsched_str = optarg; break;\n"
6386 " case \\(aqm\\(aq: main_sched_str = optarg; break;\n"
6387 " default: usage(argv[0], \"Unrecognized option\\en\");\n"
6393 #: build/C/man3/pthread_setschedparam.3:342
6396 " if (use_null_attrib &&\n"
6397 " (inheritsched_str != NULL || attr_sched_str != NULL))\n"
6398 " usage(argv[0], \"Can\\(aqt specify -A with -i or -a\\en\");\n"
6402 #: build/C/man3/pthread_setschedparam.3:345
6405 " /* Optionally set scheduling attributes of main thread,\n"
6406 " and display the attributes */\n"
6410 #: build/C/man3/pthread_setschedparam.3:350
6413 " if (main_sched_str != NULL) {\n"
6414 " if (!get_policy(main_sched_str[0], &policy))\n"
6415 " usage(argv[0], \"Bad policy for main thread (-m)\\en\");\n"
6416 " param.sched_priority = strtol(&main_sched_str[1], NULL, 0);\n"
6420 #: build/C/man3/pthread_setschedparam.3:355
6423 " s = pthread_setschedparam(pthread_self(), policy, ¶m);\n"
6425 " handle_error_en(s, \"pthread_setschedparam\");\n"
6430 #: build/C/man3/pthread_setschedparam.3:358
6433 " display_thread_sched_attr(\"Scheduler settings of main thread\");\n"
6434 " printf(\"\\en\");\n"
6438 #: build/C/man3/pthread_setschedparam.3:360
6440 msgid " /* Initialize thread attributes object according to options */\n"
6444 #: build/C/man3/pthread_setschedparam.3:369
6447 " if (!use_null_attrib) {\n"
6448 " s = pthread_attr_init(&attr);\n"
6450 " handle_error_en(s, \"pthread_attr_init\");\n"
6456 #: build/C/man3/pthread_setschedparam.3:377
6459 " if (inheritsched_str != NULL) {\n"
6460 " if (inheritsched_str[0] == \\(aqe\\(aq)\n"
6461 " inheritsched = PTHREAD_EXPLICIT_SCHED;\n"
6462 " else if (inheritsched_str[0] == \\(aqi\\(aq)\n"
6463 " inheritsched = PTHREAD_INHERIT_SCHED;\n"
6465 " usage(argv[0], \"Value for -i must be \\(aqe\\(aq or "
6466 "\\(aqi\\(aq\\en\");\n"
6470 #: build/C/man3/pthread_setschedparam.3:382
6473 " s = pthread_attr_setinheritsched(&attr, inheritsched);\n"
6475 " handle_error_en(s, \"pthread_attr_setinheritsched\");\n"
6480 #: build/C/man3/pthread_setschedparam.3:388
6483 " if (attr_sched_str != NULL) {\n"
6484 " if (!get_policy(attr_sched_str[0], &policy))\n"
6486 " \"Bad policy for \\(aqattr\\(aq (-a)\\en\");\n"
6487 " param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);\n"
6491 #: build/C/man3/pthread_setschedparam.3:396
6494 " s = pthread_attr_setschedpolicy(&attr, policy);\n"
6496 " handle_error_en(s, \"pthread_attr_setschedpolicy\");\n"
6497 " s = pthread_attr_setschedparam(&attr, ¶m);\n"
6499 " handle_error_en(s, \"pthread_attr_setschedparam\");\n"
6504 #: build/C/man3/pthread_setschedparam.3:399
6507 " /* If we initialized a thread attributes object, display\n"
6508 " the scheduling attributes that were set in the object */\n"
6512 #: build/C/man3/pthread_setschedparam.3:407
6515 " if (attrp != NULL) {\n"
6516 " s = pthread_attr_getschedparam(&attr, ¶m);\n"
6518 " handle_error_en(s, \"pthread_attr_getschedparam\");\n"
6519 " s = pthread_attr_getschedpolicy(&attr, &policy);\n"
6521 " handle_error_en(s, \"pthread_attr_getschedpolicy\");\n"
6525 #: build/C/man3/pthread_setschedparam.3:410
6528 " printf(\"Scheduler settings in \\(aqattr\\(aq\\en\");\n"
6529 " display_sched_attr(policy, ¶m);\n"
6533 #: build/C/man3/pthread_setschedparam.3:418
6536 " s = pthread_attr_getinheritsched(&attr, &inheritsched);\n"
6537 " printf(\" inheritsched is %s\\en\",\n"
6538 " (inheritsched == PTHREAD_INHERIT_SCHED) ? \"INHERIT\" :\n"
6539 " (inheritsched == PTHREAD_EXPLICIT_SCHED) ? \"EXPLICIT\" :\n"
6541 " printf(\"\\en\");\n"
6546 #: build/C/man3/pthread_setschedparam.3:420
6548 msgid " /* Create a thread that will display its scheduling attributes */\n"
6552 #: build/C/man3/pthread_setschedparam.3:424
6555 " s = pthread_create(&thread, attrp, &thread_start, NULL);\n"
6557 " handle_error_en(s, \"pthread_create\");\n"
6561 #: build/C/man3/pthread_setschedparam.3:426
6563 msgid " /* Destroy unneeded thread attributes object */\n"
6567 #: build/C/man3/pthread_setschedparam.3:432
6570 " if (!use_null_attrib) {\n"
6571 " s = pthread_attr_destroy(&attr);\n"
6573 " handle_error_en(s, \"pthread_attr_destroy\");\n"
6578 #: build/C/man3/pthread_setschedparam.3:436
6581 " s = pthread_join(thread, NULL);\n"
6583 " handle_error_en(s, \"pthread_join\");\n"
6587 #: build/C/man3/pthread_setschedparam.3:454
6589 "B<getrlimit>(2), B<sched_get_priority_min>(2), B<pthread_attr_init>(3), "
6590 "B<pthread_attr_setinheritsched>(3), B<pthread_attr_setschedparam>(3), "
6591 "B<pthread_attr_setschedpolicy>(3), B<pthread_create>(3), B<pthread_self>(3), "
6592 "B<pthread_setschedprio>(3), B<pthreads>(7), B<sched>(7)"
6596 #: build/C/man3/pthread_setschedprio.3:26
6598 msgid "PTHREAD_SETSCHEDPRIO"
6602 #: build/C/man3/pthread_setschedprio.3:29
6603 msgid "pthread_setschedprio - set scheduling priority of a thread"
6607 #: build/C/man3/pthread_setschedprio.3:34
6609 msgid "B<int pthread_setschedprio(pthread_t >I<thread>B<, int >I<prio>B<);>\n"
6612 #. FIXME . nptl/pthread_setschedprio.c has the following
6613 #. /* If the thread should have higher priority because of some
6614 #. PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
6615 #. Eventually (perhaps after writing the mutexattr pages), we
6616 #. may want to add something on the topic to this page.
6617 #. nptl/pthread_setschedparam.c has a similar case.
6619 #: build/C/man3/pthread_setschedprio.3:53
6621 "The B<pthread_setschedprio>() function sets the scheduling priority of the "
6622 "thread I<thread> to the value specified in I<prio>. (By contrast "
6623 "B<pthread_setschedparam>(3) changes both the scheduling policy and priority "
6628 #: build/C/man3/pthread_setschedprio.3:61
6630 "On success, this function returns 0; on error, it returns a nonzero error "
6631 "number. If B<pthread_setschedprio>() fails, the scheduling priority of "
6632 "I<thread> is not changed."
6636 #: build/C/man3/pthread_setschedprio.3:66
6637 msgid "I<prio> is not valid for the scheduling policy of the specified thread."
6641 #: build/C/man3/pthread_setschedprio.3:70
6643 "The caller does not have appropriate privileges to set the specified "
6648 #: build/C/man3/pthread_setschedprio.3:81
6650 "POSIX.1-2001 also documents an B<ENOTSUP> (\"attempt was made to set the "
6651 "priority to an unsupported value\") error for B<pthread_setschedparam>(3)."
6655 #: build/C/man3/pthread_setschedprio.3:83
6656 msgid "This function is available in glibc since version 2.3.4."
6660 #: build/C/man3/pthread_setschedprio.3:88
6661 msgid "The B<pthread_setschedprio>() function is thread-safe."
6665 #: build/C/man3/pthread_setschedprio.3:96
6667 "For a description of the permissions required to, and the effect of, "
6668 "changing a thread's scheduling priority, and details of the permitted ranges "
6669 "for priorities in each scheduling policy, see B<sched>(7)."
6673 #: build/C/man3/pthread_setschedprio.3:110
6675 "B<getrlimit>(2), B<sched_get_priority_min>(2), B<pthread_attr_init>(3), "
6676 "B<pthread_attr_setinheritsched>(3), B<pthread_attr_setschedparam>(3), "
6677 "B<pthread_attr_setschedpolicy>(3), B<pthread_create>(3), B<pthread_self>(3), "
6678 "B<pthread_setschedparam>(3), B<pthreads>(7), B<sched>(7)"
6682 #: build/C/man3/pthread_sigmask.3:26
6684 msgid "PTHREAD_SIGMASK"
6688 #: build/C/man3/pthread_sigmask.3:26 build/C/man3/pthread_testcancel.3:26
6694 #: build/C/man3/pthread_sigmask.3:29
6695 msgid "pthread_sigmask - examine and change mask of blocked signals"
6699 #: build/C/man3/pthread_sigmask.3:35
6702 "B<int pthread_sigmask(int >I<how>B<, const sigset_t *>I<set>B<, sigset_t "
6703 "*>I<oldset>B<);>\n"
6707 #: build/C/man3/pthread_sigmask.3:46
6708 msgid "B<pthread_sigmask>():"
6712 #: build/C/man3/pthread_sigmask.3:58
6714 "The B<pthread_sigmask>() function is just like B<sigprocmask>(2), with the "
6715 "difference that its use in multithreaded programs is explicitly specified by "
6716 "POSIX.1-2001. Other differences are noted in this page."
6720 #: build/C/man3/pthread_sigmask.3:61
6722 "For a description of the arguments and operation of this function, see "
6723 "B<sigprocmask>(2)."
6727 #: build/C/man3/pthread_sigmask.3:66
6729 "On success, B<pthread_sigmask>() returns 0; on error, it returns an error "
6734 #: build/C/man3/pthread_sigmask.3:69
6735 msgid "See B<sigprocmask>(2)."
6739 #: build/C/man3/pthread_sigmask.3:74
6740 msgid "The B<pthread_sigmask>() function is thread-safe."
6744 #: build/C/man3/pthread_sigmask.3:78
6745 msgid "A new thread inherits a copy of its creator's signal mask."
6749 #: build/C/man3/pthread_sigmask.3:83
6751 "The program below blocks some signals in the main thread, and then creates a "
6752 "dedicated thread to fetch those signals via B<sigwait>(3). The following "
6753 "shell session demonstrates its use:"
6757 #: build/C/man3/pthread_sigmask.3:94
6762 "$B< kill -QUIT %1>\n"
6763 "Signal handling thread got signal 3\n"
6764 "$B< kill -USR1 %1>\n"
6765 "Signal handling thread got signal 10\n"
6766 "$B< kill -TERM %1>\n"
6767 "[1]+ Terminated ./a.out\n"
6771 #: build/C/man3/pthread_sigmask.3:105
6774 "#include E<lt>pthread.hE<gt>\n"
6775 "#include E<lt>stdio.hE<gt>\n"
6776 "#include E<lt>stdlib.hE<gt>\n"
6777 "#include E<lt>unistd.hE<gt>\n"
6778 "#include E<lt>signal.hE<gt>\n"
6779 "#include E<lt>errno.hE<gt>\n"
6783 #: build/C/man3/pthread_sigmask.3:107
6785 msgid "/* Simple error handling functions */\n"
6789 #: build/C/man3/pthread_sigmask.3:116
6793 "sig_thread(void *arg)\n"
6795 " sigset_t *set = arg;\n"
6800 #: build/C/man3/pthread_sigmask.3:124
6804 " s = sigwait(set, &sig);\n"
6806 " handle_error_en(s, \"sigwait\");\n"
6807 " printf(\"Signal handling thread got signal %d\\en\", sig);\n"
6813 #: build/C/man3/pthread_sigmask.3:131
6817 "main(int argc, char *argv[])\n"
6819 " pthread_t thread;\n"
6825 #: build/C/man3/pthread_sigmask.3:134
6828 " /* Block SIGQUIT and SIGUSR1; other threads created by main()\n"
6829 " will inherit a copy of the signal mask. */\n"
6833 #: build/C/man3/pthread_sigmask.3:141
6836 " sigemptyset(&set);\n"
6837 " sigaddset(&set, SIGQUIT);\n"
6838 " sigaddset(&set, SIGUSR1);\n"
6839 " s = pthread_sigmask(SIG_BLOCK, &set, NULL);\n"
6841 " handle_error_en(s, \"pthread_sigmask\");\n"
6845 #: build/C/man3/pthread_sigmask.3:145
6848 " s = pthread_create(&thread, NULL, &sig_thread, (void *) &set);\n"
6850 " handle_error_en(s, \"pthread_create\");\n"
6854 #: build/C/man3/pthread_sigmask.3:148
6857 " /* Main thread carries on to create other threads and/or do\n"
6862 #: build/C/man3/pthread_sigmask.3:151
6865 " pause(); /* Dummy pause so we can test program */\n"
6870 #: build/C/man3/pthread_sigmask.3:161
6872 "B<sigaction>(2), B<sigpending>(2), B<sigprocmask>(2), B<pthread_create>(3), "
6873 "B<pthread_kill>(3), B<sigsetops>(3), B<pthreads>(7), B<signal>(7)"
6877 #: build/C/man3/pthread_sigqueue.3:25
6879 msgid "PTHREAD_SIGQUEUE"
6883 #: build/C/man3/pthread_sigqueue.3:28
6884 msgid "pthread_sigqueue - queue a signal and data to a thread"
6888 #: build/C/man3/pthread_sigqueue.3:32
6891 "B<#include E<lt>signal.hE<gt>>\n"
6892 "B<#include E<lt>pthread.hE<gt>>\n"
6896 #: build/C/man3/pthread_sigqueue.3:35
6899 "B<int pthread_sigqueue(pthread_t >I<thread>B<, int >I<sig>B<,>\n"
6900 "B< const union sigval >I<value>B<);>\n"
6904 #: build/C/man3/pthread_sigqueue.3:46
6905 msgid "B<pthread_sigqueue>(): _GNU_SOURCE"
6909 #: build/C/man3/pthread_sigqueue.3:54
6911 "The B<pthread_sigqueue>() function performs a similar task to "
6912 "B<sigqueue>(3), but, rather than sending a signal to a process, it sends a "
6913 "signal to a thread in the same process as the calling thread."
6917 #: build/C/man3/pthread_sigqueue.3:66
6919 "The I<thread> argument is the ID of a thread in the same process as the "
6920 "caller. The I<sig> argument specifies the signal to be sent. The I<value> "
6921 "argument specifies data to accompany the signal; see B<sigqueue>(3) for "
6926 #: build/C/man3/pthread_sigqueue.3:71
6928 "On success, B<pthread_sigqueue>() returns 0; on error, it returns an error "
6933 #: build/C/man3/pthread_sigqueue.3:78
6935 "The limit of signals which may be queued has been reached. (See "
6936 "B<signal>(7) for further information.)"
6940 #: build/C/man3/pthread_sigqueue.3:82
6941 msgid "I<sig> was invalid."
6945 #: build/C/man3/pthread_sigqueue.3:82
6951 #: build/C/man3/pthread_sigqueue.3:86
6952 msgid "B<pthread_sigqueue>() is not supported on this system."
6956 #: build/C/man3/pthread_sigqueue.3:90
6957 msgid "I<thread> is not valid."
6961 #: build/C/man3/pthread_sigqueue.3:94
6962 msgid "The B<pthread_sigqueue>() function first appeared in glibc 2.11."
6966 #: build/C/man3/pthread_sigqueue.3:99
6967 msgid "The B<pthread_sigqueue>() function is thread-safe."
6971 #: build/C/man3/pthread_sigqueue.3:101
6972 msgid "This function is a GNU extension."
6976 #: build/C/man3/pthread_sigqueue.3:109
6978 "B<rt_tgsigqueueinfo>(2), B<sigaction>(2), B<pthread_sigmask>(3), "
6979 "B<sigqueue>(3), B<sigwait>(3), B<pthreads>(7), B<signal>(7)"
6983 #: build/C/man3/pthread_testcancel.3:26
6985 msgid "PTHREAD_TESTCANCEL"
6989 #: build/C/man3/pthread_testcancel.3:29
6990 msgid "pthread_testcancel - request delivery of any pending cancellation request"
6994 #: build/C/man3/pthread_testcancel.3:34
6996 msgid "B<void pthread_testcancel(void);>\n"
7000 #: build/C/man3/pthread_testcancel.3:43
7002 "Calling B<pthread_testcancel>() creates a cancellation point within the "
7003 "calling thread, so that a thread that is otherwise executing code that "
7004 "contains no cancellation points will respond to a cancellation request."
7008 #: build/C/man3/pthread_testcancel.3:50
7010 "If cancelability is disabled (using B<pthread_setcancelstate>(3)), or no "
7011 "cancellation request is pending, then a call to B<pthread_testcancel>() has "
7016 #: build/C/man3/pthread_testcancel.3:54
7018 "This function does not return a value. If the calling thread is canceled as "
7019 "a consequence of a call to this function, then the function does not return."
7023 #: build/C/man3/pthread_testcancel.3:63
7024 msgid "The B<pthread_testcancel>() function is thread-safe."
7028 #: build/C/man3/pthread_testcancel.3:68
7029 msgid "See B<pthread_cleanup_push>(3)."
7033 #: build/C/man3/pthread_testcancel.3:73
7035 "B<pthread_cancel>(3), B<pthread_cleanup_push>(3), "
7036 "B<pthread_setcancelstate>(3), B<pthreads>(7)"
7040 #: build/C/man3/pthread_tryjoin_np.3:26
7042 msgid "PTHREAD_TRYJOIN_NP"
7046 #: build/C/man3/pthread_tryjoin_np.3:26
7052 #: build/C/man3/pthread_tryjoin_np.3:30
7054 "pthread_tryjoin_np, pthread_timedjoin_np - try to join with a terminated "
7059 #: build/C/man3/pthread_tryjoin_np.3:36
7061 msgid "B<int pthread_tryjoin_np(pthread_t >I<thread>B<, void **>I<retval>B<);>\n"
7065 #: build/C/man3/pthread_tryjoin_np.3:39
7068 "B<int pthread_timedjoin_np(pthread_t >I<thread>B<, void **>I<retval>B<,>\n"
7069 "B< const struct timespec *>I<abstime>B<);>\n"
7073 #: build/C/man3/pthread_tryjoin_np.3:46
7075 "These functions operate in the same way as B<pthread_join>(3), except for "
7076 "the differences described on this page."
7080 #: build/C/man3/pthread_tryjoin_np.3:58
7082 "The B<pthread_tryjoin_np>() function performs a nonblocking join with the "
7083 "thread I<thread>, returning the exit status of the thread in I<*retval>. If "
7084 "I<thread> has not yet terminated, then instead of blocking, as is done by "
7085 "B<pthread_join>(3), the call returns an error."
7089 #: build/C/man3/pthread_tryjoin_np.3:76
7091 "The B<pthread_timedjoin_np>() function performs a join-with-timeout. If "
7092 "I<thread> has not yet terminated, then the call blocks until a maximum time, "
7093 "specified in I<abstime>. If the timeout expires before I<thread> "
7094 "terminates, the call returns an error. The I<abstime> argument is a "
7095 "structure of the following form, specifying an absolute time measured since "
7096 "the Epoch (see B<time>(2)):"
7100 #: build/C/man3/pthread_tryjoin_np.3:83
7103 "struct timespec {\n"
7104 " time_t tv_sec; /* seconds */\n"
7105 " long tv_nsec; /* nanoseconds */\n"
7110 #: build/C/man3/pthread_tryjoin_np.3:89
7111 msgid "On success, these functions return 0; on error, they return an error number."
7115 #: build/C/man3/pthread_tryjoin_np.3:94
7117 "These functions can fail with the same errors as B<pthread_join>(3). "
7118 "B<pthread_tryjoin_np>() can in addition fail with the following error:"
7122 #: build/C/man3/pthread_tryjoin_np.3:94
7128 #: build/C/man3/pthread_tryjoin_np.3:98
7129 msgid "I<thread> had not yet terminated at the time of the call."
7133 #: build/C/man3/pthread_tryjoin_np.3:101
7134 msgid "B<pthread_timedjoin_np>() can in addition fail with the following errors:"
7138 #: build/C/man3/pthread_tryjoin_np.3:101
7140 msgid "B<ETIMEDOUT>"
7144 #: build/C/man3/pthread_tryjoin_np.3:106
7145 msgid "The call timed out before I<thread> terminated."
7149 #: build/C/man3/pthread_tryjoin_np.3:114
7151 "I<abstime> value is invalid (I<tv_sec> is less than 0 or I<tv_nsec> is "
7152 "greater than 1e9)."
7156 #: build/C/man3/pthread_tryjoin_np.3:118
7157 msgid "B<pthread_timedjoin_np>() never returns the error B<EINTR>."
7161 #: build/C/man3/pthread_tryjoin_np.3:120
7162 msgid "These functions first appeared in glibc in version 2.3.3."
7166 #: build/C/man3/pthread_tryjoin_np.3:125
7167 msgid "The following code waits to join for up to 5 seconds:"
7171 #: build/C/man3/pthread_tryjoin_np.3:129
7174 " struct timespec ts;\n"
7179 #: build/C/man3/pthread_tryjoin_np.3:131
7185 #: build/C/man3/pthread_tryjoin_np.3:135
7188 " if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {\n"
7189 "\t/* Handle error */\n"
7194 #: build/C/man3/pthread_tryjoin_np.3:137
7196 msgid " ts.tv_sec += 5;\n"
7200 #: build/C/man3/pthread_tryjoin_np.3:142
7203 " s = pthread_timedjoin_np(thread, NULL, &ts);\n"
7205 " /* Handle error */\n"
7210 #: build/C/man3/pthread_tryjoin_np.3:148
7211 msgid "B<clock_gettime>(2), B<pthread_exit>(3), B<pthread_join>(3), B<pthreads>(7)"
7215 #: build/C/man3/pthread_yield.3:25
7217 msgid "PTHREAD_YIELD"
7221 #: build/C/man3/pthread_yield.3:28
7222 msgid "pthread_yield - yield the processor"
7226 #: build/C/man3/pthread_yield.3:34
7228 msgid "B<int pthread_yield(void);>\n"
7232 #: build/C/man3/pthread_yield.3:44
7234 "B<pthread_yield>() causes the calling thread to relinquish the CPU. The "
7235 "thread is placed at the end of the run queue for its static priority and "
7236 "another thread is scheduled to run. For further details, see "
7241 #: build/C/man3/pthread_yield.3:49
7243 "On success, B<pthread_yield>() returns 0; on error, it returns an error "
7248 #: build/C/man3/pthread_yield.3:53
7250 "On Linux, this call always succeeds (but portable and future-proof "
7251 "applications should nevertheless handle a possible error return)."
7255 #: build/C/man3/pthread_yield.3:58
7256 msgid "The B<pthread_yield>() function is thread-safe."
7259 #. e.g., the BSDs, Tru64, AIX, and Irix.
7261 #: build/C/man3/pthread_yield.3:64
7263 "This call is nonstandard, but present on several other systems. Use the "
7264 "standardized B<sched_yield>(2) instead."
7268 #: build/C/man3/pthread_yield.3:67
7269 msgid "On Linux, this function is implemented as a call to B<sched_yield>(2)."
7273 #: build/C/man3/pthread_yield.3:71
7274 msgid "B<sched_yield>(2), B<pthreads>(7), B<sched>(7)"
7278 #: build/C/man7/pthreads.7:26
7284 #: build/C/man7/pthreads.7:29
7285 msgid "pthreads - POSIX threads"
7289 #: build/C/man7/pthreads.7:36
7291 "POSIX.1 specifies a set of interfaces (functions, header files) for threaded "
7292 "programming commonly known as POSIX threads, or Pthreads. A single process "
7293 "can contain multiple threads, all of which are executing the same program. "
7294 "These threads share the same global memory (data and heap segments), but "
7295 "each thread has its own stack (automatic variables)."
7299 #: build/C/man7/pthreads.7:39
7301 "POSIX.1 also requires that threads share a range of other attributes (i.e., "
7302 "these attributes are process-wide rather than per-thread):"
7306 #: build/C/man7/pthreads.7:39 build/C/man7/pthreads.7:41 build/C/man7/pthreads.7:43 build/C/man7/pthreads.7:45 build/C/man7/pthreads.7:47 build/C/man7/pthreads.7:49 build/C/man7/pthreads.7:51 build/C/man7/pthreads.7:54 build/C/man7/pthreads.7:56 build/C/man7/pthreads.7:59 build/C/man7/pthreads.7:65 build/C/man7/pthreads.7:70 build/C/man7/pthreads.7:73 build/C/man7/pthreads.7:76 build/C/man7/pthreads.7:84 build/C/man7/pthreads.7:88 build/C/man7/pthreads.7:91 build/C/man7/pthreads.7:95 build/C/man7/pthreads.7:98 build/C/man7/pthreads.7:103 build/C/man7/pthreads.7:106 build/C/man7/pthreads.7:683 build/C/man7/pthreads.7:690 build/C/man7/pthreads.7:702 build/C/man7/pthreads.7:712 build/C/man7/pthreads.7:716 build/C/man7/pthreads.7:725 build/C/man7/pthreads.7:735 build/C/man7/pthreads.7:742 build/C/man7/pthreads.7:749 build/C/man7/pthreads.7:751 build/C/man7/pthreads.7:754 build/C/man7/pthreads.7:760 build/C/man7/pthreads.7:763 build/C/man7/pthreads.7:765 build/C/man7/pthreads.7:767 build/C/man7/pthreads.7:777 build/C/man7/pthreads.7:797 build/C/man7/pthreads.7:806 build/C/man7/pthreads.7:812 build/C/man7/pthreads.7:814 build/C/man7/pthreads.7:816 build/C/man7/pthreads.7:820 build/C/man7/pthreads.7:825 build/C/man7/pthreads.7:833
7312 #: build/C/man7/pthreads.7:41
7317 #: build/C/man7/pthreads.7:43
7318 msgid "parent process ID"
7322 #: build/C/man7/pthreads.7:45
7323 msgid "process group ID and session ID"
7327 #: build/C/man7/pthreads.7:47
7328 msgid "controlling terminal"
7332 #: build/C/man7/pthreads.7:49
7333 msgid "user and group IDs"
7337 #: build/C/man7/pthreads.7:51
7338 msgid "open file descriptors"
7342 #: build/C/man7/pthreads.7:54
7343 msgid "record locks (see B<fcntl>(2))"
7347 #: build/C/man7/pthreads.7:56
7348 msgid "signal dispositions"
7352 #: build/C/man7/pthreads.7:59
7353 msgid "file mode creation mask (B<umask>(2))"
7357 #: build/C/man7/pthreads.7:65
7358 msgid "current directory (B<chdir>(2)) and root directory (B<chroot>(2))"
7362 #: build/C/man7/pthreads.7:70
7363 msgid "interval timers (B<setitimer>(2)) and POSIX timers (B<timer_create>(2))"
7367 #: build/C/man7/pthreads.7:73
7368 msgid "nice value (B<setpriority>(2))"
7372 #: build/C/man7/pthreads.7:76
7373 msgid "resource limits (B<setrlimit>(2))"
7377 #: build/C/man7/pthreads.7:81
7379 "measurements of the consumption of CPU time (B<times>(2)) and resources "
7384 #: build/C/man7/pthreads.7:84
7386 "As well as the stack, POSIX.1 specifies that various other attributes are "
7387 "distinct for each thread, including:"
7391 #: build/C/man7/pthreads.7:88
7392 msgid "thread ID (the I<pthread_t> data type)"
7396 #: build/C/man7/pthreads.7:91
7397 msgid "signal mask (B<pthread_sigmask>(3))"
7401 #: build/C/man7/pthreads.7:95
7402 msgid "the I<errno> variable"
7406 #: build/C/man7/pthreads.7:98
7407 msgid "alternate signal stack (B<sigaltstack>(2))"
7411 #: build/C/man7/pthreads.7:101
7412 msgid "real-time scheduling policy and priority (B<sched>(7))"
7416 #: build/C/man7/pthreads.7:103
7417 msgid "The following Linux-specific features are also per-thread:"
7421 #: build/C/man7/pthreads.7:106
7422 msgid "capabilities (see B<capabilities>(7))"
7426 #: build/C/man7/pthreads.7:109
7427 msgid "CPU affinity (B<sched_setaffinity>(2))"
7431 #: build/C/man7/pthreads.7:109
7433 msgid "Pthreads function return values"
7437 #: build/C/man7/pthreads.7:116
7439 "Most pthreads functions return 0 on success, and an error number of "
7440 "failure. Note that the pthreads functions do not set I<errno>. For each of "
7441 "the pthreads functions that can return an error, POSIX.1-2001 specifies that "
7442 "the function can never fail with the error B<EINTR>."
7446 #: build/C/man7/pthreads.7:116
7452 #: build/C/man7/pthreads.7:130
7454 "Each of the threads in a process has a unique thread identifier (stored in "
7455 "the type I<pthread_t>). This identifier is returned to the caller of "
7456 "B<pthread_create>(3), and a thread can obtain its own thread identifier "
7457 "using B<pthread_self>(3). Thread IDs are guaranteed to be unique only "
7458 "within a process. A thread ID may be reused after a terminated thread has "
7459 "been joined, or a detached thread has terminated. In all pthreads functions "
7460 "that accept a thread ID as an argument, that ID by definition refers to a "
7461 "thread in the same process as the caller."
7465 #: build/C/man7/pthreads.7:130
7467 msgid "Thread-safe functions"
7471 #: build/C/man7/pthreads.7:134
7473 "A thread-safe function is one that can be safely (i.e., it will deliver the "
7474 "same results regardless of whether it is) called from multiple threads at "
7479 #: build/C/man7/pthreads.7:138
7481 "POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the "
7482 "standard shall be thread-safe, except for the following functions:"
7486 #: build/C/man7/pthreads.7:232
7493 "ctermid() if passed a non-NULL argument\n"
7507 "ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7512 "fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7514 "gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7516 "getchar_unlocked()\n"
7522 "gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7523 "gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7530 "getprotobyname()\n"
7531 "getprotobynumber()\n"
7559 "putchar_unlocked()\n"
7570 "strsignal() [Added in POSIX.1-2008]\n"
7572 "system() [Added in POSIX.1-2008]\n"
7573 "tmpnam() if passed a non-NULL argument\n"
7576 "wcrtomb() if its final argument is NULL\n"
7577 "wcsrtombs() if its final argument is NULL\n"
7583 #: build/C/man7/pthreads.7:234
7585 msgid "Async-cancel-safe functions"
7589 #: build/C/man7/pthreads.7:238
7591 "An async-cancel-safe function is one that can be safely called in an "
7592 "application where asynchronous cancelability is enabled (see "
7593 "B<pthread_setcancelstate>(3))."
7597 #: build/C/man7/pthreads.7:241
7599 "Only the following functions are required to be async-cancel-safe by "
7600 "POSIX.1-2001 and POSIX.1-2008:"
7604 #: build/C/man7/pthreads.7:247
7607 "pthread_cancel()\n"
7608 "pthread_setcancelstate()\n"
7609 "pthread_setcanceltype()\n"
7613 #: build/C/man7/pthreads.7:249
7615 msgid "Cancellation points"
7619 #: build/C/man7/pthreads.7:256
7621 "POSIX.1 specifies that certain functions must, and certain other functions "
7622 "may, be cancellation points. If a thread is cancelable, its cancelability "
7623 "type is deferred, and a cancellation request is pending for the thread, then "
7624 "the thread is canceled when it calls a function that is a cancellation "
7629 #: build/C/man7/pthreads.7:259
7631 "The following functions are required to be cancellation points by "
7632 "POSIX.1-2001 and/or POSIX.1-2008:"
7636 #: build/C/man7/pthreads.7:322
7641 "clock_nanosleep()\n"
7645 "fcntl() F_SETLKW\n"
7653 "mq_timedreceive()\n"
7660 "openat() [Added in POSIX.1-2008]\n"
7665 "pthread_cond_timedwait()\n"
7666 "pthread_cond_wait()\n"
7668 "pthread_testcancel()\n"
7683 "sigpause() [POSIX.1-2001 only (moves to \"may\" list in POSIX.1-2008)]\n"
7691 "usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]\n"
7700 #: build/C/man7/pthreads.7:327
7702 "The following functions may be cancellation points according to POSIX.1-2001 "
7703 "and/or POSIX.1-2008:"
7707 #: build/C/man7/pthreads.7:555
7716 "chmod() [Added in POSIX.1-2008]\n"
7717 "chown() [Added in POSIX.1-2008]\n"
7731 "dprintf() [Added in POSIX.1-2008]\n"
7739 "faccessat() [Added in POSIX.1-2008]\n"
7740 "fchmod() [Added in POSIX.1-2008]\n"
7741 "fchmodat() [Added in POSIX.1-2008]\n"
7742 "fchown() [Added in POSIX.1-2008]\n"
7743 "fchownat() [Added in POSIX.1-2008]\n"
7745 "fcntl() (for any value of cmd argument)\n"
7767 "fstatat() [Added in POSIX.1-2008]\n"
7771 "futimens() [Added in POSIX.1-2008]\n"
7779 "getchar_unlocked()\n"
7782 "getdelim() [Added in POSIX.1-2008]\n"
7788 "gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]\n"
7789 "gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]\n"
7793 "getline() [Added in POSIX.1-2008]\n"
7800 "getopt() (if opterr is nonzero)\n"
7801 "getprotobyname()\n"
7802 "getprotobynumber()\n"
7818 "getwd() [SUSv3 only (function removed in POSIX.1-2008)]\n"
7824 "linkat() [Added in POSIX.1-2008]\n"
7825 "lio_listio() [Added in POSIX.1-2008]\n"
7828 "lockf() [Added in POSIX.1-2008]\n"
7831 "mkdir() [Added in POSIX.1-2008]\n"
7832 "mkdirat() [Added in POSIX.1-2008]\n"
7833 "mkdtemp() [Added in POSIX.1-2008]\n"
7834 "mkfifo() [Added in POSIX.1-2008]\n"
7835 "mkfifoat() [Added in POSIX.1-2008]\n"
7836 "mknod() [Added in POSIX.1-2008]\n"
7837 "mknodat() [Added in POSIX.1-2008]\n"
7848 "posix_fallocate()\n"
7853 "posix_trace_clear()\n"
7854 "posix_trace_close()\n"
7855 "posix_trace_create()\n"
7856 "posix_trace_create_withlog()\n"
7857 "posix_trace_eventtypelist_getnext_id()\n"
7858 "posix_trace_eventtypelist_rewind()\n"
7859 "posix_trace_flush()\n"
7860 "posix_trace_get_attr()\n"
7861 "posix_trace_get_filter()\n"
7862 "posix_trace_get_status()\n"
7863 "posix_trace_getnext_event()\n"
7864 "posix_trace_open()\n"
7865 "posix_trace_rewind()\n"
7866 "posix_trace_set_filter()\n"
7867 "posix_trace_shutdown()\n"
7868 "posix_trace_timedgetnext_event()\n"
7869 "posix_typed_mem_open()\n"
7871 "psiginfo() [Added in POSIX.1-2008]\n"
7872 "psignal() [Added in POSIX.1-2008]\n"
7873 "pthread_rwlock_rdlock()\n"
7874 "pthread_rwlock_timedrdlock()\n"
7875 "pthread_rwlock_timedwrlock()\n"
7876 "pthread_rwlock_wrlock()\n"
7880 "putchar_unlocked()\n"
7887 "readlink() [Added in POSIX.1-2008]\n"
7888 "readlinkat() [Added in POSIX.1-2008]\n"
7891 "renameat() [Added in POSIX.1-2008]\n"
7894 "scandir() [Added in POSIX.1-2008]\n"
7905 "sigpause() [Added in POSIX.1-2008]\n"
7911 "symlinkat() [Added in POSIX.1-2008]\n"
7922 "unlinkat() [Added in POSIX.1-2008]\n"
7923 "utime() [Added in POSIX.1-2008]\n"
7924 "utimensat() [Added in POSIX.1-2008]\n"
7925 "utimes() [Added in POSIX.1-2008]\n"
7926 "vdprintf() [Added in POSIX.1-2008]\n"
7937 #. So, scanning "cancellation point" comments in the glibc 2.8 header
7938 #. files, it looks as though at least the following nonstandard
7939 #. functions are cancellation points:
7979 #. getprotobynumber_r
7994 #. getwchar_unlocked
8001 #. pthread_timedjoin_np
8007 #. putwchar_unlocked
8028 #: build/C/man7/pthreads.7:653
8030 "An implementation may also mark other functions not specified in the "
8031 "standard as cancellation points. In particular, an implementation is likely "
8032 "to mark any nonstandard function that may block as a cancellation point. "
8033 "(This includes most functions that can touch files.)"
8037 #: build/C/man7/pthreads.7:653
8039 msgid "Compiling on Linux"
8043 #: build/C/man7/pthreads.7:656
8045 "On Linux, programs that use the Pthreads API should be compiled using I<cc "
8050 #: build/C/man7/pthreads.7:656
8052 msgid "Linux implementations of POSIX threads"
8056 #: build/C/man7/pthreads.7:659
8058 "Over time, two threading implementations have been provided by the GNU C "
8063 #: build/C/man7/pthreads.7:659
8065 msgid "B<LinuxThreads>"
8069 #: build/C/man7/pthreads.7:663
8071 "This is the original Pthreads implementation. Since glibc 2.4, this "
8072 "implementation is no longer supported."
8076 #: build/C/man7/pthreads.7:663
8078 msgid "B<NPTL> (Native POSIX Threads Library)"
8082 #: build/C/man7/pthreads.7:671
8084 "This is the modern Pthreads implementation. By comparison with "
8085 "LinuxThreads, NPTL provides closer conformance to the requirements of the "
8086 "POSIX.1 specification and better performance when creating large numbers of "
8087 "threads. NPTL is available since glibc 2.3.2, and requires features that "
8088 "are present in the Linux 2.6 kernel."
8092 #: build/C/man7/pthreads.7:681
8094 "Both of these are so-called 1:1 implementations, meaning that each thread "
8095 "maps to a kernel scheduling entity. Both threading implementations employ "
8096 "the Linux B<clone>(2) system call. In NPTL, thread synchronization "
8097 "primitives (mutexes, thread joining, and so on) are implemented using the "
8098 "Linux B<futex>(2) system call."
8102 #: build/C/man7/pthreads.7:681
8104 msgid "LinuxThreads"
8108 #: build/C/man7/pthreads.7:683
8109 msgid "The notable features of this implementation are the following:"
8113 #: build/C/man7/pthreads.7:690
8115 "In addition to the main (initial) thread, and the threads that the program "
8116 "creates using B<pthread_create>(3), the implementation creates a \"manager\" "
8117 "thread. This thread handles thread creation and termination. (Problems can "
8118 "result if this thread is inadvertently killed.)"
8122 #: build/C/man7/pthreads.7:702
8124 "Signals are used internally by the implementation. On Linux 2.2 and later, "
8125 "the first three real-time signals are used (see also B<signal>(7)). On "
8126 "older Linux kernels, B<SIGUSR1> and B<SIGUSR2> are used. Applications must "
8127 "avoid the use of whichever set of signals is employed by the implementation."
8131 #: build/C/man7/pthreads.7:709
8133 "Threads do not share process IDs. (In effect, LinuxThreads threads are "
8134 "implemented as processes which share more information than usual, but which "
8135 "do not share a common process ID.) LinuxThreads threads (including the "
8136 "manager thread) are visible as separate processes using B<ps>(1)."
8140 #: build/C/man7/pthreads.7:712
8142 "The LinuxThreads implementation deviates from the POSIX.1 specification in a "
8143 "number of ways, including the following:"
8147 #: build/C/man7/pthreads.7:716
8148 msgid "Calls to B<getpid>(2) return a different value in each thread."
8152 #: build/C/man7/pthreads.7:725
8154 "Calls to B<getppid>(2) in threads other than the main thread return the "
8155 "process ID of the manager thread; instead B<getppid>(2) in these threads "
8156 "should return the same value as B<getppid>(2) in the main thread."
8160 #: build/C/man7/pthreads.7:735
8162 "When one thread creates a new child process using B<fork>(2), any thread "
8163 "should be able to B<wait>(2) on the child. However, the implementation "
8164 "only allows the thread that created the child to B<wait>(2) on it."
8168 #: build/C/man7/pthreads.7:742
8170 "When a thread calls B<execve>(2), all other threads are terminated (as "
8171 "required by POSIX.1). However, the resulting process has the same PID as "
8172 "the thread that called B<execve>(2): it should have the same PID as the main "
8177 #: build/C/man7/pthreads.7:749
8179 "Threads do not share user and group IDs. This can cause complications with "
8180 "set-user-ID programs and can cause failures in Pthreads functions if an "
8181 "application changes its credentials using B<seteuid>(2) or similar."
8185 #: build/C/man7/pthreads.7:751
8186 msgid "Threads do not share a common session ID and process group ID."
8190 #: build/C/man7/pthreads.7:754
8191 msgid "Threads do not share record locks created using B<fcntl>(2)."
8195 #: build/C/man7/pthreads.7:760
8197 "The information returned by B<times>(2) and B<getrusage>(2) is per-thread "
8198 "rather than process-wide."
8202 #: build/C/man7/pthreads.7:763
8203 msgid "Threads do not share semaphore undo values (see B<semop>(2))."
8207 #: build/C/man7/pthreads.7:765
8208 msgid "Threads do not share interval timers."
8211 #. FIXME . bug report filed for NPTL nice nonconformance
8212 #. http://bugzilla.kernel.org/show_bug.cgi?id=6258
8213 #. Sep 08: there is a patch by Denys Vlasenko to address this
8214 #. "make setpriority POSIX compliant; introduce PRIO_THREAD extension"
8215 #. Monitor this to see if it makes it into mainline.
8217 #: build/C/man7/pthreads.7:767 build/C/man7/pthreads.7:804
8218 msgid "Threads do not share a common nice value."
8222 #: build/C/man7/pthreads.7:777
8224 "POSIX.1 distinguishes the notions of signals that are directed to the "
8225 "process as a whole and signals that are directed to individual threads. "
8226 "According to POSIX.1, a process-directed signal (sent using B<kill>(2), for "
8227 "example) should be handled by a single, arbitrarily selected thread within "
8228 "the process. LinuxThreads does not support the notion of process-directed "
8229 "signals: signals may be sent only to specific threads."
8233 #: build/C/man7/pthreads.7:786
8235 "Threads have distinct alternate signal stack settings. However, a new "
8236 "thread's alternate signal stack settings are copied from the thread that "
8237 "created it, so that the threads initially share an alternate signal stack. "
8238 "(A new thread should start with no alternate signal stack defined. If two "
8239 "threads handle signals on their shared alternate signal stack at the same "
8240 "time, unpredictable program failures are likely to occur.)"
8244 #: build/C/man7/pthreads.7:786
8250 #: build/C/man7/pthreads.7:795
8252 "With NPTL, all of the threads in a process are placed in the same thread "
8253 "group; all members of a thread group share the same PID. NPTL does not "
8254 "employ a manager thread. NPTL makes internal use of the first two real-time "
8255 "signals (see also B<signal>(7)); these signals cannot be used in "
8260 #: build/C/man7/pthreads.7:797
8261 msgid "NPTL still has at least one nonconformance with POSIX.1:"
8265 #: build/C/man7/pthreads.7:806
8266 msgid "Some NPTL nonconformances occur only with older kernels:"
8270 #: build/C/man7/pthreads.7:812
8272 "The information returned by B<times>(2) and B<getrusage>(2) is per-thread "
8273 "rather than process-wide (fixed in kernel 2.6.9)."
8277 #: build/C/man7/pthreads.7:814
8278 msgid "Threads do not share resource limits (fixed in kernel 2.6.10)."
8282 #: build/C/man7/pthreads.7:816
8283 msgid "Threads do not share interval timers (fixed in kernel 2.6.12)."
8287 #: build/C/man7/pthreads.7:820
8289 "Only the main thread is permitted to start a new session using B<setsid>(2) "
8290 "(fixed in kernel 2.6.16)."
8294 #: build/C/man7/pthreads.7:825
8296 "Only the main thread is permitted to make the process into a process group "
8297 "leader using B<setpgid>(2) (fixed in kernel 2.6.16)."
8301 #: build/C/man7/pthreads.7:831
8303 "Threads have distinct alternate signal stack settings. However, a new "
8304 "thread's alternate signal stack settings are copied from the thread that "
8305 "created it, so that the threads initially share an alternate signal stack "
8306 "(fixed in kernel 2.6.16)."
8310 #: build/C/man7/pthreads.7:833
8311 msgid "Note the following further points about the NPTL implementation:"
8315 #: build/C/man7/pthreads.7:847
8317 "If the stack size soft resource limit (see the description of "
8318 "B<RLIMIT_STACK> in B<setrlimit>(2)) is set to a value other than "
8319 "I<unlimited>, then this value defines the default stack size for new "
8320 "threads. To be effective, this limit must be set before the program is "
8321 "executed, perhaps using the I<ulimit -s> shell built-in command (I<limit "
8322 "stacksize> in the C shell)."
8326 #: build/C/man7/pthreads.7:847
8328 msgid "Determining the threading implementation"
8332 #: build/C/man7/pthreads.7:852
8334 "Since glibc 2.3.2, the B<getconf>(1) command can be used to determine the "
8335 "system's threading implementation, for example:"
8339 #: build/C/man7/pthreads.7:857
8342 "bash$ getconf GNU_LIBPTHREAD_VERSION\n"
8347 #: build/C/man7/pthreads.7:862
8349 "With older glibc versions, a command such as the following should be "
8350 "sufficient to determine the default threading implementation:"
8354 #: build/C/man7/pthreads.7:868
8357 "bash$ $( ldd /bin/ls | grep libc.so | awk \\(aq{print $3}\\(aq ) | \\e\n"
8358 " egrep -i \\(aqthreads|nptl\\(aq\n"
8359 " Native POSIX Threads Library by Ulrich Drepper et al\n"
8363 #: build/C/man7/pthreads.7:870
8365 msgid "Selecting the threading implementation: LD_ASSUME_KERNEL"
8369 #: build/C/man7/pthreads.7:885
8371 "On systems with a glibc that supports both LinuxThreads and NPTL (i.e., "
8372 "glibc 2.3.I<x>), the B<LD_ASSUME_KERNEL> environment variable can be used to "
8373 "override the dynamic linker's default choice of threading implementation. "
8374 "This variable tells the dynamic linker to assume that it is running on top "
8375 "of a particular kernel version. By specifying a kernel version that does "
8376 "not provide the support required by NPTL, we can force the use of "
8377 "LinuxThreads. (The most likely reason for doing this is to run a (broken) "
8378 "application that depends on some nonconformant behavior in LinuxThreads.) "
8383 #: build/C/man7/pthreads.7:891
8386 "bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\e\n"
8387 " awk \\(aq{print $3}\\(aq ) | egrep -i "
8388 "\\(aqthreads|nptl\\(aq\n"
8389 " linuxthreads-0.10 by Xavier Leroy\n"
8393 #: build/C/man7/pthreads.7:903
8395 "B<clone>(2), B<futex>(2), B<gettid>(2), B<proc>(5), B<futex>(7), "
8396 "B<sigevent>(7), B<signal>(7),"
8400 #: build/C/man7/pthreads.7:927
8402 "Various Pthreads manual pages, for example: B<pthread_attr_init>(3), "
8403 "B<pthread_atfork>(3), B<pthread_cancel>(3), B<pthread_cleanup_push>(3), "
8404 "B<pthread_cond_signal>(3), B<pthread_cond_wait>(3), B<pthread_create>(3), "
8405 "B<pthread_detach>(3), B<pthread_equal>(3), B<pthread_exit>(3), "
8406 "B<pthread_key_create>(3), B<pthread_kill>(3), B<pthread_mutex_lock>(3), "
8407 "B<pthread_mutex_unlock>(3), B<pthread_once>(3), "
8408 "B<pthread_setcancelstate>(3), B<pthread_setcanceltype>(3), "
8409 "B<pthread_setspecific>(3), B<pthread_sigmask>(3), B<pthread_sigqueue>(3), "
8410 "and B<pthread_testcancel>(3)"