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