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 2019-03-06 "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 .PP
  40 .BI "void CPU_ZERO(cpu_set_t *" set );
  41 .PP
  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 .PP
  46 .BI "int  CPU_COUNT(cpu_set_t *" set );
  47 .PP
  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 .PP
  55 .BI "int  CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 );
  56 .PP
  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 .PP
  61 .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set );
  62 .PP
  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 .PP
  67 .BI "int  CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set );
  68 .PP
  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 .PP
  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 .PP
  87 The
  88 .I cpu_set_t
  89 data type is implemented as a bit mask.
  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 .PP
  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 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 No assumptions should be made about particular CPUs being
 135 available, or the set of CPUs being contiguous, since CPUs can
 136 be taken offline dynamically or be otherwise absent.
 137 The constant
 138 .B CPU_SETSIZE
 139 (currently 1024) specifies a value one greater than the maximum CPU
 140 number that can be stored in
 141 .IR cpu_set_t .
 142 .PP
 143 The following macros perform logical operations on CPU sets:
 144 .TP 17
 145 .BR CPU_AND ()
 146 Store the intersection of the sets
 147 .I srcset1
 148 and
 149 .I srcset2
 150 in
 151 .I destset
 152 (which may be one of the source sets).
 153 .TP
 154 .BR CPU_OR ()
 155 Store the union of the sets
 156 .I srcset1
 157 and
 158 .I srcset2
 159 in
 160 .I destset
 161 (which may be one of the source sets).
 162 .TP
 163 .BR CPU_XOR ()
 164 Store the XOR of the sets
 165 .I srcset1
 166 and
 167 .I srcset2
 168 in
 169 .I destset
 170 (which may be one of the source sets).
 171 The XOR means the set of CPUs that are in either
 172 .I srcset1
 173 or
 174 .IR srcset2 ,
 175 but not both.
 176 .TP
 177 .BR CPU_EQUAL ()
 178 Test whether two CPU set contain exactly the same CPUs.
 179 .SS Dynamically sized CPU sets
 180 Because some applications may require the ability to dynamically
 181 size CPU sets (e.g., to allocate sets larger than that
 182 defined by the standard
 183 .I cpu_set_t
 184 data type), glibc nowadays provides a set of macros to support this.
 185 .PP
 186 The following macros are used to allocate and deallocate CPU sets:
 187 .TP 17
 188 .BR CPU_ALLOC ()
 189 Allocate a CPU set large enough to hold CPUs
 190 in the range 0 to
 191 .IR num_cpus-1 .
 192 .TP
 193 .BR CPU_ALLOC_SIZE ()
 194 Return the size in bytes of the CPU set that would be needed to
 195 hold CPUs in the range 0 to
 196 .IR num_cpus-1 .
 197 This macro provides the value that can be used for the
 198 .I setsize
 199 argument in the
 200 .BR CPU_*_S ()
 201 macros described below.
 202 .TP
 203 .BR CPU_FREE ()
 204 Free a CPU set previously allocated by
 205 .BR CPU_ALLOC ().
 206 .PP
 207 The macros whose names end with "_S" are the analogs of
 208 the similarly named macros without the suffix.
 209 These macros perform the same tasks as their analogs,
 210 but operate on the dynamically allocated CPU set(s) whose size is
 211 .I setsize
 212 bytes.
 213 .SH RETURN VALUE
 214 .BR CPU_ISSET ()
 215 and
 216 .BR CPU_ISSET_S ()
 217 return nonzero if
 218 .I cpu
 219 is in
 220 .IR set ;
 221 otherwise, it returns 0.
 222 .PP
 223 .BR CPU_COUNT ()
 224 and
 225 .BR CPU_COUNT_S ()
 226 return the number of CPUs in
 227 .IR set .
 228 .PP
 229 .BR CPU_EQUAL ()
 230 and
 231 .BR CPU_EQUAL_S ()
 232 return nonzero if the two CPU sets are equal; otherwise they return 0.
 233 .PP
 234 .BR CPU_ALLOC ()
 235 returns a pointer on success, or NULL on failure.
 236 (Errors are as for
 237 .BR malloc (3).)
 238 .PP
 239 .BR CPU_ALLOC_SIZE ()
 240 returns the number of bytes required to store a
 241 CPU set of the specified cardinality.
 242 .PP
 243 The other functions do not return a value.
 244 .SH VERSIONS
 245 The
 246 .BR CPU_ZERO (),
 247 .BR CPU_SET (),
 248 .BR CPU_CLR (),
 249 and
 250 .BR CPU_ISSET ()
 251 macros were added in glibc 2.3.3.
 252 .PP
 253 .BR CPU_COUNT ()
 254 first appeared in glibc 2.6.
 255 .PP
 256 .BR CPU_AND (),
 257 .BR CPU_OR (),
 258 .BR CPU_XOR (),
 259 .BR CPU_EQUAL (),
 260 .BR CPU_ALLOC (),
 261 .BR CPU_ALLOC_SIZE (),
 262 .BR CPU_FREE (),
 263 .BR CPU_ZERO_S (),
 264 .BR CPU_SET_S (),
 265 .BR CPU_CLR_S (),
 266 .BR CPU_ISSET_S (),
 267 .BR CPU_AND_S (),
 268 .BR CPU_OR_S (),
 269 .BR CPU_XOR_S (),
 270 and
 271 .BR CPU_EQUAL_S ()
 272 first appeared in glibc 2.7.
 273 .SH CONFORMING TO
 274 These interfaces are Linux-specific.
 275 .SH NOTES
 276 To duplicate a CPU set, use
 277 .BR memcpy (3).
 278 .PP
 279 Since CPU sets are bit masks allocated in units of long words,
 280 the actual number of CPUs in a dynamically
 281 allocated CPU set will be rounded up to the next multiple of
 282 .IR "sizeof(unsigned long)" .
 283 An application should consider the contents of these extra bits
 284 to be undefined.
 285 .PP
 286 Notwithstanding the similarity in the names,
 287 note that the constant
 288 .B CPU_SETSIZE
 289 indicates the number of CPUs in the
 290 .I cpu_set_t
 291 data type (thus, it is effectively a count of the bits in the bit mask),
 292 while the
 293 .I setsize
 294 argument of the
 295 .BR CPU_*_S ()
 296 macros is a size in bytes.
 297 .PP
 298 The data types for arguments and return values shown
 299 in the SYNOPSIS are hints what about is expected in each case.
 300 However, since these interfaces are implemented as macros,
 301 the compiler won't necessarily catch all type errors
 302 if you violate the suggestions.
 303 .SH BUGS
 304 On 32-bit platforms with glibc 2.8 and earlier,
 305 .BR CPU_ALLOC ()
 306 allocates twice as much space as is required, and
 307 .BR CPU_ALLOC_SIZE ()
 308 returns a value twice as large as it should.
 309 This bug should not affect the semantics of a program,
 310 but does result in wasted memory
 311 and less efficient operation of the macros that
 312 operate on dynamically allocated CPU sets.
 313 These bugs are fixed in glibc 2.9.
 314 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
 315 .SH EXAMPLE
 316 The following program demonstrates the use of some of the macros
 317 used for dynamically allocated CPU sets.
 318 .PP
 319 .EX
 320 #define _GNU_SOURCE
 321 #include <sched.h>
 322 #include <stdlib.h>
 323 #include <unistd.h>
 324 #include <stdio.h>
 325 #include <assert.h>
 326
 327 int
 328 main(int argc, char *argv[])
 329 {
 330     cpu_set_t *cpusetp;
 331     size_t size;
 332     int num_cpus, cpu;
 333
 334     if (argc < 2) {
 335         fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
 336         exit(EXIT_FAILURE);
 337     }
 338
 339     num_cpus = atoi(argv[1]);
 340
 341     cpusetp = CPU_ALLOC(num_cpus);
 342     if (cpusetp == NULL) {
 343         perror("CPU_ALLOC");
 344         exit(EXIT_FAILURE);
 345     }
 346
 347     size = CPU_ALLOC_SIZE(num_cpus);
 348
 349     CPU_ZERO_S(size, cpusetp);
 350     for (cpu = 0; cpu < num_cpus; cpu += 2)
 351         CPU_SET_S(cpu, size, cpusetp);
 352
 353     printf("CPU_COUNT() of set:    %d\en", CPU_COUNT_S(size, cpusetp));
 354
 355     CPU_FREE(cpusetp);
 356     exit(EXIT_SUCCESS);
 357 }
 358 .EE
 359 .SH SEE ALSO
 360 .BR sched_setaffinity (2),
 361 .BR pthread_attr_setaffinity_np (3),
 362 .BR pthread_setaffinity_np (3),
 363 .BR cpuset (7)