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 .TH CPU_SET 3 2012\-03\-15 Linux "Linux Programmer's Manual"
  33 .SH 名前
  34 CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR,
  35 CPU_EQUAL, CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, CPU_SET_S, CPU_CLR_S,
  36 CPU_ISSET_S, CPU_ZERO_S, CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S,
  37 CPU_EQUAL_S \- macros for manipulating CPU sets
  38 .SH 書式
  39 .nf
  40 \fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
  41 \fB#include <sched.h>\fP
  42 .sp
  43 \fBvoid CPU_ZERO(cpu_set_t *\fP\fIset\fP\fB);\fP
  44 .sp
  45 \fBvoid CPU_SET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  46 \fBvoid CPU_CLR(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  47 \fBint  CPU_ISSET(int \fP\fIcpu\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  48 .sp
  49 \fBint  CPU_COUNT(cpu_set_t *\fP\fIset\fP\fB);\fP
  50 .sp
  51 \fBvoid CPU_AND(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  52 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  53 \fBvoid CPU_OR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  54 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  55 \fBvoid CPU_XOR(cpu_set_t *\fP\fIdestset\fP\fB,\fP
  56 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  57 .sp
  58 \fBint  CPU_EQUAL(cpu_set_t *\fP\fIset1\fP\fB, cpu_set_t *\fP\fIset2\fP\fB);\fP
  59 .sp
  60 \fBcpu_set_t *CPU_ALLOC(int \fP\fInum_cpus\fP\fB);\fP
  61 \fBvoid CPU_FREE(cpu_set_t *\fP\fIset\fP\fB);\fP
  62 \fBsize_t CPU_ALLOC_SIZE(int \fP\fInum_cpus\fP\fB);\fP
  63 .sp
  64 \fBvoid CPU_ZERO_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  65 .sp
  66 \fBvoid CPU_SET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  67 \fBvoid CPU_CLR_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  68 \fBint  CPU_ISSET_S(int \fP\fIcpu\fP\fB, size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  69 .sp
  70 \fBint  CPU_COUNT_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIset\fP\fB);\fP
  71 .sp
  72 \fBvoid CPU_AND_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  73 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  74 \fBvoid CPU_OR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  75 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  76 \fBvoid CPU_XOR_S(size_t \fP\fIsetsize\fP\fB, cpu_set_t *\fP\fIdestset\fP\fB,\fP
  77 \fB             cpu_set_t *\fP\fIsrcset1\fP\fB, cpu_set_t *\fP\fIsrcset2\fP\fB);\fP
  78 .sp
  79 \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
  80 .fi
  81 .SH 説明
  82 The \fIcpu_set_t\fP data structure represents a set of CPUs.  CPU sets are used
  83 by \fBsched_setaffinity\fP(2)  and similar interfaces.
  84
  85 The \fIcpu_set_t\fP data type is implemented as a bitset.  However, the data
  86 structure treated as considered opaque: all manipulation of CPU sets should
  87 be done via the macros described in this page.
  88
  89 The following macros are provided to operate on the CPU set \fIset\fP:
  90 .TP  17
  91 \fBCPU_ZERO\fP()
  92 Clears \fIset\fP, so that it contains no CPUs.
  93 .TP
  94 \fBCPU_SET\fP()
  95 Add CPU \fIcpu\fP to \fIset\fP.
  96 .TP
  97 \fBCPU_CLR\fP()
  98 Remove CPU \fIcpu\fP from \fIset\fP.
  99 .TP
 100 \fBCPU_ISSET\fP()
 101 Test to see if CPU \fIcpu\fP is a member of \fIset\fP.
 102 .TP
 103 \fBCPU_COUNT\fP()
 104 Return the number of CPUs in \fIset\fP.
 105 .PP
 106 Where a \fIcpu\fP argument is specified, it should not produce side effects,
 107 since the above macros may evaluate the argument more than once.
 108 .PP
 109 The first available CPU on the system corresponds to a \fIcpu\fP value of 0,
 110 the next CPU corresponds to a \fIcpu\fP value of 1, and so on.  The constant
 111 \fBCPU_SETSIZE\fP (currently 1024) specifies a value one greater than the
 112 maximum CPU number that can be stored in \fIcpu_set_t\fP.
 113
 114 The following macros perform logical operations on CPU sets:
 115 .TP  17
 116 \fBCPU_AND\fP()
 117 Store the intersection of the sets \fIsrcset1\fP and \fIsrcset2\fP in \fIdestset\fP
 118 (which may be one of the source sets).
 119 .TP
 120 \fBCPU_OR\fP()
 121 Store the union of the sets \fIsrcset1\fP and \fIsrcset2\fP in \fIdestset\fP (which
 122 may be one of the source sets).
 123 .TP
 124 \fBCPU_XOR\fP()
 125 Store the XOR of the sets \fIsrcset1\fP and \fIsrcset2\fP in \fIdestset\fP (which may
 126 be one of the source sets).  The XOR means the set of CPUs that are in
 127 either \fIsrcset1\fP or \fIsrcset2\fP, but not both.
 128 .TP
 129 \fBCPU_EQUAL\fP()
 130 Test whether two CPU set contain exactly the same CPUs.
 131 .SS "Dynamically sized CPU sets"
 132 Because some applications may require the ability to dynamically size CPU
 133 sets (e.g., to allocate sets larger than that defined by the standard
 134 \fIcpu_set_t\fP data type), glibc nowadays provides a set of macros to support
 135 this.
 136
 137 The following macros are used to allocate and deallocate CPU sets:
 138 .TP  17
 139 \fBCPU_ALLOC\fP()
 140 Allocate a CPU set large enough to hold CPUs in the range 0 to
 141 \fInum_cpus\-1\fP.
 142 .TP
 143 \fBCPU_ALLOC_SIZE\fP()
 144 Return the size in bytes of the CPU set that would be needed to hold CPUs in
 145 the range 0 to \fInum_cpus\-1\fP.  This macro provides the value that can be
 146 used for the \fIsetsize\fP argument in the \fBCPU_*_S\fP()  macros described
 147 below.
 148 .TP
 149 \fBCPU_FREE\fP()
 150 Free a CPU set previously allocated by \fBCPU_ALLOC\fP().
 151 .PP
 152 The macros whose names end with "_S" are the analogs of the similarly named
 153 macros without the suffix.  These macros perform the same tasks as their
 154 analogs, but operate on the dynamically allocated CPU set(s) whose size is
 155 \fIsetsize\fP bytes.
 156 .SH 返り値
 157 \fBCPU_ISSET\fP()  and \fBCPU_ISSET_S\fP()  return nonzero if \fIcpu\fP is in \fIset\fP;
 158 otherwise, it returns 0.
 159
 160 \fBCPU_COUNT\fP()  and \fBCPU_COUNT_S\fP()  return the number of CPUs in \fIset\fP.
 161
 162 \fBCPU_EQUAL\fP()  and \fBCPU_EQUAL_S\fP()  return nonzero if the two CPU sets are
 163 equal; otherwise it returns 0.
 164
 165 \fBCPU_ALLOC\fP()  returns a pointer on success, or NULL on failure.  (Errors
 166 are as for \fBmalloc\fP(3).)
 167
 168 \fBCPU_ALLOC_SIZE\fP()  returns the number of bytes required to store a CPU set
 169 of the specified cardinality.
 170
 171 The other functions do not return a value.
 172 .SH バージョン
 173 The \fBCPU_ZERO\fP(), \fBCPU_SET\fP(), \fBCPU_CLR\fP(), and \fBCPU_ISSET\fP()  macros
 174 were added in glibc 2.3.3.
 175
 176 \fBCPU_COUNT\fP()  first appeared in glibc 2.6.
 177
 178 \fBCPU_AND\fP(), \fBCPU_OR\fP(), \fBCPU_XOR\fP(), \fBCPU_EQUAL\fP(), \fBCPU_ALLOC\fP(),
 179 \fBCPU_ALLOC_SIZE\fP(), \fBCPU_FREE\fP(), \fBCPU_ZERO_S\fP(), \fBCPU_SET_S\fP(),
 180 \fBCPU_CLR_S\fP(), \fBCPU_ISSET_S\fP(), \fBCPU_AND_S\fP(), \fBCPU_OR_S\fP(),
 181 \fBCPU_XOR_S\fP(), and \fBCPU_EQUAL_S\fP()  first appeared in glibc 2.7.
 182 .SH 準拠
 183 These interfaces are Linux\-specific.
 184 .SH 注意
 185 To duplicate a CPU set, use \fBmemcpy\fP(3).
 186
 187 Since CPU sets are bitsets allocated in units of long words, the actual
 188 number of CPUs in a dynamically allocated CPU set will be rounded up to the
 189 next multiple of \fIsizeof(unsigned long)\fP.  An application should consider
 190 the contents of these extra bits to be undefined.
 191
 192 Notwithstanding the similarity in the names, note that the constant
 193 \fBCPU_SETSIZE\fP indicates the number of CPUs in the \fIcpu_set_t\fP data type
 194 (thus, it is effectively a count of bits in the bitset), while the
 195 \fIsetsize\fP argument of the \fBCPU_*_S\fP()  macros is a size in bytes.
 196
 197 The data types for arguments and return values shown in the SYNOPSIS are
 198 hints what about is expected in each case.  However, since these interfaces
 199 are implemented as macros, the compiler won't necessarily catch all type
 200 errors if you violate the suggestions.
 201 .SH バグ
 202 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
 203 On 32\-bit platforms with glibc 2.8 and earlier, \fBCPU_ALLOC\fP()  allocates
 204 twice as much space as is required, and \fBCPU_ALLOC_SIZE\fP()  returns a value
 205 twice as large as it should.  This bug should not affect the semantics of a
 206 program, but does result in wasted memory and less efficient operation of
 207 the macros that operate on dynamically allocated CPU sets.  These bugs are
 208 fixed in glibc 2.9.
 209 .SH EXAMPLE
 210 The following program demonstrates the use of some of the macros used for
 211 dynamically allocated CPU sets.
 212
 213 .nf
 214 #define _GNU_SOURCE
 215 #include <sched.h>
 216 #include <stdlib.h>
 217 #include <unistd.h>
 218 #include <stdio.h>
 219 #include <assert.h>
 220
 221 int
 222 main(int argc, char *argv[])
 223 {
 224     cpu_set_t *cpusetp;
 225     size_t size;
 226     int num_cpus, cpu;
 227
 228     if (argc < 2) {
 229         fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
 230         exit(EXIT_FAILURE);
 231     }
 232
 233     num_cpus = atoi(argv[1]);
 234
 235     cpusetp = CPU_ALLOC(num_cpus);
 236     if (cpusetp == NULL) {
 237         perror("CPU_ALLOC");
 238         exit(EXIT_FAILURE);
 239     }
 240
 241     size = CPU_ALLOC_SIZE(num_cpus);
 242
 243     CPU_ZERO_S(size, cpusetp);
 244     for (cpu = 0; cpu < num_cpus; cpu += 2)
 245         CPU_SET_S(cpu, size, cpusetp);
 246
 247     printf("CPU_COUNT() of set:    %d\en", CPU_COUNT_S(size, cpusetp));
 248
 249     CPU_FREE(cpusetp);
 250     exit(EXIT_SUCCESS);
 251 }
 252 .fi
 253 .SH 関連項目
 254 \fBsched_setaffinity\fP(2), \fBpthread_attr_setaffinity_np\fP(3),
 255 \fBpthread_setaffinity_np\fP(3), \fBcpuset\fP(7)
 256 .SH この文書について
 257 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 258 である。プロジェクトの説明とバグ報告に関する情報は
 259 http://www.kernel.org/doc/man\-pages/ に書かれている。