.\" Copyright (C) 2006 Michael Kerrisk
.\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2013  Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>
.\" 
.TH CPU_SET 3 2012\-03\-15 Linux "Linux Programmer's Manual"
.SH 名前
CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR,
CPU_EQUAL, CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, CPU_SET_S, CPU_CLR_S,
CPU_ISSET_S, CPU_ZERO_S, CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S,
CPU_EQUAL_S \- CPU 集合を操作するためのマクロ
.SH 書式
.nf
\fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
\fB#include <sched.h>\fP
.sp
\fBvoid CPU_ZERO(cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBvoid CPU_SET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
\fBvoid CPU_CLR(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
\fBint  CPU_ISSET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBint  CPU_COUNT(cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBvoid CPU_AND(cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
\fBvoid CPU_OR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
\fBvoid CPU_XOR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
.sp
\fBint  CPU_EQUAL(cpu_set_t *\fP\fIset1\fP\fB, cpu_set_t *\fP\fIset2\fP\fB);\fP
.sp
\fBcpu_set_t *CPU_ALLOC(int \fP\fInum_cpus\fP\fB);\fP
\fBvoid CPU_FREE(cpu_set_t *\fP\fIset\fP\fB);\fP
\fBsize_t CPU_ALLOC_SIZE(int \fP\fInum_cpus\fP\fB);\fP
.sp
\fBvoid CPU_ZERO_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBvoid CPU_SET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
\fBvoid CPU_CLR_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
\fBint  CPU_ISSET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBint  CPU_COUNT_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
.sp
\fBvoid CPU_AND_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
\fBvoid CPU_OR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
\fBvoid CPU_XOR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
\fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
.sp
\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
.fi
.SH 説明
\fIcpu_set_t\fP データ構造体は CPU 集合を表現している。 CPU 集合は \fBsched_setaffinity\fP(2)
や同様のインタフェースで使用されている。

\fIcpu_set_t\fP データ型はビット集合として実装されている。 しかし、 データ構造体はその実装を意識せずに扱うものとされており、 CPU
集合のすべての操作は、 このページで説明されているマクロを通して行うべきである。

以下のマクロが CPU 集合 \fIset\fP を操作するために提供されている。
.TP  17
\fBCPU_ZERO\fP()
\fIset\fP をクリアする。 集合には何も CPU が含まれない状態となる。
.TP 
\fBCPU_SET\fP()
\fIset\fP に \fIcpu\fP を追加する。
.TP 
\fBCPU_CLR\fP()
\fIset\fP から \fIcpu\fP を削除する。
.TP 
\fBCPU_ISSET\fP()
CPU \fIcpu\fP が \fIset\fP のメンバーであるかを検査する。
.TP 
\fBCPU_COUNT\fP()
\fIset\fP に含まれる CPU 数を返す。
.PP
\fIcpu\fP 引き数が指定する場合、 その引き数は副作用を伴うべきではない。 上記のマクロは引き数を複数回評価する可能性があるからである。
.PP
そのシステムで利用可能な最初の CPU が \fIcpu\fP 値 0 に対応し、 次の CPU が \fIcpu\fP 値 1 に対応し、 以降も同様である。
定数 \fBCPU_SETSIZE\fP (現在のところ 1024) は \fIcpu_set_t\fP に格納できる最大 CPU 数よりも大きな値である。

以下のマクロは CPU 集合どうしの論理操作を行う。
.TP  17
\fBCPU_AND\fP()
集合 \fIsrcset1\fP と \fIsrcset2\fP の積集合を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
として使用される場合もある)。
.TP 
\fBCPU_OR\fP()
集合 \fIsrcset1\fP と \fIsrcset2\fP の和集合を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
として使用される場合もある)。
.TP 
\fBCPU_XOR\fP()
集合 \fIsrcset1\fP と \fIsrcset2\fP の XOR を \fIdestset\fP に格納する (元の集合のいずれかが \fIdestset\fP
として使用される場合もある)。 XOR とは、 \fIsrcset1\fP か \fIsrcset2\fP
のいずれかに含まれるが、両方には含まれない集合のことである。
.TP 
\fBCPU_EQUAL\fP()
二つの CPU 集合が全く同じ CPU を含んでいるかを検査する。
.SS "動的に大きさが決まる CPU 集合"
いくつかのアプリケーションでは CPU 集合の大きさを動的に決める能力 (例えば、 標準の \fIcpu_set_t\fP
データ型で定義されたよりも大きい集合を割り当てるなど) が必要となることがあるため、 現在 glibc
はこれに対応するためにいくつかのマクロを提供している。

以下のマクロを使うと CPU 集合の割り当てと解放ができる。
.TP  17
\fBCPU_ALLOC\fP()
0 から \fInum_cpus\-1\fP までの範囲の CPU を保持するのに十分な大きさの CPU 集合を割り当てる。
.TP 
\fBCPU_ALLOC_SIZE\fP()
0 から \fInum_cpus\-1\fP までの範囲の CPU を保持するのに必要な CPU 集合の大きさをバイト数で返す。 このマクロが返す値は、 後述の
\fBCPU_*_S\fP() マクロの \fIsetsize\fP 引き数として使用できる。
.TP 
\fBCPU_FREE\fP()
以前に \fBCPU_ALLOC\fP() で割り当てられた CPU 集合を解放する。
.PP
名前が "_S" で終わるマクロは "_S" なしの同じ名前のマクロと同等である。 これらのマクロは "_S" なしのものと同じ動作をするが、
動的に割り当てられた、 大きさが \fIsetsize\fP バイトの CPU 集合に対して操作を行う点が異なる。
.SH 返り値
\fBCPU_ISSET\fP() と \fBCPU_ISSET_S\fP() は、 \fIcpu\fP が \fIset\fP に含まれていれば 0
以外を返し、含まれない場合 0 を返す。

\fBCPU_COUNT\fP() と \fBCPU_COUNT_S\fP() は \fIset\fP に含まれる CPU 数を返す。

\fBCPU_EQUAL\fP() と \fBCPU_EQUAL_S\fP() は、 二つの CPU 集合が等しければ 0 以外を返し、 等しくない場合 0
を返す。

\fBCPU_ALLOC\fP() は成功するとポインタを返し、 失敗すると NULL を返す (エラーは \fBmalloc\fP(3) と同じである)。

\fBCPU_ALLOC_SIZE\fP() は指定された大きさの CPU 集合を格納するのに必要なバイト数を返す。

他の関数は値を返さない。
.SH バージョン
マクロ \fBCPU_ZERO\fP(), \fBCPU_SET\fP(), \fBCPU_CLR\fP(), \fBCPU_ISSET\fP() は glibc 2.3.3
で追加された。

\fBCPU_COUNT\fP() は glibc 2.6 で初めて登場した。

\fBCPU_AND\fP(), \fBCPU_OR\fP(), \fBCPU_XOR\fP(), \fBCPU_EQUAL\fP(), \fBCPU_ALLOC\fP(),
\fBCPU_ALLOC_SIZE\fP(), \fBCPU_FREE\fP(), \fBCPU_ZERO_S\fP(), \fBCPU_SET_S\fP(),
\fBCPU_CLR_S\fP(), \fBCPU_ISSET_S\fP(), \fBCPU_AND_S\fP(), \fBCPU_OR_S\fP(),
\fBCPU_XOR_S\fP(), \fBCPU_EQUAL_S\fP() は glibc 2.7 で初めて登場した。
.SH 準拠
これらのインタフェースは Linux 固有である。
.SH 注意
CPU 集合を複製するには、 \fBmemcpy\fP(3) を使用する。

CPU 集合はロングワード単位に割り当てられるビット集合なので、 動的に割り当てられた CPU 集合の実際の CPU 数は
\fIsizeof(unsigned long)\fP の次の倍数に切り上げられることになる。 アプリケーションは、
これらの余分なビットの内容は不定と考えるべきである。

名前は似ているが、 定数 \fBCPU_SETSIZE\fP は \fIcpu_set_t\fP データ型に含まれる CPU 数
(つまり、事実上ビット集合内のビットカウント) を示すのに対して、 マクロ \fBCPU_*_S\fP() の \fIsetsize\fP
引き数はバイト単位のサイズである点に注意すること。

「書式」に書かれている引き数と返り値のデータ型は、それぞれの場合でどんな型が期待されるかのヒントである。 しかしながら、
これらのインタフェースはマクロとして実装されているため、 このヒントを守らなかった場合に、 コンパイラが必ずしも全ての型エラーを捕捉できるとは限らない。
.SH バグ
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
glibc 2.8 以前の 32 ビットプラットフォームでは、 \fBCPU_ALLOC\fP() は必要な空間の割り当てを二度行い、
\fBCPU_ALLOC_SIZE\fP() は本来あるべき値の二倍の値を返す。 このバグはプログラムの動作には影響を与えないはずだが、
無駄にメモリを消費し、 動的に割り当てられた CPU 集合に対して操作を行うマクロの動作の効率が下がる結果となる。 これらのバグは glibc 2.9
で修正された。
.SH 例
以下のプログラムは、動的に割り当てた CPU 集合に対していくつかのマクロを使用する例を示している。

.nf
#define _GNU_SOURCE
#include <sched.h>
#include <stdlib.h>
#include <unistd.h>
#include <stdio.h>
#include <assert.h>

int
main(int argc, char *argv[])
{
    cpu_set_t *cpusetp;
    size_t size;
    int num_cpus, cpu;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
        exit(EXIT_FAILURE);
    }

    num_cpus = atoi(argv[1]);

    cpusetp = CPU_ALLOC(num_cpus);
    if (cpusetp == NULL) {
        perror("CPU_ALLOC");
        exit(EXIT_FAILURE);
    }

    size = CPU_ALLOC_SIZE(num_cpus);

    CPU_ZERO_S(size, cpusetp);
    for (cpu = 0; cpu < num_cpus; cpu += 2)
        CPU_SET_S(cpu, size, cpusetp);

    printf("CPU_COUNT() of set:    %d\en", CPU_COUNT_S(size, cpusetp));

    CPU_FREE(cpusetp);
    exit(EXIT_SUCCESS);
}
.fi
.SH 関連項目
\fBsched_setaffinity\fP(2), \fBpthread_attr_setaffinity_np\fP(3),
\fBpthread_setaffinity_np\fP(3), \fBcpuset\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。