+++ /dev/null
-.\" Copyright (C) 2006 Michael Kerrisk
-.\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk
-.\" <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH CPU_SET 3 (date) "Linux man-pages (unreleased)"
-.SH NAME
-CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT,
-CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL,
-CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE,
-CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S,
-CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \-
-macros for manipulating CPU sets
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.B #include <sched.h>
-.P
-.BI "void CPU_ZERO(cpu_set_t *" set );
-.P
-.BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
-.BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
-.BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set );
-.P
-.BI "int CPU_COUNT(cpu_set_t *" set );
-.P
-.BI "void CPU_AND(cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.BI "void CPU_OR(cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.BI "void CPU_XOR(cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.P
-.BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 );
-.P
-.BI "cpu_set_t *CPU_ALLOC(int " num_cpus );
-.BI "void CPU_FREE(cpu_set_t *" set );
-.BI "size_t CPU_ALLOC_SIZE(int " num_cpus );
-.P
-.BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set );
-.P
-.BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
-.BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
-.BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
-.P
-.BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set );
-.P
-.BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset ,
-.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.P
-.BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \
-", cpu_set_t *" set2 );
-.fi
-.SH DESCRIPTION
-The
-.I cpu_set_t
-data structure represents a set of CPUs.
-CPU sets are used by
-.BR sched_setaffinity (2)
-and similar interfaces.
-.P
-The
-.I cpu_set_t
-data type is implemented as a bit mask.
-However, the data structure should be treated as opaque:
-all manipulation of CPU sets should be done via the macros
-described in this page.
-.P
-The following macros are provided to operate on the CPU set
-.IR set :
-.TP
-.BR CPU_ZERO ()
-Clears
-.IR set ,
-so that it contains no CPUs.
-.TP
-.BR CPU_SET ()
-Add CPU
-.I cpu
-to
-.IR set .
-.TP
-.BR CPU_CLR ()
-Remove CPU
-.I cpu
-from
-.IR set .
-.TP
-.BR CPU_ISSET ()
-Test to see if CPU
-.I cpu
-is a member of
-.IR set .
-.TP
-.BR CPU_COUNT ()
-Return the number of CPUs in
-.IR set .
-.P
-Where a
-.I cpu
-argument is specified, it should not produce side effects,
-since the above macros may evaluate the argument more than once.
-.P
-The first CPU on the system corresponds to a
-.I cpu
-value of 0, the next CPU corresponds to a
-.I cpu
-value of 1, and so on.
-No assumptions should be made about particular CPUs being
-available, or the set of CPUs being contiguous, since CPUs can
-be taken offline dynamically or be otherwise absent.
-The constant
-.B CPU_SETSIZE
-(currently 1024) specifies a value one greater than the maximum CPU
-number that can be stored in
-.IR cpu_set_t .
-.P
-The following macros perform logical operations on CPU sets:
-.TP
-.BR CPU_AND ()
-Store the intersection of the sets
-.I srcset1
-and
-.I srcset2
-in
-.I destset
-(which may be one of the source sets).
-.TP
-.BR CPU_OR ()
-Store the union of the sets
-.I srcset1
-and
-.I srcset2
-in
-.I destset
-(which may be one of the source sets).
-.TP
-.BR CPU_XOR ()
-Store the XOR of the sets
-.I srcset1
-and
-.I srcset2
-in
-.I destset
-(which may be one of the source sets).
-The XOR means the set of CPUs that are in either
-.I srcset1
-or
-.IR srcset2 ,
-but not both.
-.TP
-.BR CPU_EQUAL ()
-Test whether two CPU set contain exactly the same CPUs.
-.SS Dynamically sized CPU sets
-Because some applications may require the ability to dynamically
-size CPU sets (e.g., to allocate sets larger than that
-defined by the standard
-.I cpu_set_t
-data type), glibc nowadays provides a set of macros to support this.
-.P
-The following macros are used to allocate and deallocate CPU sets:
-.TP
-.BR CPU_ALLOC ()
-Allocate a CPU set large enough to hold CPUs
-in the range 0 to
-.IR num_cpus\-1 .
-.TP
-.BR CPU_ALLOC_SIZE ()
-Return the size in bytes of the CPU set that would be needed to
-hold CPUs in the range 0 to
-.IR num_cpus\-1 .
-This macro provides the value that can be used for the
-.I setsize
-argument in the
-.BR CPU_*_S ()
-macros described below.
-.TP
-.BR CPU_FREE ()
-Free a CPU set previously allocated by
-.BR CPU_ALLOC ().
-.P
-The macros whose names end with "_S" are the analogs of
-the similarly named macros without the suffix.
-These macros perform the same tasks as their analogs,
-but operate on the dynamically allocated CPU set(s) whose size is
-.I setsize
-bytes.
-.SH RETURN VALUE
-.BR CPU_ISSET ()
-and
-.BR CPU_ISSET_S ()
-return nonzero if
-.I cpu
-is in
-.IR set ;
-otherwise, it returns 0.
-.P
-.BR CPU_COUNT ()
-and
-.BR CPU_COUNT_S ()
-return the number of CPUs in
-.IR set .
-.P
-.BR CPU_EQUAL ()
-and
-.BR CPU_EQUAL_S ()
-return nonzero if the two CPU sets are equal; otherwise they return 0.
-.P
-.BR CPU_ALLOC ()
-returns a pointer on success, or NULL on failure.
-(Errors are as for
-.BR malloc (3).)
-.P
-.BR CPU_ALLOC_SIZE ()
-returns the number of bytes required to store a
-CPU set of the specified cardinality.
-.P
-The other functions do not return a value.
-.SH STANDARDS
-Linux.
-.SH HISTORY
-The
-.BR CPU_ZERO (),
-.BR CPU_SET (),
-.BR CPU_CLR (),
-and
-.BR CPU_ISSET ()
-macros were added in glibc 2.3.3.
-.P
-.BR CPU_COUNT ()
-first appeared in glibc 2.6.
-.P
-.BR CPU_AND (),
-.BR CPU_OR (),
-.BR CPU_XOR (),
-.BR CPU_EQUAL (),
-.BR CPU_ALLOC (),
-.BR CPU_ALLOC_SIZE (),
-.BR CPU_FREE (),
-.BR CPU_ZERO_S (),
-.BR CPU_SET_S (),
-.BR CPU_CLR_S (),
-.BR CPU_ISSET_S (),
-.BR CPU_AND_S (),
-.BR CPU_OR_S (),
-.BR CPU_XOR_S (),
-and
-.BR CPU_EQUAL_S ()
-first appeared in glibc 2.7.
-.SH NOTES
-To duplicate a CPU set, use
-.BR memcpy (3).
-.P
-Since CPU sets are bit masks allocated in units of long words,
-the actual number of CPUs in a dynamically
-allocated CPU set will be rounded up to the next multiple of
-.IR "sizeof(unsigned long)" .
-An application should consider the contents of these extra bits
-to be undefined.
-.P
-Notwithstanding the similarity in the names,
-note that the constant
-.B CPU_SETSIZE
-indicates the number of CPUs in the
-.I cpu_set_t
-data type (thus, it is effectively a count of the bits in the bit mask),
-while the
-.I setsize
-argument of the
-.BR CPU_*_S ()
-macros is a size in bytes.
-.P
-The data types for arguments and return values shown
-in the SYNOPSIS are hints what about is expected in each case.
-However, since these interfaces are implemented as macros,
-the compiler won't necessarily catch all type errors
-if you violate the suggestions.
-.SH BUGS
-On 32-bit platforms with glibc 2.8 and earlier,
-.BR CPU_ALLOC ()
-allocates twice as much space as is required, and
-.BR CPU_ALLOC_SIZE ()
-returns a value twice as large as it should.
-This bug should not affect the semantics of a program,
-but does result in wasted memory
-and less efficient operation of the macros that
-operate on dynamically allocated CPU sets.
-These bugs are fixed in glibc 2.9.
-.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
-.SH EXAMPLES
-The following program demonstrates the use of some of the macros
-used for dynamically allocated CPU sets.
-.P
-.\" SRC BEGIN (CPU_SET.c)
-.EX
-#define _GNU_SOURCE
-#include <sched.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-\&
-#include <assert.h>
-\&
-int
-main(int argc, char *argv[])
-{
- cpu_set_t *cpusetp;
- size_t size, num_cpus;
-\&
- if (argc < 2) {
- fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
- exit(EXIT_FAILURE);
- }
-\&
- num_cpus = atoi(argv[1]);
-\&
- cpusetp = CPU_ALLOC(num_cpus);
- if (cpusetp == NULL) {
- perror("CPU_ALLOC");
- exit(EXIT_FAILURE);
- }
-\&
- size = CPU_ALLOC_SIZE(num_cpus);
-\&
- CPU_ZERO_S(size, cpusetp);
- for (size_t cpu = 0; cpu < num_cpus; cpu += 2)
- CPU_SET_S(cpu, size, cpusetp);
-\&
- printf("CPU_COUNT() of set: %d\en", CPU_COUNT_S(size, cpusetp));
-\&
- CPU_FREE(cpusetp);
- exit(EXIT_SUCCESS);
-}
-.EE
-.\" SRC END
-.SH SEE ALSO
-.BR sched_setaffinity (2),
-.BR pthread_attr_setaffinity_np (3),
-.BR pthread_setaffinity_np (3),
-.BR cpuset (7)
projects / thirdparty / man-pages.git / blobdiff