CPU_ISSET(3)

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

RETURN VALUE

125       CPU_ISSET()  and  CPU_ISSET_S() return nonzero if cpu is in set; other‐
126       wise, it returns 0.
127
128       CPU_COUNT() and CPU_COUNT_S() return the number of CPUs in set.
129
130       CPU_EQUAL() and CPU_EQUAL_S() return nonzero if the two  CPU  sets  are
131       equal; otherwise they return 0.
132
133       CPU_ALLOC()  returns a pointer on success, or NULL on failure.  (Errors
134       are as for malloc(3).)
135
136       CPU_ALLOC_SIZE() returns the number of bytes required to  store  a  CPU
137       set of the specified cardinality.
138
139       The other functions do not return a value.
140

VERSIONS

142       The CPU_ZERO(), CPU_SET(), CPU_CLR(), and CPU_ISSET() macros were added
143       in glibc 2.3.3.
144
145       CPU_COUNT() first appeared in glibc 2.6.
146
147       CPU_AND(),    CPU_OR(),    CPU_XOR(),     CPU_EQUAL(),     CPU_ALLOC(),
148       CPU_ALLOC_SIZE(),  CPU_FREE(),  CPU_ZERO_S(), CPU_SET_S(), CPU_CLR_S(),
149       CPU_ISSET_S(), CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and  CPU_EQUAL_S()
150       first appeared in glibc 2.7.
151

CONFORMING TO

153       These interfaces are Linux-specific.
154

NOTES

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

BUGS

174       On 32-bit platforms with glibc 2.8 and earlier,  CPU_ALLOC()  allocates
175       twice  as  much  space  as  is required, and CPU_ALLOC_SIZE() returns a
176       value twice as large as it should.  This  bug  should  not  affect  the
177       semantics of a program, but does result in wasted memory and less effi‐
178       cient operation of the macros that operate on dynamically allocated CPU
179       sets.  These bugs are fixed in glibc 2.9.
180

EXAMPLE

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

COLOPHON

229       This  page  is  part of release 4.15 of the Linux man-pages project.  A
230       description of the project, information about reporting bugs,  and  the
231       latest     version     of     this    page,    can    be    found    at
232       https://www.kernel.org/doc/man-pages/.
233
234
235
236Linux                             2017-09-15                        CPU_SET(3)