release/man3/pthread_create.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   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.
   8 .\"
   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.
  13 .\"
  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
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
  33 .\"         all rights reserved.
  34 .\" Translated 2012-05-04, Akihiro MOTOKI <amotoki@gmail.com>
  35 .\"
  36 .TH PTHREAD_CREATE 3 2014\-05\-28 Linux "Linux Programmer's Manual"
  37 .SH 名前
  38 pthread_create \- 新しいスレッドを作成する
  39 .SH 書式
  40 .nf
  41 \fB#include <pthread.h>\fP
  42
  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
  45 .fi
  46 .sp
  47 \fI\-pthread\fP を付けてコンパイルとリンクを行う。
  48 .SH 説明
  49 \fBpthread_create\fP() 関数は、呼び出したプロセス内に新しいスレッドを作成する。
  50 新しいスレッドの実行は、 \fIstart_routine\fP() を起動することで開始される。
  51 \fIstart_routine\fP() は引き数を一つだけ取り、
  52 \fIarg\fP が \fIstart_routine\fP() の引き数として渡される。
  53
  54 新しく作成されたスレッドは、以下のいずれかで終了する。
  55 .IP * 2
  56 スレッドが \fBpthread_exit\fP(3) を呼び出す。
  57 \fBpthread_exit\fP(3) を呼び出す際には終了ステータス値を指定する。
  58 この値は \fBpthread_join\fP(3) を呼び出した同じプロセス内の
  59 別のスレッドで参照できる。
  60 .IP *
  61 スレッドが \fIstart_routine\fP() から返る。これは、
  62 \fIreturn\fP 文に渡した値で \fBpthread_exit\fP(3) を呼び出すのと等価である。
  63 .IP *
  64 スレッドがキャンセルされる (\fBpthread_cancel\fP(3) 参照)。
  65 .IP *
  66 プロセス内のいずれかのスレッドで \fBexit\fP(3) が呼ばれるか、
  67 メインスレッドで \fImain\fP() 内で return が実行される。
  68 この場合は、プロセス内の全てのスレッドが終了される。
  69 .PP
  70 \fIattr\fP 引き数は \fIpthread_attr_t\fP 構造体へのポインターであり、
  71 \fIpthread_attr_t\fP 構造体の内容を使用して、スレッド作成時に
  72 新しいスレッドの属性が決定される。
  73 この構造体は \fBpthread_attr_init\fP(3) や関連の関数を使って初期化される。
  74 \fIattr\fP が NULL の場合、新しいスレッドはデフォルトの属性で作成される。
  75
  76 成功した場合は、 \fBpthread_create\fP() は返る前に新しいスレッドの ID を
  77 \fIthread\fP が指すバッファーに格納する。この ID は、これ以降に他の
  78 pthreads 関数の呼び出しでスレッドを参照するのに使用される。
  79
  80 新しいスレッドは、スレッドを作成したスレッドのシグナルマスク
  81 (\fBpthread_sigmask\fP(3) 参照) のコピーを継承する。
  82 新しいスレッドの処理待ちシグナル (\fBsigpending\fP(2)) の集合は空となる。
  83 新しいスレッドはスレッドを作成したスレッドの代替シグナルスタック
  84 (\fBsigaltstack\fP(2)) を継承しない。
  85
  86 新しいスレッドは呼び出したスレッドの浮動小数点環境 (\fBfenv\fP(3))
  87 を継承する。
  88
  89 .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2)
  90 新しいスレッドの CPU 時間時計の初期値は 0 である
  91 (\fBpthread_getcpuclockid\fP(3) 参照)。
  92 .SS "Linux 固有の詳細"
  93 新しいスレッドは、呼び出したスレッドの
  94 ケーパビリティセット (\fBcapabilities\fP(7) 参照) と
  95 CPU affinity マスク (\fBsched_setaffinity\fP(2) 参照) の
  96 コピーをを継承しない。
  97 .SH 返り値
  98 成功すると、 \fBpthread_create\fP() は 0 を返す。
  99 エラーの場合は、エラー番号が返され、 \fI*thread\fP の内容は不定である。
 100 .SH エラー
 101 .TP
 102 \fBEAGAIN\fP
 103 別のスレッドを作成するのに十分なリソースがない。
 104 .TP
 105 \fBEAGAIN\fP
 106 .\" NOTE! The following should match the description in fork(2)
 107 システムで設定されたスレッド数の上限に達していた。 このエラーの原因となる上限値はいくつかある。 実ユーザー ID
 108 当たりのプロセス数とスレッド数の上限である、ソフトリソース上限 \fBRLIMIT_NPROC\fP に達していた (\fBsetrlimit\fP(2)
 109 で設定できる)。 カーネルのシステム全体のプロセスとスレッドの数の上限値である \fI/proc/sys/kernel/threads\-max\fP
 110 が達していた (\fBproc\fP(5) 参照)。 PID の最大値 \fI/proc/sys/kernel/pid_max\fP に達していた
 111 (\fBproc\fP(5) 参照)。
 112 .TP
 113 \fBEINVAL\fP
 114 \fIattr\fP で指定された設定が不正である。
 115 .TP
 116 .\" FIXME . Test the following
 117 \fBEPERM\fP
 118 \fIattr\fP に指定されたスケジューリングポリシーとパラメーターを
 119 設定する許可がない。
 120 .SH 準拠
 121 POSIX.1\-2001.
 122 .SH 注意
 123 \fBpthread_create\fP() が \fI*thread\fP で返すスレッド ID についての
 124 詳しい情報は \fBpthread_self\fP(3) を参照のこと。
 125 リアルタイムスケジューリングポリシーが使用されない限り、
 126 \fBpthread_create\fP() の呼び出し後に、
 127 どのスレッドが\(em呼び出したスレッドか新しいスレッドか\(em
 128 次に実行されるかは決まっていない。
 129
 130 スレッドは \fIjoin 可能\fPか \fIdetached (切り離された状態)\fP のどちらかに
 131 することができる。スレッドが join 可能な場合、別のスレッドが
 132 \fBpthread_join\fP(3) を使って終了したスレッドを待ち、終了ステータスを取得
 133 することができる。終了した join 可能なスレッドは join された場合にのみ、
 134 そのスレッドの最後に残ったリソースが解放されシステムに戻される。
 135 detached 状態のスレッドが終了すると、そのスレッドのリソースは自動的に
 136 システムに戻される。detached 状態のスレッドを join して、その終了
 137 ステータスを取得することはできない。スレッドを detached 状態にするのは、
 138 その終了ステータスをアプリケーションが気にする必要がないある種の
 139 デーモン (daemon) スレッドでは有用である。
 140 デフォルトでは、新しいスレッドは join 可能な状態で作成される。
 141 (\fBpthread_attr_setdetachstate\fP(3) を使って) \fIattr\fP でスレッドが
 142 detached 状態で作成されるように設定されていない限り、join 可能な状態で
 143 作成される。
 144
 145 .\" FIXME . Perhaps some of the following detail should be in
 146 .\" a future pthread_attr_setstacksize(3) page.
 147 Linux/x86\-32 では、新しいスレッドのデフォルトのスタックサイズは 2MB で
 148 ある。NPTL スレッド実装の下では、\fIプログラム開始時の\fP \fBRLIMIT_STACK\fP
 149 ソフトリソース上限が"unlimited" 以外の場合、その値が新しいスレッドのデ
 150 フォルトのスタックサイズとなる。
 151 \fBpthread_attr_setstacksize\fP(3) を使って、スレッドを作成する際の
 152 \fIattr\fP 引き数に明示的にスタックサイズ属性を設定することで、
 153 デフォルト値以外のスタックサイズを得ることができる。
 154 .SH バグ
 155 廃止予定の LinuxThreads 実装では、プロセス内の各スレッドは異なる
 156 プロセス ID を持つ。これは POSIX スレッドの規格に違反しており、
 157 他の多くの標準非準拠の点の原因になっている。
 158 \fBpthreads\fP(7) を参照のこと。
 159 .SH 例
 160 以下のプログラムは、 \fBpthread_create\fP() や
 161 pthreads API の他のいろいろな関数の使用例を示している。
 162
 163 以下の実行例は、 NPTL スレッド実装が提供されているシステムでのもので、
 164 スタックサイズがデフォルト値の "stack size" リソース上限で指定される値
 165 になる。
 166
 167 .in +4n
 168 .nf
 169 $\fB ulimit \-s\fP
 170 8192            # The stack size limit is 8 MB (0x800000 bytes)
 171 $\fB ./a.out hola salut servus\fP
 172 Thread 1: top of stack near 0xb7dd03b8; argv_string=hola
 173 Thread 2: top of stack near 0xb75cf3b8; argv_string=salut
 174 Thread 3: top of stack near 0xb6dce3b8; argv_string=servus
 175 Joined with thread 1; returned value was HOLA
 176 Joined with thread 2; returned value was SALUT
 177 Joined with thread 3; returned value was SERVUS
 178 .fi
 179 .in
 180
 181 次の実行例では、プログラム内で、作成されるスレッドに対して
 182 (\fBpthread_attr_setstacksize\fP(3) を使って1MB のスタックサイズを
 183 明示的に設定している。
 184
 185 .in +4n
 186 .nf
 187 $\fB ./a.out \-s 0x100000 hola salut servus\fP
 188 Thread 1: top of stack near 0xb7d723b8; argv_string=hola
 189 Thread 2: top of stack near 0xb7c713b8; argv_string=salut
 190 Thread 3: top of stack near 0xb7b703b8; argv_string=servus
 191 Joined with thread 1; returned value was HOLA
 192 Joined with thread 2; returned value was SALUT
 193 Joined with thread 3; returned value was SERVUS
 194 .fi
 195 .in
 196 .SS プログラムのソース
 197 \&
 198 .nf
 199 #include <pthread.h>
 200 #include <string.h>
 201 #include <stdio.h>
 202 #include <stdlib.h>
 203 #include <unistd.h>
 204 #include <errno.h>
 205 #include <ctype.h>
 206
 207 #define handle_error_en(en, msg) \e
 208         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 209
 210 #define handle_error(msg) \e
 211         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 212
 213 struct thread_info {    /* Used as argument to thread_start() */
 214     pthread_t thread_id;        /* ID returned by pthread_create() */
 215     int       thread_num;       /* Application\-defined thread # */
 216     char     *argv_string;      /* From command\-line argument */
 217 };
 218
 219 /* Thread start function: display address near top of our stack,
 220    and return upper\-cased copy of argv_string */
 221
 222 static void *
 223 thread_start(void *arg)
 224 {
 225     struct thread_info *tinfo = arg;
 226     char *uargv, *p;
 227
 228     printf("Thread %d: top of stack near %p; argv_string=%s\en",
 229             tinfo\->thread_num, &p, tinfo\->argv_string);
 230
 231     uargv = strdup(tinfo\->argv_string);
 232     if (uargv == NULL)
 233         handle_error("strdup");
 234
 235     for (p = uargv; *p != \(aq\e0\(aq; p++)
 236         *p = toupper(*p);
 237
 238     return uargv;
 239 }
 240
 241 int
 242 main(int argc, char *argv[])
 243 {
 244     int s, tnum, opt, num_threads;
 245     struct thread_info *tinfo;
 246     pthread_attr_t attr;
 247     int stack_size;
 248     void *res;
 249
 250     /* The "\-s" option specifies a stack size for our threads */
 251
 252     stack_size = \-1;
 253     while ((opt = getopt(argc, argv, "s:")) != \-1) {
 254         switch (opt) {
 255         case \(aqs\(aq:
 256             stack_size = strtoul(optarg, NULL, 0);
 257             break;
 258
 259         default:
 260             fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en",
 261                     argv[0]);
 262             exit(EXIT_FAILURE);
 263         }
 264     }
 265
 266     num_threads = argc \- optind;
 267
 268     /* Initialize thread creation attributes */
 269
 270     s = pthread_attr_init(&attr);
 271     if (s != 0)
 272         handle_error_en(s, "pthread_attr_init");
 273
 274     if (stack_size > 0) {
 275         s = pthread_attr_setstacksize(&attr, stack_size);
 276         if (s != 0)
 277             handle_error_en(s, "pthread_attr_setstacksize");
 278     }
 279
 280     /* Allocate memory for pthread_create() arguments */
 281
 282     tinfo = calloc(num_threads, sizeof(struct thread_info));
 283     if (tinfo == NULL)
 284         handle_error("calloc");
 285
 286     /* Create one thread for each command\-line argument */
 287
 288     for (tnum = 0; tnum < num_threads; tnum++) {
 289         tinfo[tnum].thread_num = tnum + 1;
 290         tinfo[tnum].argv_string = argv[optind + tnum];
 291
 292         /* The pthread_create() call stores the thread ID into
 293            corresponding element of tinfo[] */
 294
 295         s = pthread_create(&tinfo[tnum].thread_id, &attr,
 296                            &thread_start, &tinfo[tnum]);
 297         if (s != 0)
 298             handle_error_en(s, "pthread_create");
 299     }
 300
 301     /* Destroy the thread attributes object, since it is no
 302        longer needed */
 303
 304     s = pthread_attr_destroy(&attr);
 305     if (s != 0)
 306         handle_error_en(s, "pthread_attr_destroy");
 307
 308     /* Now join with each thread, and display its returned value */
 309
 310     for (tnum = 0; tnum < num_threads; tnum++) {
 311         s = pthread_join(tinfo[tnum].thread_id, &res);
 312         if (s != 0)
 313             handle_error_en(s, "pthread_join");
 314
 315         printf("Joined with thread %d; returned value was %s\en",
 316                 tinfo[tnum].thread_num, (char *) res);
 317         free(res);      /* Free memory allocated by thread */
 318     }
 319
 320     free(tinfo);
 321     exit(EXIT_SUCCESS);
 322 }
 323 .fi
 324 .SH 関連項目
 325 .ad l
 326 .nh
 327 \fBgetrlimit\fP(2), \fBpthread_attr_init\fP(3), \fBpthread_cancel\fP(3),
 328 \fBpthread_detach\fP(3), \fBpthread_equal\fP(3), \fBpthread_exit\fP(3),
 329 \fBpthread_getattr_np\fP(3), \fBpthread_join\fP(3), \fBpthread_self\fP(3),
 330 \fBpthreads\fP(7)
 331 .SH この文書について
 332 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 333 である。プロジェクトの説明とバグ報告に関する情報は
 334 http://www.kernel.org/doc/man\-pages/ に書かれている。