draft/man3/pthread_getattr_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" This file was generated with po4a. Translate the source file.
  27 .\"
  28 .\"*******************************************************************
  29 .TH PTHREAD_GETATTR_NP 3 2010\-09\-10 Linux "Linux Programmer's Manual"
  30 .SH 名前
  31 pthread_getattr_np \- 作成されたスレッドの属性を取得する
  32 .SH 書式
  33 .nf
  34 \fB#define _GNU_SOURCE\fP             /* See feature_test_macros(7) */
  35 \fB#include <pthread.h>\fP
  36
  37 \fBint pthread_getattr_np(pthread_t \fP\fIthread\fP\fB, pthread_attr_t *\fP\fIattr\fP\fB);\fP
  38 .sp
  39 \fI\-pthread\fP でコンパイルしてリンクする。
  40 .fi
  41 .SH 説明
  42 \fBpthread_getattr_np\fP() 関数は、
  43 \fIattr\fP が参照するスレッド属性オブジェクトを初期化し、
  44 そのオブジェクトに実行中のスレッド \fIthread\fP の実際の属性値を
  45 格納して返す。
  46
  47 返される属性値は、\fBpthread_create\fP(3) でスレッドを作成する際に
  48 使われた\fIattr\fP オブジェクトで渡された属性値と異なる場合がある。
  49 特に、以下の属性は異なる場合がある。
  50 .IP * 2
  51 detach state. join 可能なスレッドは作成後に自分自身を
  52 切り離す (detach する) ことができるからである。
  53 .IP *
  54 スタックサイズ。
  55 スレッドの実装によって適切な境界に揃えられる可能があるためである。
  56 .IP *
  57 guard size.
  58 スレッドの実装によりページサイズの倍数に切り上げられたり、
  59 アプリケーションが自分でスタックを割り当てる場合には無視される
  60 (0 として扱われる) ことがあるからである。
  61 .PP
  62 さらに、スレッドを作成する際に使用されたスレッド属性オブジェクトで
  63 スタックアドレスが設定されていなかった場合、
  64 返されたスレッド属性オブジェクトではスレッドの実装がそのスレッドに
  65 割り当てた実際のスタックアドレスが報告される。
  66
  67 \fBpthread_getattr_np\fP() が返したスレッド属性オブジェクトが
  68 必要なくなった際には、  \fBpthread_attr_destroy\fP(3) を使って
  69 そのオブジェクトを破棄すべきである。
  70 .SH 返り値
  71 成功すると、この関数は 0 を返す。
  72 エラーの場合、 0 以外のエラー番号を返す。
  73 .SH エラー
  74 .TP
  75 \fBENOMEM\fP
  76 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
  77 メモリが十分になかった。
  78 .PP
  79 さらに、 \fIthread\fP がメインスレッドを参照している場合には、
  80 \fBpthread_getattr_np\fP() は内部で行われる様々な呼び出しでの
  81 エラーで失敗する可能性がある。
  82 \fI/proc/self/maps\fP がオープンできない場合には \fBfopen\fP(3)
  83 でエラーが発生し、リソース上限 \fBRLIMIT_STACK\fP が
  84 サポートされていない場合には \fBgetrlimit\fP(2) でエラーが発生する。
  85 .SH バージョン
  86 この関数は glibc バージョン 2.2.3 以降で利用できる。
  87 .SH 準拠
  88 この関数は非標準の GNU による拡張である。
  89 そのため、名前に "_np" (nonportable; 移植性がない) という接尾辞が
  90 付いている。
  91 .SH 例
  92 以下のプログラムは \fBpthread_getattr_np\fP() の使用例を示したものである。
  93 このプログラムは、スレッドを作成し、それから
  94 \fBpthread_getattr_np\fP() を使ってそのスレッドの属性 guard size、
  95 スタックアドレス、スタックサイズを取得し表示する。
  96 コマンドライン引き数での指定で、スレッドを作成する際に
  97 上記の属性にデフォルト値以外の値を設定することができる。
  98 下記のシェルのセッションはこのプログラムの使用例である。
  99
 100 最初の実行例は、デフォルトの属性でスレッドが作成されている
 101 (x86\-32 システム上で実行)。
 102
 103 .in +4n
 104 .nf
 105 $\fB ulimit \-s\fP      # No stack limit ==> default stack size is 2MB
 106 unlimited
 107 $\fB ./a.out\fP
 108 Attributes of created thread:
 109         Guard size          = 4096 bytes
 110         Stack address       = 0x40196000 (EOS = 0x40397000)
 111         Stack size          = 0x201000 (2101248) bytes
 112 .fi
 113 .in
 114
 115 次の実行例では、guard size が指定された場合、
 116 guard size はシステムのページサイズの倍数に切り上げられることが分かる
 117 (x86\-32 ではシステムのページサイズは 4096 バイトである)。
 118
 119 .in +4n
 120 .nf
 121 $\fB ./a.out \-g 4097\fP
 122 Thread attributes object after initializations:
 123         Guard size          = 4097 bytes
 124         Stack address       = (nil)
 125         Stack size          = 0x0 (0) bytes
 126
 127 Attributes of created thread:
 128         Guard size          = 8192 bytes
 129         Stack address       = 0x40196000 (EOS = 0x40397000)
 130         Stack size          = 0x201000 (2101248) bytes
 131 .fi
 132 .in
 133
 134 .\".in +4n
 135 .\".nf
 136 .\"$ ./a.out \-s 0x8000
 137 .\"Thread attributes object after initializations:
 138 .\"        Guard size          = 4096 bytes
 139 .\"        Stack address       = 0xffff8000 (EOS = (nil))
 140 .\"        Stack size          = 0x8000 (32768) bytes
 141 .\"
 142 .\"Attributes of created thread:
 143 .\"        Guard size          = 4096 bytes
 144 .\"        Stack address       = 0x4001e000 (EOS = 0x40026000)
 145 .\"        Stack size          = 0x8000 (32768) bytes
 146 .\".fi
 147 .\".in
 148 最後の実行例では、プログラムでスレッド用のスタックを手動で割り当てている。
 149 この場合には、guard size 属性は無視される。
 150
 151 .in +4n
 152 .nf
 153 $\fB ./a.out \-g 4096 \-s 0x8000 \-a\fP
 154 Allocated thread stack at 0x804d000
 155
 156 Thread attributes object after initializations:
 157         Guard size          = 4096 bytes
 158         Stack address       = 0x804d000 (EOS = 0x8055000)
 159         Stack size          = 0x8000 (32768) bytes
 160
 161 Attributes of created thread:
 162         Guard size          = 0 bytes
 163         Stack address       = 0x804d000 (EOS = 0x8055000)
 164         Stack size          = 0x8000 (32768) bytes
 165 .fi
 166 .in
 167 .SS プログラムのソース
 168 \&
 169 .nf
 170 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 171 #include <pthread.h>
 172 #include <stdio.h>
 173 #include <stdlib.h>
 174 #include <unistd.h>
 175 #include <errno.h>
 176
 177 #define handle_error_en(en, msg) \e
 178         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 179
 180 static void
 181 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
 182 {
 183     int s;
 184     size_t stack_size, guard_size;
 185     void *stack_addr;
 186
 187     s = pthread_attr_getguardsize(attr, &guard_size);
 188     if (s != 0)
 189         handle_error_en(s, "pthread_attr_getguardsize");
 190     printf("%sGuard size          = %d bytes\en", prefix, guard_size);
 191
 192     s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
 193     if (s != 0)
 194         handle_error_en(s, "pthread_attr_getstack");
 195     printf("%sStack address       = %p", prefix, stack_addr);
 196     if (stack_size > 0)
 197         printf(" (EOS = %p)", (char *) stack_addr + stack_size);
 198     printf("\en");
 199     printf("%sStack size          = 0x%x (%d) bytes\en",
 200             prefix, stack_size, stack_size);
 201 }
 202
 203 static void
 204 display_thread_attributes(pthread_t thread, char *prefix)
 205 {
 206     int s;
 207     pthread_attr_t attr;
 208
 209     s = pthread_getattr_np(thread, &attr);
 210     if (s != 0)
 211         handle_error_en(s, "pthread_getattr_np");
 212
 213     display_stack_related_attributes(&attr, prefix);
 214
 215     s = pthread_attr_destroy(&attr);
 216     if (s != 0)
 217         handle_error_en(s, "pthread_attr_destroy");
 218 }
 219
 220 static void *           /* Start function for thread we create */
 221 thread_start(void *arg)
 222 {
 223     printf("Attributes of created thread:\en");
 224     display_thread_attributes(pthread_self(), "\et");
 225
 226     exit(EXIT_SUCCESS);         /* Terminate all threads */
 227 }
 228
 229 static void
 230 usage(char *pname, char *msg)
 231 {
 232     if (msg != NULL)
 233         fputs(msg, stderr);
 234     fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]"
 235             " [\-g guard\-size]\en", pname);
 236     fprintf(stderr, "\et\et\-a means program should allocate stack\en");
 237     exit(EXIT_FAILURE);
 238 }
 239
 240 static pthread_attr_t *   /* Get thread attributes from command line */
 241 get_thread_attributes_from_cl(int argc, char *argv[],
 242                               pthread_attr_t *attrp)
 243 {
 244     int s, opt, allocate_stack;
 245     long stack_size, guard_size;
 246             void *stack_addr;
 247     pthread_attr_t *ret_attrp = NULL;   /* Set to attrp if we initialize
 248                                            a thread attributes object */
 249     allocate_stack = 0;
 250     stack_size = \-1;
 251     guard_size = \-1;
 252
 253     while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
 254         switch (opt) {
 255         case \(aqa\(aq:   allocate_stack = 1;                     break;
 256         case \(aqg\(aq:   guard_size = strtoul(optarg, NULL, 0);  break;
 257         case \(aqs\(aq:   stack_size = strtoul(optarg, NULL, 0);  break;
 258         default:    usage(argv[0], NULL);
 259         }
 260     }
 261
 262     if (allocate_stack && stack_size == \-1)
 263         usage(argv[0], "Specifying \-a without \-s makes no sense\en");
 264
 265     if (argc > optind)
 266         usage(argv[0], "Extraneous command\-line arguments\en");
 267
 268     if (stack_size >= 0 || guard_size > 0) {
 269         ret_attrp = attrp;
 270
 271         s = pthread_attr_init(attrp);
 272         if (s != 0)
 273             handle_error_en(s, "pthread_attr_init");
 274     }
 275
 276     if (stack_size >= 0) {
 277         if (!allocate_stack) {
 278             s = pthread_attr_setstacksize(attrp, stack_size);
 279             if (s != 0)
 280                 handle_error_en(s, "pthread_attr_setstacksize");
 281         } else {
 282             s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
 283                                stack_size);
 284             if (s != 0)
 285                 handle_error_en(s, "posix_memalign");
 286             printf("Allocated thread stack at %p\en\en", stack_addr);
 287
 288             s = pthread_attr_setstack(attrp, stack_addr, stack_size);
 289             if (s != 0)
 290                 handle_error_en(s, "pthread_attr_setstacksize");
 291         }
 292     }
 293
 294     if (guard_size >= 0) {
 295         s = pthread_attr_setguardsize(attrp, guard_size);
 296         if (s != 0)
 297             handle_error_en(s, "pthread_attr_setstacksize");
 298     }
 299
 300     return ret_attrp;
 301 }
 302
 303 int
 304 main(int argc, char *argv[])
 305 {
 306     int s;
 307     pthread_t thr;
 308     pthread_attr_t attr;
 309     pthread_attr_t *attrp = NULL;    /* Set to &attr if we initialize
 310                                         a thread attributes object */
 311
 312     attrp = get_thread_attributes_from_cl(argc, argv, &attr);
 313
 314     if (attrp != NULL) {
 315         printf("Thread attributes object after initializations:\en");
 316         display_stack_related_attributes(attrp, "\et");
 317         printf("\en");
 318     }
 319
 320     s = pthread_create(&thr, attrp, &thread_start, NULL);
 321     if (s != 0)
 322         handle_error_en(s, "pthread_create");
 323
 324     if (attrp != NULL) {
 325         s = pthread_attr_destroy(attrp);
 326         if (s != 0)
 327             handle_error_en(s, "pthread_attr_destroy");
 328     }
 329
 330     pause();    /* Terminates when other thread calls exit() */
 331 }
 332 .fi
 333 .SH 関連項目
 334 \fBpthread_attr_getaffinity_np\fP(3), \fBpthread_attr_getdetachstate\fP(3),
 335 \fBpthread_attr_getguardsize\fP(3), \fBpthread_attr_getinheritsched\fP(3),
 336 \fBpthread_attr_getschedparam\fP(3), \fBpthread_attr_getschedpolicy\fP(3),
 337 \fBpthread_attr_getscope\fP(3), \fBpthread_attr_getstack\fP(3),
 338 \fBpthread_attr_getstackaddr\fP(3), \fBpthread_attr_getstacksize\fP(3),
 339 \fBpthread_attr_init\fP(3), \fBpthread_create\fP(3), \fBpthreads\fP(7)
 340 .SH この文書について
 341 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.41 の一部
 342 である。プロジェクトの説明とバグ報告に関する情報は
 343 http://www.kernel.org/doc/man\-pages/ に書かれている。