1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\"*******************************************************************
28 .\" This file was generated with po4a. Translate the source file.
30 .\"*******************************************************************
32 .\" Japanese Version Copyright (c) 2012 Akihiro MOTOKI
33 .\" all rights reserved.
34 .\" Translated 2012-05-04, Akihiro MOTOKI <amotoki@gmail.com>
36 .TH PTHREAD_CREATE 3 2014\-05\-28 Linux "Linux Programmer's Manual"
38 pthread_create \- 新しいスレッドを作成する
41 \fB#include <pthread.h>\fP
43 \fBint pthread_create(pthread_t *\fP\fIthread\fP\fB, const pthread_attr_t *\fP\fIattr\fP\fB,\fP
44 \fB void *(*\fP\fIstart_routine\fP\fB) (void *), void *\fP\fIarg\fP\fB);\fP
47 \fI\-pthread\fP を付けてコンパイルとリンクを行う。
49 \fBpthread_create\fP() 関数は、呼び出したプロセス内に新しいスレッドを作成する。
50 新しいスレッドの実行は、 \fIstart_routine\fP() を起動することで開始される。
51 \fIstart_routine\fP() は引き数を一つだけ取り、
52 \fIarg\fP が \fIstart_routine\fP() の引き数として渡される。
54 新しく作成されたスレッドは、以下のいずれかで終了する。
56 スレッドが \fBpthread_exit\fP(3) を呼び出す。
57 \fBpthread_exit\fP(3) を呼び出す際には終了ステータス値を指定する。
58 この値は \fBpthread_join\fP(3) を呼び出した同じプロセス内の
61 スレッドが \fIstart_routine\fP() から返る。これは、
62 \fIreturn\fP 文に渡した値で \fBpthread_exit\fP(3) を呼び出すのと等価である。
64 スレッドがキャンセルされる (\fBpthread_cancel\fP(3) 参照)。
66 プロセス内のいずれかのスレッドで \fBexit\fP(3) が呼ばれるか、
67 メインスレッドで \fImain\fP() 内で return が実行される。
68 この場合は、プロセス内の全てのスレッドが終了される。
70 \fIattr\fP 引き数は \fIpthread_attr_t\fP 構造体へのポインタであり、
71 \fIpthread_attr_t\fP 構造体の内容を使用して、スレッド作成時に
73 この構造体は \fBpthread_attr_init\fP(3) や関連の関数を使って初期化される。
74 \fIattr\fP が NULL の場合、新しいスレッドはデフォルトの属性で作成される。
76 成功した場合は、 \fBpthread_create\fP() は返る前に新しいスレッドの ID を
77 \fIthread\fP が指すバッファに格納する。この ID は、これ以降に他の
78 pthreads 関数の呼び出しでスレッドを参照するのに使用される。
80 新しいスレッドは、スレッドを作成したスレッドのシグナルマスク
81 (\fBpthread_sigmask\fP(3) 参照) のコピーを継承する。
82 新しいスレッドの処理待ちシグナル (\fBsigpending\fP(2)) の集合は空となる。
83 新しいスレッドはスレッドを作成したスレッドの代替シグナルスタック
84 (\fBsigaltstack\fP(2)) を継承しない。
86 新しいスレッドは呼び出したスレッドの浮動小数点環境 (\fBfenv\fP(3))
89 .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2)
90 新しいスレッドの CPU 時間時計の初期値は 0 である
91 (\fBpthread_getcpuclockid\fP(3) 参照)。
94 ケーパビリティセット (\fBcapabilities\fP(7) 参照) と
95 CPU affinity マスク (\fBsched_setaffinity\fP(2) 参照) の
98 成功すると、 \fBpthread_create\fP() は 0 を返す。
99 エラーの場合は、エラー番号が返され、 \fI*thread\fP の内容は不定である。
103 Insufficient resources to create another thread.
106 .\" NOTE! The following should match the description in fork(2)
107 A system\-imposed limit on the number of threads was encountered. There are
108 a number of limits that may trigger this error: the \fBRLIMIT_NPROC\fP soft
109 resource limit (set via \fBsetrlimit\fP(2)), which limits the number of
110 processes and threads for a real user ID, was reached; the kernel's
111 system\-wide limit on the number of processes threads,
112 \fI/proc/sys/kernel/threads\-max\fP, was reached (see \fBproc\fP(5)); or the
113 maximum number of PIDs, \fI/proc/sys/kernel/pid_max\fP, was reached (see
117 \fIattr\fP で指定された設定が不正である。
119 .\" FIXME . Test the following
121 \fIattr\fP に指定されたスケジューリングポリシーとパラメータを
126 \fBpthread_create\fP() が \fI*thread\fP で返すスレッド ID についての
127 詳しい情報は \fBpthread_self\fP(3) を参照のこと。
128 リアルタイムスケジューリングポリシーが使用されない限り、
129 \fBpthread_create\fP() の呼び出し後に、
130 どのスレッドが\(em呼び出したスレッドか新しいスレッドか\(em
133 スレッドは \fIjoin 可能\fPか \fIdetached (切り離された状態)\fP のどちらかに
134 することができる。スレッドが join 可能な場合、別のスレッドが
135 \fBpthread_join\fP(3) を使って終了したスレッドを待ち、終了ステータスを取得
136 することができる。終了した join 可能なスレッドは join された場合にのみ、
137 そのスレッドの最後に残ったリソースが解放されシステムに戻される。
138 detached 状態のスレッドが終了すると、そのスレッドのリソースは自動的に
139 システムに戻される。detached 状態のスレッドを join して、その終了
140 ステータスを取得することはできない。スレッドを detached 状態にするのは、
141 その終了ステータスをアプリケーションが気にする必要がないある種の
142 デーモン (daemon) スレッドでは有用である。
143 デフォルトでは、新しいスレッドは join 可能な状態で作成される。
144 (\fBpthread_attr_setdetachstate\fP(3) を使って) \fIattr\fP でスレッドが
145 detached 状態で作成されるように設定されていない限り、join 可能な状態で
148 .\" FIXME . Perhaps some of the following detail should be in
149 .\" a future pthread_attr_setstacksize(3) page.
150 Linux/x86\-32 では、新しいスレッドのデフォルトのスタックサイズは 2MB で
151 ある。NPTL スレッド実装の下では、\fIプログラム開始時の\fP \fBRLIMIT_STACK\fP
152 ソフトリソース上限が"unlimited" 以外の場合、その値が新しいスレッドのデ
154 \fBpthread_attr_setstacksize\fP(3) を使って、スレッドを作成する際の
155 \fIattr\fP 引き数に明示的にスタックサイズ属性を設定することで、
156 デフォルト値以外のスタックサイズを得ることができる。
158 廃止予定の LinuxThreads 実装では、プロセス内の各スレッドは異なる
159 プロセス ID を持つ。これは POSIX スレッドの規格に違反しており、
160 他の多くの標準非準拠の点の原因になっている。
161 \fBpthreads\fP(7) を参照のこと。
163 以下のプログラムは、 \fBpthread_create\fP() や
164 pthreads API の他のいろいろな関数の使用例を示している。
166 以下の実行例は、 NPTL スレッド実装が提供されているシステムでのもので、
167 スタックサイズがデフォルト値の "stack size" リソース上限で指定される値
173 8192 # The stack size limit is 8 MB (0x800000 bytes)
174 $\fB ./a.out hola salut servus\fP
175 Thread 1: top of stack near 0xb7dd03b8; argv_string=hola
176 Thread 2: top of stack near 0xb75cf3b8; argv_string=salut
177 Thread 3: top of stack near 0xb6dce3b8; argv_string=servus
178 Joined with thread 1; returned value was HOLA
179 Joined with thread 2; returned value was SALUT
180 Joined with thread 3; returned value was SERVUS
184 次の実行例では、プログラム内で、作成されるスレッドに対して
185 (\fBpthread_attr_setstacksize\fP(3) を使って1MB のスタックサイズを
190 $\fB ./a.out \-s 0x100000 hola salut servus\fP
191 Thread 1: top of stack near 0xb7d723b8; argv_string=hola
192 Thread 2: top of stack near 0xb7c713b8; argv_string=salut
193 Thread 3: top of stack near 0xb7b703b8; argv_string=servus
194 Joined with thread 1; returned value was HOLA
195 Joined with thread 2; returned value was SALUT
196 Joined with thread 3; returned value was SERVUS
210 #define handle_error_en(en, msg) \e
211 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
213 #define handle_error(msg) \e
214 do { perror(msg); exit(EXIT_FAILURE); } while (0)
216 struct thread_info { /* Used as argument to thread_start() */
217 pthread_t thread_id; /* ID returned by pthread_create() */
218 int thread_num; /* Application\-defined thread # */
219 char *argv_string; /* From command\-line argument */
222 /* Thread start function: display address near top of our stack,
223 and return upper\-cased copy of argv_string */
226 thread_start(void *arg)
228 struct thread_info *tinfo = arg;
231 printf("Thread %d: top of stack near %p; argv_string=%s\en",
232 tinfo\->thread_num, &p, tinfo\->argv_string);
234 uargv = strdup(tinfo\->argv_string);
236 handle_error("strdup");
238 for (p = uargv; *p != \(aq\e0\(aq; p++)
245 main(int argc, char *argv[])
247 int s, tnum, opt, num_threads;
248 struct thread_info *tinfo;
253 /* The "\-s" option specifies a stack size for our threads */
256 while ((opt = getopt(argc, argv, "s:")) != \-1) {
259 stack_size = strtoul(optarg, NULL, 0);
263 fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en",
269 num_threads = argc \- optind;
271 /* Initialize thread creation attributes */
273 s = pthread_attr_init(&attr);
275 handle_error_en(s, "pthread_attr_init");
277 if (stack_size > 0) {
278 s = pthread_attr_setstacksize(&attr, stack_size);
280 handle_error_en(s, "pthread_attr_setstacksize");
283 /* Allocate memory for pthread_create() arguments */
285 tinfo = calloc(num_threads, sizeof(struct thread_info));
287 handle_error("calloc");
289 /* Create one thread for each command\-line argument */
291 for (tnum = 0; tnum < num_threads; tnum++) {
292 tinfo[tnum].thread_num = tnum + 1;
293 tinfo[tnum].argv_string = argv[optind + tnum];
295 /* The pthread_create() call stores the thread ID into
296 corresponding element of tinfo[] */
298 s = pthread_create(&tinfo[tnum].thread_id, &attr,
299 &thread_start, &tinfo[tnum]);
301 handle_error_en(s, "pthread_create");
304 /* Destroy the thread attributes object, since it is no
307 s = pthread_attr_destroy(&attr);
309 handle_error_en(s, "pthread_attr_destroy");
311 /* Now join with each thread, and display its returned value */
313 for (tnum = 0; tnum < num_threads; tnum++) {
314 s = pthread_join(tinfo[tnum].thread_id, &res);
316 handle_error_en(s, "pthread_join");
318 printf("Joined with thread %d; returned value was %s\en",
319 tinfo[tnum].thread_num, (char *) res);
320 free(res); /* Free memory allocated by thread */
330 \fBgetrlimit\fP(2), \fBpthread_attr_init\fP(3), \fBpthread_cancel\fP(3),
331 \fBpthread_detach\fP(3), \fBpthread_equal\fP(3), \fBpthread_exit\fP(3),
332 \fBpthread_getattr_np\fP(3), \fBpthread_join\fP(3), \fBpthread_self\fP(3),
335 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.68 の一部
336 である。プロジェクトの説明とバグ報告に関する情報は
337 http://www.kernel.org/doc/man\-pages/ に書かれている。