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