draft/man3/pthread_attr_init.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
  33 .\"         all rights reserved.
  34 .\" Translated 2012-05-03, Akihiro MOTOKI <amotoki@gmail.com>
  35 .\"
  36 .TH PTHREAD_ATTR_INIT 3 2008\-11\-11 Linux "Linux Programmer's Manual"
  37 .SH 名前
  38 pthread_attr_init, pthread_attr_destroy \-
  39 スレッド属性オブジェクトの初期化と破棄を行う
  40 .SH 書式
  41 .nf
  42 \fB#include <pthread.h>\fP
  43
  44 \fBint pthread_attr_init(pthread_attr_t *\fP\fIattr\fP\fB);\fP
  45 \fBint pthread_attr_destroy(pthread_attr_t *\fP\fIattr\fP\fB);\fP
  46 .sp
  47 \fI\-pthread\fP でコンパイルしてリンクする。
  48 .fi
  49 .SH 説明
  50 \fBpthread_attr_init\fP() 関数は \fIattr\fP が指すスレッド属性オブジェクト
  51 (thread attributes object) をデフォルトの属性値で初期化する。
  52 この呼び出しの後、オブジェクトの各属性は (関連項目に載っている) 種々の
  53 関数を使って設定することができ、このオブジェクトはスレッドの作成を行う
  54 \fBpthread_create\fP(3) の呼び出しにおいて使用することができる (一つの
  55 オブジェクトを複数の \fBpthread_create\fP(3) に渡してもよい)。
  56
  57 すでに初期化されているスレッド属性オブジェクトに対して
  58 \fBpthread_attr_init\fP() を呼び出した場合、
  59 どのような動作になるかは不定である。
  60
  61 スレッド属性オブジェクトがもはや必要なくなった際には、
  62 そのオブジェクトは \fBpthread_attr_destroy\fP() 関数を使って破棄すべきである。
  63 スレッド属性オブジェクトを破棄しても、
  64 そのオブジェクトを使って作成されたスレッドには影響はない。
  65
  66 いったん破棄したスレッド属性オブジェクトは、
  67 \fBpthread_attr_init\fP() を使って再初期化することができる。
  68 破棄したスレッド属性オブジェクトをこれ以外の用途で
  69 使った場合の結果は不定である。
  70 .SH 返り値
  71 成功すると、これらの関数は 0 を返す。
  72 エラーの場合、0 以外のエラー番号を返す。
  73 .SH エラー
  74 POSIX.1\-2001 では \fBpthread_attr_init\fP() にはエラー \fBENOMEM\fP が
  75 記載されている。
  76 Linux では、これらの関数は常に成功する
  77 (ただし、移植性や将来も動作することを保証したいアプリケーションでは
  78 正のエラーの返り値を処理するようにすべきである)。
  79 .SH 準拠
  80 POSIX.1\-2001.
  81 .SH 注意
  82 \fIpthread_attr_t\fP 型の内部構造は意識すべきではない。
  83 pthreads 関数経由以外でのオブジェクトへのアクセスは移植性がなく、
  84 どのような結果が得られるかも分からない。
  85 .SH 例
  86 下記のプログラムは、\fBpthread_attr_init\fP() と種々の関連関数を使って、
  87 スレッド属性オブジェクトの初期化を行い、
  88 そのオブジェクトを使ってスレッドを一つ作成する。
  89 作成されたスレッドは、作成後に \fBpthread_getattr_np\fP(3) 関数
  90 (非標準の GNU 拡張) を使ってスレッドの属性を取得し、
  91 取得した属性を表示する。
  92
  93 コマンドライン引き数なしでプログラムを実行した場合、
  94 \fBpthread_create\fP(3) の \fIattr\fP 引き数には NULL が渡される。
  95 この場合、スレッドはデフォルトの属性で作成される。
  96 このプログラムを NPTL スレッド実装が使われている Linux/x86\-32 で
  97 動作させると、以下のような出力が得られる。
  98
  99 .in +4n
 100 .nf
 101 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 102 $\fB ulimit \-s\fP       # No stack imit ==> default stack size is 2MB
 103 unlimited
 104 $\fB ./a.out\fP
 105 Thread attributes:
 106         Detach state        = PTHREAD_CREATE_JOINABLE
 107         Scope               = PTHREAD_SCOPE_SYSTEM
 108         Inherit scheduler   = PTHREAD_INHERIT_SCHED
 109         Scheduling policy   = SCHED_OTHER
 110         Scheduling priority = 0
 111         Guard size          = 4096 bytes
 112         Stack address       = 0x40196000
 113         Stack size          = 0x201000 bytes
 114 .fi
 115 .in
 116
 117 コマンドライン引き数でスタックサイズが与えられた場合、
 118 このプログラムは、スレッド属性オブジェクトを初期化し、
 119 そのオブジェクトの各種属性を設定し、
 120 \fBpthread_create\fP(3) の呼び出しでこのオブジェクトへのポインタを渡す。
 121 このプログラムを NPTL スレッド実装が使われている Linux/x86\-32 で
 122 動作させると、以下のような出力が得られる。
 123
 124 .in +4n
 125 .nf
 126 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 127 $\fB ./a.out 0x3000000\fP
 128 posix_memalign() allocated at 0x40197000
 129 Thread attributes:
 130         Detach state        = PTHREAD_CREATE_DETACHED
 131         Scope               = PTHREAD_SCOPE_SYSTEM
 132         Inherit scheduler   = PTHREAD_EXPLICIT_SCHED
 133         Scheduling policy   = SCHED_OTHER
 134         Scheduling priority = 0
 135         Guard size          = 0 bytes
 136         Stack address       = 0x40197000
 137         Stack size          = 0x3000000 bytes
 138 .fi
 139 .in
 140 .SS プログラムのソース
 141 \&
 142 .nf
 143 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 144 #include <pthread.h>
 145 #include <stdio.h>
 146 #include <stdlib.h>
 147 #include <unistd.h>
 148 #include <errno.h>
 149
 150 #define handle_error_en(en, msg) \e
 151         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 152
 153 static void
 154 display_pthread_attr(pthread_attr_t *attr, char *prefix)
 155 {
 156     int s, i;
 157     size_t v;
 158     void *stkaddr;
 159     struct sched_param sp;
 160
 161     s = pthread_attr_getdetachstate(attr, &i);
 162     if (s != 0)
 163         handle_error_en(s, "pthread_attr_getdetachstate");
 164     printf("%sDetach state        = %s\en", prefix,
 165             (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
 166             (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
 167             "???");
 168
 169     s = pthread_attr_getscope(attr, &i);
 170     if (s != 0)
 171         handle_error_en(s, "pthread_attr_getscope");
 172     printf("%sScope               = %s\en", prefix,
 173             (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :
 174             (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
 175             "???");
 176
 177     s = pthread_attr_getinheritsched(attr, &i);
 178     if (s != 0)
 179         handle_error_en(s, "pthread_attr_getinheritsched");
 180     printf("%sInherit scheduler   = %s\en", prefix,
 181             (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :
 182             (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
 183             "???");
 184
 185     s = pthread_attr_getschedpolicy(attr, &i);
 186     if (s != 0)
 187         handle_error_en(s, "pthread_attr_getschedpolicy");
 188     printf("%sScheduling policy   = %s\en", prefix,
 189             (i == SCHED_OTHER) ? "SCHED_OTHER" :
 190             (i == SCHED_FIFO)  ? "SCHED_FIFO" :
 191             (i == SCHED_RR)    ? "SCHED_RR" :
 192             "???");
 193
 194     s = pthread_attr_getschedparam(attr, &sp);
 195     if (s != 0)
 196         handle_error_en(s, "pthread_attr_getschedparam");
 197     printf("%sScheduling priority = %d\en", prefix, sp.sched_priority);
 198
 199     s = pthread_attr_getguardsize(attr, &v);
 200     if (s != 0)
 201         handle_error_en(s, "pthread_attr_getguardsize");
 202     printf("%sGuard size          = %d bytes\en", prefix, v);
 203
 204     s = pthread_attr_getstack(attr, &stkaddr, &v);
 205     if (s != 0)
 206         handle_error_en(s, "pthread_attr_getstack");
 207     printf("%sStack address       = %p\en", prefix, stkaddr);
 208     printf("%sStack size          = 0x%x bytes\en", prefix, v);
 209 }
 210
 211 static void *
 212 thread_start(void *arg)
 213 {
 214     int s;
 215     pthread_attr_t gattr;
 216
 217     /* pthread_getattr_np() is a non\-standard GNU extension that
 218        retrieves the attributes of the thread specified in its
 219        first argument */
 220
 221     s = pthread_getattr_np(pthread_self(), &gattr);
 222     if (s != 0)
 223         handle_error_en(s, "pthread_getattr_np");
 224
 225     printf("Thread attributes:\en");
 226     display_pthread_attr(&gattr, "\et");
 227
 228     exit(EXIT_SUCCESS);         /* Terminate all threads */
 229 }
 230
 231 int
 232 main(int argc, char *argv[])
 233 {
 234     pthread_t thr;
 235     pthread_attr_t attr;
 236     pthread_attr_t *attrp;      /* NULL or &attr */
 237     int s;
 238
 239     attrp = NULL;
 240
 241     /* If a command\-line argument was supplied, use it to set the
 242        stack\-size attribute and set a few other thread attributes,
 243        and set attrp pointing to thread attributes object */
 244
 245     if (argc > 1) {
 246         int stack_size;
 247         void *sp;
 248
 249         attrp = &attr;
 250
 251         s = pthread_attr_init(&attr);
 252         if (s != 0)
 253             handle_error_en(s, "pthread_attr_init");
 254
 255         s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
 256         if (s != 0)
 257             handle_error_en(s, "pthread_attr_setdetachstate");
 258
 259         s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
 260         if (s != 0)
 261             handle_error_en(s, "pthread_attr_setinheritsched");
 262
 263         stack_size = strtoul(argv[1], NULL, 0);
 264
 265         s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
 266         if (s != 0)
 267             handle_error_en(s, "posix_memalign");
 268
 269         printf("posix_memalign() allocated at %p\en", sp);
 270
 271         s = pthread_attr_setstack(&attr, sp, stack_size);
 272         if (s != 0)
 273             handle_error_en(s, "pthread_attr_setstack");
 274     }
 275
 276     s = pthread_create(&thr, attrp, &thread_start, NULL);
 277     if (s != 0)
 278         handle_error_en(s, "pthread_create");
 279
 280     if (attrp != NULL) {
 281         s = pthread_attr_destroy(attrp);
 282         if (s != 0)
 283             handle_error_en(s, "pthread_attr_destroy");
 284     }
 285
 286     pause();    /* Terminates when other thread calls exit() */
 287 }
 288 .fi
 289 .SH 関連項目
 290 .ad l
 291 .nh
 292 \fBpthread_attr_setaffinity_np\fP(3), \fBpthread_attr_setdetachstate\fP(3),
 293 \fBpthread_attr_setguardsize\fP(3), \fBpthread_attr_setinheritsched\fP(3),
 294 \fBpthread_attr_setschedparam\fP(3), \fBpthread_attr_setschedpolicy\fP(3),
 295 \fBpthread_attr_setscope\fP(3), \fBpthread_attr_setstack\fP(3),
 296 \fBpthread_attr_setstackaddr\fP(3), \fBpthread_attr_setstacksize\fP(3),
 297 \fBpthread_create\fP(3), \fBpthread_getattr_np\fP(3), \fBpthreads\fP(7)
 298 .SH この文書について
 299 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 300 である。プロジェクトの説明とバグ報告に関する情報は
 301 http://www.kernel.org/doc/man\-pages/ に書かれている。