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
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       void 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       void 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 bitset.  However, the data
58       structure treated as considered opaque: all manipulation  of  CPU  sets
59       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 available CPU on the system corresponds to a cpu value of  0,
77       the  next CPU corresponds to a cpu value of 1, and so on.  The constant
78       CPU_SETSIZE (currently 1024) specifies a value  one  greater  than  the
79       maximum CPU number that can be stored in cpu_set_t.
80
81       The following macros perform logical operations on CPU sets:
82
83       CPU_AND()        Store  the logical AND of the sets srcset1 and srcset2
84                        in destset (which may be one of the source sets).
85
86       CPU_OR()         Store the logical OR of the sets srcset1  and  srcset2
87                        in destset (which may be one of the source sets).
88
89       CPU_XOR()        Store  the logical XOR of the sets srcset1 and srcset2
90                        in destset (which may be one of the source sets).
91
92       CPU_EQUAL()      Test whether two CPU  set  contain  exactly  the  same
93                        CPUs.
94
95   Dynamically sized CPU sets
96       Because  some  applications may require the ability to dynamically size
97       CPU sets (e.g., to allocate sets larger than that defined by the  stan‐
98       dard  cpu_set_t  data type), glibc nowadays provides a set of macros to
99       support this.
100
101       The following macros are used to allocate and deallocate CPU sets:
102
103       CPU_ALLOC()      Allocate a CPU set large enough to hold  CPUs  in  the
104                        range 0 to num_cpus-1.
105
106       CPU_ALLOC_SIZE() Return  the size in bytes of the CPU set that would be
107                        needed to hold CPUs in  the  range  0  to  num_cpus-1.
108                        This macro provides the value that can be used for the
109                        setsize argument in  the  CPU_*_S()  macros  described
110                        below.
111
112       CPU_FREE()       Free a CPU set previously allocated by CPU_ALLOC().
113
114       The  macros  whose names end with "_S" are the analogs of the similarly
115       named macros without the suffix.  These macros perform the  same  tasks
116       as  their  analogs, but operate on the dynamically allocated CPU set(s)
117       whose size is setsize bytes.
118

RETURN VALUE

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

VERSIONS

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

CONFORMING TO

148       These interfaces are Linux-specific.
149

NOTES

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

EXAMPLE

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

BUGS

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

SEE ALSO

220       sched_setaffinity(2), pthread_attr_setaffinity_np(3), pthread_setaffin‐
221       ity_np(3), cpuset(7)
222

COLOPHON

224       This page is part of release 3.22 of the Linux  man-pages  project.   A
225       description  of  the project, and information about reporting bugs, can
226       be found at http://www.kernel.org/doc/man-pages/.
227
228
229
230Linux                             2008-11-14                        CPU_SET(3)
Impressum