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