.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk .\" .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 2012 Akihiro MOTOKI .\" all rights reserved. .\" Translated 2012-05-04, Akihiro MOTOKI .\" .TH PTHREAD_CREATE 3 2020\-11\-01 Linux "Linux Programmer's Manual" .SH 名前 pthread_create \- 新しいスレッドを作成する .SH 書式 .nf \fB#include \fP .PP \fBint pthread_create(pthread_t *\fP\fIthread\fP\fB, const pthread_attr_t *\fP\fIattr\fP\fB,\fP \fB void *(*\fP\fIstart_routine\fP\fB) (void *), void *\fP\fIarg\fP\fB);\fP .fi .PP \fI\-pthread\fP を付けてコンパイルとリンクを行う。 .SH 説明 \fBpthread_create\fP() 関数は、呼び出したプロセス内に新しいスレッドを作成する。 新しいスレッドの実行は、 \fIstart_routine\fP() を起動することで開始される。 \fIstart_routine\fP() は引数を一つだけ取り、 \fIarg\fP が \fIstart_routine\fP() の引数として渡される。 .PP 新しく作成されたスレッドは、以下のいずれかで終了する。 .IP * 2 スレッドが \fBpthread_exit\fP(3) を呼び出す。 \fBpthread_exit\fP(3) を呼び出す際には終了ステータス値を指定する。 この値は \fBpthread_join\fP(3) を呼び出した同じプロセス内の 別のスレッドで参照できる。 .IP * スレッドが \fIstart_routine\fP() から返る。これは、 \fIreturn\fP 文に渡した値で \fBpthread_exit\fP(3) を呼び出すのと等価である。 .IP * スレッドがキャンセルされる (\fBpthread_cancel\fP(3) 参照)。 .IP * プロセス内のいずれかのスレッドで \fBexit\fP(3) が呼ばれるか、 メインスレッドで \fImain\fP() 内で return が実行される。 この場合は、プロセス内の全てのスレッドが終了される。 .PP \fIattr\fP 引数は \fIpthread_attr_t\fP 構造体へのポインターであり、 \fIpthread_attr_t\fP 構造体の内容を使用して、スレッド作成時に 新しいスレッドの属性が決定される。 この構造体は \fBpthread_attr_init\fP(3) や関連の関数を使って初期化される。 \fIattr\fP が NULL の場合、新しいスレッドはデフォルトの属性で作成される。 .PP 成功した場合は、 \fBpthread_create\fP() は返る前に新しいスレッドの ID を \fIthread\fP が指すバッファーに格納する。この ID は、これ以降に他の pthreads 関数の呼び出しでスレッドを参照するのに使用される。 .PP 新しいスレッドは、スレッドを作成したスレッドのシグナルマスク (\fBpthread_sigmask\fP(3) 参照) のコピーを継承する。 新しいスレッドの処理待ちシグナル (\fBsigpending\fP(2)) の集合は空となる。 新しいスレッドはスレッドを作成したスレッドの代替シグナルスタック (\fBsigaltstack\fP(2)) を継承しない。 .PP 新しいスレッドは呼び出したスレッドの浮動小数点環境 (\fBfenv\fP(3)) を継承する。 .PP .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2) 新しいスレッドの CPU 時間時計の初期値は 0 である (\fBpthread_getcpuclockid\fP(3) 参照)。 .SS "Linux 固有の詳細" 新しいスレッドは、呼び出したスレッドの ケーパビリティセット (\fBcapabilities\fP(7) 参照) と CPU affinity マスク (\fBsched_setaffinity\fP(2) 参照) の コピーをを継承しない。 .SH 返り値 成功すると、 \fBpthread_create\fP() は 0 を返す。 エラーの場合は、エラー番号が返され、 \fI*thread\fP の内容は不定である。 .SH エラー .TP \fBEAGAIN\fP 別のスレッドを作成するのに十分なリソースがない。 .TP \fBEAGAIN\fP .\" NOTE! The following should match the description in fork(2) システムで設定されたスレッド数の上限に達していた。 このエラーの原因となる上限値はいくつかある。 実ユーザー ID 当たりのプロセス数とスレッド数の上限である、ソフトリソース上限 \fBRLIMIT_NPROC\fP に達していた (\fBsetrlimit\fP(2) で設定できる)。 カーネルのシステム全体のプロセスとスレッドの数の上限値である \fI/proc/sys/kernel/threads\-max\fP が達していた (\fBproc\fP(5) 参照)。 PID の最大値 \fI/proc/sys/kernel/pid_max\fP に達していた (\fBproc\fP(5) 参照)。 .TP \fBEINVAL\fP \fIattr\fP で指定された設定が不正である。 .TP .\" FIXME . Test the following \fBEPERM\fP \fIattr\fP に指定されたスケジューリングポリシーとパラメーターを 設定する許可がない。 .SH 属性 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。 .TS allbox; lb lb lb l l l. インターフェース 属性 値 T{ \fBpthread_create\fP() T} Thread safety MT\-Safe .TE .sp 1 .SH 準拠 POSIX.1\-2001, POSIX.1\-2008. .SH 注意 \fBpthread_create\fP() が \fI*thread\fP で返すスレッド ID についての 詳しい情報は \fBpthread_self\fP(3) を参照のこと。 リアルタイムスケジューリングポリシーが使用されない限り、 \fBpthread_create\fP() の呼び出し後に、 どのスレッドが\(em呼び出したスレッドか新しいスレッドか\(em 次に実行されるかは決まっていない。 .PP スレッドは \fIjoin 可能\fPか \fIdetached (切り離された状態)\fP のどちらかに することができる。スレッドが join 可能な場合、別のスレッドが \fBpthread_join\fP(3) を使って終了したスレッドを待ち、終了ステータスを取得 することができる。終了した join 可能なスレッドは join された場合にのみ、 そのスレッドの最後に残ったリソースが解放されシステムに戻される。 detached 状態のスレッドが終了すると、そのスレッドのリソースは自動的に システムに戻される。detached 状態のスレッドを join して、その終了 ステータスを取得することはできない。スレッドを detached 状態にするのは、 その終了ステータスをアプリケーションが気にする必要がないある種の デーモン (daemon) スレッドでは有用である。 デフォルトでは、新しいスレッドは join 可能な状態で作成される。 (\fBpthread_attr_setdetachstate\fP(3) を使って) \fIattr\fP でスレッドが detached 状態で作成されるように設定されていない限り、join 可能な状態で 作成される。 .PP Under the NPTL threading implementation, if the \fBRLIMIT_STACK\fP soft resource limit \fIat the time the program started\fP has any value other than "unlimited", then it determines the default stack size of new threads. Using \fBpthread_attr_setstacksize\fP(3), the stack size attribute can be explicitly set in the \fIattr\fP argument used to create a thread, in order to obtain a stack size other than the default. If the \fBRLIMIT_STACK\fP resource limit is set to "unlimited", a per\-architecture value is used for the stack size. Here is the value for a few architectures: .RS .TS allbox; lb lb l r. Architecture Default stack size i386 2 MB IA\-64 32 MB PowerPC 4 MB S/390 2 MB Sparc\-32 2 MB Sparc\-64 4 MB x86_64 2 MB .TE .RE .SH バグ 廃止予定の LinuxThreads 実装では、プロセス内の各スレッドは異なる プロセス ID を持つ。これは POSIX スレッドの規格に違反しており、 他の多くの標準非準拠の点の原因になっている。 \fBpthreads\fP(7) を参照のこと。 .SH 例 以下のプログラムは、 \fBpthread_create\fP() や pthreads API の他のいろいろな関数の使用例を示している。 .PP 以下の実行例は、 NPTL スレッド実装が提供されているシステムでのもので、 スタックサイズがデフォルト値の "stack size" リソース上限で指定される値 になる。 .PP .in +4n .EX $\fB ulimit \-s\fP 8192 # The stack size limit is 8 MB (0x800000 bytes) $\fB ./a.out hola salut servus\fP Thread 1: top of stack near 0xb7dd03b8; argv_string=hola Thread 2: top of stack near 0xb75cf3b8; argv_string=salut Thread 3: top of stack near 0xb6dce3b8; argv_string=servus Joined with thread 1; returned value was HOLA Joined with thread 2; returned value was SALUT Joined with thread 3; returned value was SERVUS .EE .in .PP 次の実行例では、プログラム内で、作成されるスレッドに対して (\fBpthread_attr_setstacksize\fP(3) を使って1\ MB のスタックサイズを明示的に設定している。 .PP .in +4n .EX $\fB ./a.out \-s 0x100000 hola salut servus\fP Thread 1: top of stack near 0xb7d723b8; argv_string=hola Thread 2: top of stack near 0xb7c713b8; argv_string=salut Thread 3: top of stack near 0xb7b703b8; argv_string=servus Joined with thread 1; returned value was HOLA Joined with thread 2; returned value was SALUT Joined with thread 3; returned value was SERVUS .EE .in .SS プログラムのソース \& .EX #include #include #include #include #include #include #include #define handle_error_en(en, msg) \e do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) #define handle_error(msg) \e do { perror(msg); exit(EXIT_FAILURE); } while (0) struct thread_info { /* Used as argument to thread_start() */ pthread_t thread_id; /* ID returned by pthread_create() */ int thread_num; /* Application\-defined thread # */ char *argv_string; /* From command\-line argument */ }; /* Thread start function: display address near top of our stack, and return upper\-cased copy of argv_string */ static void * thread_start(void *arg) { struct thread_info *tinfo = arg; char *uargv; printf("Thread %d: top of stack near %p; argv_string=%s\en", tinfo\->thread_num, &p, tinfo\->argv_string); uargv = strdup(tinfo\->argv_string); if (uargv == NULL) handle_error("strdup"); for (char *p = uargv; *p != \(aq\e0\(aq; p++) *p = toupper(*p); return uargv; } int main(int argc, char *argv[]) { int s, opt, num_threads; pthread_attr_t attr; size_t stack_size; void *res; /* The "\-s" option specifies a stack size for our threads */ stack_size = \-1; while ((opt = getopt(argc, argv, "s:")) != \-1) { switch (opt) { case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break; default: fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en", argv[0]); exit(EXIT_FAILURE); } } num_threads = argc \- optind; /* Initialize thread creation attributes */ s = pthread_attr_init(&attr); if (s != 0) handle_error_en(s, "pthread_attr_init"); if (stack_size > 0) { s = pthread_attr_setstacksize(&attr, stack_size); if (s != 0) handle_error_en(s, "pthread_attr_setstacksize"); } /* Allocate memory for pthread_create() arguments */ struct thread_info *tinfo = calloc(num_threads, sizeof(*tinfo)); if (tinfo == NULL) handle_error("calloc"); /* Create one thread for each command\-line argument */ for (int tnum = 0; tnum < num_threads; tnum++) { tinfo[tnum].thread_num = tnum + 1; tinfo[tnum].argv_string = argv[optind + tnum]; /* The pthread_create() call stores the thread ID into corresponding element of tinfo[] */ s = pthread_create(&tinfo[tnum].thread_id, &attr, &thread_start, &tinfo[tnum]); if (s != 0) handle_error_en(s, "pthread_create"); } /* Destroy the thread attributes object, since it is no longer needed */ s = pthread_attr_destroy(&attr); if (s != 0) handle_error_en(s, "pthread_attr_destroy"); /* Now join with each thread, and display its returned value */ for (int tnum = 0; tnum < num_threads; tnum++) { s = pthread_join(tinfo[tnum].thread_id, &res); if (s != 0) handle_error_en(s, "pthread_join"); printf("Joined with thread %d; returned value was %s\en", tinfo[tnum].thread_num, (char *) res); free(res); /* Free memory allocated by thread */ } free(tinfo); exit(EXIT_SUCCESS); } .EE .SH 関連項目 .ad l .nh \fBgetrlimit\fP(2), \fBpthread_attr_init\fP(3), \fBpthread_cancel\fP(3), \fBpthread_detach\fP(3), \fBpthread_equal\fP(3), \fBpthread_exit\fP(3), \fBpthread_getattr_np\fP(3), \fBpthread_join\fP(3), \fBpthread_self\fP(3), \fBpthread_setattr_default_np\fP(3), \fBpthreads\fP(7) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。