NAME

       cpuset, cpuset_getid, cpuset_setid — manage CPU affinity sets

LIBRARY

       Standard C Library (libc, -lc)

SYNOPSIS

       #include <sys/param.h>
       #include <sys/cpuset.h>

       int
       cpuset(cpusetid_t *setid);

       int
       cpuset_setid(cpuwhich_t which, id_t id, cpusetid_t setid);

       int
       cpuset_getid(cpulevel_t level, cpuwhich_t which, id_t id, cpusetid_t *setid);

DESCRIPTION

       The  cpuset  family of system calls allow applications to control sets of processors and assign processes
       and threads to these sets.  Processor sets contain lists of CPUs that members may run on and  exist  only
       as  long  as some process is a member of the set.  All processes in the system have an assigned set.  The
       default set for all processes in the system is the set numbered 1.  Threads belong to the same set as the
       process which contains them, however, they may further restrict their set with the  anonymous  per-thread
       mask.

       Sets are referenced by a number of type cpuset_id_t.  Each thread has a root set, an assigned set, and an
       anonymous  mask.   Only  the  root  and  assigned sets are numbered.  The root set is the set of all CPUs
       available in the system or in the system partition the thread is running  in.   The  assigned  set  is  a
       subset  of  the  root  set and is administratively assignable on a per-process basis.  Many processes and
       threads may be members of a numbered set.

       The anonymous set is a further thread-specific refinement on the  assigned  set.   It  is  intended  that
       administrators will manipulate numbered sets using cpuset(1) while application developers will manipulate
       anonymous sets using cpuset_setaffinity(2).

       To  select  the  correct  set  a  value  of  type cpulevel_t is used.  The following values for level are
       supported:

             CPU_LEVEL_ROOT      Root set
             CPU_LEVEL_CPUSET    Assigned set
             CPU_LEVEL_WHICH     Set specified by which argument

       The which argument determines how the value of id is interpreted and is of type  cpuwhich_t.   The  which
       argument may have the following values:

             CPU_WHICH_TID       id is lwpid_t (thread id)
             CPU_WHICH_PID       id is pid_t (process id)
             CPU_WHICH_CPUSET    id is a cpusetid_t (cpuset id)
             CPU_WHICH_IRQ       id is an irq number

       An  id  of '-1' may be used with a which of CPU_WHICH_TID, CPU_WHICH_PID, or CPU_WHICH_CPUSET to mean the
       current thread, process, or current thread's cpuset.  All cpuset syscalls allow this usage.

       A level argument of CPU_LEVEL_WHICH combined with a which argument other than CPU_WHICH_CPUSET refers  to
       the  anonymous  mask  of  the  object.   This  mask  does not have an id and may only be manipulated with
       cpuset_setaffinity(2).

       cpuset() creates a new set containing the same CPUs as the root set of the current process and stores its
       id in the space provided by setid.  On successful completion the calling process joins the set and is the
       only member.  Children inherit this set after a call to fork(2).

       cpuset_setid() attempts to set the  id  of  the  object  specified  by  the  which  argument.   Currently
       CPU_WHICH_PID  is  the  only  acceptable value for which as threads do not have an id distinct from their
       process and the API does not permit changing the id of an existing set.  Upon successful  completion  all
       of the threads in the target process will be running on CPUs permitted by the set.

       cpuset_getid()  retrieves  a set id from the object indicated by which and stores it in the space pointed
       to by setid.  The retrieved id may be that of either the root or assigned set depending on the  value  of
       level.   level  should be CPU_LEVEL_CPUSET or CPU_LEVEL_ROOT to get the set id from the process or thread
       specified by the id argument.  Specifying CPU_LEVEL_WHICH with a process or thread is  unsupported  since
       this references the unnumbered anonymous mask.

       The  actual  contents  of  the  sets  may  be  retrieved  or  manipulated using cpuset_getaffinity(2) and
       cpuset_setaffinity(2).  See those manual pages for more detail.

RETURN VALUES

       Upon successful completion, the value 0 is returned; otherwise the value -1 is returned  and  the  global
       variable errno is set to indicate the error.

ERRORS

       The following error codes may be set in errno:

       [EINVAL]           The which or level argument was not a valid value.

       [EDEADLK]          The cpuset_setid() call would leave a thread without a valid CPU to run on because the
                          set does not overlap with the thread's anonymous mask.

       [EFAULT]           The setid pointer passed to cpuset_getid() or cpuset() was invalid.

       [ESRCH]            The object specified by the id and which arguments could not be found.

       [EPERM]            The calling process did not have the credentials required to complete the operation.

       [ENFILE]           There was no free cpusetid_t for allocation.

SEE ALSO

       cpuset(1),     cpuset_getaffinity(2),    cpuset_setaffinity(2),    CPU_SET(3),    pthread_affinity_np(3),
       pthread_attr_affinity_np(3)

HISTORY

       The cpuset family of system calls first appeared in FreeBSD 7.1.

AUTHOR

       Jeffrey Roberson <jeff@FreeBSD.org>

Debian                                           January 8, 2010                                       CPUSET(2)