180 lines
4.9 KiB
Groff
180 lines
4.9 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.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
|