diff options
Diffstat (limited to 'lib/libc/sys/cpuset_getaffinity.2')
-rw-r--r-- | lib/libc/sys/cpuset_getaffinity.2 | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/lib/libc/sys/cpuset_getaffinity.2 b/lib/libc/sys/cpuset_getaffinity.2 new file mode 100644 index 0000000..5c75b92 --- /dev/null +++ b/lib/libc/sys/cpuset_getaffinity.2 @@ -0,0 +1,165 @@ +.\" 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 September 10, 2010 +.Dt CPUSET 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 +.Xr CPU_SET 2 +macros. +The kernel tolerates large sets as long as all CPUs specified +in the set exist. +Sets smaller than the kernel uses generate an error on calls to +.Fn cpuset_getaffinity +even if the result set would fit within the user supplied set. +Calls to +.Fn cpuset_setaffinity +tolerate small sets with no restrictions. +.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 . +.Pp +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.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 either preposterously large or smaller than the kernel set size. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr CPU_SET 3 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHOR +.An Jeffrey Roberson Aq jeff@FreeBSD.org |