release/man3/pthread_create.3

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