release/man3/CPU_SET.3

   1 .\" Copyright (C) 2006 Michael Kerrisk
   2 .\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\"*******************************************************************
  28 .\"
  29 .\" This file was generated with po4a. Translate the source file.
  30 .\"
  31 .\"*******************************************************************
  32 .\"
  33 .\" Japanese Version Copyright (c) 2013  Akihiro MOTOKI
  34 .\"         all rights reserved.
  35 .\" Translated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>
  36 .\"
  37 .TH CPU_SET 3 2012\-03\-15 Linux "Linux Programmer's Manual"
  38 .SH 名前
  39 CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR,
  40 CPU_EQUAL, CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, CPU_SET_S, CPU_CLR_S,
  41 CPU_ISSET_S, CPU_ZERO_S, CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S,
  42 CPU_EQUAL_S \- CPU 集合を操作するためのマクロ
  43 .SH 書式
  44 .nf
  45 \fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
  46 \fB#include <sched.h>\fP
  47 .sp
  48 \fBvoid CPU_ZERO(cpu_set_t *\fP\fIset\fP\fB);\fP
  49 .sp
  50 \fBvoid CPU_SET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  51 \fBvoid CPU_CLR(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  52 \fBint  CPU_ISSET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  53 .sp
  54 \fBint  CPU_COUNT(cpu_set_t *\fP\fIset\fP\fB);\fP
  55 .sp
  56 \fBvoid CPU_AND(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  57 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  58 \fBvoid CPU_OR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  59 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  60 \fBvoid CPU_XOR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  61 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  62 .sp
  63 \fBint  CPU_EQUAL(cpu_set_t *\fP\fIset1\fP\fB, cpu_set_t *\fP\fIset2\fP\fB);\fP
  64 .sp
  65 \fBcpu_set_t *CPU_ALLOC(int \fP\fInum_cpus\fP\fB);\fP
  66 \fBvoid CPU_FREE(cpu_set_t *\fP\fIset\fP\fB);\fP
  67 \fBsize_t CPU_ALLOC_SIZE(int \fP\fInum_cpus\fP\fB);\fP
  68 .sp
  69 \fBvoid CPU_ZERO_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  70 .sp
  71 \fBvoid CPU_SET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  72 \fBvoid CPU_CLR_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  73 \fBint  CPU_ISSET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  74 .sp
  75 \fBint  CPU_COUNT_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  76 .sp
  77 \fBvoid CPU_AND_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  78 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  79 \fBvoid CPU_OR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  80 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  81 \fBvoid CPU_XOR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  82 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  83 .sp
  84 \fBint  CPU_EQUAL_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset1\fP\fB, cpu_set_t *\fP\fIset2\fP\fB);\fP
  85 .fi
  86 .SH 説明
  87 \fIcpu_set_t\fP データ構造体は CPU 集合を表現している。 CPU 集合は \fBsched_setaffinity\fP(2)
  88 や同様のインタフェースで使用されている。
  89
  90 \fIcpu_set_t\fP データ型はビット集合として実装されている。 しかし、 データ構造体はその実装を意識せずに扱うものとされており、 CPU
  91 集合のすべての操作は、 このページで説明されているマクロを通して行うべきである。
  92
  93 以下のマクロが CPU 集合 \fIset\fP を操作するために提供されている。
  94 .TP  17
  95 \fBCPU_ZERO\fP()
  96 \fIset\fP をクリアする。 集合には何も CPU が含まれない状態となる。
  97 .TP
  98 \fBCPU_SET\fP()
  99 \fIset\fP に \fIcpu\fP を追加する。
 100 .TP
 101 \fBCPU_CLR\fP()
 102 \fIset\fP から \fIcpu\fP を削除する。
 103 .TP
 104 \fBCPU_ISSET\fP()
 105 CPU \fIcpu\fP が \fIset\fP のメンバーであるかを検査する。
 106 .TP
 107 \fBCPU_COUNT\fP()
 108 \fIset\fP に含まれる CPU 数を返す。
 109 .PP
 110 \fIcpu\fP 引き数が指定する場合、 その引き数は副作用を伴うべきではない。 上記のマクロは引き数を複数回評価する可能性があるからである。
 111 .PP
 112 そのシステムで利用可能な最初の CPU が \fIcpu\fP 値 0 に対応し、 次の CPU が \fIcpu\fP 値 1 に対応し、 以降も同様である。
 113 定数 \fBCPU_SETSIZE\fP (現在のところ 1024) は \fIcpu_set_t\fP に格納できる最大 CPU 数よりも大きな値である。
 114
 115 以下のマクロは CPU 集合どうしの論理操作を行う。
 116 .TP  17
 117 \fBCPU_AND\fP()
 118 集合 \fIsrcset1\fP と \fIsrcset2\fP の積集合を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
 119 として使用される場合もある)。
 120 .TP
 121 \fBCPU_OR\fP()
 122 集合 \fIsrcset1\fP と \fIsrcset2\fP の和集合を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
 123 として使用される場合もある)。
 124 .TP
 125 \fBCPU_XOR\fP()
 126 集合 \fIsrcset1\fP と \fIsrcset2\fP の XOR を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
 127 として使用される場合もある)。 XOR とは、 \fIsrcset1\fP か \fIsrcset2\fP
 128 のいずれかに含まれるが、両方には含まれない集合のことである。
 129 .TP
 130 \fBCPU_EQUAL\fP()
 131 二つの CPU 集合が全く同じ CPU を含んでいるかを検査する。
 132 .SS "動的に大きさが決まる CPU 集合"
 133 いくつかのアプリケーションでは CPU 集合の大きさを動的に決める能力 (例えば、 標準の \fIcpu_set_t\fP
 134 データ型で定義されたよりも大きい集合を割り当てるなど) が必要となることがあるため、 現在 glibc
 135 はこれに対応するためにいくつかのマクロを提供している。
 136
 137 以下のマクロを使うと CPU 集合の割り当てと解放ができる。
 138 .TP  17
 139 \fBCPU_ALLOC\fP()
 140 0 から \fInum_cpus\-1\fP までの範囲の CPU を保持するのに十分な大きさの CPU 集合を割り当てる。
 141 .TP
 142 \fBCPU_ALLOC_SIZE\fP()
 143 0 から \fInum_cpus\-1\fP までの範囲の CPU を保持するのに必要な CPU 集合の大きさをバイト数で返す。 このマクロが返す値は、 後述の
 144 \fBCPU_*_S\fP() マクロの \fIsetsize\fP 引き数として使用できる。
 145 .TP
 146 \fBCPU_FREE\fP()
 147 以前に \fBCPU_ALLOC\fP() で割り当てられた CPU 集合を解放する。
 148 .PP
 149 名前が "_S" で終わるマクロは "_S" なしの同じ名前のマクロと同等である。 これらのマクロは "_S" なしのものと同じ動作をするが、
 150 動的に割り当てられた、 大きさが \fIsetsize\fP バイトの CPU 集合に対して操作を行う点が異なる。
 151 .SH 返り値
 152 \fBCPU_ISSET\fP() と \fBCPU_ISSET_S\fP() は、 \fIcpu\fP が \fIset\fP に含まれていれば 0
 153 以外を返し、含まれない場合 0 を返す。
 154
 155 \fBCPU_COUNT\fP() と \fBCPU_COUNT_S\fP() は \fIset\fP に含まれる CPU 数を返す。
 156
 157 \fBCPU_EQUAL\fP() と \fBCPU_EQUAL_S\fP() は、 二つの CPU 集合が等しければ 0 以外を返し、 等しくない場合 0
 158 を返す。
 159
 160 \fBCPU_ALLOC\fP() は成功するとポインタを返し、 失敗すると NULL を返す (エラーは \fBmalloc\fP(3) と同じである)。
 161
 162 \fBCPU_ALLOC_SIZE\fP() は指定された大きさの CPU 集合を格納するのに必要なバイト数を返す。
 163
 164 他の関数は値を返さない。
 165 .SH バージョン
 166 マクロ \fBCPU_ZERO\fP(), \fBCPU_SET\fP(), \fBCPU_CLR\fP(), \fBCPU_ISSET\fP() は glibc 2.3.3
 167 で追加された。
 168
 169 \fBCPU_COUNT\fP() は glibc 2.6 で初めて登場した。
 170
 171 \fBCPU_AND\fP(), \fBCPU_OR\fP(), \fBCPU_XOR\fP(), \fBCPU_EQUAL\fP(), \fBCPU_ALLOC\fP(),
 172 \fBCPU_ALLOC_SIZE\fP(), \fBCPU_FREE\fP(), \fBCPU_ZERO_S\fP(), \fBCPU_SET_S\fP(),
 173 \fBCPU_CLR_S\fP(), \fBCPU_ISSET_S\fP(), \fBCPU_AND_S\fP(), \fBCPU_OR_S\fP(),
 174 \fBCPU_XOR_S\fP(), \fBCPU_EQUAL_S\fP() は glibc 2.7 で初めて登場した。
 175 .SH 準拠
 176 これらのインタフェースは Linux 固有である。
 177 .SH 注意
 178 CPU 集合を複製するには、 \fBmemcpy\fP(3) を使用する。
 179
 180 CPU 集合はロングワード単位に割り当てられるビット集合なので、 動的に割り当てられた CPU 集合の実際の CPU 数は
 181 \fIsizeof(unsigned long)\fP の次の倍数に切り上げられることになる。 アプリケーションは、
 182 これらの余分なビットの内容は不定と考えるべきである。
 183
 184 名前は似ているが、 定数 \fBCPU_SETSIZE\fP は \fIcpu_set_t\fP データ型に含まれる CPU 数
 185 (つまり、事実上ビット集合内のビットカウント) を示すのに対して、 マクロ \fBCPU_*_S\fP() の \fIsetsize\fP
 186 引き数はバイト単位のサイズである点に注意すること。
 187
 188 「書式」に書かれている引き数と返り値のデータ型は、それぞれの場合でどんな型が期待されるかのヒントである。 しかしながら、
 189 これらのインタフェースはマクロとして実装されているため、 このヒントを守らなかった場合に、 コンパイラが必ずしも全ての型エラーを捕捉できるとは限らない。
 190 .SH バグ
 191 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
 192 glibc 2.8 以前の 32 ビットプラットフォームでは、 \fBCPU_ALLOC\fP() は必要な空間の割り当てを二度行い、
 193 \fBCPU_ALLOC_SIZE\fP() は本来あるべき値の二倍の値を返す。 このバグはプログラムの動作には影響を与えないはずだが、
 194 無駄にメモリを消費し、 動的に割り当てられた CPU 集合に対して操作を行うマクロの動作の効率が下がる結果となる。 これらのバグは glibc 2.9
 195 で修正された。
 196 .SH 例
 197 以下のプログラムは、動的に割り当てた CPU 集合に対していくつかのマクロを使用する例を示している。
 198
 199 .nf
 200 #define _GNU_SOURCE
 201 #include <sched.h>
 202 #include <stdlib.h>
 203 #include <unistd.h>
 204 #include <stdio.h>
 205 #include <assert.h>
 206
 207 int
 208 main(int argc, char *argv[])
 209 {
 210     cpu_set_t *cpusetp;
 211     size_t size;
 212     int num_cpus, cpu;
 213
 214     if (argc < 2) {
 215         fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
 216         exit(EXIT_FAILURE);
 217     }
 218
 219     num_cpus = atoi(argv[1]);
 220
 221     cpusetp = CPU_ALLOC(num_cpus);
 222     if (cpusetp == NULL) {
 223         perror("CPU_ALLOC");
 224         exit(EXIT_FAILURE);
 225     }
 226
 227     size = CPU_ALLOC_SIZE(num_cpus);
 228
 229     CPU_ZERO_S(size, cpusetp);
 230     for (cpu = 0; cpu < num_cpus; cpu += 2)
 231         CPU_SET_S(cpu, size, cpusetp);
 232
 233     printf("CPU_COUNT() of set:    %d\en", CPU_COUNT_S(size, cpusetp));
 234
 235     CPU_FREE(cpusetp);
 236     exit(EXIT_SUCCESS);
 237 }
 238 .fi
 239 .SH 関連項目
 240 \fBsched_setaffinity\fP(2), \fBpthread_attr_setaffinity_np\fP(3),
 241 \fBpthread_setaffinity_np\fP(3), \fBcpuset\fP(7)
 242 .SH この文書について
 243 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.67 の一部
 244 である。プロジェクトの説明とバグ報告に関する情報は
 245 http://www.kernel.org/doc/man\-pages/ に書かれている。