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