original/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 .TH CPU_SET 3 2012-03-15 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT,
  30 CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL,
  31 CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE,
  32 CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S,
  33 CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \-
  34 macros for manipulating CPU sets
  35 .SH SYNOPSIS
  36 .nf
  37 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  38 .B #include <sched.h>
  39 .sp
  40 .BI "void CPU_ZERO(cpu_set_t *" set );
  41 .sp
  42 .BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
  43 .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
  44 .BI "int  CPU_ISSET(int " cpu ", cpu_set_t *" set );
  45 .sp
  46 .BI "int  CPU_COUNT(cpu_set_t *" set );
  47 .sp
  48 .BI "void CPU_AND(cpu_set_t *" destset ,
  49 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  50 .BI "void CPU_OR(cpu_set_t *" destset ,
  51 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  52 .BI "void CPU_XOR(cpu_set_t *" destset ,
  53 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  54 .sp
  55 .BI "int  CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 );
  56 .sp
  57 .BI "cpu_set_t *CPU_ALLOC(int " num_cpus );
  58 .BI "void CPU_FREE(cpu_set_t *" set );
  59 .BI "size_t CPU_ALLOC_SIZE(int " num_cpus );
  60 .sp
  61 .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set );
  62 .sp
  63 .BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
  64 .BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
  65 .BI "int  CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
  66 .sp
  67 .BI "int  CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set );
  68 .sp
  69 .BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset ,
  70 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  71 .BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset ,
  72 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  73 .BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset ,
  74 .BI "             cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
  75 .sp
  76 .BI "int  CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \
  77 ", cpu_set_t *" set2 );
  78 .fi
  79 .SH DESCRIPTION
  80 The
  81 .I cpu_set_t
  82 data structure represents a set of CPUs.
  83 CPU sets are used by
  84 .BR sched_setaffinity (2)
  85 and similar interfaces.
  86
  87 The
  88 .I cpu_set_t
  89 data type is implemented as a bitset.
  90 However, the data structure treated as considered opaque:
  91 all manipulation of CPU sets should be done via the macros
  92 described in this page.
  93
  94 The following macros are provided to operate on the CPU set
  95 .IR set :
  96 .TP 17
  97 .BR CPU_ZERO ()
  98 Clears
  99 .IR set ,
 100 so that it contains no CPUs.
 101 .TP
 102 .BR CPU_SET ()
 103 Add CPU
 104 .I cpu
 105 to
 106 .IR set .
 107 .TP
 108 .BR CPU_CLR ()
 109 Remove CPU
 110 .I cpu
 111 from
 112 .IR set .
 113 .TP
 114 .BR CPU_ISSET ()
 115 Test to see if CPU
 116 .I cpu
 117 is a member of
 118 .IR set .
 119 .TP
 120 .BR CPU_COUNT ()
 121 Return the number of CPUs in
 122 .IR set .
 123 .PP
 124 Where a
 125 .I cpu
 126 argument is specified, it should not produce side effects,
 127 since the above macros may evaluate the argument more than once.
 128 .PP
 129 The first available CPU on the system corresponds to a
 130 .I cpu
 131 value of 0, the next CPU corresponds to a
 132 .I cpu
 133 value of 1, and so on.
 134 The constant
 135 .B CPU_SETSIZE
 136 (currently 1024) specifies a value one greater than the maximum CPU
 137 number that can be stored in
 138 .IR cpu_set_t .
 139
 140 The following macros perform logical operations on CPU sets:
 141 .TP 17
 142 .BR CPU_AND ()
 143 Store the intersection of the sets
 144 .I srcset1
 145 and
 146 .I srcset2
 147 in
 148 .I destset
 149 (which may be one of the source sets).
 150 .TP
 151 .BR CPU_OR ()
 152 Store the union of the sets
 153 .I srcset1
 154 and
 155 .I srcset2
 156 in
 157 .I destset
 158 (which may be one of the source sets).
 159 .TP
 160 .BR CPU_XOR ()
 161 Store the XOR of the sets
 162 .I srcset1
 163 and
 164 .I srcset2
 165 in
 166 .I destset
 167 (which may be one of the source sets).
 168 The XOR means the set of CPUs that are in either
 169 .I srcset1
 170 or
 171 .IR srcset2 ,
 172 but not both.
 173 .TP
 174 .BR CPU_EQUAL ()
 175 Test whether two CPU set contain exactly the same CPUs.
 176 .SS Dynamically sized CPU sets
 177 Because some applications may require the ability to dynamically
 178 size CPU sets (e.g., to allocate sets larger than that
 179 defined by the standard
 180 .I cpu_set_t
 181 data type), glibc nowadays provides a set of macros to support this.
 182
 183 The following macros are used to allocate and deallocate CPU sets:
 184 .TP 17
 185 .BR CPU_ALLOC ()
 186 Allocate a CPU set large enough to hold CPUs
 187 in the range 0 to
 188 .IR num_cpus-1 .
 189 .TP
 190 .BR CPU_ALLOC_SIZE ()
 191 Return the size in bytes of the CPU set that would be needed to
 192 hold CPUs in the range 0 to
 193 .IR num_cpus-1 .
 194 This macro provides the value that can be used for the
 195 .I setsize
 196 argument in the
 197 .BR CPU_*_S ()
 198 macros described below.
 199 .TP
 200 .BR CPU_FREE ()
 201 Free a CPU set previously allocated by
 202 .BR CPU_ALLOC ().
 203 .PP
 204 The macros whose names end with "_S" are the analogs of
 205 the similarly named macros without the suffix.
 206 These macros perform the same tasks as their analogs,
 207 but operate on the dynamically allocated CPU set(s) whose size is
 208 .I setsize
 209 bytes.
 210 .SH RETURN VALUE
 211 .BR CPU_ISSET ()
 212 and
 213 .BR CPU_ISSET_S ()
 214 return nonzero if
 215 .I cpu
 216 is in
 217 .IR set ;
 218 otherwise, it returns 0.
 219
 220 .BR CPU_COUNT ()
 221 and
 222 .BR CPU_COUNT_S ()
 223 return the number of CPUs in
 224 .IR set .
 225
 226 .BR CPU_EQUAL ()
 227 and
 228 .BR CPU_EQUAL_S ()
 229 return nonzero if the two CPU sets are equal; otherwise it returns 0.
 230
 231 .BR CPU_ALLOC ()
 232 returns a pointer on success, or NULL on failure.
 233 (Errors are as for
 234 .BR malloc (3).)
 235
 236 .BR CPU_ALLOC_SIZE ()
 237 returns the number of bytes required to store a
 238 CPU set of the specified cardinality.
 239
 240 The other functions do not return a value.
 241 .SH VERSIONS
 242 The
 243 .BR CPU_ZERO (),
 244 .BR CPU_SET (),
 245 .BR CPU_CLR (),
 246 and
 247 .BR CPU_ISSET ()
 248 macros were added in glibc 2.3.3.
 249
 250 .BR CPU_COUNT ()
 251 first appeared in glibc 2.6.
 252
 253 .BR CPU_AND (),
 254 .BR CPU_OR (),
 255 .BR CPU_XOR (),
 256 .BR CPU_EQUAL (),
 257 .BR CPU_ALLOC (),
 258 .BR CPU_ALLOC_SIZE (),
 259 .BR CPU_FREE (),
 260 .BR CPU_ZERO_S (),
 261 .BR CPU_SET_S (),
 262 .BR CPU_CLR_S (),
 263 .BR CPU_ISSET_S (),
 264 .BR CPU_AND_S (),
 265 .BR CPU_OR_S (),
 266 .BR CPU_XOR_S (),
 267 and
 268 .BR CPU_EQUAL_S ()
 269 first appeared in glibc 2.7.
 270 .SH CONFORMING TO
 271 These interfaces are Linux-specific.
 272 .SH NOTES
 273 To duplicate a CPU set, use
 274 .BR memcpy (3).
 275
 276 Since CPU sets are bitsets allocated in units of long words,
 277 the actual number of CPUs in a dynamically
 278 allocated CPU set will be rounded up to the next multiple of
 279 .IR "sizeof(unsigned long)" .
 280 An application should consider the contents of these extra bits
 281 to be undefined.
 282
 283 Notwithstanding the similarity in the names,
 284 note that the constant
 285 .B CPU_SETSIZE
 286 indicates the number of CPUs in the
 287 .I cpu_set_t
 288 data type (thus, it is effectively a count of bits in the bitset),
 289 while the
 290 .I setsize
 291 argument of the
 292 .BR CPU_*_S ()
 293 macros is a size in bytes.
 294
 295 The data types for arguments and return values shown
 296 in the SYNOPSIS are hints what about is expected in each case.
 297 However, since these interfaces are implemented as macros,
 298 the compiler won't necessarily catch all type errors
 299 if you violate the suggestions.
 300 .SH BUGS
 301 On 32-bit platforms with glibc 2.8 and earlier,
 302 .BR CPU_ALLOC ()
 303 allocates twice as much space as is required, and
 304 .BR CPU_ALLOC_SIZE ()
 305 returns a value twice as large as it should.
 306 This bug should not affect the semantics of a program,
 307 but does result in wasted memory
 308 and less efficient operation of the macros that
 309 operate on dynamically allocated CPU sets.
 310 These bugs are fixed in glibc 2.9.
 311 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
 312 .SH EXAMPLE
 313 The following program demonstrates the use of some of the macros
 314 used for dynamically allocated CPU sets.
 315
 316 .nf
 317 #define _GNU_SOURCE
 318 #include <sched.h>
 319 #include <stdlib.h>
 320 #include <unistd.h>
 321 #include <stdio.h>
 322 #include <assert.h>
 323
 324 int
 325 main(int argc, char *argv[])
 326 {
 327     cpu_set_t *cpusetp;
 328     size_t size;
 329     int num_cpus, cpu;
 330
 331     if (argc < 2) {
 332         fprintf(stderr, "Usage: %s <num\-cpus>\\n", argv[0]);
 333         exit(EXIT_FAILURE);
 334     }
 335
 336     num_cpus = atoi(argv[1]);
 337
 338     cpusetp = CPU_ALLOC(num_cpus);
 339     if (cpusetp == NULL) {
 340         perror("CPU_ALLOC");
 341         exit(EXIT_FAILURE);
 342     }
 343
 344     size = CPU_ALLOC_SIZE(num_cpus);
 345
 346     CPU_ZERO_S(size, cpusetp);
 347     for (cpu = 0; cpu < num_cpus; cpu += 2)
 348         CPU_SET_S(cpu, size, cpusetp);
 349
 350     printf("CPU_COUNT() of set:    %d\\n", CPU_COUNT_S(size, cpusetp));
 351
 352     CPU_FREE(cpusetp);
 353     exit(EXIT_SUCCESS);
 354 }
 355 .fi
 356 .SH SEE ALSO
 357 .BR sched_setaffinity (2),
 358 .BR pthread_attr_setaffinity_np (3),
 359 .BR pthread_setaffinity_np (3),
 360 .BR cpuset (7)
 361 .SH COLOPHON
 362 This page is part of release 3.64 of the Linux
 363 .I man-pages
 364 project.
 365 A description of the project,
 366 and information about reporting bugs,
 367 can be found at
 368 \%http://www.kernel.org/doc/man\-pages/.