Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 348 insertions, 0 deletions

diff --git a/man/man3/CPU_SET.3 b/man/man3/CPU_SET.3
new file mode 100644
index 0000000..b937a8e
--- /dev/null
+++ b/man/man3/CPU_SET.3
@@ -0,0 +1,348 @@
+.\" 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 2024-05-02 "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)