1CPU_SET(3)                 Linux Programmer's Manual                CPU_SET(3)
2
3
4

NAME

6       CPU_SET,  CPU_CLR,  CPU_ISSET,  CPU_ZERO,  CPU_COUNT,  CPU_AND, CPU_OR,
7       CPU_XOR, CPU_EQUAL,  CPU_ALLOC,  CPU_ALLOC_SIZE,  CPU_FREE,  CPU_SET_S,
8       CPU_CLR_S,  CPU_ISSET_S,  CPU_ZERO_S, CPU_COUNT_S, CPU_AND_S, CPU_OR_S,
9       CPU_XOR_S, CPU_EQUAL_S - macros for manipulating CPU sets
10

SYNOPSIS

12       #define _GNU_SOURCE             /* See feature_test_macros(7) */
13       #include <sched.h>
14
15       void CPU_ZERO(cpu_set_t *set);
16
17       void CPU_SET(int cpu, cpu_set_t *set);
18       void CPU_CLR(int cpu, cpu_set_t *set);
19       int  CPU_ISSET(int cpu, cpu_set_t *set);
20
21       int  CPU_COUNT(cpu_set_t *set);
22
23       void CPU_AND(cpu_set_t *destset,
24                    cpu_set_t *srcset1, cpu_set_t *srcset2);
25       void CPU_OR(cpu_set_t *destset,
26                    cpu_set_t *srcset1, cpu_set_t *srcset2);
27       void CPU_XOR(cpu_set_t *destset,
28                    cpu_set_t *srcset1, cpu_set_t *srcset2);
29
30       int  CPU_EQUAL(cpu_set_t *set1, cpu_set_t *set2);
31
32       cpu_set_t *CPU_ALLOC(int num_cpus);
33       void CPU_FREE(cpu_set_t *set);
34       size_t CPU_ALLOC_SIZE(int num_cpus);
35
36       void CPU_ZERO_S(size_t setsize, cpu_set_t *set);
37
38       void CPU_SET_S(int cpu, size_t setsize, cpu_set_t *set);
39       void CPU_CLR_S(int cpu, size_t setsize, cpu_set_t *set);
40       int  CPU_ISSET_S(int cpu, size_t setsize, cpu_set_t *set);
41
42       int  CPU_COUNT_S(size_t setsize, cpu_set_t *set);
43
44       void CPU_AND_S(size_t setsize, cpu_set_t *destset,
45                    cpu_set_t *srcset1, cpu_set_t *srcset2);
46       void CPU_OR_S(size_t setsize, cpu_set_t *destset,
47                    cpu_set_t *srcset1, cpu_set_t *srcset2);
48       void CPU_XOR_S(size_t setsize, cpu_set_t *destset,
49                    cpu_set_t *srcset1, cpu_set_t *srcset2);
50
51       int  CPU_EQUAL_S(size_t setsize, cpu_set_t *set1, cpu_set_t *set2);
52

DESCRIPTION

54       The cpu_set_t data structure represents a set of CPUs.   CPU  sets  are
55       used by sched_setaffinity(2) and similar interfaces.
56
57       The  cpu_set_t  data  type  is implemented as a bit mask.  However, the
58       data structure should be treated as opaque:  all  manipulation  of  CPU
59       sets should be done via the macros described in this page.
60
61       The following macros are provided to operate on the CPU set set:
62
63       CPU_ZERO()
64              Clears set, so that it contains no CPUs.
65
66       CPU_SET()
67              Add CPU cpu to set.
68
69       CPU_CLR()
70              Remove CPU cpu from set.
71
72       CPU_ISSET()
73              Test to see if CPU cpu is a member of set.
74
75       CPU_COUNT()
76              Return the number of CPUs in set.
77
78       Where  a cpu argument is specified, it should not produce side effects,
79       since the above macros may evaluate the argument more than once.
80
81       The first CPU on the system corresponds to a cpu value of 0,  the  next
82       CPU  corresponds to a cpu value of 1, and so on.  No assumptions should
83       be made about particular CPUs being available, or the set of CPUs being
84       contiguous, since CPUs can be taken offline dynamically or be otherwise
85       absent.  The constant CPU_SETSIZE (currently 1024)  specifies  a  value
86       one  greater  than  the  maximum  CPU  number  that  can  be  stored in
87       cpu_set_t.
88
89       The following macros perform logical operations on CPU sets:
90
91       CPU_AND()
92              Store the intersection of the sets srcset1 and srcset2 in  dest‐
93              set (which may be one of the source sets).
94
95       CPU_OR()
96              Store  the  union  of  the  sets  srcset1 and srcset2 in destset
97              (which may be one of the source sets).
98
99       CPU_XOR()
100              Store the XOR of the sets srcset1 and srcset2 in destset  (which
101              may  be  one of the source sets).  The XOR means the set of CPUs
102              that are in either srcset1 or srcset2, but not both.
103
104       CPU_EQUAL()
105              Test whether two CPU set contain exactly the same CPUs.
106
107   Dynamically sized CPU sets
108       Because some applications may require the ability to  dynamically  size
109       CPU  sets (e.g., to allocate sets larger than that defined by the stan‐
110       dard cpu_set_t data type), glibc nowadays provides a set of  macros  to
111       support this.
112
113       The following macros are used to allocate and deallocate CPU sets:
114
115       CPU_ALLOC()
116              Allocate  a  CPU set large enough to hold CPUs in the range 0 to
117              num_cpus-1.
118
119       CPU_ALLOC_SIZE()
120              Return the size in bytes of the CPU set that would be needed  to
121              hold CPUs in the range 0 to num_cpus-1.  This macro provides the
122              value that can be used for the setsize argument in the CPU_*_S()
123              macros described below.
124
125       CPU_FREE()
126              Free a CPU set previously allocated by CPU_ALLOC().
127
128       The  macros  whose names end with "_S" are the analogs of the similarly
129       named macros without the suffix.  These macros perform the  same  tasks
130       as  their  analogs, but operate on the dynamically allocated CPU set(s)
131       whose size is setsize bytes.
132

RETURN VALUE

134       CPU_ISSET() and CPU_ISSET_S() return nonzero if cpu is in  set;  other‐
135       wise, it returns 0.
136
137       CPU_COUNT() and CPU_COUNT_S() return the number of CPUs in set.
138
139       CPU_EQUAL()  and  CPU_EQUAL_S()  return nonzero if the two CPU sets are
140       equal; otherwise they return 0.
141
142       CPU_ALLOC() returns a pointer on success, or NULL on failure.   (Errors
143       are as for malloc(3).)
144
145       CPU_ALLOC_SIZE()  returns  the  number of bytes required to store a CPU
146       set of the specified cardinality.
147
148       The other functions do not return a value.
149

VERSIONS

151       The CPU_ZERO(), CPU_SET(), CPU_CLR(), and CPU_ISSET() macros were added
152       in glibc 2.3.3.
153
154       CPU_COUNT() first appeared in glibc 2.6.
155
156       CPU_AND(),   CPU_OR(),  CPU_XOR(),  CPU_EQUAL(),  CPU_ALLOC(),  CPU_AL‐
157       LOC_SIZE(), CPU_FREE(), CPU_ZERO_S(), CPU_SET_S(), CPU_CLR_S(), CPU_IS‐
158       SET_S(),  CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and CPU_EQUAL_S() first
159       appeared in glibc 2.7.
160

CONFORMING TO

162       These interfaces are Linux-specific.
163

NOTES

165       To duplicate a CPU set, use memcpy(3).
166
167       Since CPU sets are bit masks allocated in units of long words, the  ac‐
168       tual  number of CPUs in a dynamically allocated CPU set will be rounded
169       up to the next  multiple  of  sizeof(unsigned  long).   An  application
170       should consider the contents of these extra bits to be undefined.
171
172       Notwithstanding  the  similarity  in  the names, note that the constant
173       CPU_SETSIZE indicates the number of CPUs in  the  cpu_set_t  data  type
174       (thus,  it  is  effectively a count of the bits in the bit mask), while
175       the setsize argument of the CPU_*_S() macros is a size in bytes.
176
177       The data types for arguments and return values shown  in  the  SYNOPSIS
178       are  hints  what  about is expected in each case.  However, since these
179       interfaces are implemented as macros, the  compiler  won't  necessarily
180       catch all type errors if you violate the suggestions.
181

BUGS

183       On  32-bit  platforms with glibc 2.8 and earlier, CPU_ALLOC() allocates
184       twice as much space as is  required,  and  CPU_ALLOC_SIZE()  returns  a
185       value  twice as large as it should.  This bug should not affect the se‐
186       mantics of a program, but does result in wasted memory and  less  effi‐
187       cient operation of the macros that operate on dynamically allocated CPU
188       sets.  These bugs are fixed in glibc 2.9.
189

EXAMPLES

191       The following program demonstrates the use of some of the  macros  used
192       for dynamically allocated CPU sets.
193
194       #define _GNU_SOURCE
195       #include <sched.h>
196       #include <stdlib.h>
197       #include <unistd.h>
198       #include <stdio.h>
199       #include <assert.h>
200
201       int
202       main(int argc, char *argv[])
203       {
204           cpu_set_t *cpusetp;
205           size_t size;
206           int num_cpus;
207
208           if (argc < 2) {
209               fprintf(stderr, "Usage: %s <num-cpus>\n", argv[0]);
210               exit(EXIT_FAILURE);
211           }
212
213           num_cpus = atoi(argv[1]);
214
215           cpusetp = CPU_ALLOC(num_cpus);
216           if (cpusetp == NULL) {
217               perror("CPU_ALLOC");
218               exit(EXIT_FAILURE);
219           }
220
221           size = CPU_ALLOC_SIZE(num_cpus);
222
223           CPU_ZERO_S(size, cpusetp);
224           for (int cpu = 0; cpu < num_cpus; cpu += 2)
225               CPU_SET_S(cpu, size, cpusetp);
226
227           printf("CPU_COUNT() of set:    %d\n", CPU_COUNT_S(size, cpusetp));
228
229           CPU_FREE(cpusetp);
230           exit(EXIT_SUCCESS);
231       }
232

SEE ALSO

234       sched_setaffinity(2), pthread_attr_setaffinity_np(3), pthread_setaffin‐
235       ity_np(3), cpuset(7)
236

COLOPHON

238       This page is part of release 5.12 of the Linux  man-pages  project.   A
239       description  of  the project, information about reporting bugs, and the
240       latest    version    of    this    page,    can     be     found     at
241       https://www.kernel.org/doc/man-pages/.
242
243
244
245Linux                             2021-03-22                        CPU_SET(3)
Impressum