Copyright (c) 2008 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Mindaugas Rasiukevicius <rmind at NetBSD org>.
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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 February 21, 2025 .Dt PSET 3 .Os .Sh NAME .Nm pset_create , .Nm pset_assign , .Nm pset_bind , .Nm pset_destroy .Nd processor sets .Sh LIBRARY .Lb librt .Sh SYNOPSIS n sys/pset.h .Ft int .Fn pset_create "psetid_t *psid" .Ft int .Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid" .Ft int .Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid" .Ft int .Fn pset_destroy "psetid_t psid" .Sh DESCRIPTION The processor sets API provides the possibility to exclusively dedicate specific processors or groups of processors to processes or threads. After processes or threads are bound to a group of processors by the API, the group henceforth runs only those processes or threads. This section describes the functions used to control processor sets. .Sh FUNCTIONS l -tag -width compact t Fn pset_create psid Creates a processor set, and returns its ID into .Fa psid . t Fn pset_assign psid cpu opsid Assigns the processor specified by .Fa cpuid to the processor set specified by .Fa psid . Stores the current processor set ID of the processor or .Dv PS_NONE into .Fa opsid , if the pointer is not .Dv NULL .
p The following actions can be specified: l -enum -offset 2n t If .Fa psid is set to .Dv PS_QUERY , then the current processor set ID will be returned into .Fa psid , and no assignment will be performed. t If .Fa psid is set to .Dv PS_MYID , then the processor set ID of the calling process will be used, and .Fa psid will be ignored. t If .Fa psid is set to .Dv PS_NONE , any assignment to the processor will be cleared. .El t Fn pset_bind psid type id opsid Dedicates the processor set specified by .Fa psid to the target specified by .Fa id . The current processor set ID to which the target is bound or .Dv PS_NONE will be returned in .Fa opsid , if the pointer is not .Dv NULL . .Nx supports the following types of targets specified by .Fa type : l -tag -width P_LWPID -offset 2n t Dv P_PID Process identified by the PID. t Dv P_LWPID Thread of the calling process identified by the LID. .El
p The following actions can be specified: l -enum -offset 2n t If .Fa psid is set to .Dv PS_QUERY , then the current processor set ID to which the target is bound or .Dv PS_NONE will be returned in .Fa opsid , and no binding will be performed. t If .Fa psid is set to .Dv PS_MYID , then the processor set ID of the calling process will be used. t If .Fa psid is set to .Dv PS_NONE , the specified target will be unbound from the processor set. .El t Fn pset_destroy psid Destroys the processor set specified by .Fa psid . Before destroying the processor set, all related assignments of the processors will be cleared, and all bound threads will be unbound.
p If .Fa psid is .Dv PS_MYID , the processor set ID of the caller thread will be used. .El .Sh IMPLEMENTATION NOTES Except for .Dv PS_QUERY operations, these interfaces require super-user privileges.
p The .Fn pset_bind function can return the current processor set ID to which the target is bound, or .Dv PS_NONE . However, for example, the process may have many threads, which could be bound to different processor sets. In such a case it is unspecified which thread will be used to return the information.
p There is an alternative thread affinity interface, see .Xr affinity 3 . However, processor sets and thread affinity are mutually exclusive, hence mixing of these interfaces is prohibited. .Sh RETURN VALUES Upon successful completion these functions return 0. Otherwise, -1 is returned and .Va errno is set to indicate the error. .Sh EXAMPLES An example of code fragment, which assigns the CPU whose ID is 0, for current process: d -literal psetid_t psid; cpuid_t ci = 0; if (pset_create(&psid) < 0) err(EXIT_FAILURE, "pset_create"); /* Assign CPU 0 to the processor-set */ if (pset_assign(psid, ci, NULL) < 0) err(EXIT_FAILURE, "pset_assign"); /* Bind the current process to the processor-set */ if (pset_bind(psid, P_PID, P_MYID, NULL) < 0) err(EXIT_FAILURE, "pset_bind"); /* * At this point, CPU 0 runs only the current process. */ perform_work(); if (pset_destroy(psid) < 0) err(EXIT_FAILURE, "pset_destroy"); .Ed .Sh ERRORS The .Fn pset_create function fails if: l -tag -width Er t Bq Er ENOMEM No memory is available for creation of the processor set, or limit of the allowed count of the processor sets was reached. t Bq Er EPERM The calling process is not the super-user. .El
p The .Fn pset_assign function fails if: l -tag -width Er t Bq Er EBUSY Another operation is performing on the processor set. t Bq Er EINVAL .Fa psid or .Fa cpuid are invalid. t Bq Er EPERM The calling process is not the super-user, and .Fa psid is not .Dv PS_QUERY . .El
p The .Fn pset_bind function fails if: l -tag -width Er t Bq Er EBUSY Another operation is performing on the processor set. t Bq Er EINVAL .Fa psid or .Fa type are invalid. t Bq Er EPERM The calling process is not the super-user, and .Fa psid is not .Dv PS_QUERY . t Bq Er ESRCH The specified target was not found. .El
p The .Fn pset_destroy function fails if: l -tag -width Er t Bq Er EBUSY Another operation is performing on the processor set. t Bq Er EPERM The calling process is not the super-user. .El .Sh SEE ALSO .Xr affinity 3 , .Xr cpuset 3 , .Xr sched 3 , .Xr schedctl 8 .Sh STANDARDS This API is expected to be compatible with the APIs found in Solaris and HP-UX operating systems. .Sh HISTORY The processor sets appeared in .Nx 5.0 .
Indexes created Tue Sep 23 07:09:52 GMT 2025