CPU_CLR_S(3)

1CPU_SET(3)                 Library Functions 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

LIBRARY

12       Standard C library (libc, -lc)
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

STANDARDS

154       Linux.
155

HISTORY

157       The CPU_ZERO(), CPU_SET(), CPU_CLR(), and CPU_ISSET() macros were added
158       in glibc 2.3.3.
159
160       CPU_COUNT() first appeared in glibc 2.6.
161
162       CPU_AND(),   CPU_OR(),  CPU_XOR(),  CPU_EQUAL(),  CPU_ALLOC(),  CPU_AL‐
163       LOC_SIZE(), CPU_FREE(), CPU_ZERO_S(), CPU_SET_S(), CPU_CLR_S(), CPU_IS‐
164       SET_S(),  CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and CPU_EQUAL_S() first
165       appeared in glibc 2.7.
166

NOTES

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

BUGS

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

EXAMPLES

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