From 34d5fc97f7eebcfb5b37d1bef8e1f34febeb4db8 Mon Sep 17 00:00:00 2001 From: Akihiro MOTOKI Date: Thu, 3 May 2012 17:51:31 +0900 Subject: [PATCH] (split) LDP: drafts generated from latest pthread/ja.po. --- draft/man3/pthread_attr_init.3 | 292 +++++++++++++++++++++++++ draft/man3/pthread_attr_setaffinity_np.3 | 103 +++++++++ draft/man3/pthread_attr_setdetachstate.3 | 94 ++++++++ draft/man3/pthread_attr_setguardsize.3 | 130 +++++++++++ draft/man3/pthread_attr_setinheritsched.3 | 109 ++++++++++ draft/man3/pthread_attr_setschedparam.3 | 95 +++++++++ draft/man3/pthread_attr_setschedpolicy.3 | 85 ++++++++ draft/man3/pthread_attr_setstack.3 | 127 +++++++++++ draft/man3/pthread_attr_setstackaddr.3 | 89 ++++++++ draft/man3/pthread_attr_setstacksize.3 | 96 +++++++++ draft/man3/pthread_cancel.3 | 28 +-- draft/man3/pthread_equal.3 | 59 +++++ draft/man3/pthread_getattr_np.3 | 343 ++++++++++++++++++++++++++++++ draft/man3/pthread_getcpuclockid.3 | 168 +++++++++++++++ draft/man3/pthread_setaffinity_np.3 | 181 ++++++++++++++++ draft/man7/pthreads.7 | 7 +- 16 files changed, 1991 insertions(+), 15 deletions(-) create mode 100644 draft/man3/pthread_attr_init.3 create mode 100644 draft/man3/pthread_attr_setaffinity_np.3 create mode 100644 draft/man3/pthread_attr_setdetachstate.3 create mode 100644 draft/man3/pthread_attr_setguardsize.3 create mode 100644 draft/man3/pthread_attr_setinheritsched.3 create mode 100644 draft/man3/pthread_attr_setschedparam.3 create mode 100644 draft/man3/pthread_attr_setschedpolicy.3 create mode 100644 draft/man3/pthread_attr_setstack.3 create mode 100644 draft/man3/pthread_attr_setstackaddr.3 create mode 100644 draft/man3/pthread_attr_setstacksize.3 create mode 100644 draft/man3/pthread_equal.3 create mode 100644 draft/man3/pthread_getattr_np.3 create mode 100644 draft/man3/pthread_getcpuclockid.3 create mode 100644 draft/man3/pthread_setaffinity_np.3 diff --git a/draft/man3/pthread_attr_init.3 b/draft/man3/pthread_attr_init.3 new file mode 100644 index 00000000..488b25e8 --- /dev/null +++ b/draft/man3/pthread_attr_init.3 @@ -0,0 +1,292 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_INIT 3 2008\-11\-11 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_init, pthread_attr_destroy \- +スレッド属性オブジェクトの初期化と破棄を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_init(pthread_attr_t *\fP\fIattr\fP\fB);\fP +\fBint pthread_attr_destroy(pthread_attr_t *\fP\fIattr\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_init\fP() 関数は \fIattr\fP が指すスレッド属性オブジェクト +(thread attributes object) をデフォルトの属性値で初期化する。 +この呼び出しの後、オブジェクトの各属性は (関連項目に載っている) 種々の +関数を使って設定することができ、このオブジェクトはスレッドの作成を行う +\fBpthread_create\fP(3) の呼び出しにおいて使用することができる (一つの +オブジェクトを複数の \fBpthread_create\fP(3) に渡してもよい)。 + +すでに初期化されているスレッド属性オブジェクトに対して +\fBpthread_attr_init\fP() を呼び出した場合、 +どのような動作になるかは不定である。 + +スレッド属性オブジェクトがもはや必要なくなった際には、 +そのオブジェクトは \fBpthread_attr_destroy\fP() 関数を使って破棄すべきである。 +スレッド属性オブジェクトを破棄しても、 +そのオブジェクトを使って作成されたスレッドには影響はない。 + +いったん破棄したスレッド属性オブジェクトは、 +\fBpthread_attr_init\fP() を使って再初期化することができる。 +破棄したスレッド属性オブジェクトをこれ以外の用途で +使った場合の結果は不定である。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +POSIX.1\-2001 では \fBpthread_attr_init\fP() にはエラー \fBENOMEM\fP が +記載されている。 +Linux では、これらの関数は常に作成する +(ただし、移植性や将来も動作することを保証したいアプリケーションでは +正のエラーの返り値を処理するようにすべきである)。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +\fIpthread_attr_t\fP 型の内部構造は意識すべきではない。 +pthreads 関数経由以外でのオブジェクトへのアクセスは移植性がなく、 +どのような結果が得られるかも分からない。 +.SH 例 +下記のプログラムは、\fBpthread_attr_init\fP() と種々の関連関数を使って、 +スレッド属性オブジェクトの初期化を行い、 +そのオブジェクトを使ってスレッドを一つ作成する。 +作成されたスレッドは、作成後に \fBpthread_getattr_np\fP(3) 関数 +(非標準の GNU 拡張) を使ってスレッドの属性を取得し、 +取得した属性を表示する。 + +コマンドライン引き数なしでプログラムを実行した場合、 +\fBpthread_create\fP(3) の \fIattr\fP 引き数には NULL が渡される。 +この場合、スレッドはデフォルトの属性で作成される。 +このプログラムを NPTL スレッド実装が使われている Linux/x86\-32 で +動作させると、以下のような出力が得られる。 + +.in +4n +.nf +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +$\fB ulimit \-s\fP # No stack imit ==> default stack size is 2MB +unlimited +$\fB ./a.out\fP +Thread attributes: + Detach state = PTHREAD_CREATE_JOINABLE + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_INHERIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 4096 bytes + Stack address = 0x40196000 + Stack size = 0x201000 bytes +.fi +.in + +コマンドライン引き数でスタックサイズが与えられた場合、 +このプログラムは、スレッド属性オブジェクトを初期化し、 +そのオブジェクトの各種属性を設定し、 +\fBpthread_create\fP(3) の呼び出しでこのオブジェクトへのポインタを渡す。 +このプログラムを NPTL スレッド実装が使われている Linux/x86\-32 で +動作させると、以下のような出力が得られる。 + +.in +4n +.nf +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +$\fB ./a.out 0x3000000\fP +posix_memalign() allocated at 0x40197000 +Thread attributes: + Detach state = PTHREAD_CREATE_DETACHED + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_EXPLICIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 0 bytes + Stack address = 0x40197000 + Stack size = 0x3000000 bytes +.fi +.in +.SS プログラムのソース +\& +.nf +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +display_pthread_attr(pthread_attr_t *attr, char *prefix) +{ + int s, i; + size_t v; + void *stkaddr; + struct sched_param sp; + + s = pthread_attr_getdetachstate(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getdetachstate"); + printf("%sDetach state = %s\en", prefix, + (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : + (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : + "???"); + + s = pthread_attr_getscope(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getscope"); + printf("%sScope = %s\en", prefix, + (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : + (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : + "???"); + + s = pthread_attr_getinheritsched(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getinheritsched"); + printf("%sInherit scheduler = %s\en", prefix, + (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : + (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : + "???"); + + s = pthread_attr_getschedpolicy(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedpolicy"); + printf("%sScheduling policy = %s\en", prefix, + (i == SCHED_OTHER) ? "SCHED_OTHER" : + (i == SCHED_FIFO) ? "SCHED_FIFO" : + (i == SCHED_RR) ? "SCHED_RR" : + "???"); + + s = pthread_attr_getschedparam(attr, &sp); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedparam"); + printf("%sScheduling priority = %d\en", prefix, sp.sched_priority); + + s = pthread_attr_getguardsize(attr, &v); + if (s != 0) + handle_error_en(s, "pthread_attr_getguardsize"); + printf("%sGuard size = %d bytes\en", prefix, v); + + s = pthread_attr_getstack(attr, &stkaddr, &v); + if (s != 0) + handle_error_en(s, "pthread_attr_getstack"); + printf("%sStack address = %p\en", prefix, stkaddr); + printf("%sStack size = 0x%x bytes\en", prefix, v); +} + +static void * +thread_start(void *arg) +{ + int s; + pthread_attr_t gattr; + + /* pthread_getattr_np() is a non\-standard GNU extension that + retrieves the attributes of the thread specified in its + first argument */ + + s = pthread_getattr_np(pthread_self(), &gattr); + if (s != 0) + handle_error_en(s, "pthread_getattr_np"); + + printf("Thread attributes:\en"); + display_pthread_attr(&gattr, "\et"); + + exit(EXIT_SUCCESS); /* Terminate all threads */ +} + +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp; /* NULL or &attr */ + int s; + + attrp = NULL; + + /* If a command\-line argument was supplied, use it to set the + stack\-size attribute and set a few other thread attributes, + and set attrp pointing to thread attributes object */ + + if (argc > 1) { + int stack_size; + void *sp; + + attrp = &attr; + + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + + s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); + if (s != 0) + handle_error_en(s, "pthread_attr_setdetachstate"); + + s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); + if (s != 0) + handle_error_en(s, "pthread_attr_setinheritsched"); + + stack_size = strtoul(argv[1], NULL, 0); + + s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); + if (s != 0) + handle_error_en(s, "posix_memalign"); + + printf("posix_memalign() allocated at %p\en", sp); + + s = pthread_attr_setstack(&attr, sp, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstack"); + } + + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } + + pause(); /* Terminates when other thread calls exit() */ +} +.fi +.SH 関連項目 +\fBpthread_attr_setaffinity_np\fP(3), \fBpthread_attr_setdetachstate\fP(3), +\fBpthread_attr_setguardsize\fP(3), \fBpthread_attr_setinheritsched\fP(3), +\fBpthread_attr_setschedparam\fP(3), \fBpthread_attr_setschedpolicy\fP(3), +\fBpthread_attr_setscope\fP(3), \fBpthread_attr_setstack\fP(3), +\fBpthread_attr_setstackaddr\fP(3), \fBpthread_attr_setstacksize\fP(3), +\fBpthread_create\fP(3), \fBpthread_getattr_np\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setaffinity_np.3 b/draft/man3/pthread_attr_setaffinity_np.3 new file mode 100644 index 00000000..4b1b52a0 --- /dev/null +++ b/draft/man3/pthread_attr_setaffinity_np.3 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETAFFINITY_NP 3 2010\-09\-10 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- +スレッド属性オブジェクトの CPU affinity 属性の設定/取得を行う +.SH 書式 +.nf +\fB#define _GNU_SOURCE\fP /* See feature_test_macros(7) */ +\fB#include \fP + +\fBint pthread_attr_setaffinity_np(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB size_t \fP\fIcpusetsize\fP\fB, const cpu_set_t *\fP\fIcpuset\fP\fB);\fP +\fBint pthread_attr_getaffinity_np(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB size_t \fP\fIcpusetsize\fP\fB, cpu_set_t *\fP\fIcpuset\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setaffinity_np\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトの CPU affinity マスク属性を +\fIcpuset\fP で指定された値に設定する。 +この属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されたスレッドの CPU affinity マスクが決定される。 + +\fBpthread_attr_getaffinity_np\fP() 関数は、 \fIattr\fP が参照する +スレッド属性オブジェクトの CPU affinity マスク属性を +\fIcpuset\fP が指すバッファに入れて返す。 + +\fIcpusetsize\fP 引き数は \fIcpuset\fP が指すバッファの (バイト単位の) +大きさである。通常は、この引き数には \fIsizeof(cpu_set_t)\fP を +指定することだろう。 + +CPU affinity マスクの詳細については、 +\fBsched_setaffinity\fP(2) を参照してほしい。 +CPU 集合の操作や取得を行う際に利用できるマクロ群の説明は +\fBCPU_SET\fP(3) を参照してほしい。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +.TP +\fBEINVAL\fP +.\" cpumask_t +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +(\fBpthread_attr_setaffinity_np\fP()) +\fIcpuset\fP がカーネルがサポートする CPU 集合にない CPU を指定していた。 +(CPU 集合を表現するのに使われるカーネルのデータ型がサポートする集合の範囲は、 +カーネルの設定オプション \fBCONFIG_NR_CPUS\fP により定義される)。 +.TP +\fBEINVAL\fP +(\fBpthread_attr_getaffinity_np\fP()) +\fIattr\fP が参照するスレッド属性オブジェクトの affinity マスク内の CPU が、 +\fIcpusetsize\fP により指定された範囲の中になかった +(すなわち、\fIcpuset\fP/\fIcpusetsize\fP が小さすぎる)。 +.TP +\fBENOMEM\fP +(\fBpthread_attr_setaffinity_np\fP()) メモリを割り当てることができなかった。 +.SH バージョン +これらの関数は glibc バージョン 2.3.4 以降で提供されている。 +.SH 準拠 +これらの関数は非標準の GNU による拡張である。 +そのため、名前に "_np" (nonportable; 移植性がない) という接尾辞が +付いている。 +.SH 注意 +(このバージョンだけであるが) glibc 2.3.3 では、 +これらの関数は \fIcpusetsize\fP 引き数を持っていなかった。 +内部で呼ばれるシステムコールに渡される CPU セットの大きさは +常に \fIsizeof(cpu_set_t)\fP であった。 +.SH 関連項目 +\fBsched_setaffinity\fP(2), \fBpthread_attr_init\fP(3), +\fBpthread_setaffinity_np\fP(3), \fBcpuset\fP(7), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setdetachstate.3 b/draft/man3/pthread_attr_setdetachstate.3 new file mode 100644 index 00000000..739d5a3b --- /dev/null +++ b/draft/man3/pthread_attr_setdetachstate.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETDETACHSTATE 3 2010\-02\-03 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setdetachstate, pthread_attr_getdetachstate \- +スレッド属性オブジェクトの detach state 属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setdetachstate(pthread_attr_t *\fP\fIattr\fP\fB, int \fP\fIdetachstate\fP\fB);\fP +\fBint pthread_attr_getdetachstate(pthread_attr_t *\fP\fIattr\fP\fB, int *\fP\fIdetachstate\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setdetachstate\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトの detach state 属性を +\fIdetachstate\fP で指定された値に設定する。 +detach state 属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドが、 join 可能な状態で作成されるか、 +detached (切り離された) 状態で作成されるかが決定される。 + +\fIdetachstate\fP には以下の値を指定できる。 +.TP +\fBPTHREAD_CREATE_DETACHED\fP +\fIattr\fP を使って作成されるスレッドは detached 状態で作成される。 +.TP +\fBPTHREAD_CREATE_JOINABLE\fP +\fIattr\fP を使って作成されるスレッドは join 可能な状態で作成される。 +.PP +新規に初期化されたスレッド属性オブジェクトの detach state 属性の +デフォルト設定は \fBPTHREAD_CREATE_JOINABLE\fP である。 + +\fBpthread_attr_getdetachstate\fP() は、 +スレッド属性オブジェクト \fIattr\fP の detach state 属性を +\fIdetachstate\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +\fBpthread_attr_setdetachstate\fP() は以下のエラーで失敗する場合がある。 +.TP +\fBEINVAL\fP +無効な値が \fIdetachstate\fP で指定された。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +detached 状態のスレッド、join 可能状態のスレッドの詳細については、 +\fBpthread_create\fP(3) を参照。 + +join 可能状態で作成されたスレッドは、最終的に +\fBpthread_join\fP(3) を使って join するか、 +\fBpthread_detach\fP(3) を使って切り離すか、 +のどちらかを行うべきである。 + +detached 状態で作成されたスレッドのスレッド ID を指定して、 +\fBpthread_detach\fP(3) や \fBpthread_join\fP(3) を後から呼び出すのは +エラーである。 +.SH 例 +\fBpthread_attr_init\fP(3) を参照。 +.SH 関連項目 +\fBpthread_attr_init\fP(3), \fBpthread_create\fP(3), \fBpthread_detach\fP(3), +\fBpthread_join\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setguardsize.3 b/draft/man3/pthread_attr_setguardsize.3 new file mode 100644 index 00000000..8f971ead --- /dev/null +++ b/draft/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETGUARDSIZE 3 2008\-10\-24 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setguardsize, pthread_attr_getguardsize \- +スレッド属性オブジェクトの guard size 属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setguardsize(pthread_attr_t *\fP\fIattr\fP\fB, size_t \fP\fIguardsize\fP\fB);\fP +\fBint pthread_attr_getguardsize(pthread_attr_t *\fP\fIattr\fP\fB, size_t *\fP\fIguardsize\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setguardsize\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトの guard size 属性を +\fIguardsize\fP で指定された値に設定する。 + +\fIguardsize\fP が 0 より大きい場合、 +\fIattr\fP を使って新しく作成された各スレッドに対して、 +システムはスレッドのスタックの末尾に少なくとも \fIguardsize\fP バイトの +追加領域を割り当てる。この追加領域はスタックに対するガード領域として +機能する (ただし「バグ」の節も参照)。 + +\fIguardsize\fP が 0 の場合、 +\fIattr\fP を使って新しく作成されたスレッドはガード領域を持たない。 + +デフォルトの guard size はシステムのページサイズと同じである。 + +(\fBpthread_attr_setstack\fP(3) や \fBpthread_attr_setstackaddr\fP(3)を使って) +\fIattr\fP でスタックアドレス属性が設定されている場合には、呼び出し側がそ +のスレッドのスタックを割り当てていることを意味するので、guard size 属性 +は無視される (すなわち、システムによるガード領域の作成は行われない)。 +この場合、スタックオーバーフローが起こらないように対処するのはアプリ +ケーション側の責任となる (おそらく \fBmprotect\fP(2) を使って、割り当て +られたスタックの最後に手動でガード領域を定義することになるだろう)。 + +\fBpthread_attr_getguardsize\fP() は、 +スレッド属性オブジェクト \fIattr\fP の guard size 属性を +\fIguardsize\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +POSIX.1\-2001 では、エラー \fBEINVAL\fP が + \fIattr\fP か \fIguardsize\fP が無効な場合に対して規定されている。 +Linux では、これらの関数は常に作成する +(ただし、移植性や将来も動作することを保証したいアプリケーションでは +正のエラーの返り値を処理するようにすべきである)。 +.SH バージョン +これらの関数は glibc バージョン 2.1 以降で提供されている。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +ガード領域は、読み出し/書き込みアクセスが行われないように保護がかけ +られた仮想メモリページで構成で構成される。スレッドがスタックをガード +領域までオーバーフローさせた場合、ほとんどのハードウェアアーキテクチャ +では、スレッドに \fBSIGSEGV\fP シグナルが送られ、オーバーフローが発生した +ことが通知される。ガード領域はページ境界から開始され、ガード領域の +大きさはスレッド作成時に内部的にシステムのページサイズに切り上げられる +(その場合も \fBpthread_attr_getguardsize\fP() では +\fBpthread_attr_setguardsize\fP() で設定された guard size が返される)。 + +多くのスレッドを作成するアプリケーションで、かつ、スタックオーバーフロー +が決して発生しないことが分かっている場合には、guard size を 0 に設定 +することで、メモリを節約できることもある。 + +スレッドがスタックに大きなデータ構造を割り当てる場合には、 +スタックオーバーフローを検出するためには、デフォルトサイズよりも +大きな guard size を選ぶ必要があるかもしれない。 +.SH バグ +glibc 2.8 の時点では、 NPTL スレッド実装ではガード領域はスタックサイズ +で割り当てられる領域の中に含まれている。一方、POSIX.1 では、スタックの +末尾に追加の領域を割り当てることが求められている。 +(このため、ガード領域が大きすぎて、 +実際のスタック用の場所がなくなってしまう場合、 +\fBpthread_create\fP(3) で \fBEINVAL\fP エラーが発生することになる。) + +.\" glibc includes the guardsize within the allocated stack size, +.\" which looks pretty clearly to be in violation of POSIX. +.\" +.\" Filed bug, 22 Oct 2008: +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973 +.\" +.\" Older reports: +.\" https//bugzilla.redhat.com/show_bug.cgi?id=435337 +.\" Reportedly, LinuxThreads did the right thing, allocating +.\" extra space at the end of the stack: +.\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html +廃止予定の LinuxThreads 実装では、 +POSIX.1 で求められている通りの動作で、 +ガード領域がスタックの末尾に追加の領域が割り当てられる。 +.SH 例 +\fBpthread_getattr_np\fP(3) を参照。 +.SH 関連項目 +\fBmmap\fP(2), \fBmprotect\fP(2), \fBpthread_attr_init\fP(3), +\fBpthread_attr_setstack\fP(3), \fBpthread_attr_setstacksize\fP(3), +\fBpthread_create\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setinheritsched.3 b/draft/man3/pthread_attr_setinheritsched.3 new file mode 100644 index 00000000..2d05bf8b --- /dev/null +++ b/draft/man3/pthread_attr_setinheritsched.3 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETINHERITSCHED 3 2012\-03\-15 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setinheritsched, pthread_attr_getinheritsched \- +スレッド属性オブジェクトの inherit scheduler 属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setinheritsched(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB int \fP\fIinheritsched\fP\fB);\fP +\fBint pthread_attr_getinheritsched(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB int *\fP\fIinheritsched\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setinheritsched\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトの inherit scheduler 属性を +\fIinheritsched\fP で指定された値に設定する。 +inherit scheduler 属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドが、呼び出したスレッドのスケジューリング属性を継承 +するか、\fIattr\fP からスケジューリング属性を取得するかが決定される。 + +以下の値を \fIinheritsched\fP に指定できる。 +.TP +\fBPTHREAD_INHERIT_SCHED\fP +\fIattr\fP を使って作成されたスレッドは、 +スレッドを作成するスレッドからスケジューリング属性を継承する。 +\fIattr\fP 内のスケジューリング属性は無視される。 +.TP +\fBPTHREAD_EXPLICIT_SCHED\fP +.\" FIXME what are the defaults for scheduler settings? +\fIattr\fP を使って作成されたスレッドは、スレッド属性オブジェクトで +指定された値からスケジューリング属性を取得する。 +.PP +新たに初期化されたスレッド属性オブジェクトの inherit scheduler 属性の +デフォルト設定は \fBPTHREAD_INHERIT_SCHED\fP である。 + +\fBpthread_attr_getinheritsched\fP() は、 +スレッド属性オブジェクト \fIattr\fP の inherit scheduler 属性を +\fIinheritsched\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +\fBpthread_attr_setinheritsched\fP() は以下のエラーで失敗する場合がある。 +.TP +\fBEINVAL\fP +\fIinheritsched\fP に無効な値が指定された。 +.PP +.\" .SH VERSIONS +.\" Available since glibc 2.0. +POSIX.1\-2001 では、 \fBpthread_attr_setinheritsched\fP() に関して +エラー \fBENOTSUP\fP ("サポートされていない値を属性に設定しようとした") +も追加で規定されている。 +.SH 準拠 +POSIX.1\-2001. +.SH バグ +.\" FIXME . Track status of the following bug: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7007 +glibc 2.8 の時点では、スレッド属性オブジェクトが +\fBpthread_attr_init\fP(3) を使って初期化された場合、 +スレッド属性オブジェクトのスケジューリングポリシーが \fBSCHED_OTHER\fP に、 +スケジューリング優先度が 0 に設定される。一方、その後 inherit +scheduling 属性に \fBPTHREAD_EXPLICIT_SCHED\fP が設定されると、このスレッ +ド属性オブジェクトを使って作成されたスレッドでは、スレッドを作成するス +レッドのスケジューリング属性が間違って継承されてしまう。 +\fBpthread_create\fP(3) を呼び出す前にスケジューリングポリシー属性か +スケジューリング優先度属性のどちらかが明示的に設定された場合には、 +このバグは発生しない。 +.SH 例 +\fBpthread_setschedparam\fP(3) を参照。 +.SH 関連項目 +\fBsched_setscheduler\fP(2), \fBpthread_attr_init\fP(3), +\fBpthread_attr_setschedparam\fP(3), \fBpthread_attr_setschedpolicy\fP(3), +\fBpthread_create\fP(3), \fBpthread_setschedparam\fP(3), +\fBpthread_setschedprio\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setschedparam.3 b/draft/man3/pthread_attr_setschedparam.3 new file mode 100644 index 00000000..4b7076c1 --- /dev/null +++ b/draft/man3/pthread_attr_setschedparam.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETSCHEDPARAM 3 2012\-03\-15 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setschedparam, pthread_attr_getschedparam \- +スレッド属性オブジェクトのスケジューリングパラメータ属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setschedparam(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB const struct sched_param *\fP\fIparam\fP\fB);\fP +\fBint pthread_attr_getschedparam(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB struct sched_param *\fP\fIparam\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setschedparam\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトのスケジューリング +パラメータ属性を \fIparam\fP が指すバッファで指定された値に設定する。 +これらの属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドのスケジューリングパラメータが決定される。 + +\fBpthread_attr_getschedparam\fP() は、 +スレッド属性オブジェクト \fIattr\fP のスケジューリングパラメータ属性を +\fIparam\fP が指すバッファに入れて返す。 + +スケジューリングパラメータは以下の構造体で管理される。 + +.in +4n +.nf +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.fi +.in + +見て分かる通り、サポートされているスケジューリングパラメータは一つだけ +である。各スケジューリングポリシーで許可されるスケジューリング優先度の +詳細については、\fBsched_setscheduler\fP(2) を参照のこと。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +.\" .SH VERSIONS +.\" Available since glibc 2.0. +POSIX.1 では、 +\fBpthread_attr_setschedparam\fP() について +\fBEINVAL\fP と \fBENOTSUP\fP が規定されている。 +Linux では、これらの関数は常に作成する +(ただし、移植性や将来も動作することを保証したいアプリケーションでは +正のエラーの返り値を処理するようにすべきである)。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +Linux でサポートされているスレッドのスケジューリングポリシーのリストに +ついては、 \fBpthread_attr_setschedpolicy\fP(3) を参照。 +.SH 例 +\fBpthread_setschedparam\fP(3) を参照。 +.SH 関連項目 +\fBsched_get_priority_min\fP(2), \fBsched_setscheduler\fP(2), +\fBpthread_attr_init\fP(3), \fBpthread_attr_setinheritsched\fP(3), +\fBpthread_attr_setschedpolicy\fP(3), \fBpthread_create\fP(3), +\fBpthread_setschedparam\fP(3), \fBpthread_setschedprio\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setschedpolicy.3 b/draft/man3/pthread_attr_setschedpolicy.3 new file mode 100644 index 00000000..dac1b173 --- /dev/null +++ b/draft/man3/pthread_attr_setschedpolicy.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETSCHEDPOLICY 3 2010\-02\-03 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy \- スレッド属性 +オブジェクトのスケジューリングポリシー属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setschedpolicy(pthread_attr_t *\fP\fIattr\fP\fB, int \fP\fIpolicy\fP\fB);\fP +\fBint pthread_attr_getschedpolicy(pthread_attr_t *\fP\fIattr\fP\fB, int \fP\fI*policy\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setschedpolicy\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトのスケジューリング +ポリシー属性を \fIpolicy\fP で指定された値に設定する。 +この属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドのスケジューリングポリシーが決定される。 + +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +\fIpolicy\fP に指定できる値は \fBSCHED_FIFO\fP, \fBSCHED_RR\fP, \fBSCHED_OTHER\fP +である。それぞれの意味は \fBsched_setscheduler\fP(2) で説明している通り +である。 + +\fBpthread_attr_getschedpolicy\fP() は、 +スレッド属性オブジェクト \fIattr\fP のスケジューリングポリシー属性を +\fIpolicy\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +\fBpthread_attr_setschedpolicy\fP() は以下のエラーで失敗する場合がある。 +.TP +\fBEINVAL\fP +\fIpolicy\fP に無効な値が指定された。 +.PP +.\" .SH VERSIONS +.\" Available since glibc 2.0. +POSIX.1\-2001 では、 \fBpthread_attr_setschedpolicy\fP() に関して +エラー \fBENOTSUP\fP ("サポートされていない値を属性に設定しようとした") +も追加で規定されている。 +.SH 準拠 +POSIX.1\-2001. +.SH 例 +\fBpthread_setschedparam\fP(3) を参照。 +.SH 関連項目 +\fBsched_setscheduler\fP(2), \fBpthread_attr_init\fP(3), +\fBpthread_attr_setinheritsched\fP(3), \fBpthread_attr_setschedparam\fP(3), +\fBpthread_create\fP(3), \fBpthread_setschedparam\fP(3), +\fBpthread_setschedprio\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setstack.3 b/draft/man3/pthread_attr_setstack.3 new file mode 100644 index 00000000..1f86f2a1 --- /dev/null +++ b/draft/man3/pthread_attr_setstack.3 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETSTACK 3 2008\-10\-24 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setstack, pthread_attr_getstack \- +スレッド属性オブジェクトのスタック属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setstack(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB void *\fP\fIstackaddr\fP\fB, size_t \fP\fIstacksize\fP\fB);\fP +\fBint pthread_attr_getstack(pthread_attr_t *\fP\fIattr\fP\fB,\fP +\fB void **\fP\fIstackaddr\fP\fB, size_t *\fP\fIstacksize\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.in +.sp +.ad l +\fBpthread_attr_getstack\fP(), \fBpthread_attr_setstack\fP(): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600 +.RE +.ad b +.SH 説明 +\fBpthread_attr_setstack\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトのスタックアドレス属性と +スタックサイズ属性をそれぞれ \fIstackaddr\fP と \fIstacksize\fP で +指定された値に設定する。 +これらの属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドが使用すべきスタックの位置とサイズが指定される。 + +\fIstackaddr\fP は、呼び出し側で割り当てた、大きさが \fIstacksize\fP バイトの +バッファ内の指定できる最小のアドレスバイトを指すべきである。 +割り当てられたバッファのページは読み書き両方が可能なページとなっている +べきである。 + +\fBpthread_attr_getstack\fP() 関数は、 +スレッド属性オブジェクト \fIattr\fP のスタックアドレス属性と +スタックサイズ属性をそれぞれ \fIstackaddr\fP と \fIstacksize\fP が +指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +\fBpthread_attr_setstack\fP() は以下のエラーで失敗する場合がある。 +.TP +\fBEINVAL\fP +\fIstacksize\fP が \fBPTHREAD_STACK_MIN\fP (16384) よりも小さい。 +システムによっては、 \fIstackaddr\fP か +\fIstackaddr\ +\ stacksize\fP のアライメントが適切でない場合にも +このエラーが発生する。 +.PP +POSIX.1\-2001 では エラー \fBEACCES\fP も規定されており、 +このエラーは \fIstackaddr\fP と \fIstacksize\fP で規定されるスタック領域に +呼び出し側から読み書き両方のアクセスができない状況を表す。 +.SH バージョン +これらの関数は glibc バージョン 2.2 以降で提供されている。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +これらの関数は、スレッドのスタックが特定の場所に配置されることを保証 +しなければならないアプリケーションのために提供されている。 +ほとんどのアプリケーションでは、このようなことは必要なく、 +これらの関数を使うのは避けるべきである。 +(アプリケーションが単にスタックサイズだけをデフォルトの値から変更する +必要がある場合には \fBpthread_attr_setstacksize\fP(3) を使うこと) + +アプリケーションが \fBpthread_attr_setstack\fP() を利用する際には、 +スタックの割り当てに責任を持つ必要がある。 +\fBpthread_attr_setguardsize\fP(3) を使って設定された +guard size の値は無視される。 +必要と思われる場合は、アプリケーションが責任を持ってガード領域 (読み書 +きが行われないように保護された 1 個かそれ以上のページ) の割り当てを行い、 +スタックオーバーフローの可能性に対処するようにする必要がある。 + +\fIstackaddr\fP に指定するアドレスは適切なアライメントとなっているべきである。 +完全な移植性を持たせるためには、 +ページ境界 (\fIsysconf(_SC_PAGESIZE)\fP) に揃えること。 +割り当てには \fBposix_memalign\fP(3) を使うとよい。 +たいていは、 \fIstacksize\fP はシステムのページサイズの倍数とすべきである。 + +一つの \fIattr\fP を使って複数のスレッドを作成する場合、 +\fBpthread_create\fP(3) の次の呼び出しを行う前に、 +呼び出し側でスタックアドレス属性を変更しなければならない。 +さもなければ、複数のスレッドがスタックとして同じメモリ領域を +使おうとするため、訳の分からない状況が発生してしまう。 +.SH 例 +\fBpthread_attr_init\fP(3) を参照。 +.SH 関連項目 +\fBmmap\fP(2), \fBmprotect\fP(2), \fBposix_memalign\fP(3), \fBpthread_attr_init\fP(3), +\fBpthread_attr_setguardsize\fP(3), \fBpthread_attr_setstackaddr\fP(3), +\fBpthread_attr_setstacksize\fP(3), \fBpthread_create\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setstackaddr.3 b/draft/man3/pthread_attr_setstackaddr.3 new file mode 100644 index 00000000..3047a183 --- /dev/null +++ b/draft/man3/pthread_attr_setstackaddr.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETSTACKADDR 3 2008\-10\-24 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setstackaddr, pthread_attr_getstackaddr \- +スレッド属性オブジェクトのスタックアドレス属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setstackaddr(pthread_attr_t *\fP\fIattr\fP\fB, void *\fP\fIstackaddr\fP\fB);\fP +\fBint pthread_attr_getstackaddr(pthread_attr_t *\fP\fIattr\fP\fB, void **\fP\fIstackaddr\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +これらの関数は廃止予定であり、\fB使用しないこと\fP。 +代わりに Use \fBpthread_attr_setstack\fP(3) と \fBpthread_attr_getstack\fP(3) を使うこと。 + +\fBpthread_attr_setstackaddr\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトのスタックアドレス +属性を \fIstackaddr\fP で指定された値に設定する。 +この属性により、スレッド属性オブジェクト \fIattr\fP を使って +作成されるスレッドが使用すべきスタックの位置が指定される。 + +\fIstackaddr\fP は呼び出し側が割り当てたバッファ (大きさは +少なくとも \fBPTHREAD_STACK_MIN\fP バイト)を指すべきである。 +割り当てられたバッファのページは読み書き両方が可能なページと +なっているべきである。 + +\fBpthread_attr_getstackaddr\fP() は、 +スレッド属性オブジェクト \fIattr\fP のスタックアドレス属性を +\fIstackaddr\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +エラーは定義されていない (ただし、アプリケーションは正のエラーの +返り値を処理するようにすべきである)。 +.SH バージョン +これらの関数は glibc バージョン 2.1 以降で提供されている。 +.SH 準拠 +POSIX.1\-2001 では、これらの関数が規定されているが、廃止予定となっている。 +POSIX.1\-2008 では、これらの関数の規定は削除されている。 +.SH 注意 +\fIこれらの関数を使用しないこと!\fP これらの関数は移植性がある形では使用で +きない。なぜなら、これらの関数ではスタック領域がどちらの方向に伸びるの +かを指定する手段が提供されていないからである。 +例えば、スタックが下向き (アドレスが小さい方向) に伸びるアーキテクチャ +では、\fIstackaddr\fP には割り当てられたスタック領域の\fI最も大きな\fPアドレ +スの次のアドレスを指定する。一方、スタックが上向き (アドレスが大きい +方向) に伸びるアーキテクチャでは、\fIstackaddr\fP には割り当てられた +スタック領域の\fI最も小さい\fPアドレスを指定する。これに対して、 +\fBpthread_attr_setstack\fP(3) と \fBpthread_attr_getstack\fP(3) が使用する +\fIstackaddr\fP は、常に割り当てられたスタック領域の最も小さいアドレス +へのポインタである (\fIstacksize\fP 引き数はスタックの範囲を指定する)。 +.SH 関連項目 +\fBpthread_attr_init\fP(3), \fBpthread_attr_setstack\fP(3), +\fBpthread_attr_setstacksize\fP(3), \fBpthread_create\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_attr_setstacksize.3 b/draft/man3/pthread_attr_setstacksize.3 new file mode 100644 index 00000000..1b3d339e --- /dev/null +++ b/draft/man3/pthread_attr_setstacksize.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_ATTR_SETSTACKSIZE 3 2012\-03\-15 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_attr_setstacksize, pthread_attr_getstacksize \- +スレッド属性オブジェクトのスタックサイズ属性の設定/取得を行う +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_attr_setstacksize(pthread_attr_t *\fP\fIattr\fP\fB, size_t \fP\fIstacksize\fP\fB);\fP +\fBint pthread_attr_getstacksize(pthread_attr_t *\fP\fIattr\fP\fB, size_t *\fP\fIstacksize\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_attr_setstacksize\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトのスタックアドレス +属性を \fIstacksize\fP で指定された値に設定する。 + +スタックサイズ属性により、 +スレッド属性オブジェクト \fIattr\fP を使って作成されたスレッド +に割り当てられる最小サイズ (バイト単位) が決定される。 + +\fBpthread_attr_getstacksize\fP() は、 +スレッド属性オブジェクト \fIattr\fP のスタックアドレス属性を +\fIstacksize\fP が指すバッファに入れて返す。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +\fBpthread_attr_setstacksize\fP() は以下のエラーで失敗する場合がある。 +.TP +\fBEINVAL\fP +スタックサイズが \fBPTHREAD_STACK_MIN\fP (16384) バイト未満である。 +.PP +.\" e.g., MacOS +いくつかのシステムでは、 \fBpthread_attr_setstacksize\fP() は +\fIstacksize\fP がシステムのページサイズの倍数でない場合にも +エラー \fBEINVAL\fP で失敗する。 +.SH バージョン +これらの関数は glibc バージョン 2.1 以降で提供されている。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +新しいスレッドのデフォルトのスタックサイズの詳細については +\fBpthread_create\fP(3) を参照。 + +スレッドのスタックサイズは、スレッド作成時点では固定である。 +メインスレッドだけがスタックを動的に伸ばすことができる。 + +\fBpthread_attr_setstack\fP(3) 関数を使うと、 +アプリケーションは、スレッドが使用するスタックとして、 +呼び出し側で割り当てたスタックのサイズと場所を指定できる。 +.SH バグ +glibc 2.8 の時点では、指定された \fIstacksize\fP が \fBSTACK_ALIGN\fP +(ほとんどのアーキテクチャでは 16 バイト) の倍数でない場合、 +\fIstacksize\fP は\fI小さくなる方向に\fPに丸められる。 +これは POSIX.1\-2001 に違反している。 +POSIX.1\-2001 では、割り当てらたスタックの大きさは +少なくとも \fIstacksize\fP バイトになると書かれている。 +.SH 例 +\fBpthread_create\fP(3) を参照。 +.SH 関連項目 +\fBgetrlimit\fP(2), \fBpthread_attr_init\fP(3), \fBpthread_attr_setguardsize\fP(3), +\fBpthread_attr_setstack\fP(3), \fBpthread_create\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_cancel.3 b/draft/man3/pthread_cancel.3 index d49e7502..c7105e37 100644 --- a/draft/man3/pthread_cancel.3 +++ b/draft/man3/pthread_cancel.3 @@ -38,17 +38,17 @@ pthread_cancel \- スレッドにキャンセル要求を送る \fI\-pthread\fP でコンパイルしてリンクする。 .fi .SH 説明 -\fBpthread_cancel\fP() 関数は指定されたスレッド \fIthread\fP にキャンセル要求を送信 -する。対象のスレッドがキャンセル要求に反応するかどうか、いつ反応するかは対象 -のスレッドの制御下にある 2 つの属性、cancelability \fIstate\fP と \fItype\fPにより -決まる。 - -あるスレッドの cancelability state は \fBpthread_setcancelstate\fP(3) で設定され、 -\fIenabled\fP と \fIdisabled\fP のいずれとなる (\fIenabled\fP が新しいスレッドのデフォ -ルト値である)。スレッドがキャンセルを無効にしていた場合、キャンセル要求はその -スレッドがキャンセルを有効にするまでキューに入れられたままになる。スレッドが -キャンセルを有効にしていた場合、cancelability type によって、いつキャンセルが -発生するかが決まる。 +\fBpthread_cancel\fP() 関数は指定されたスレッド \fIthread\fP にキャンセル要求 +を送信する。対象のスレッドがキャンセル要求に反応するかどうか、いつ反応 +するかは対象のスレッドの制御下にある 2 つの属性、cancelability +\fIstate\fP と \fItype\fPにより決まる。 + +あるスレッドの cancelability state は \fBpthread_setcancelstate\fP(3) で +設定され、\fIenabled\fP と \fIdisabled\fP のいずれとなる (\fIenabled\fP が新しい +スレッドのデフォルト値である)。スレッドがキャンセルを無効にしていた場合、 +キャンセル要求はそのスレッドがキャンセルを有効にするまでキューに入れら +れたままになる。スレッドがキャンセルを有効にしていた場合、 +cancelability type によって、いつキャンセルが発生するかが決まる。 スレッドの cancellation type は \fBpthread_setcanceltype\fP(3) で設定され、 \fIasynchronous\fP か \fIdeferred\fP のいずれかとなる(\fIdeferred\fP が新しいスレッド @@ -58,13 +58,13 @@ pthread_cancel \- スレッドにキャンセル要求を送る そのことを保証しているわけではない)。 遅延キャンセル (deferred cancelability) では、そのスレッドが \fIcancellation point\fP となっている関数を次に呼び出すまでキャンセルが遅延される。 -cancellation point に設定されていたり設定したりできる関数のリストは -\fIpthreads\fP(7) に記載している。 +取り消しポイント (cancellation point) に設定されていたり設定したりできる +関数のリストは \fIpthreads\fP(7) に記載している。 キャンセル要求が実行されると、 \fIthread\fP では以下のステップが (この順序で) 行われる。 .IP 1. 3 -キャンセルのクリーンアップハンドラが (push されたのと逆順で) +キャンセルクリーンアップハンドラが (push されたのと逆順で) 取り出され (pop され)、呼び出される。 (\fBpthread_cleanup_push\fP(3) 参照) .IP 2. diff --git a/draft/man3/pthread_equal.3 b/draft/man3/pthread_equal.3 new file mode 100644 index 00000000..f840d3a4 --- /dev/null +++ b/draft/man3/pthread_equal.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_EQUAL 3 2009\-03\-30 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_equal \- スレッド ID を比較する +.SH 書式 +.nf +\fB#include \fP + +\fBint pthread_equal(pthread_t \fP\fIt1\fP\fB, pthread_t \fP\fIt2\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_equal\fP() 関数は 2 つのスレッド識別子の比較を行う。 +.SH 返り値 +\fBpthread_equal\fP() は、2 つのスレッド ID が等しければ 0 以外の値を返し、 +そうでなければ 0 を返す。 +.SH エラー +この関数は常に成功する。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +\fBpthread_equal\fP() 関数が必要なのは、 +スレッド ID はその内部構造を意識すべきではないためである。 +アプリケーションが 2 つの \fIpthread_t\fP の値を直接比較する場合、 +移植性を確保できる形で比較する方法はない。 +.SH 関連項目 +\fBpthread_create\fP(3), \fBpthread_self\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_getattr_np.3 b/draft/man3/pthread_getattr_np.3 new file mode 100644 index 00000000..f6e08076 --- /dev/null +++ b/draft/man3/pthread_getattr_np.3 @@ -0,0 +1,343 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_GETATTR_NP 3 2010\-09\-10 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_getattr_np \- 作成されたスレッドの属性を取得する +.SH 書式 +.nf +\fB#define _GNU_SOURCE\fP /* See feature_test_macros(7) */ +\fB#include \fP + +\fBint pthread_getattr_np(pthread_t \fP\fIthread\fP\fB, pthread_attr_t *\fP\fIattr\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_getattr_np\fP() 関数は、 +\fIattr\fP が参照するスレッド属性オブジェクトを初期化し、 +そのオブジェクトに実行中のスレッド \fIthread\fP の実際の属性値を +格納して返す。 + +返される属性値は、\fBpthread_create\fP(3) でスレッドを作成する際に +使われた\fIattr\fP オブジェクトで渡された属性値と異なる場合がある。 +特に、以下の属性は異なる場合がある。 +.IP * 2 +detach state. join 可能なスレッドは作成後に自分自身を +切り離す (detach する) ことができるからである。 +.IP * +スタックサイズ。 +スレッドの実装によって適切な境界に揃えられる可能があるためである。 +.IP * +guard size. +スレッドの実装によりページサイズの倍数に切り上げられたり、 +アプリケーションが自分でスタックを割り当てる場合には無視される +(0 として扱われる) ことがあるからである。 +.PP +さらに、スレッドを作成する際に使用されたスレッド属性オブジェクトで +スタックアドレスが設定されていなかった場合、 +返されたスレッド属性オブジェクトではスレッドの実装がそのスレッドに +割り当てた実際のスタックアドレスが報告される。 + +\fBpthread_getattr_np\fP() が返したスレッド属性オブジェクトが +必要なくなった際には、 \fBpthread_attr_destroy\fP(3) を使って +そのオブジェクトを破棄すべきである。 +.SH 返り値 +成功すると、この関数は 0 を返す。 +エラーの場合、 0 以外のエラー番号を返す。 +.SH エラー +.TP +\fBENOMEM\fP +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +メモリが十分になかった。 +.PP +さらに、 \fIthread\fP がメインスレッドを参照している場合には、 +\fBpthread_getattr_np\fP() は内部で行われる様々な呼び出しでの +エラーで失敗する可能性がある。 +\fI/proc/self/maps\fP がオープンできない場合には \fBfopen\fP(3) +でエラーが発生し、リソース上限 \fBRLIMIT_STACK\fP が +サポートされていない場合には \fBgetrlimit\fP(2) でエラーが発生する。 +.SH バージョン +この関数は glibc バージョン 2.2.3 以降で利用できる。 +.SH 準拠 +この関数は非標準の GNU による拡張である。 +そのため、名前に "_np" (nonportable; 移植性がない) という接尾辞が +付いている。 +.SH 例 +以下のプログラムは \fBpthread_getattr_np\fP() の使用例を示したものである。 +このプログラムは、スレッドを作成し、それから +\fBpthread_getattr_np\fP() を使ってそのスレッドの属性 guard size、 +スタックアドレス、スタックサイズを取得し表示する。 +コマンドライン引き数での指定で、スレッドを作成する際に +上記の属性にデフォルト値以外の値を設定することができる。 +下記のシェルのセッションはこのプログラムの使用例である。 + +最初の実行例は、デフォルトの属性でスレッドが作成されている +(x86\-32 システム上で実行)。 + +.in +4n +.nf +$\fB ulimit \-s\fP # No stack limit ==> default stack size is 2MB +unlimited +$\fB ./a.out\fP +Attributes of created thread: + Guard size = 4096 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.fi +.in + +次の実行例では、guard size が指定された場合、 +guard size はシステムのページサイズの倍数に切り上げられることが分かる +(x86\-32 ではシステムのページサイズは 4096 バイトである)。 + +.in +4n +.nf +$\fB ./a.out \-g 4097\fP +Thread attributes object after initializations: + Guard size = 4097 bytes + Stack address = (nil) + Stack size = 0x0 (0) bytes + +Attributes of created thread: + Guard size = 8192 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.fi +.in + +.\".in +4n +.\".nf +.\"$ ./a.out \-s 0x8000 +.\"Thread attributes object after initializations: +.\" Guard size = 4096 bytes +.\" Stack address = 0xffff8000 (EOS = (nil)) +.\" Stack size = 0x8000 (32768) bytes +.\" +.\"Attributes of created thread: +.\" Guard size = 4096 bytes +.\" Stack address = 0x4001e000 (EOS = 0x40026000) +.\" Stack size = 0x8000 (32768) bytes +.\".fi +.\".in +最後の実行例では、プログラムでスレッド用のスタックを手動で割り当てている。 +この場合には、guard size 属性は無視される。 + +.in +4n +.nf +$\fB ./a.out \-g 4096 \-s 0x8000 \-a\fP +Allocated thread stack at 0x804d000 + +Thread attributes object after initializations: + Guard size = 4096 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes + +Attributes of created thread: + Guard size = 0 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +.fi +.in +.SS プログラムのソース +\& +.nf +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +display_stack_related_attributes(pthread_attr_t *attr, char *prefix) +{ + int s; + size_t stack_size, guard_size; + void *stack_addr; + + s = pthread_attr_getguardsize(attr, &guard_size); + if (s != 0) + handle_error_en(s, "pthread_attr_getguardsize"); + printf("%sGuard size = %d bytes\en", prefix, guard_size); + + s = pthread_attr_getstack(attr, &stack_addr, &stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_getstack"); + printf("%sStack address = %p", prefix, stack_addr); + if (stack_size > 0) + printf(" (EOS = %p)", (char *) stack_addr + stack_size); + printf("\en"); + printf("%sStack size = 0x%x (%d) bytes\en", + prefix, stack_size, stack_size); +} + +static void +display_thread_attributes(pthread_t thread, char *prefix) +{ + int s; + pthread_attr_t attr; + + s = pthread_getattr_np(thread, &attr); + if (s != 0) + handle_error_en(s, "pthread_getattr_np"); + + display_stack_related_attributes(&attr, prefix); + + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); +} + +static void * /* Start function for thread we create */ +thread_start(void *arg) +{ + printf("Attributes of created thread:\en"); + display_thread_attributes(pthread_self(), "\et"); + + exit(EXIT_SUCCESS); /* Terminate all threads */ +} + +static void +usage(char *pname, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]" + " [\-g guard\-size]\en", pname); + fprintf(stderr, "\et\et\-a means program should allocate stack\en"); + exit(EXIT_FAILURE); +} + +static pthread_attr_t * /* Get thread attributes from command line */ +get_thread_attributes_from_cl(int argc, char *argv[], + pthread_attr_t *attrp) +{ + int s, opt, allocate_stack; + long stack_size, guard_size; + void *stack_addr; + pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize + a thread attributes object */ + allocate_stack = 0; + stack_size = \-1; + guard_size = \-1; + + while ((opt = getopt(argc, argv, "ag:s:")) != \-1) { + switch (opt) { + case \(aqa\(aq: allocate_stack = 1; break; + case \(aqg\(aq: guard_size = strtoul(optarg, NULL, 0); break; + case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break; + default: usage(argv[0], NULL); + } + } + + if (allocate_stack && stack_size == \-1) + usage(argv[0], "Specifying \-a without \-s makes no sense\en"); + + if (argc > optind) + usage(argv[0], "Extraneous command\-line arguments\en"); + + if (stack_size >= 0 || guard_size > 0) { + ret_attrp = attrp; + + s = pthread_attr_init(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + } + + if (stack_size >= 0) { + if (!allocate_stack) { + s = pthread_attr_setstacksize(attrp, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } else { + s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE), + stack_size); + if (s != 0) + handle_error_en(s, "posix_memalign"); + printf("Allocated thread stack at %p\en\en", stack_addr); + + s = pthread_attr_setstack(attrp, stack_addr, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } + } + + if (guard_size >= 0) { + s = pthread_attr_setguardsize(attrp, guard_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } + + return ret_attrp; +} + +int +main(int argc, char *argv[]) +{ + int s; + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize + a thread attributes object */ + + attrp = get_thread_attributes_from_cl(argc, argv, &attr); + + if (attrp != NULL) { + printf("Thread attributes object after initializations:\en"); + display_stack_related_attributes(attrp, "\et"); + printf("\en"); + } + + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } + + pause(); /* Terminates when other thread calls exit() */ +} +.fi +.SH 関連項目 +\fBpthread_attr_getaffinity_np\fP(3), \fBpthread_attr_getdetachstate\fP(3), +\fBpthread_attr_getguardsize\fP(3), \fBpthread_attr_getinheritsched\fP(3), +\fBpthread_attr_getschedparam\fP(3), \fBpthread_attr_getschedpolicy\fP(3), +\fBpthread_attr_getscope\fP(3), \fBpthread_attr_getstack\fP(3), +\fBpthread_attr_getstackaddr\fP(3), \fBpthread_attr_getstacksize\fP(3), +\fBpthread_attr_init\fP(3), \fBpthread_create\fP(3), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_getcpuclockid.3 b/draft/man3/pthread_getcpuclockid.3 new file mode 100644 index 00000000..53d85ae8 --- /dev/null +++ b/draft/man3/pthread_getcpuclockid.3 @@ -0,0 +1,168 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_GETCPUCLOCKID 3 2009\-02\-08 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_getcpuclockid \- スレッドの CPU 時間時計の ID を取得する +.SH 書式 +.nf +\fB#include \fP +\fB#include \fP + +\fBint pthread_getcpuclockid(pthread_t \fP\fIthread\fP\fB, clockid_t *\fP\fIclock_id);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +.\" The clockid is constructed as follows: +.\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE) +.\" where CLOCK_IDFIELD_SIZE is 3. +\fBpthread_getcpuclockid\fP() 関数は、 +スレッド \fIthread\fP の CPU 時間時計のクロック ID を返す。 +.SH 返り値 +成功すると、この関数は 0 を返す。 +エラーの場合、 0 以外のエラー番号を返す。 +.SH エラー +.TP +\fBENOENT\fP +.\" CLOCK_THREAD_CPUTIME_ID not defined +.\" +.\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would +.\" be possible if kernel thread IDs took more than 29 bits (which +.\" they currently cannot). +スレッド単位の CPU 時間時計はこのシステムではサポートされていない。 +.TP +\fBESRCH\fP +ID が \fIthread\fP のスレッドが見つからなかった。 +.SH バージョン +この関数は glibc バージョン 2.2 以降で利用できる。 +.SH 準拠 +POSIX.1\-2001. +.SH 注意 +\fIthread\fP が呼び出したスレッドを参照している場合、 +クロック ID \fBCLOCK_THREAD_CPUTIME_ID\fP が指定されていれば、 +\fBclock_gettime\fP(2) と \fBclock_settime\fP(2) が操作するのと同じ時計 +を参照する ID が返される。 +.SH 例 +以下のプログラムは、スレッドを作成し、それから +\fBclock_gettime\fP(2) を使ってプロセス全体の CPU 時間を取得し、 +\fBpthread_getcpuclockid\fP(3) を使って 2 つのスレッドが消費した +スレッド毎の CPU 時間を取得する。 +下記のシェルのセッションは実行例である。 +.in +4n +.nf +$ \fB./a.out\fP +Main thread sleeping +Subthread starting infinite loop +Main thread consuming some CPU time... +Process total CPU time: 1.368 +Main thread CPU time: 0.376 +Subthread CPU time: 0.992 +.fi +.in +.SS プログラムのソース +\& +.nf +/* "\-lrt" でリンクする */ + +#include +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void * +thread_start(void *arg) +{ + printf("Subthread starting infinite loop\en"); + for (;;) + continue; +} + +static void +pclock(char *msg, clockid_t cid) +{ + struct timespec ts; + + printf("%s", msg); + if (clock_gettime(cid, &ts) == \-1) + handle_error("clock_gettime"); + printf("%4ld.%03ld\en", ts.tv_sec, ts.tv_nsec / 1000000); +} + +int +main(int argc, char *argv[]) +{ + pthread_t thread; + clockid_t cid; + int j, s; + + s = pthread_create(&thread, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + printf("Main thread sleeping\en"); + sleep(1); + + printf("Main thread consuming some CPU time...\en"); + for (j = 0; j < 2000000; j++) + getppid(); + + pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID); + + s = pthread_getcpuclockid(pthread_self(), &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Main thread CPU time: ", cid); + + /* The preceding 4 lines of code could have been replaced by: + pclock("Main thread CPU time: ", CLOCK_THREAD_CPUTIME_ID); */ + + s = pthread_getcpuclockid(thread, &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Subthread CPU time: 1 ", cid); + + exit(EXIT_SUCCESS); /* Terminates both threads */ +} +.fi +.SH 関連項目 +\fBclock_gettime\fP(2), \fBclock_settime\fP(2), \fBtimer_create\fP(2), +\fBclock_getcpuclockid\fP(3), \fBpthread_self\fP(3), \fBpthreads\fP(7), \fBtime\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man3/pthread_setaffinity_np.3 b/draft/man3/pthread_setaffinity_np.3 new file mode 100644 index 00000000..72f69405 --- /dev/null +++ b/draft/man3/pthread_setaffinity_np.3 @@ -0,0 +1,181 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" 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. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH PTHREAD_SETAFFINITY_NP 3 2010\-09\-10 Linux "Linux Programmer's Manual" +.SH 名前 +pthread_setaffinity_np, pthread_getaffinity_np \- スレッドの +CPU affinity の設定/取得を行う +.SH 書式 +.nf +\fB#define _GNU_SOURCE\fP /* See feature_test_macros(7) */ +\fB#include \fP + +\fBint pthread_setaffinity_np(pthread_t \fP\fIthread\fP\fB, size_t \fP\fIcpusetsize\fP\fB,\fP +\fB const cpu_set_t *\fP\fIcpuset\fP\fB);\fP +\fBint pthread_getaffinity_np(pthread_t \fP\fIthread\fP\fB, size_t \fP\fIcpusetsize\fP\fB,\fP +\fB cpu_set_t *\fP\fIcpuset\fP\fB);\fP +.sp +\fI\-pthread\fP でコンパイルしてリンクする。 +.fi +.SH 説明 +\fBpthread_setaffinity_np\fP() 関数は、スレッド \fIthread\fP の CPU affinity +マスクに \fIcpuset\fP が指す CPU 集合を設定する。呼び出しが成功し、 +そのスレッドが現在 \fIcpuset\fP で指定された CPU 上でが実行されていない +場合は、スレッドは指定された CPU のいずれかに移動される。 + +\fBpthread_getaffinity_np\fP() 関数は、スレッド \fIthread\fP の CPU affinity +マスクを、\fIcpuset\fP が指すバッファに入れて返す。 + +CPU affinity マスクの詳細については、 +\fBsched_setaffinity\fP(2) を参照してほしい。 +CPU 集合の操作や取得を行う際に利用できるマクロ群の説明は +\fBCPU_SET\fP(3) を参照してほしい。 + +引き数 \fIcpusetsize\fP は \fIcpuset\fP が指すバッファの長さ (バイト単位) で +ある。通常は、この引き数には \fIsizeof(cpu_set_t)\fP を指定する +(\fBCPU_SET\fP(3) に書かれているマクロを使って CPU 集合を動的に +割り当てている場合には、別の値になることもある)。 +.SH 返り値 +成功すると、これらの関数は 0 を返す。 +エラーの場合、0 以外のエラー番号を返す。 +.SH エラー +.TP +\fBEFAULT\fP +指定されたメモリアドレスが無効である。 +.TP +\fBEINVAL\fP +(\fBpthread_setaffinity_np\fP()) affinity ビットマスク \fImask\fP に、 +その時点でシステム上に物理的に存在して、かつそのスレッドに対して許可 +されているプロセッサが一つも含まれていない。 +スレッドに対してどのプロセッサの利用が許可されるかは、\fBcpuset\fP(7) で +説明されている "cpuset" 機構に適用される制限に基づいて決まる。 +.TP +\fBEINVAL\fP +.\" FIXME . ? +.\" Loic Domaigne commented: it seems that in the future the +.\" kernel developers want to make cpumask_t dynamic, so +.\" CONFIG_NR_CPUS might become obsolete in the future. +.\" cpumask_t +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +(\fBpthread_setaffinity_np\fP()) \fIcpuset\fP が、カーネルがサポートする CPU +集合に含まれない CPU を指定していた。(カーネルの設定オプション +\fBCONFIG_NR_CPUS\fP により、CPU 集合を表現するのに使われるカーネルの +データ型がサポートする CPU 集合の範囲が定義される。) +.TP +\fBEINVAL\fP +(\fBpthread_getaffinity_np\fP()) \fIcpusetsize\fP がカーネルが使用する +affinity マスクの大きさよりも小さい。 +.TP +\fBESRCH\fP +ID が \fIthread\fP のスレッドが見つからなかった。 +.SH バージョン +これらの関数は glibc バージョン 2.3.4 以降で提供されている。 +.SH 準拠 +これらの関数は非標準の GNU による拡張である。 +そのため、名前に "_np" (nonportable; 移植性がない) という接尾辞が +付いている。 +.SH 注意 +\fBpthread_setaffinity_np\fP() を呼び出した後、 +そのスレッドが実際に実行される CPU 集合は、 +\fIcpuset\fP 引き数で指定された集合と +システムに実際に存在する CPU 集合の共通部分になる。 +また、 \fBcpuset\fP(7) で説明されている "cpuset" 機構が使われている場合 +には、そのスレッドが実行される CPU 集合がシステムによってさらに制限 +される場合がある。そのスレッドが実行される実際の CPU 集合に対する +これらの制限は、カーネルにより黙って適用される。 + +これらの関数は、システムコール \fBsched_setaffinity\fP(2) と +\fBsched_getaffinity\fP(2) を使って実装されている。 + +(このバージョンだけであるが) glibc 2.3.3 では、 +これらの関数は \fIcpusetsize\fP 引き数を持っていなかった。 +内部で呼ばれるシステムコールに渡される CPU セットの大きさは +常に \fIsizeof(cpu_set_t)\fP であった。 + +\fBpthread_create\fP(3) で作成される新しいスレッドは、 +作成者の CPU affinity マスクを継承する。 +.SH 例 +以下のプログラムでは、メインスレッドは +\fBpthread_setaffinity_np\fP() を使って自分の CPU affinity マスクに +CPU 0 から 7 が含まれるように設定し +(システム上には 0 から 7 に対応する CPU が全て存在するとは限らない)、 +その後で \fBpthread_getaffinity_np\fP() を使って +スレッドに実際に設定された CPU affinity マスクを確認している。 + +.nf +#define _GNU_SOURCE +#include +#include +#include +#include + +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + int s, j; + cpu_set_t cpuset; + pthread_t thread; + + thread = pthread_self(); + + /* Set affinity mask to include CPUs 0 to 7 */ + + CPU_ZERO(&cpuset); + for (j = 0; j < 8; j++) + CPU_SET(j, &cpuset); + + s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset); + if (s != 0) + handle_error_en(s, "pthread_setaffinity_np"); + + /* Check the actual affinity mask assigned to the thread */ + + s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset); + if (s != 0) + handle_error_en(s, "pthread_getaffinity_np"); + + printf("Set returned by pthread_getaffinity_np() contained:\en"); + for (j = 0; j < CPU_SETSIZE; j++) + if (CPU_ISSET(j, &cpuset)) + printf(" CPU %d\en", j); + + exit(EXIT_SUCCESS); +} +.fi +.SH 関連項目 +\fBsched_setaffinity\fP(2), \fBsched_setscheduler\fP(2), +\fBpthread_attr_setaffinity_np\fP(3), \fBpthread_self\fP(3), \fBsched_getcpu\fP(3), +\fBcpuset\fP(7), \fBpthreads\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/draft/man7/pthreads.7 b/draft/man7/pthreads.7 index f4bad4b6..5ac84e11 100644 --- a/draft/man7/pthreads.7 +++ b/draft/man7/pthreads.7 @@ -611,7 +611,8 @@ Linux では、Pthreads API を用いたプログラムは \fIcc \-pthread\fP これまで、2つのスレッドの実装が Linux の GNU C ライブラリにより 提供されてきた。 .TP \fBLinuxThreads\fP -最初の Pthreads の実装。 glibc 2.4 以降は、この実装はもはやサポートされていない。 +最初の Pthreads の実装。 +glibc 2.4 以降は、この実装はもはやサポートされていない。 .TP \fBNPTL\fP (Native POSIX Threads Library) 新しい Pthreads の実装。LinuxThreads と比べると、 NPTL は POSIX.1 の要求仕様への準拠の度合いが高く、 @@ -760,3 +761,7 @@ bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e \fBpthread_setcancelstate\fP(3), \fBpthread_setcanceltype\fP(3), \fBpthread_setspecific\fP(3), \fBpthread_sigmask\fP(3), \fBpthread_sigqueue\fP(3), and \fBpthread_testcancel\fP(3) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 -- 2.11.0