1.\" $NetBSD: pset.3,v 1.2 2008/03/11 18:09:40 rmind Exp $ 2.\" 3.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 10, 2008 38.Dt PSET 3 39.Os 40.Sh NAME 41.Nm pset_create , 42.Nm pset_assign , 43.Nm pset_bind , 44.Nm pset_destroy 45.Nd processor sets 46.Sh SYNOPSIS 47.In sys/pset.h 48.Ft int 49.Fn pset_create "psetid_t *psid" 50.Ft int 51.Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid" 52.Ft int 53.Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid" 54.Ft int 55.Fn pset_destroy "psetid_t psid" 56.Sh DESCRIPTION 57The processor sets API provides the possibility to bind processes or 58threads to specific processors or groups of processors. 59This section describes the functions used to control processor sets. 60.Ss FUNCTIONS 61.Bl -tag -width compact 62.It Fn pset_create psid 63Creates a processor set, and returns its ID into 64.Fa psid . 65.It Fn pset_assign psid cpu opsid 66Assigns the processor specified by 67.Fa cpuid 68to the processor set specified by 69.Fa psid . 70Stores the current processor set ID of the processor or 71.Dv PS_NONE 72into 73.Fa opsid , 74if the pointer is not 75.Dv NULL . 76.Pp 77If 78.Fa psid 79is set to 80.Dv PS_QUERY , 81then the current processor set ID will be returned into 82.Fa psid , 83and no assignment will be performed. 84.Pp 85If 86.Fa psid 87is set to 88.Dv PS_MYID , 89then the processor set ID of the calling process will be used, and 90.Fa psid 91will be ignored. 92.Pp 93If 94.Fa psid 95is set to 96.Dv PS_NONE , 97any assignment to the processor will be cleared. 98.It Fn pset_bind psid type id opsid 99Binds the target specified by 100.Fa id 101to the processor set specified by 102.Fa psid . 103The current processor set ID to which the target is bound or 104.Dv PS_NONE 105will be returned in 106.Fa opsid , 107if the pointer is not 108.Dv NULL . 109.Nx 110supports the following types of targets specified by 111.Fa type : 112.Bl -tag -width P_PID 113.It Dv P_PID 114Process identified by the PID. 115.It Dv P_LWPID 116Thread of the calling process indentified by the LID. 117.El 118.Pp 119If 120.Fa psid 121is set to 122.Dv PS_QUERY , 123then the current processor set ID to which the target is bound or 124.Dv PS_NONE 125will be returned in 126.Fa opsid , 127and no binding will be performed. 128If 129.Fa psid 130is set to 131.Dv PS_MYID , 132then the processor set ID of the calling process will be used. 133.Pp 134If 135.Fa psid 136is set to 137.Dv PS_NONE , 138the specified target will be unbound from the processor set. 139.It Fn pset_destroy psid 140Destroys the processor set specified by 141.Fa psid . 142Before destroying the processor set, all related assignments of the 143processors will be cleared, and all bound threads will be unbound. 144.Pp 145If 146.Fa psid 147is 148.Dv PS_MYID , 149the processor set ID of the caller thread will be used. 150.El 151.Ss NOTES 152The 153.Fa pset_bind 154function can return the current processor set ID to which the 155target is bound, or 156.Dv PS_NONE . 157However, for example, the process may have many threads, which could be 158bound to different processor sets. 159In such a case it is unspecified which thread will be used to return 160the information. 161.Sh RETURN VALUES 162Upon successful completion these functions return 0. 163Otherwise, \-1 is returned and 164.Va errno 165is set to indicate the error. 166.Sh ERRORS 167The 168.Fn pset_create 169function fails if: 170.Bl -tag -width Er 171.It Bq Er ENOMEM 172No memory is available for creation of the processor set, or limit 173of the allowed count of the processor sets was reached. 174.It Bq Er EPERM 175The calling process is not the super-user. 176.El 177.Pp 178The 179.Fn pset_assign 180function fails if: 181.Bl -tag -width Er 182.It Bq Er EBUSY 183Another operation is performing on the processor set. 184.It Bq Er EINVAL 185.Fa psid 186or 187.Fa cpuid 188are invalid. 189.It Bq Er EPERM 190The calling process is not the super-user, and 191.Fa psid 192is not 193.Dv PS_QUERY . 194.El 195.Pp 196The 197.Fn pset_bind 198function fails if: 199.Bl -tag -width Er 200.It Bq Er EBUSY 201Another operation is performing on the processor set. 202.It Bq Er EINVAL 203.Fa psid 204or 205.Fa type 206are invalid. 207.It Bq Er EPERM 208The calling process is not the super-user, and 209.Fa psid 210is not 211.Dv PS_QUERY . 212.It Bq Er ESRCH 213The specified target was not found. 214.El 215.Pp 216The 217.Fn pset_destroy 218function fails if: 219.Bl -tag -width Er 220.It Bq Er EBUSY 221Another operation is performing on the processor set. 222.It Bq Er EPERM 223The calling process is not the super-user. 224.El 225.Sh SEE ALSO 226.Xr sched 3 , 227.Xr schedctl 8 228.Sh STANDARDS 229This API is expected to be compatible with the APIs found in Solaris and 230HP-UX operating systems. 231.Sh HISTORY 232The processor sets appeared in 233.Nx 5.0 . 234.Sh BUGS 235Currently, these functions are valid and work correctly only with 236the SCHED_M2 thread scheduler implementation. 237