diff options
Diffstat (limited to 'lib/libsys/cpuset_getaffinity.2')
| -rw-r--r-- | lib/libsys/cpuset_getaffinity.2 | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/lib/libsys/cpuset_getaffinity.2 b/lib/libsys/cpuset_getaffinity.2 new file mode 100644 index 000000000000..850ec2a28e03 --- /dev/null +++ b/lib/libsys/cpuset_getaffinity.2 @@ -0,0 +1,177 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 27, 2022 +.Dt CPUSET_GETAFFINITY 2 +.Os +.Sh NAME +.Nm cpuset_getaffinity , +.Nm cpuset_setaffinity +.Nd manage CPU affinity +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/cpuset.h +.Ft int +.Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" +.Ft int +.Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" +.Sh DESCRIPTION +.Fn cpuset_getaffinity +and +.Fn cpuset_setaffinity +allow the manipulation of sets of CPUs available to processes, threads, +interrupts, jails and other resources. +These functions may manipulate sets of CPUs that contain many processes +or per-object anonymous masks that effect only a single object. +.Pp +The valid values for the +.Fa level +and +.Fa which +arguments are documented in +.Xr cpuset 2 . +These arguments specify which object and which set of the object we are +referring to. +Not all possible combinations are valid. +For example, only processes may belong to a numbered set accessed by a +.Fa level +argument of +.Dv CPU_LEVEL_CPUSET . +All resources, however, have a mask which may be manipulated with +.Dv CPU_LEVEL_WHICH . +.Pp +Masks of type +.Ft cpuset_t +are composed using the +.Dv CPU_SET +macros. +If the user-supplied mask is not large enough to fit all of the matching CPUs, +.Fn cpuset_getaffinity +fails with +.Er ERANGE . +Calls to +.Fn cpuset_setaffinity +tolerate masks of any size with no restrictions. +The kernel uses the meaningful part of the mask, where the upper bound is +the maximum CPU id present in the system. +If bits for non-existing CPUs are set, calls to +.Fn cpuset_setaffinity +fail with +.Er EINVAL . +.Pp +The supplied mask should have a size of +.Fa setsize +bytes. +This size is usually provided by calling +.Li sizeof(mask) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn cpuset_getaffinity +retrieves the +mask from the object specified by +.Fa level , +.Fa which +and +.Fa id +and stores it in the space provided by +.Fa mask . +.Pp +.Fn cpuset_setaffinity +attempts to set the mask for the object specified by +.Fa level , +.Fa which +and +.Fa id +to the value in +.Fa mask . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EINVAL +The +.Fa level +or +.Fa which +argument was not a valid value. +.It Bq Er EINVAL +The +.Fa mask +argument specified when calling +.Fn cpuset_setaffinity +was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setaffinity +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The mask pointer passed was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er ERANGE +The +.Fa cpusetsize +was smaller than needed to fit all of the matching CPUs. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.It Bq Er ECAPMODE +The calling process attempted to act on a process other than itself, while +in capability mode. +See +.Xr capsicum 4 . +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getdomain 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setdomain 2 , +.Xr cpuset_setid 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr capsicum 4 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org |